@tryinget/pi-activity-strip 0.3.0 → 0.5.0

package/src/common/contracts.d.ts

@@ -8,7 +8,17 @@ export type SessionState = "idle" | "thinking" | "tool" | "waiting" | "success"
 
 export interface SessionSnapshot {
   sessionId: string;
+  publisherId: string;
+  publisherSequence: number;
   processId: number;
+  terminalKind: "ghostty-surface" | "unbound";
+  terminalKey: string;
+  terminalFamily: string;
+  terminalSurfaceId: string;
+  cardId?: string;
+  publisherCount?: number;
+  publisherIds?: string[];
+  publisherRecordKeys?: string[];
   cwd: string;
   repoLabel: string;
   sessionName: string;
@@ -20,6 +30,7 @@ export interface SessionSnapshot {
   state: SessionState;
   turnIndex: number;
   updatedAt: number;
+  lastEventAt: number;
   startedAt: number;
   agentStartedAt: number | null;
   agentActive: boolean;
@@ -36,13 +47,25 @@ export type ActivityStripRuntimeState = "starting" | "ready" | "error";
 
 export interface ActivityStripRuntimeStatus {
   state: ActivityStripRuntimeState;
+  backend?: "native-layer-shell";
   startedAt: number;
   readyAt?: number | null;
   windowVisible?: boolean;
   displayServer?: "wayland" | "x11" | "headless" | "unknown";
   windowManager?: string | null;
   displayCount?: number | null;
-  alignmentMode?: "niri" | "generic";
+  alignmentMode?: "layer-shell";
+  rendererCardCount?: number;
+  rendererCardIds?: string[];
+  rendererVisibilityTransitionCount?: number;
+  controllerPid?: number;
+  panelPid?: number | null;
+  panelExpanded?: boolean;
+  clickThrough?: boolean;
+  panelMoveCount?: number;
+  panelActivationCount?: number;
+  panelRestartCount?: number;
+  lastMovedCardId?: string | null;
   warnings?: string[];
   error?: string | null;
 }
@@ -63,6 +86,7 @@ export interface BrokerClientOptions {
 
 export interface SessionStoreOptions {
   staleAfterMs?: number;
+  maxSessions?: number;
 }
 
 export interface ActivityStripBrokerOptions {
@@ -71,10 +95,11 @@ export interface ActivityStripBrokerOptions {
   store?: {
     snapshot(): BrokerSnapshot;
     upsert(session: Partial<SessionSnapshot> | Record<string, unknown>): boolean;
-    remove(sessionId: string): boolean;
+    remove(sessionId: string, publisherId?: string): boolean;
   };
   getRuntimeStatus?: () => ActivityStripRuntimeStatus | undefined;
-  focusSession?: (sessionId: string) => Promise<{ ok: boolean; error?: string; windowId?: number }>;
+  focusSession?: (targetId: string) => Promise<{ ok: boolean; error?: string; windowId?: number }>;
+  focusStrip?: () => Promise<{ ok: boolean; error?: string }>;
 }
 
 export interface ToolCallDescription {
@@ -115,6 +140,11 @@ export interface TurnStartEventLike {
   turnIndex?: number;
 }
 
+export interface TurnEndEventLike {
+  turnIndex?: number;
+  message?: unknown;
+}
+
 export interface AssistantMessageEventLike {
   type?: string;
   delta?: unknown;
@@ -136,15 +166,34 @@ export interface SessionTelemetryOptions {
   pi?: TelemetryPiLike;
   cwd?: string;
   sessionName?: string;
+  env?: NodeJS.ProcessEnv;
+  stdinIsTTY?: boolean;
+  resolveTerminalIdentity?: (options: {
+    env?: NodeJS.ProcessEnv;
+    hasUI?: boolean;
+    stdinIsTTY?: boolean;
+    ttyPath?: string;
+    processId?: number;
+    ancestorExecutable?: string;
+  }) => {
+    terminalKind: "ghostty-surface" | "unbound";
+    terminalKey: string;
+    terminalFamily: string;
+    terminalSurfaceId: string;
+  };
+  transport?: {
+    publish: (session: SessionSnapshot) => Promise<unknown>;
+    remove: (session: { sessionId: string; publisherId: string }) => Promise<unknown>;
+  };
 }
 
 export interface ActivityStripCompatibilityReport {
   ok: boolean;
+  backend: string;
   displayServer: "wayland" | "x11" | "headless" | "unknown";
   windowManager: string | null;
-  electronPath: string | null;
   displayCount: number | null;
-  alignmentMode: "niri" | "generic";
+  alignmentMode: "layer-shell";
   primaryDisplayOnly: boolean;
   clickThroughDefault: boolean;
   blockers: string[];

package/src/common/contracts.ts

@@ -8,7 +8,17 @@ export type SessionState = "idle" | "thinking" | "tool" | "waiting" | "success"
 
 export interface SessionSnapshot {
   sessionId: string;
+  publisherId: string;
+  publisherSequence: number;
   processId: number;
+  terminalKind: "ghostty-surface" | "unbound";
+  terminalKey: string;
+  terminalFamily: string;
+  terminalSurfaceId: string;
+  cardId?: string;
+  publisherCount?: number;
+  publisherIds?: string[];
+  publisherRecordKeys?: string[];
   cwd: string;
   repoLabel: string;
   sessionName: string;
@@ -20,6 +30,7 @@ export interface SessionSnapshot {
   state: SessionState;
   turnIndex: number;
   updatedAt: number;
+  lastEventAt: number;
   startedAt: number;
   agentStartedAt: number | null;
   agentActive: boolean;
@@ -36,13 +47,25 @@ export type ActivityStripRuntimeState = "starting" | "ready" | "error";
 
 export interface ActivityStripRuntimeStatus {
   state: ActivityStripRuntimeState;
+  backend?: "native-layer-shell";
   startedAt: number;
   readyAt?: number | null;
   windowVisible?: boolean;
   displayServer?: "wayland" | "x11" | "headless" | "unknown";
   windowManager?: string | null;
   displayCount?: number | null;
-  alignmentMode?: "niri" | "generic";
+  alignmentMode?: "layer-shell";
+  rendererCardCount?: number;
+  rendererCardIds?: string[];
+  rendererVisibilityTransitionCount?: number;
+  controllerPid?: number;
+  panelPid?: number | null;
+  panelExpanded?: boolean;
+  clickThrough?: boolean;
+  panelMoveCount?: number;
+  panelActivationCount?: number;
+  panelRestartCount?: number;
+  lastMovedCardId?: string | null;
   warnings?: string[];
   error?: string | null;
 }
@@ -63,6 +86,7 @@ export interface BrokerClientOptions {
 
 export interface SessionStoreOptions {
   staleAfterMs?: number;
+  maxSessions?: number;
 }
 
 export interface ActivityStripBrokerOptions {
@@ -71,10 +95,11 @@ export interface ActivityStripBrokerOptions {
   store?: {
     snapshot(): BrokerSnapshot;
     upsert(session: Partial<SessionSnapshot> | Record<string, unknown>): boolean;
-    remove(sessionId: string): boolean;
+    remove(sessionId: string, publisherId?: string): boolean;
   };
   getRuntimeStatus?: () => ActivityStripRuntimeStatus | undefined;
-  focusSession?: (sessionId: string) => Promise<{ ok: boolean; error?: string; windowId?: number }>;
+  focusSession?: (targetId: string) => Promise<{ ok: boolean; error?: string; windowId?: number }>;
+  focusStrip?: () => Promise<{ ok: boolean; error?: string }>;
 }
 
 export interface ToolCallDescription {
@@ -115,6 +140,11 @@ export interface TurnStartEventLike {
   turnIndex?: number;
 }
 
+export interface TurnEndEventLike {
+  turnIndex?: number;
+  message?: unknown;
+}
+
 export interface AssistantMessageEventLike {
   type?: string;
   delta?: unknown;
@@ -136,15 +166,34 @@ export interface SessionTelemetryOptions {
   pi?: TelemetryPiLike;
   cwd?: string;
   sessionName?: string;
+  env?: NodeJS.ProcessEnv;
+  stdinIsTTY?: boolean;
+  resolveTerminalIdentity?: (options: {
+    env?: NodeJS.ProcessEnv;
+    hasUI?: boolean;
+    stdinIsTTY?: boolean;
+    ttyPath?: string;
+    processId?: number;
+    ancestorExecutable?: string;
+  }) => {
+    terminalKind: "ghostty-surface" | "unbound";
+    terminalKey: string;
+    terminalFamily: string;
+    terminalSurfaceId: string;
+  };
+  transport?: {
+    publish: (session: SessionSnapshot) => Promise<unknown>;
+    remove: (session: { sessionId: string; publisherId: string }) => Promise<unknown>;
+  };
 }
 
 export interface ActivityStripCompatibilityReport {
   ok: boolean;
+  backend: string;
   displayServer: "wayland" | "x11" | "headless" | "unknown";
   windowManager: string | null;
-  electronPath: string | null;
   displayCount: number | null;
-  alignmentMode: "niri" | "generic";
+  alignmentMode: "layer-shell";
   primaryDisplayOnly: boolean;
   clickThroughDefault: boolean;
   blockers: string[];

package/src/common/niri-focus.mjs

@@ -6,6 +6,13 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { projectSessionCards, sessionCardId } from "./session-cards.mjs";
+import {
+  appIdForGhosttyFamily,
+  canonicalGhosttyTerminalKey,
+  normalizeGhosttySurfaceId,
+  terminalTitleSegment,
+} from "./terminal-identity.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;
@@ -92,11 +99,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 +116,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 +135,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;
 
@@ -153,16 +181,15 @@ export function resolveFocusedSnapshotSessionId(windows, sessions, options = {})
   const matches = sessions.filter((session) => {
     const sessionId = resolvePiSessionIdentity(session, options);
     if (!sessionId) return false;
-    return resolveExactGhosttyWindow(windows, sessionId)?.id === focusedWindow.id;
+    return resolveExactGhosttyWindow(windows, sessionId, session)?.id === focusedWindow.id;
   });
   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.
+ * requires an exact Ghostty window. Multiple publisher streams bound to the same terminal are
+ * aggregated into one stable card; ambiguity between distinct windows still fails closed.
  * @param {Array<Record<string, unknown>>} windows
  * @param {Record<string, unknown>} workspace
  * @param {Array<Record<string, unknown>>} sessions
@@ -170,26 +197,57 @@ export function resolveFocusedSnapshotSessionId(windows, sessions, options = {})
  */
 export function resolveWorkspaceView(windows, workspace, sessions, options = {}) {
   if (!Number.isInteger(workspace?.id)) return null;
-  /** @type {Array<{session: Record<string, unknown>; window: Record<string, unknown>}>} */
+  /** @type {Array<{cardId: string; 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);
+    const window = resolveExactGhosttyWindow(windows, sessionIdentity, session);
     if (!window || window.workspace_id !== workspace.id) continue;
-    candidates.push({ session, window });
+    const cardId = sessionCardId(session);
+    if (!cardId) continue;
+    candidates.push({ cardId, session: { ...session, cardId }, window });
+  }
+
+  const cardIdsByWindow = new Map();
+  for (const candidate of candidates) {
+    const ids = cardIdsByWindow.get(candidate.window.id) ?? new Set();
+    ids.add(candidate.cardId);
+    cardIdsByWindow.set(candidate.window.id, ids);
   }
-  const windowCounts = new Map();
+  const allowedCardByWindow = new Map();
+  for (const [windowId, ids] of cardIdsByWindow) {
+    const terminalIds = [...ids].filter((cardId) => cardId.startsWith("terminal:"));
+    if (terminalIds.length === 1) allowedCardByWindow.set(windowId, terminalIds[0]);
+    else if (ids.size === 1) allowedCardByWindow.set(windowId, [...ids][0]);
+  }
+
+  /** @type {Map<string, Array<{session: Record<string, unknown>; window: Record<string, unknown>}>>} */
+  const groups = new Map();
   for (const candidate of candidates) {
-    windowCounts.set(candidate.window.id, (windowCounts.get(candidate.window.id) ?? 0) + 1);
+    if (allowedCardByWindow.get(candidate.window.id) !== candidate.cardId) continue;
+    const group = groups.get(candidate.cardId) ?? [];
+    group.push(candidate);
+    groups.set(candidate.cardId, group);
   }
-  const projectedSessions = candidates
-    .filter((candidate) => windowCounts.get(candidate.window.id) === 1)
-    .map((candidate) => candidate.session);
+
+  const projectedSessions = [];
+  for (const [cardId, group] of groups) {
+    const windowIds = new Set(group.map((candidate) => candidate.window.id));
+    if (windowIds.size !== 1) continue;
+    const [card] = projectSessionCards(group.map((candidate) => candidate.session));
+    if (!card) continue;
+    const window = group[0]?.window;
+    projectedSessions.push({ ...card, cardId, windowId: window?.id });
+  }
+  const focusedCard = projectedSessions.find((session) =>
+    windows.some((window) => window?.id === session.windowId && window?.is_focused === true),
+  );
   return {
     workspace,
     sessions: projectedSessions,
-    focusedSessionId: resolveFocusedSnapshotSessionId(windows, projectedSessions, options),
+    focusedSessionId: focusedCard ? String(focusedCard.sessionId ?? "") || null : null,
+    focusedCardId: focusedCard ? String(focusedCard.cardId ?? "") || null : null,
   };
 }
 
@@ -216,65 +274,6 @@ export function resolveFocusedNiriWorkspace(workspaces) {
   return matches.length === 1 ? matches[0] : null;
 }
 
-/**
- * @param {Array<Record<string, unknown>>} windows
- * @param {number | null} [workspaceId]
- */
-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;
-}
-
-/**
- * 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]
- */
-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.",
-    };
-  }
-}
-
 /**
  * @param {string | Record<string, unknown>} session
  * @param {(file: string, args: string[], options: object) => Promise<{stdout?: string}>} execFileAsync
@@ -304,7 +303,8 @@ export async function focusNiriSession(session, execFileAsync, env = process.env
   if (!Array.isArray(windows)) {
     return { ok: false, error: "Unexpected Niri window data; focus did nothing." };
   }
-  const target = resolveExactGhosttyWindow(windows, sessionId);
+  const record = session && typeof session === "object" ? session : {};
+  const target = resolveExactGhosttyWindow(windows, sessionId, record);
   if (!target) {
     return {
       ok: false,

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,36 +39,55 @@ 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 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 ?? ""),
+    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,
+    lastEventAt,
     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,102 @@
+// ---
+// 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[]}>}
+ */
+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[]}>} */
+  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),
+    });
+  }
+  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])
+  );
+}