@tryinget/pi-activity-strip 0.4.0 → 0.6.0

package/src/common/niri-focus.mjs

@@ -6,12 +6,34 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { presentGhosttySurface } from "./ghostty-present.mjs";
+import { projectSessionCards, sessionCardId } from "./session-cards.mjs";
+import { parseTerminalTitleBinding } from "./surface-bindings.mjs";
+import {
+  appIdForGhosttyFamily,
+  canonicalGhosttyTerminalKey,
+  normalizeGhosttySurfaceId,
+  terminalTitleSegment,
+} from "./terminal-identity.mjs";
+import { resolveHiddenSurfaceWindow } from "./window-placement.mjs";
 
 const GHOSTTY_APP_IDS = new Set(["com.mitchellh.ghostty", "com.tryinget.ghosttysidequest"]);
 const PI_SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const SESSION_PRESENCE_SOURCE = "@tryinget/pi-little-helpers/session-presence";
 const SESSION_TITLE_TOKEN_HEX_LENGTH = 32;
 const LEGACY_SESSION_TITLE_TOKEN_HEX_LENGTH = 8;
+const PRESENT_VERIFY_ATTEMPTS = 4;
+const PRESENT_VERIFY_DELAY_MS = 120;
+
+/** @typedef {import("./window-placement.mjs").PlacementOptions} PlacementOptions */
+/** @typedef {import("./window-placement.mjs").WindowPlacement} WindowPlacement */
+/**
+ * @typedef {PlacementOptions & {
+ *   env?: NodeJS.ProcessEnv;
+ *   readFileSync?: typeof fs.readFileSync;
+ *   existsSync?: typeof fs.existsSync;
+ * }} ResolveOptions
+ */
 
 /**
  * Read one bounded Niri JSON list. Polling callers treat command, timeout,
@@ -92,11 +114,15 @@ export function shortSessionId(value, hexLength = SESSION_TITLE_TOKEN_HEX_LENGTH
     .toLowerCase();
 }
 
-/** @param {Array<Record<string, unknown>>} sessions @param {string} sessionId */
-export function resolveSnapshotSession(sessions, sessionId) {
-  const requestedId = String(sessionId ?? "");
-  const matches = sessions.filter((session) => session?.sessionId === requestedId);
-  return matches.length === 1 ? matches[0] : null;
+/** @param {Array<Record<string, unknown>>} sessions @param {string} targetId */
+export function resolveSnapshotSession(sessions, targetId) {
+  const requestedId = String(targetId ?? "");
+  const cardMatches = sessions.filter(
+    (session) => session?.cardId === requestedId || sessionCardId(session) === requestedId,
+  );
+  if (cardMatches.length === 1) return cardMatches[0];
+  const logicalMatches = sessions.filter((session) => session?.sessionId === requestedId);
+  return logicalMatches.length === 1 ? logicalMatches[0] : null;
 }
 
 /**
@@ -105,8 +131,9 @@ export function resolveSnapshotSession(sessions, sessionId) {
  * must also identify a known Ghostty build, and ambiguity always returns no match.
  * @param {Array<Record<string, unknown>>} windows
  * @param {string} sessionId
+ * @param {Record<string, unknown>} [session]
  */
-export function resolveExactGhosttyWindow(windows, sessionId) {
+export function resolveExactGhosttyWindow(windows, sessionId, session = {}) {
   const fullId = String(sessionId ?? "").trim();
   if (!PI_SESSION_ID.test(fullId)) return null;
 
@@ -123,6 +150,22 @@ export function resolveExactGhosttyWindow(windows, sessionId) {
   };
 
   const currentToken = shortSessionId(fullId);
+  if (session.terminalKind === "ghostty-surface" && !canonicalGhosttyTerminalKey(session)) {
+    return null;
+  }
+  const surfaceId = normalizeGhosttySurfaceId(session.terminalSurfaceId);
+  const titleSegment = terminalTitleSegment(session);
+  const expectedAppId = appIdForGhosttyFamily(String(session.terminalFamily ?? ""));
+  if (surfaceId && titleSegment && expectedAppId) {
+    const surfaceSuffix = ` · ${titleSegment} · ${currentToken}`;
+    const surfaceMatches = windows.filter(
+      (window) =>
+        Number.isInteger(window?.id) &&
+        String(window?.app_id ?? "") === expectedAppId &&
+        String(window?.title ?? "").endsWith(surfaceSuffix),
+    );
+    return surfaceMatches.length === 1 ? surfaceMatches[0] : null;
+  }
   const currentMatches = matchesForToken(currentToken);
   if (currentMatches.length > 0) return currentMatches.length === 1 ? currentMatches[0] : null;
 
@@ -139,184 +182,210 @@ export function resolveExactGhosttyWindow(windows, sessionId) {
 }
 
 /**
- * Resolve the one snapshot session whose exact Ghostty window currently owns
- * compositor focus. Missing, ambiguous, non-Ghostty, and stale identities all
- * fail closed so the renderer never highlights a guessed session.
+ * Place a session on its window. A visible title is exact proof; a bound surface whose tab is
+ * hidden behind another tab is placed through its Ghostty host process and remembered window.
  * @param {Array<Record<string, unknown>>} windows
- * @param {Array<Record<string, unknown>>} sessions
- * @param {{env?: NodeJS.ProcessEnv; readFileSync?: typeof fs.readFileSync; existsSync?: typeof fs.existsSync}} [options]
+ * @param {string} sessionId
+ * @param {Record<string, unknown>} [session]
+ * @param {PlacementOptions} [options]
+ * @returns {WindowPlacement | null}
  */
-export function resolveFocusedSnapshotSessionId(windows, sessions, options = {}) {
-  const focusedWindows = windows.filter((window) => window?.is_focused === true);
-  if (focusedWindows.length !== 1) return null;
-  const focusedWindow = focusedWindows[0];
-  const matches = sessions.filter((session) => {
-    const sessionId = resolvePiSessionIdentity(session, options);
-    if (!sessionId) return false;
-    return resolveExactGhosttyWindow(windows, sessionId)?.id === focusedWindow.id;
+export function resolveSessionWindow(windows, sessionId, session = {}, options = {}) {
+  const exact = resolveExactGhosttyWindow(windows, sessionId, session);
+  if (exact) return { window: exact, placement: "title" };
+  return resolveHiddenSurfaceWindow(windows, session, {
+    ...options,
+    sessionToken: shortSessionId(sessionId),
   });
-  return matches.length === 1 ? String(matches[0]?.sessionId ?? "") || null : null;
 }
 
 /**
- * Project the global broker snapshot onto one exact Niri workspace. Membership
- * requires an exact, unique Ghostty window; two telemetry records resolving to
- * the same window are both excluded rather than guessed. Activity state does
- * not affect membership.
+ * A tab occupied by a coding agent other than Pi carries no Pi identity, so it is placed by the
+ * exact title the agent put on its own terminal, and otherwise by host containment and window
+ * memory. A title claimed by more than one window is ambiguous and places nothing.
  * @param {Array<Record<string, unknown>>} windows
- * @param {Record<string, unknown>} workspace
- * @param {Array<Record<string, unknown>>} sessions
- * @param {{env?: NodeJS.ProcessEnv; readFileSync?: typeof fs.readFileSync; existsSync?: typeof fs.existsSync}} [options]
+ * @param {Record<string, unknown>} session
+ * @param {PlacementOptions} [options]
+ * @returns {WindowPlacement | null}
  */
-export function resolveWorkspaceView(windows, workspace, sessions, options = {}) {
-  if (!Number.isInteger(workspace?.id)) return null;
-  /** @type {Array<{session: Record<string, unknown>; window: Record<string, unknown>}>} */
-  const candidates = [];
-  for (const session of sessions) {
-    const sessionIdentity = resolvePiSessionIdentity(session, options);
-    if (!sessionIdentity) continue;
-    const window = resolveExactGhosttyWindow(windows, sessionIdentity);
-    if (!window || window.workspace_id !== workspace.id) continue;
-    candidates.push({ session, window });
-  }
-  const windowCounts = new Map();
-  for (const candidate of candidates) {
-    windowCounts.set(candidate.window.id, (windowCounts.get(candidate.window.id) ?? 0) + 1);
+export function resolveAgentSessionWindow(windows, session, options = {}) {
+  const titleSuffix = String(session.titleSuffix ?? "").trim();
+  if (titleSuffix) {
+    const expectedAppId = appIdForGhosttyFamily(String(session.terminalFamily ?? ""));
+    const matches = windows.filter(
+      (window) =>
+        Number.isInteger(window?.id) &&
+        String(window?.app_id ?? "") === expectedAppId &&
+        String(window?.title ?? "").endsWith(titleSuffix),
+    );
+    if (matches.length === 1) return { window: matches[0], placement: "title" };
+    if (matches.length > 1) return null;
   }
-  const projectedSessions = candidates
-    .filter((candidate) => windowCounts.get(candidate.window.id) === 1)
-    .map((candidate) => candidate.session);
-  return {
-    workspace,
-    sessions: projectedSessions,
-    focusedSessionId: resolveFocusedSnapshotSessionId(windows, projectedSessions, options),
-  };
+  return resolveHiddenSurfaceWindow(windows, session, options);
 }
 
 /**
- * Project the global broker snapshot onto the one focused Niri workspace.
- * @param {Array<Record<string, unknown>>} windows
- * @param {Array<Record<string, unknown>>} workspaces
- * @param {Array<Record<string, unknown>>} sessions
- * @param {{env?: NodeJS.ProcessEnv; readFileSync?: typeof fs.readFileSync; existsSync?: typeof fs.existsSync}} [options]
+ * Whether a session could ever be placed by a title. Activation can only confirm that a presented
+ * tab became visible for these; for anything else the compositor offers no readable proof.
+ * @param {Record<string, unknown>} session
+ * @param {ResolveOptions} [options]
  */
-export function resolveFocusedWorkspaceView(windows, workspaces, sessions, options = {}) {
-  const workspace = resolveFocusedNiriWorkspace(workspaces);
-  return workspace ? resolveWorkspaceView(windows, workspace, sessions, options) : null;
-}
-
-/** @param {Array<Record<string, unknown>>} workspaces */
-export function resolveFocusedNiriWorkspace(workspaces) {
-  const matches = workspaces.filter(
-    (workspace) =>
-      workspace?.is_focused === true &&
-      Number.isInteger(workspace?.id) &&
-      (typeof workspace?.name === "string" || Number.isInteger(workspace?.idx)),
-  );
-  return matches.length === 1 ? matches[0] : null;
+export function canVerifyTabVisibility(session, options = {}) {
+  if (resolvePiSessionIdentity(session, options)) return true;
+  return String(session?.titleSuffix ?? "").trim().length > 0;
 }
 
 /**
+ * Place any tracked session: a Pi session by its exact Pi identity, an agent tab by its own title.
  * @param {Array<Record<string, unknown>>} windows
- * @param {number | null} [workspaceId]
+ * @param {Record<string, unknown>} session
+ * @param {ResolveOptions} [options]
+ * @returns {WindowPlacement | null}
  */
-export function resolveActivityStripWindow(windows, workspaceId = null) {
-  const matches = windows.filter(
-    (window) =>
-      Number.isInteger(window?.id) &&
-      window?.title === "Pi Activity Strip" &&
-      (workspaceId == null || window?.workspace_id === workspaceId),
-  );
-  return matches.length === 1 ? matches[0] : null;
+export function placeSessionWindow(windows, session, options = {}) {
+  const piSessionId = resolvePiSessionIdentity(session, options);
+  if (piSessionId) return resolveSessionWindow(windows, piSessionId, session, options);
+  return canonicalGhosttyTerminalKey(session)
+    ? resolveAgentSessionWindow(windows, session, options)
+    : null;
 }
 
 /**
- * Focus the unique strip already resident on the focused workspace. This command is
- * designed for a compositor key binding and never moves a strip across workspaces.
- * @param {(file: string, args: string[], options: object) => Promise<{stdout?: string}>} execFileAsync
- * @param {NodeJS.ProcessEnv} [env]
- * @param {Array<unknown>} [sessions]
+ * Resolve the one snapshot session whose exact Ghostty window currently owns
+ * compositor focus. Missing, ambiguous, non-Ghostty, and stale identities all
+ * fail closed so the renderer never highlights a guessed session.
+ * @param {Array<Record<string, unknown>>} windows
+ * @param {Array<Record<string, unknown>>} sessions
+ * @param {{env?: NodeJS.ProcessEnv; readFileSync?: typeof fs.readFileSync; existsSync?: typeof fs.existsSync}} [options]
  */
-export async function focusNiriStrip(execFileAsync, env = process.env, sessions = []) {
-  if (!env.NIRI_SOCKET)
-    return { ok: false, error: "Niri is not available; strip focus did nothing." };
-  try {
-    const [{ stdout: windowOutput }, { stdout: workspaceOutput }] = await Promise.all([
-      execFileAsync("niri", ["msg", "-j", "windows"], { env }),
-      execFileAsync("niri", ["msg", "-j", "workspaces"], { env }),
-    ]);
-    const windows = JSON.parse(String(windowOutput ?? "[]"));
-    const workspaces = JSON.parse(String(workspaceOutput ?? "[]"));
-    if (!Array.isArray(windows) || !Array.isArray(workspaces))
-      throw new Error("unexpected payload");
-    const focusedWorkspace = resolveFocusedNiriWorkspace(workspaces);
-    const strip = focusedWorkspace
-      ? resolveActivityStripWindow(windows, Number(focusedWorkspace.id))
-      : null;
-    const sessionRecords = Array.isArray(sessions)
-      ? /** @type {Array<Record<string, unknown>>} */ (sessions)
-      : [];
-    const view = resolveFocusedWorkspaceView(windows, workspaces, sessionRecords, { env });
-    if (!strip || !view?.sessions.length) {
-      return {
-        ok: false,
-        error: "No visible resident strip with exact tracked sessions exists here; nothing moved.",
-      };
-    }
-    await execFileAsync("niri", ["msg", "action", "focus-window", "--id", String(strip.id)], {
-      env,
-    });
-    return { ok: true, windowId: strip.id };
-  } catch {
-    return {
-      ok: false,
-      error: "Could not focus the strip through Niri; nothing else was focused.",
-    };
-  }
+export function resolveFocusedSnapshotSessionId(windows, sessions, options = {}) {
+  const focusedWindows = windows.filter((window) => window?.is_focused === true);
+  if (focusedWindows.length !== 1) return null;
+  const focusedWindow = focusedWindows[0];
+  const matches = sessions.filter((session) => {
+    const sessionId = resolvePiSessionIdentity(session, options);
+    if (!sessionId) return false;
+    return resolveExactGhosttyWindow(windows, sessionId, session)?.id === focusedWindow.id;
+  });
+  return matches.length === 1 ? String(matches[0]?.sessionId ?? "") || null : null;
 }
 
 /**
+ * Focus the exact terminal behind a card. A visible tab needs only compositor focus. A hidden tab
+ * is first presented inside its proven Ghostty host process, then its window is focused, and the
+ * result counts as success only once the window title proves the tab became visible.
  * @param {string | Record<string, unknown>} session
  * @param {(file: string, args: string[], options: object) => Promise<{stdout?: string}>} execFileAsync
  * @param {NodeJS.ProcessEnv} [env]
- * @param {{readFileSync?: typeof fs.readFileSync; existsSync?: typeof fs.existsSync}} [options]
+ * @param {PlacementOptions & {
+ *   readFileSync?: typeof fs.readFileSync;
+ *   existsSync?: typeof fs.existsSync;
+ *   presentSurface?: typeof presentGhosttySurface;
+ *   sleep?: (milliseconds: number) => Promise<void>;
+ * }} [options]
+ * @returns {Promise<{ok: boolean; error?: string; windowId?: number; presented?: boolean; verified?: boolean}>}
  */
 export async function focusNiriSession(session, execFileAsync, env = process.env, options = {}) {
   if (!env.NIRI_SOCKET) return { ok: false, error: "Niri is not available; focus did nothing." };
-  const sessionId = resolvePiSessionIdentity(session, {
-    env,
-    readFileSync: options.readFileSync,
-    existsSync: options.existsSync,
-  });
-  if (!sessionId) {
+  const record =
+    session && typeof session === "object" ? session : { sessionId: String(session ?? "") };
+  const placementOptions = { ...options, env };
+  if (!resolvePiSessionIdentity(record, placementOptions) && !canonicalGhosttyTerminalKey(record)) {
     return {
       ok: false,
       error: "Exact Pi identity is unavailable; reload that Pi tab and try again.",
     };
   }
+  const readWindows = async () => {
+    const result = await execFileAsync("niri", ["msg", "-j", "windows"], { env });
+    const windows = JSON.parse(String(result.stdout ?? "[]"));
+    if (!Array.isArray(windows)) throw new Error("Unexpected Niri window data");
+    return windows;
+  };
   let windows;
   try {
-    const result = await execFileAsync("niri", ["msg", "-j", "windows"], { env });
-    windows = JSON.parse(String(result.stdout ?? "[]"));
-  } catch {
-    return { ok: false, error: "Could not inspect Niri windows; focus did nothing." };
-  }
-  if (!Array.isArray(windows)) {
-    return { ok: false, error: "Unexpected Niri window data; focus did nothing." };
+    windows = await readWindows();
+  } catch (error) {
+    return {
+      ok: false,
+      error:
+        error instanceof Error && error.message === "Unexpected Niri window data"
+          ? "Unexpected Niri window data; focus did nothing."
+          : "Could not inspect Niri windows; focus did nothing.",
+    };
   }
-  const target = resolveExactGhosttyWindow(windows, sessionId);
-  if (!target) {
+  const placed = placeSessionWindow(windows, record, placementOptions);
+  if (!placed) {
     return {
       ok: false,
-      error: "Pi identity did not resolve to exactly one Ghostty window; focus did nothing.",
+      error: "That session did not resolve to exactly one Ghostty window; focus did nothing.",
     };
   }
+  const target = placed.window;
+  const targetId = Number(target.id);
+  const focusWindow = () =>
+    execFileAsync("niri", ["msg", "action", "focus-window", "--id", String(targetId)], { env });
+  if (placed.placement === "title") {
+    try {
+      await focusWindow();
+      return { ok: true, windowId: targetId };
+    } catch {
+      return { ok: false, error: "Niri rejected the exact focus request; focus did nothing." };
+    }
+  }
+
+  const presented = await (options.presentSurface ?? presentGhosttySurface)({
+    execFileAsync,
+    env,
+    hostPid: Number(target.pid),
+    terminalFamily: record.terminalFamily,
+    surfaceId: record.terminalSurfaceId,
+  });
   try {
-    await execFileAsync("niri", ["msg", "action", "focus-window", "--id", String(target.id)], {
-      env,
-    });
-    return { ok: true, windowId: target.id };
+    await focusWindow();
   } catch {
-    return { ok: false, error: "Niri rejected the exact focus request; focus did nothing." };
+    return {
+      ok: false,
+      windowId: targetId,
+      presented: false,
+      error: presented.ok
+        ? "Presented the hidden tab, but Niri rejected the window focus request."
+        : "Niri rejected the exact focus request; focus did nothing.",
+    };
+  }
+  if (!presented.ok) {
+    return {
+      ok: false,
+      windowId: targetId,
+      presented: false,
+      error: `Focused the Ghostty window, but could not present the hidden tab (${presented.error}); select it manually.`,
+    };
   }
+  if (!canVerifyTabVisibility(record, placementOptions)) {
+    // Nothing this session writes is readable from the compositor, so the presented tab cannot be
+    // confirmed. The action succeeded; the outcome is reported without claiming proof.
+    return { ok: true, windowId: targetId, presented: true, verified: false };
+  }
+  const sleep =
+    options.sleep ??
+    ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+  for (let attempt = 0; attempt < PRESENT_VERIFY_ATTEMPTS; attempt += 1) {
+    if (attempt > 0) await sleep(PRESENT_VERIFY_DELAY_MS);
+    try {
+      const current = await readWindows();
+      const confirmed = placeSessionWindow(current, record, placementOptions);
+      if (confirmed?.placement === "title" && Number(confirmed.window.id) === targetId) {
+        return { ok: true, windowId: targetId, presented: true, verified: true };
+      }
+    } catch {
+      break;
+    }
+  }
+  return {
+    ok: false,
+    windowId: targetId,
+    presented: false,
+    error:
+      "Focused the Ghostty window, but the hidden tab did not become visible; select it manually.",
+  };
 }

package/src/common/protocol.mjs

@@ -5,6 +5,7 @@
 // ---
 
 import { randomUUID } from "node:crypto";
+import { canonicalGhosttyTerminalKey, normalizeGhosttySurfaceId } from "./terminal-identity.mjs";
 
 /** @typedef {import("./contracts.ts").SessionState} SessionState */
 /** @typedef {import("./contracts.ts").SessionSnapshot} SessionSnapshot */
@@ -12,6 +13,21 @@ import { randomUUID } from "node:crypto";
 /** @type {Set<SessionState>} */
 const SESSION_STATES = new Set(["idle", "thinking", "tool", "waiting", "success", "error"]);
 
+const MAX_CLOCK_SKEW_MS = 60_000;
+
+/** @param {unknown} value @param {number} maxLength */
+function boundedString(value, maxLength) {
+  return String(value ?? "").slice(0, maxLength);
+}
+
+/** @param {unknown} value @param {number} fallback @param {number} now */
+function finiteTimestamp(value, fallback, now) {
+  const timestamp = Number(value);
+  return Number.isFinite(timestamp) && timestamp >= 0 && timestamp <= now + MAX_CLOCK_SKEW_MS
+    ? timestamp
+    : fallback;
+}
+
 /** @param {string} type @param {Record<string, unknown>} [payload] */
 export function makeMessage(type, payload = {}) {
   return {
@@ -23,30 +39,46 @@ export function makeMessage(type, payload = {}) {
 
 /** @param {Partial<SessionSnapshot> | Record<string, unknown>} [session] @returns {SessionSnapshot} */
 export function normalizeSessionSnapshot(session = {}) {
+  if (!session || typeof session !== "object") session = {};
   const now = Date.now();
-  const updatedAt = Number(session.updatedAt ?? now) || now;
-  const lastEventAt = Number(session.lastEventAt ?? updatedAt) || updatedAt;
-  const startedAt = Number(session.startedAt ?? updatedAt) || updatedAt;
+  const updatedAt = finiteTimestamp(session.updatedAt, now, now);
+  const lastEventAt = finiteTimestamp(session.lastEventAt, updatedAt, now);
+  const startedAt = finiteTimestamp(session.startedAt, updatedAt, now);
+  const normalizedAgentStartedAt = finiteTimestamp(session.agentStartedAt, 0, now);
   const agentStartedAt =
-    session.agentStartedAt == null ? null : Number(session.agentStartedAt) || null;
+    session.agentStartedAt == null || !normalizedAgentStartedAt ? null : normalizedAgentStartedAt;
   const rawState = typeof session.state === "string" ? session.state : "idle";
   /** @type {SessionState} */
   const state = SESSION_STATES.has(/** @type {SessionState} */ (rawState))
     ? /** @type {SessionState} */ (rawState)
     : "idle";
 
+  const terminalKey = canonicalGhosttyTerminalKey(session);
+  const terminalKind = terminalKey ? "ghostty-surface" : "unbound";
+  const terminalFamily = terminalKey ? String(session.terminalFamily) : "";
+  const terminalSurfaceId = terminalKey ? normalizeGhosttySurfaceId(session.terminalSurfaceId) : "";
+  const rawPublisherSequence = Number(session.publisherSequence ?? 0);
+  const publisherSequence =
+    Number.isSafeInteger(rawPublisherSequence) && rawPublisherSequence >= 0
+      ? rawPublisherSequence
+      : 0;
   return {
-    sessionId: String(session.sessionId ?? ""),
-    publisherId: String(session.publisherId ?? ""),
+    sessionId: boundedString(session.sessionId, 256),
+    publisherId: boundedString(session.publisherId, 256),
+    publisherSequence,
     processId: Number(session.processId ?? 0) || 0,
-    cwd: String(session.cwd ?? ""),
-    repoLabel: String(session.repoLabel ?? "pi session"),
-    sessionName: String(session.sessionName ?? ""),
-    phase: String(session.phase ?? "Idle"),
-    detail: String(session.detail ?? "Ready"),
-    assistantPreview: String(session.assistantPreview ?? ""),
-    toolName: String(session.toolName ?? ""),
-    toolTarget: String(session.toolTarget ?? ""),
+    terminalKind,
+    terminalKey,
+    terminalFamily,
+    terminalSurfaceId,
+    cwd: boundedString(session.cwd, 4096),
+    repoLabel: boundedString(session.repoLabel ?? "pi session", 256),
+    sessionName: boundedString(session.sessionName, 256),
+    phase: boundedString(session.phase ?? "Idle", 512),
+    detail: boundedString(session.detail ?? "Ready", 2048),
+    assistantPreview: boundedString(session.assistantPreview, 2048),
+    toolName: boundedString(session.toolName, 256),
+    toolTarget: boundedString(session.toolTarget, 2048),
     state,
     turnIndex: Number(session.turnIndex ?? 0) || 0,
     updatedAt,
@@ -54,8 +86,8 @@ export function normalizeSessionSnapshot(session = {}) {
     startedAt,
     agentStartedAt,
     agentActive: Boolean(session.agentActive),
-    lastPromptPreview: String(session.lastPromptPreview ?? ""),
-    errorMessage: String(session.errorMessage ?? ""),
+    lastPromptPreview: boundedString(session.lastPromptPreview, 2048),
+    errorMessage: boundedString(session.errorMessage, 2048),
   };
 }
 

package/src/common/session-cards.mjs

@@ -0,0 +1,105 @@
+// ---
+// summary: "projects publisher snapshots into stable operator-facing terminal cards"
+// read_when:
+//   - "changing publisher aggregation, card identity, or membership comparison"
+// ---
+
+import { isActiveSession } from "./activity-order.mjs";
+import { canonicalGhosttyTerminalKey } from "./terminal-identity.mjs";
+
+/** @typedef {import("./contracts.ts").SessionSnapshot} SessionSnapshot */
+/** @typedef {Partial<SessionSnapshot> & Record<string, unknown>} SessionLike */
+
+/** @param {SessionLike} session */
+export function sessionRecordKey(session) {
+  const sessionId = String(session?.sessionId ?? "");
+  const publisherId = String(session?.publisherId ?? "");
+  return publisherId ? `${sessionId}|${publisherId}` : sessionId;
+}
+
+/** @param {SessionLike} session */
+export function sessionCardId(session) {
+  const terminalKey = canonicalGhosttyTerminalKey(session);
+  if (terminalKey) return `terminal:${terminalKey}`;
+  const sessionId = String(session?.sessionId ?? "").trim();
+  return sessionId ? `session:${sessionId}` : "";
+}
+
+/** @param {SessionLike} session */
+export function sessionMembershipKey(session) {
+  return `${sessionRecordKey(session)}→${sessionCardId(session)}`;
+}
+
+/** @param {SessionLike} session */
+function attentionRank(session) {
+  if (isActiveSession(session)) return 3;
+  if (session?.state === "error") return 2;
+  if (session?.state === "success") return 1;
+  return 0;
+}
+
+/** @param {SessionLike} left @param {SessionLike} right */
+export function comparePublisherRepresentatives(left, right) {
+  const rankDelta = attentionRank(right) - attentionRank(left);
+  if (rankDelta) return rankDelta;
+  const eventDelta = Number(right?.lastEventAt ?? 0) - Number(left?.lastEventAt ?? 0);
+  if (eventDelta) return eventDelta;
+  const turnDelta = Number(right?.turnIndex ?? 0) - Number(left?.turnIndex ?? 0);
+  if (turnDelta) return turnDelta;
+  const startDelta = Number(right?.startedAt ?? 0) - Number(left?.startedAt ?? 0);
+  if (startDelta) return startDelta;
+  return sessionRecordKey(left).localeCompare(sessionRecordKey(right));
+}
+
+/**
+ * @param {SessionLike[]} [sessions]
+ * @param {Set<string> | null} [allowedCardIds]
+ * @returns {Array<SessionLike & {cardId: string; publisherCount: number; publisherIds: string[]; publisherRecordKeys: string[]; publisherSessionIds: string[]}>}
+ */
+export function projectSessionCards(sessions = [], allowedCardIds = null) {
+  /** @type {Map<string, SessionLike[]>} */
+  const groups = new Map();
+  for (const session of sessions) {
+    const cardId = sessionCardId(session);
+    if (!cardId || (allowedCardIds && !allowedCardIds.has(cardId))) continue;
+    const group = groups.get(cardId) ?? [];
+    group.push(session);
+    groups.set(cardId, group);
+  }
+
+  /** @type {Array<SessionLike & {cardId: string; publisherCount: number; publisherIds: string[]; publisherRecordKeys: string[]; publisherSessionIds: string[]}>} */
+  const cards = [];
+  for (const [cardId, group] of groups) {
+    const ordered = [...group].sort(comparePublisherRepresentatives);
+    const representative = ordered[0];
+    if (!representative) continue;
+    cards.push({
+      ...representative,
+      cardId,
+      publisherCount: group.length,
+      publisherIds: group.map((session) => String(session.publisherId ?? "")).filter(Boolean),
+      publisherRecordKeys: group.map(sessionRecordKey),
+      publisherSessionIds: [
+        ...new Set(group.map((session) => String(session.sessionId ?? "")).filter(Boolean)),
+      ],
+    });
+  }
+  return cards;
+}
+
+/** @param {SessionLike[]} [left] @param {SessionLike[]} [right] */
+export function haveSameRecordMembership(left = [], right = []) {
+  if (left.length !== right.length) return false;
+  const leftKeys = left.map(sessionMembershipKey).sort();
+  const rightKeys = right.map(sessionMembershipKey).sort();
+  return leftKeys.every((key, index) => key === rightKeys[index]);
+}
+
+/** @param {SessionLike[]} [left] @param {SessionLike[]} [right] */
+export function haveSameCardMembership(left = [], right = []) {
+  const leftKeys = [...new Set(left.map(sessionCardId).filter(Boolean))].sort();
+  const rightKeys = [...new Set(right.map(sessionCardId).filter(Boolean))].sort();
+  return (
+    leftKeys.length === rightKeys.length && leftKeys.every((key, index) => key === rightKeys[index])
+  );
+}