@tryinget/pi-activity-strip 0.4.0 → 0.6.0

package/src/common/status-report.mjs

@@ -14,6 +14,7 @@ export function formatBrokerRuntimeStatus(result) {
 
   const lines = [
     runtime.state === "ready" ? "running (ready)" : `running (${runtime.state})`,
+    `backend: ${runtime.backend || "unknown"}`,
     `display: ${runtime.displayServer || "unknown"}`,
     `window manager: ${runtime.windowManager || "unknown"}`,
     `alignment: ${runtime.alignmentMode || "unknown"}`,
@@ -23,7 +24,58 @@ export function formatBrokerRuntimeStatus(result) {
     lines.push(`displays: ${runtime.displayCount}`);
   }
   if (typeof runtime.windowVisible === "boolean") {
-    lines.push(`window visible: ${runtime.windowVisible ? "yes" : "no"}`);
+    lines.push(`surface visible: ${runtime.windowVisible ? "yes" : "no"}`);
+  }
+  if (typeof runtime.rendererCardCount === "number") {
+    const hidden =
+      typeof runtime.rendererHiddenTabCardCount === "number"
+        ? ` (${runtime.rendererHiddenTabCardCount} hidden tabs)`
+        : "";
+    lines.push(`cards on focused workspace: ${runtime.rendererCardCount}${hidden}`);
+  }
+  if (typeof runtime.surfaceBindingCount === "number") {
+    lines.push(`remembered tab windows: ${runtime.surfaceBindingCount}`);
+  }
+  if (typeof runtime.agentTabCount === "number") {
+    lines.push(`agent tabs discovered: ${runtime.agentTabCount}`);
+  }
+  if (runtime.themeName) {
+    lines.push(`theme: ${runtime.themeName} (${runtime.themeScheme ?? "unknown"})`);
+  }
+  if (runtime.agentScanError) {
+    lines.push(`agent discovery error: ${runtime.agentScanError}`);
+  }
+  if (typeof runtime.heightRepairState === "string") {
+    const repaired = Number(runtime.heightRepairCount ?? 0);
+    lines.push(
+      `window height repair: ${runtime.heightRepairState}${repaired > 0 ? ` (${repaired} restored to automatic)` : ""}`,
+    );
+  }
+  if (typeof runtime.tabInventoryState === "string") {
+    const detail =
+      runtime.tabInventoryState === "ready"
+        ? ` (${runtime.tabInventoryFrameCount ?? 0} Ghostty windows, ${runtime.tabInventoryTabCount ?? 0} tabs)`
+        : runtime.tabInventoryDetail
+          ? ` (${runtime.tabInventoryDetail})`
+          : "";
+    lines.push(`tab inventory: ${runtime.tabInventoryState}${detail}`);
+  }
+  if (typeof runtime.akTaskState === "string") {
+    if (runtime.akTaskState === "ok") {
+      const orphaned = Number(runtime.akTaskOrphanCount ?? 0);
+      lines.push(
+        `AK task refs: ok (${runtime.akTaskClaimCount ?? 0} live claims, ${runtime.akTaskDeferredCount ?? 0} deferred${orphaned > 0 ? `, ${orphaned} orphaned claims` : ""})`,
+      );
+    } else if (runtime.akTaskState !== "disabled") {
+      lines.push(
+        `AK task refs: ${runtime.akTaskState}${runtime.akTaskError ? ` (${runtime.akTaskError})` : ""}`,
+      );
+    }
+  }
+  if (typeof runtime.unplacedSurfaceCount === "number" && runtime.unplacedSurfaceCount > 0) {
+    lines.push(
+      `unplaced hidden tabs: ${runtime.unplacedSurfaceCount} (placed once the tab inventory or a visible title reveals their window)`,
+    );
   }
   if (runtime.error) {
     lines.push(`error: ${runtime.error}`);

package/src/common/surface-bindings.mjs

@@ -0,0 +1,234 @@
+// ---
+// summary: "remembers which Niri window last displayed each Ghostty terminal surface so hidden tabs stay placed"
+// read_when:
+//   - "changing hidden-tab placement memory, its persistence, or its invalidation rules"
+// ---
+
+import fs from "node:fs";
+import path from "node:path";
+import { appIdForGhosttyFamily, normalizeGhosttySurfaceId } from "./terminal-identity.mjs";
+
+export const SURFACE_BINDINGS_SCHEMA = "pi-activity-strip-surface-bindings.v1";
+const TITLE_BINDING = / · gs:(main|legacy):(\d+) · ([0-9a-f]{32})$/i;
+const SESSION_BINDING_PREFIX = "pi-session:";
+
+/**
+ * Ghostty surface ids are per-process handles that can drift from the value a long-lived Pi
+ * process captured at startup, while the 32-hex session token in the same title never does. Both
+ * keys are therefore remembered, and lookups prefer the more specific surface key.
+ * @param {unknown} sessionToken
+ */
+export function sessionBindingKey(sessionToken) {
+  const token = String(sessionToken ?? "")
+    .trim()
+    .toLowerCase();
+  return /^[0-9a-f]{32}$/.test(token) ? `${SESSION_BINDING_PREFIX}${token}` : "";
+}
+
+/** @typedef {{windowId: number; windowPid: number; appId: string; observedAt: number}} SurfaceBinding */
+/** @typedef {{instanceKey: string; filePath?: string; fs?: Pick<typeof fs, "readFileSync" | "writeFileSync" | "renameSync" | "mkdirSync" | "unlinkSync">; now?: () => number}} SurfaceBindingStoreOptions */
+
+/**
+ * A Ghostty window title only names its active tab. Parse that name into the bound terminal key so
+ * every observation of a visible title teaches which window currently owns the surface.
+ * @param {unknown} title
+ */
+export function parseTerminalTitleBinding(title) {
+  const match = String(title ?? "").match(TITLE_BINDING);
+  if (!match) return null;
+  const surfaceId = normalizeGhosttySurfaceId(match[2]);
+  if (!surfaceId) return null;
+  const family = String(match[1]).toLowerCase();
+  const sessionToken = String(match[3]).toLowerCase();
+  return {
+    family,
+    surfaceId,
+    sessionToken,
+    terminalKey: `ghostty:${family}:${surfaceId}`,
+    sessionKey: sessionBindingKey(sessionToken),
+  };
+}
+
+/**
+ * Every binding key a title or tab label teaches: the exact surface, and the logical session.
+ * @param {ReturnType<typeof parseTerminalTitleBinding>} parsed
+ */
+export function bindingKeysFor(parsed) {
+  return parsed ? [parsed.terminalKey, parsed.sessionKey].filter(Boolean) : [];
+}
+
+/**
+ * Bindings are memory, not proof: they are only consulted for windows that still exist, still
+ * belong to the same Ghostty process, and are still admitted by the terminal's own host process.
+ * Persisted memory is bound to one Niri instance because window ids restart with the compositor.
+ * @param {SurfaceBindingStoreOptions} options
+ */
+export function createSurfaceBindingStore({
+  instanceKey,
+  filePath = "",
+  fs: fsImpl = fs,
+  now = Date.now,
+}) {
+  /** @type {Map<string, SurfaceBinding>} */
+  const bindings = new Map();
+  let dirty = false;
+
+  function load() {
+    if (!filePath) return;
+    /** @type {any} */
+    let parsed;
+    try {
+      parsed = JSON.parse(fsImpl.readFileSync(filePath, "utf8"));
+    } catch {
+      return;
+    }
+    if (parsed?.schema !== SURFACE_BINDINGS_SCHEMA || parsed.instanceKey !== instanceKey) return;
+    const entries = /** @type {Array<[string, any]>} */ (Object.entries(parsed.bindings ?? {}));
+    for (const [terminalKey, value] of entries) {
+      if (
+        !Number.isInteger(value?.windowId) ||
+        !Number.isInteger(value?.windowPid) ||
+        typeof value?.appId !== "string"
+      ) {
+        continue;
+      }
+      bindings.set(terminalKey, {
+        windowId: value.windowId,
+        windowPid: value.windowPid,
+        appId: value.appId,
+        observedAt: Number(value.observedAt) || 0,
+      });
+    }
+  }
+
+  function persist() {
+    if (!filePath || !dirty) return false;
+    const temporaryPath = `${filePath}.tmp.${process.pid}`;
+    try {
+      fsImpl.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+      fsImpl.writeFileSync(
+        temporaryPath,
+        JSON.stringify({
+          schema: SURFACE_BINDINGS_SCHEMA,
+          instanceKey,
+          savedAt: now(),
+          bindings: Object.fromEntries(bindings),
+        }),
+        { mode: 0o600 },
+      );
+      fsImpl.renameSync(temporaryPath, filePath);
+      dirty = false;
+      return true;
+    } catch {
+      try {
+        fsImpl.unlinkSync(temporaryPath);
+      } catch {
+        // The temporary file never existed or is already gone.
+      }
+      return false;
+    }
+  }
+
+  /**
+   * Learn from every Ghostty window whose title carries a surface segment. Accepts a complete
+   * window list or a single window event. Returns the terminal keys whose binding changed.
+   * @param {Array<Record<string, unknown>>} windows
+   */
+  function observeWindows(windows) {
+    const changed = [];
+    for (const window of windows ?? []) {
+      if (!Number.isInteger(window?.id) || !Number.isInteger(window?.pid)) continue;
+      const parsed = parseTerminalTitleBinding(window.title);
+      if (!parsed) continue;
+      const appId = String(window.app_id ?? "");
+      if (appId !== appIdForGhosttyFamily(parsed.family)) continue;
+      for (const key of bindingKeysFor(parsed)) {
+        const previous = bindings.get(key);
+        if (previous?.windowId === window.id && previous?.windowPid === window.pid) continue;
+        bindings.set(key, {
+          windowId: Number(window.id),
+          windowPid: Number(window.pid),
+          appId,
+          observedAt: now(),
+        });
+        changed.push(key);
+        dirty = true;
+      }
+    }
+    return changed;
+  }
+
+  /**
+   * Adopt bindings established by an exact external inventory (for example AT-SPI tab labels
+   * already mapped onto windows). Returns the terminal keys whose binding changed.
+   * @param {Array<{bindingKey: string; windowId: number; windowPid: number; appId: string}>} observed
+   */
+  function observeBindings(observed) {
+    const changed = [];
+    for (const binding of observed ?? []) {
+      if (
+        typeof binding?.bindingKey !== "string" ||
+        !binding.bindingKey ||
+        !Number.isInteger(binding.windowId) ||
+        !Number.isInteger(binding.windowPid) ||
+        typeof binding.appId !== "string"
+      ) {
+        continue;
+      }
+      const previous = bindings.get(binding.bindingKey);
+      if (previous?.windowId === binding.windowId && previous?.windowPid === binding.windowPid) {
+        continue;
+      }
+      bindings.set(binding.bindingKey, {
+        windowId: binding.windowId,
+        windowPid: binding.windowPid,
+        appId: binding.appId,
+        observedAt: now(),
+      });
+      changed.push(binding.bindingKey);
+      dirty = true;
+    }
+    return changed;
+  }
+
+  /**
+   * Forget bindings whose window vanished or changed process identity. Only a complete window list
+   * may prune; an empty observation is indistinguishable from a failed read and is ignored.
+   * @param {Array<Record<string, unknown>>} windows
+   */
+  function prune(windows) {
+    if (!Array.isArray(windows) || windows.length === 0) return [];
+    const byId = new Map(
+      windows.filter((window) => Number.isInteger(window?.id)).map((window) => [window.id, window]),
+    );
+    const removed = [];
+    for (const [terminalKey, binding] of bindings) {
+      const window = byId.get(binding.windowId);
+      if (
+        window &&
+        window.pid === binding.windowPid &&
+        String(window.app_id ?? "") === binding.appId
+      ) {
+        continue;
+      }
+      bindings.delete(terminalKey);
+      removed.push(terminalKey);
+      dirty = true;
+    }
+    return removed;
+  }
+
+  load();
+  return {
+    observeWindows,
+    observeBindings,
+    prune,
+    persist,
+    /** @param {string} terminalKey */
+    lookup: (terminalKey) => bindings.get(terminalKey) ?? null,
+    entries: () => [...bindings.entries()],
+    get size() {
+      return bindings.size;
+    },
+  };
+}

package/src/common/telemetry.mjs

@@ -67,18 +67,25 @@ export function createSessionId() {
   return `${os.hostname()}-${process.pid}-${Date.now()}-${randomUUID().slice(0, 6)}`;
 }
 
-/** @param {{ cwd?: string; sessionName?: string; sessionId?: string; publisherId?: string }} [options] @returns {SessionSnapshot} */
+/** @param {{ cwd?: string; sessionName?: string; sessionId?: string; publisherId?: string; terminalIdentity?: {terminalKind?: string; terminalKey?: string; terminalFamily?: string; terminalSurfaceId?: string} }} [options] @returns {SessionSnapshot} */
 export function createInitialSnapshot({
   cwd = process.cwd(),
   sessionName = "",
   sessionId = "",
   publisherId = "",
+  terminalIdentity = {},
 } = {}) {
   const now = Date.now();
   return {
     sessionId: sessionId.trim() || createSessionId(),
     publisherId: publisherId.trim() || randomUUID(),
+    publisherSequence: 0,
     processId: process.pid,
+    terminalKind:
+      terminalIdentity.terminalKind === "ghostty-surface" ? "ghostty-surface" : "unbound",
+    terminalKey: String(terminalIdentity.terminalKey ?? ""),
+    terminalFamily: String(terminalIdentity.terminalFamily ?? ""),
+    terminalSurfaceId: String(terminalIdentity.terminalSurfaceId ?? ""),
     cwd,
     repoLabel: formatRepoLabel(cwd, sessionName),
     sessionName: compactWhitespace(sessionName),

package/src/common/terminal-identity.mjs

@@ -0,0 +1,212 @@
+// ---
+// summary: "derives bounded terminal-surface identities for activity-strip publisher and focus contracts"
+// read_when:
+//   - "changing terminal card identity, Ghostty surface admission, or title matching"
+// ---
+
+import fs from "node:fs";
+import path from "node:path";
+
+const UINT64_MAX = 18_446_744_073_709_551_615n;
+const GHOSTTY_MAIN_APP_ID = "com.mitchellh.ghostty";
+const GHOSTTY_LEGACY_APP_ID = "com.tryinget.ghosttysidequest";
+const HOST_PID_CACHE_LIMIT = 1024;
+
+/** @typedef {{terminalKind: "ghostty-surface" | "unbound"; terminalKey: string; terminalFamily: string; terminalSurfaceId: string}} TerminalIdentity */
+/** @typedef {{env?: NodeJS.ProcessEnv; hasUI?: boolean; stdinIsTTY?: boolean; ttyPath?: string; processId?: number; ancestorExecutable?: string}} TerminalIdentityOptions */
+/** @typedef {{readFile: (filePath: string) => string; readLink: (filePath: string) => string}} ProcfsReader */
+
+/** @param {string} filePath */
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** @param {string} filePath */
+function safeReadLink(filePath) {
+  try {
+    return fs.readlinkSync(filePath);
+  } catch {
+    return "";
+  }
+}
+
+/** @type {ProcfsReader} */
+const defaultProcfs = { readFile: safeReadFile, readLink: safeReadLink };
+
+/**
+ * Fields after the parenthesized command name in /proc/<pid>/stat: index 1 is the parent pid and
+ * index 19 is the process start time in clock ticks since boot.
+ * @param {number} pid
+ * @param {ProcfsReader} procfs
+ */
+function readStatFields(pid, procfs) {
+  const value = procfs.readFile(path.join("/proc", String(pid), "stat"));
+  const lastParen = value.lastIndexOf(")");
+  if (lastParen < 0) return [];
+  return value
+    .slice(lastParen + 2)
+    .trim()
+    .split(/\s+/);
+}
+
+/** @param {number} pid @param {ProcfsReader} [procfs] */
+function readParentPid(pid, procfs = defaultProcfs) {
+  const parentPid = Number.parseInt(readStatFields(pid, procfs)[1] ?? "", 10);
+  return Number.isInteger(parentPid) && parentPid > 0 ? parentPid : 0;
+}
+
+/** @param {number} pid @param {ProcfsReader} [procfs] */
+export function readProcessStartTime(pid, procfs = defaultProcfs) {
+  const startTime = readStatFields(pid, procfs)[19] ?? "";
+  return /^\d+$/.test(startTime) ? startTime : "";
+}
+
+/** @param {unknown} value */
+export function normalizeGhosttySurfaceId(value) {
+  try {
+    const normalized = BigInt(String(value ?? "").trim());
+    return normalized >= 0n && normalized <= UINT64_MAX ? normalized.toString(10) : "";
+  } catch {
+    return "";
+  }
+}
+
+/** @param {unknown} executable */
+export function classifyGhosttyFamily(executable) {
+  const normalized = String(executable ?? "").toLowerCase();
+  if (!normalized) return "";
+  if (normalized.includes("ghostty-sidequest")) return "legacy";
+  if (path.basename(normalized) === "ghostty" || normalized.includes("ghostty-origin"))
+    return "main";
+  return "";
+}
+
+/** @param {unknown} family */
+export function appIdForGhosttyFamily(family) {
+  if (family === "main") return GHOSTTY_MAIN_APP_ID;
+  if (family === "legacy") return GHOSTTY_LEGACY_APP_ID;
+  return "";
+}
+
+/**
+ * Walk the parent chain to the nearest live Ghostty process. That process owns every Wayland window
+ * a tab of this terminal can live in, which makes it the placement authority for hidden tabs.
+ * @param {number} [processId]
+ * @param {ProcfsReader} [procfs]
+ * @returns {{pid: number; executable: string} | null}
+ */
+export function findGhosttyAncestor(processId = process.pid, procfs = defaultProcfs) {
+  let pid = Number(processId) || 0;
+  for (let depth = 0; depth < 12 && pid > 0; depth += 1) {
+    pid = readParentPid(pid, procfs);
+    if (pid <= 0) break;
+    const command = procfs
+      .readFile(path.join("/proc", String(pid), "comm"))
+      .trim()
+      .toLowerCase();
+    if (command === "ghostty") {
+      return { pid, executable: procfs.readLink(path.join("/proc", String(pid), "exe")) };
+    }
+  }
+  return null;
+}
+
+/** @param {number} [processId] @param {ProcfsReader} [procfs] */
+export function findGhosttyAncestorExecutable(processId = process.pid, procfs = defaultProcfs) {
+  return findGhosttyAncestor(processId, procfs)?.executable ?? "";
+}
+
+/**
+ * Resolve the live Ghostty process hosting a bound terminal surface. The publisher process must
+ * still exist and its Ghostty ancestor must belong to the admitted executable family; anything else
+ * fails closed to 0. Results are cached per process start time so pid reuse cannot leak a stale host.
+ * @param {Record<string, unknown>} session
+ * @param {{procfs?: ProcfsReader; cache?: Map<string, number>}} [options]
+ */
+export function resolveTerminalHostPid(session, options = {}) {
+  if (!canonicalGhosttyTerminalKey(session)) return 0;
+  const processId = Number(session.processId ?? 0);
+  if (!Number.isInteger(processId) || processId <= 0) return 0;
+  const procfs = options.procfs ?? defaultProcfs;
+  const startTime = readProcessStartTime(processId, procfs);
+  if (!startTime) return 0;
+  const cacheKey = `${processId}:${startTime}`;
+  const cached = options.cache?.get(cacheKey);
+  if (cached !== undefined) return cached;
+  const ancestor = findGhosttyAncestor(processId, procfs);
+  const hostPid =
+    ancestor && classifyGhosttyFamily(ancestor.executable) === session.terminalFamily
+      ? ancestor.pid
+      : 0;
+  if (options.cache) {
+    if (options.cache.size >= HOST_PID_CACHE_LIMIT) options.cache.clear();
+    options.cache.set(cacheKey, hostPid);
+  }
+  return hostPid;
+}
+
+/** @returns {TerminalIdentity} */
+export function unboundTerminalIdentity() {
+  return {
+    terminalKind: "unbound",
+    terminalKey: "",
+    terminalFamily: "",
+    terminalSurfaceId: "",
+  };
+}
+
+/**
+ * Admit a terminal binding only for an interactive TUI attached to a real TTY and a recognized
+ * Ghostty process family. Headless descendants commonly inherit Ghostty environment variables, so
+ * GHOSTTY_SURFACE_ID alone is not evidence of an operator-visible terminal.
+ * @param {TerminalIdentityOptions} [options]
+ * @returns {TerminalIdentity}
+ */
+export function resolveTerminalIdentity({
+  env = process.env,
+  hasUI = false,
+  stdinIsTTY = Boolean(process.stdin.isTTY),
+  ttyPath = safeReadLink("/proc/self/fd/0"),
+  processId = process.pid,
+  ancestorExecutable,
+} = {}) {
+  if (
+    !hasUI ||
+    !stdinIsTTY ||
+    !ttyPath.startsWith("/dev/") ||
+    String(env.TERM_PROGRAM ?? "").toLowerCase() !== "ghostty"
+  ) {
+    return unboundTerminalIdentity();
+  }
+  const surfaceId = normalizeGhosttySurfaceId(env.GHOSTTY_SURFACE_ID);
+  const executable = ancestorExecutable ?? findGhosttyAncestorExecutable(processId);
+  const family = classifyGhosttyFamily(executable);
+  if (!surfaceId || !family) return unboundTerminalIdentity();
+  return {
+    terminalKind: "ghostty-surface",
+    terminalKey: `ghostty:${family}:${surfaceId}`,
+    terminalFamily: family,
+    terminalSurfaceId: surfaceId,
+  };
+}
+
+/** @param {Partial<TerminalIdentity> | Record<string, unknown>} identity */
+export function canonicalGhosttyTerminalKey(identity) {
+  if (identity?.terminalKind !== "ghostty-surface") return "";
+  const family = String(identity.terminalFamily ?? "");
+  if (family !== "main" && family !== "legacy") return "";
+  const surfaceId = normalizeGhosttySurfaceId(identity.terminalSurfaceId);
+  if (!surfaceId) return "";
+  const expectedKey = `ghostty:${family}:${surfaceId}`;
+  return String(identity.terminalKey ?? "") === expectedKey ? expectedKey : "";
+}
+
+/** @param {Partial<TerminalIdentity> | Record<string, unknown>} identity */
+export function terminalTitleSegment(identity) {
+  if (!canonicalGhosttyTerminalKey(identity)) return "";
+  return `gs:${identity.terminalFamily}:${normalizeGhosttySurfaceId(identity.terminalSurfaceId)}`;
+}

package/src/common/window-placement.mjs

@@ -0,0 +1,59 @@
+// ---
+// summary: "places bound Pi terminal surfaces onto Niri windows, including tabs hidden behind another tab"
+// read_when:
+//   - "changing how hidden Ghostty tabs are attributed to windows, workspaces, or activation targets"
+// ---
+
+import { sessionBindingKey } from "./surface-bindings.mjs";
+import { appIdForGhosttyFamily, canonicalGhosttyTerminalKey } from "./terminal-identity.mjs";
+
+/** @typedef {"title" | "host" | "binding"} SurfacePlacement */
+/** @typedef {{window: Record<string, unknown>; placement: SurfacePlacement}} WindowPlacement */
+/**
+ * @typedef {{
+ *   resolveHostPid?: (session: Record<string, unknown>) => number;
+ *   lookupBinding?: (bindingKey: string) => {windowId: number; windowPid: number} | null;
+ * }} PlacementOptions
+ */
+
+/**
+ * Place a bound surface whose title is not visible in any window. A surface can only live inside
+ * a window of its own Ghostty process, so a single host window is an exact placement. Several host
+ * windows require the window that last displayed this surface; without that memory the surface
+ * stays unplaced rather than guessed.
+ * @param {Array<Record<string, unknown>>} windows
+ * @param {Record<string, unknown>} session
+ * @param {PlacementOptions & {sessionToken?: string}} [options]
+ * @returns {WindowPlacement | null}
+ */
+export function resolveHiddenSurfaceWindow(windows, session, options = {}) {
+  const terminalKey = canonicalGhosttyTerminalKey(session);
+  if (!terminalKey) return null;
+  const hostPid = Number(options.resolveHostPid?.(session) ?? 0);
+  if (!Number.isInteger(hostPid) || hostPid <= 0) return null;
+  const appId = appIdForGhosttyFamily(String(session.terminalFamily ?? ""));
+  const hostWindows = windows.filter(
+    (window) =>
+      Number.isInteger(window?.id) &&
+      window.pid === hostPid &&
+      String(window.app_id ?? "") === appId,
+  );
+  if (hostWindows.length === 1) return { window: hostWindows[0], placement: "host" };
+  if (hostWindows.length === 0) return null;
+  for (const key of [terminalKey, sessionBindingKey(options.sessionToken)].filter(Boolean)) {
+    const binding = options.lookupBinding?.(key);
+    if (!binding) continue;
+    const remembered = hostWindows.find(
+      (window) => window.id === binding.windowId && window.pid === binding.windowPid,
+    );
+    if (remembered) return { window: remembered, placement: "binding" };
+  }
+  return null;
+}
+
+/** @param {SurfacePlacement | undefined} placement */
+export function describePlacement(placement) {
+  if (placement === "host") return "hidden tab inside its Ghostty process's only window";
+  if (placement === "binding") return "hidden tab in the window that last displayed it";
+  return "visible tab";
+}