@tryinget/pi-activity-strip 0.4.0 → 0.6.0

package/src/common/ak-tasks.mjs

@@ -0,0 +1,354 @@
+// ---
+// summary: "parses read-only AK task output and joins live session-bound claims onto terminal cards"
+// read_when:
+//   - "changing AK claim parsing, lease/vacant-custody rules, or task chip join semantics"
+// ---
+
+/**
+ * AK is a read-only projection for the strip: these helpers only parse CLI output and derive
+ * display facts. They never write, never touch the society database directly, and fail closed
+ * (malformed input yields no chips rather than invented state).
+ */
+
+/** Chip states rendered by the native panel. */
+export const AK_TASK_CHIP_ACTIVE = "active";
+export const AK_TASK_CHIP_DEFERRED = "deferred";
+export const AK_TASK_CHIP_ORPHANED = "orphaned";
+
+/** AK5700 claim semantics: only `session-<uuid>` claims can belong to a live Pi terminal. */
+const SESSION_CLAIM_PATTERN =
+  /^session-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
+/** Bound the title carried into the panel protocol. */
+const MAX_TITLE_LENGTH = 96;
+/** A card shows at most two live-claim buttons and two state badges; the rest fold into overflow. */
+const MAX_ACTIVE_CHIPS = 2;
+const MAX_BADGE_CHIPS = 2;
+
+/**
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+function isString(value) {
+  return typeof value === "string";
+}
+
+/**
+ * AK timestamps are RFC 3339 with offset. Unparseable or non-positive values are rejected so an
+ * unprovable lease can never be presented as live custody.
+ * @param {unknown} value
+ * @returns {number | null}
+ */
+export function parseAkTimestampMs(value) {
+  if (!isString(value) || !value.trim()) return null;
+  const parsed = Date.parse(value.trim());
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number | null} positive safe integer task id, or null
+ */
+function parseTaskId(value) {
+  const id = Number(value);
+  return Number.isSafeInteger(id) && id > 0 ? id : null;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string} bounded title
+ */
+function boundTitle(value) {
+  return isString(value) ? value.trim().slice(0, MAX_TITLE_LENGTH) : "";
+}
+
+/**
+ * Normalize a repo path for prefix matching. Only absolute paths can join; anything else would
+ * invent a relationship between a card and a task.
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+function normalizeRepoPath(value) {
+  if (!isString(value)) return null;
+  const trimmed = value.trim().replace(/\/+$/, "");
+  return trimmed.startsWith("/") ? trimmed : null;
+}
+
+/**
+ * True when a session working directory sits inside the task's registered repo.
+ * @param {unknown} cardCwd
+ * @param {string} taskRepo
+ */
+export function cwdIsInsideRepo(cardCwd, taskRepo) {
+  if (!isString(cardCwd)) return false;
+  const cwd = cardCwd.trim().replace(/\/+$/, "");
+  return cwd.length > 0 && (cwd === taskRepo || cwd.startsWith(`${taskRepo}/`));
+}
+
+/**
+ * Parse `ak task list --format json --verbose` output into raw claim rows. Rows without a
+ * session-bound claim or a parseable lease are skipped; anything malformed at the envelope level
+ * fails the whole parse so callers can drop chips entirely.
+ * @param {string} raw
+ * @returns {{ok: true; claims: import("./contracts.ts").AkTaskClaim[]} | {ok: false; error: string}}
+ */
+export function parseAkClaimList(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(raw ?? ""));
+  } catch (error) {
+    return {
+      ok: false,
+      error: `AK task list is not JSON: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  if (!Array.isArray(parsed)) {
+    return { ok: false, error: "AK task list did not return a JSON array." };
+  }
+  /** @type {import("./contracts.ts").AkTaskClaim[]} */
+  const claims = [];
+  for (const entry of parsed) {
+    if (!entry || typeof entry !== "object") continue;
+    const record = /** @type {Record<string, unknown>} */ (entry);
+    const id = parseTaskId(record.id);
+    const claimedBy = isString(record.claimed_by) ? record.claimed_by.trim() : "";
+    const match = SESSION_CLAIM_PATTERN.exec(claimedBy);
+    const leaseExpiresAt = parseAkTimestampMs(record.lease_expires_at);
+    const claimedAt = parseAkTimestampMs(record.claimed_at);
+    const repo = normalizeRepoPath(record.repo);
+    const title = boundTitle(record.title);
+    if (id === null || !match || leaseExpiresAt === null || !repo || !title) continue;
+    if (record.status !== "claimed") continue;
+    claims.push({
+      id,
+      title,
+      repo,
+      sessionId: match[1].toLowerCase(),
+      leaseExpiresAt,
+      claimedAt: claimedAt ?? 0,
+    });
+  }
+  return { ok: true, claims };
+}
+
+/**
+ * Parse `ak task deferred --format json` output. Only rows whose deferral is still active join.
+ * @param {string} raw
+ * @returns {{ok: true; deferred: import("./contracts.ts").AkTaskDeferred[]} | {ok: false; error: string}}
+ */
+export function parseAkDeferredList(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(raw ?? ""));
+  } catch (error) {
+    return {
+      ok: false,
+      error: `AK deferred list is not JSON: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  if (!Array.isArray(parsed)) {
+    return { ok: false, error: "AK deferred list did not return a JSON array." };
+  }
+  /** @type {import("./contracts.ts").AkTaskDeferred[]} */
+  const deferred = [];
+  for (const entry of parsed) {
+    if (!entry || typeof entry !== "object") continue;
+    const record = /** @type {Record<string, unknown>} */ (entry);
+    const task = record.task;
+    const deferral = record.deferral;
+    if (!task || typeof task !== "object" || !deferral || typeof deferral !== "object") continue;
+    const taskRecord = /** @type {Record<string, unknown>} */ (task);
+    const deferralRecord = /** @type {Record<string, unknown>} */ (deferral);
+    const id = parseTaskId(taskRecord.id);
+    const repo = normalizeRepoPath(taskRecord.repo);
+    const title = boundTitle(taskRecord.title);
+    if (id === null || !repo || !title) continue;
+    if (deferralRecord.state !== "active") continue;
+    deferred.push({ id, title, repo });
+  }
+  return { ok: true, deferred };
+}
+
+/**
+ * AK5700: an expired lease is vacant custody, so the claim no longer names an active owner.
+ * @param {{leaseExpiresAt: number}} claim
+ * @param {number} nowMs
+ */
+export function claimIsLive(claim, nowMs) {
+  return claim.leaseExpiresAt > nowMs;
+}
+
+/**
+ * Cards whose session holds a live claim get clickable task references. A claim is ambiguous when
+ * the claiming session id backs more than one card (one logical session resumed into two
+ * terminals); ambiguous claims bind nothing. A task that also carries an active deferral never
+ * becomes a button: the deferred badge state wins.
+ * @param {Array<Record<string, unknown>>} cards
+ * @param {import("./contracts.ts").AkTaskClaim[]} claims
+ * @param {Set<number>} deferredIds
+ * @param {number} nowMs
+ * @returns {Map<string, import("./contracts.ts").AkTaskClaim[]>} active claims per cardId
+ */
+function activeClaimsByCardId(cards, claims, deferredIds, nowMs) {
+  /** @type {Map<string, Set<string>>} */
+  const sessionIdToCardIds = new Map();
+  for (const card of cards) {
+    const cardId = String(card.cardId ?? "");
+    for (const sessionId of cardSessionIds(card)) {
+      const cardIds = sessionIdToCardIds.get(sessionId) ?? new Set();
+      cardIds.add(cardId);
+      sessionIdToCardIds.set(sessionId, cardIds);
+    }
+  }
+  /** @type {Map<string, import("./contracts.ts").AkTaskClaim[]>} */
+  const byCardId = new Map();
+  for (const card of cards) {
+    const cardId = String(card.cardId ?? "");
+    byCardId.set(
+      cardId,
+      claims
+        .filter((claim) => claimIsLive(claim, nowMs))
+        .filter((claim) => !deferredIds.has(claim.id))
+        .filter((claim) => {
+          const cardIds = sessionIdToCardIds.get(claim.sessionId);
+          return cardIds?.size === 1 && cardIds.has(cardId);
+        })
+        .sort(compareClaimsNewestFirst),
+    );
+  }
+  return byCardId;
+}
+
+/**
+ * @param {Record<string, unknown>} card
+ * @returns {string[]}
+ */
+function cardSessionIds(card) {
+  const ids = Array.isArray(card.publisherSessionIds) ? card.publisherSessionIds : [];
+  return [...new Set(ids.map((value) => String(value ?? "").trim()).filter(Boolean))];
+}
+
+/** @param {import("./contracts.ts").AkTaskClaim} left @param {import("./contracts.ts").AkTaskClaim} right */
+function compareClaimsNewestFirst(left, right) {
+  if (left.claimedAt !== right.claimedAt) return right.claimedAt - left.claimedAt;
+  if (left.leaseExpiresAt !== right.leaseExpiresAt)
+    return right.leaseExpiresAt - left.leaseExpiresAt;
+  return left.id - right.id;
+}
+
+/** @param {import("./contracts.ts").AkTaskClaim} left @param {import("./contracts.ts").AkTaskClaim} right */
+function compareOrphansSoonestVacantFirst(left, right) {
+  if (left.leaseExpiresAt !== right.leaseExpiresAt)
+    return left.leaseExpiresAt - right.leaseExpiresAt;
+  return left.id - right.id;
+}
+
+/**
+ * Join AK task references onto projected cards.
+ *
+ * - `active` chips: the card's own session holds a live claim (exact session-id join, unique).
+ * - `orphaned` badges: a live-lease claim by a session with no live card, joined by repo. Custody
+ *   has not lapsed yet, but the owner is gone, so the fact is a badge rather than a button.
+ * - `deferred` badges: tasks with an active deferral, joined by repo.
+ *
+ * @param {{
+ *   cards: Array<Record<string, unknown>>;
+ *   claims?: import("./contracts.ts").AkTaskClaim[];
+ *   deferred?: import("./contracts.ts").AkTaskDeferred[];
+ *   liveSessionIds?: Set<string> | string[];
+ *   nowMs: number;
+ * }} options
+ * @returns {{cards: Array<Record<string, unknown>>; orphanedClaimCount: number; renderedCounts: {active: number; orphaned: number; deferred: number}}}
+ */
+export function joinAkTaskChips({
+  cards,
+  claims = [],
+  deferred = [],
+  liveSessionIds = new Set(),
+  nowMs,
+}) {
+  const liveIds =
+    liveSessionIds instanceof Set ? liveSessionIds : new Set([...liveSessionIds].map(String));
+  const deferredIds = new Set(deferred.map((task) => task.id));
+  const byCardId = activeClaimsByCardId(cards, claims, deferredIds, nowMs);
+
+  const liveClaims = claims.filter((claim) => claimIsLive(claim, nowMs));
+  const orphanedClaims = liveClaims.filter((claim) => !liveIds.has(claim.sessionId));
+  const orphanedIds = new Set(orphanedClaims.map((claim) => claim.id));
+
+  /** @type {number} */
+  let renderedActive = 0;
+  /** @type {number} */
+  let renderedOrphaned = 0;
+  /** @type {number} */
+  let renderedDeferred = 0;
+
+  const joined = cards.map((card) => {
+    const cardActive = byCardId.get(String(card.cardId ?? "")) ?? [];
+    const active = cardActive.slice(0, MAX_ACTIVE_CHIPS);
+    const activeOverflow = Math.max(0, cardActive.length - active.length);
+    const activeIds = new Set(cardActive.map((claim) => claim.id));
+    const cwd = String(card.cwd ?? "");
+
+    const orphaned = orphanedClaims
+      .filter((claim) => cwdIsInsideRepo(cwd, claim.repo))
+      .sort(compareOrphansSoonestVacantFirst);
+    const deferredForCard = deferred
+      .filter((task) => cwdIsInsideRepo(cwd, task.repo) && !orphanedIds.has(task.id))
+      .filter((task) => !activeIds.has(task.id))
+      .sort((left, right) => left.id - right.id);
+    const badges = [...orphaned, ...deferredForCard].slice(0, MAX_BADGE_CHIPS);
+    const badgeOverflow = Math.max(0, orphaned.length + deferredForCard.length - badges.length);
+
+    const chips = [
+      ...active.map((claim) => ({ id: claim.id, title: claim.title, state: AK_TASK_CHIP_ACTIVE })),
+      ...badges.map((task) => ({
+        id: task.id,
+        title: task.title,
+        state: orphanedIds.has(task.id) ? AK_TASK_CHIP_ORPHANED : AK_TASK_CHIP_DEFERRED,
+      })),
+    ];
+    renderedActive += active.length;
+    renderedOrphaned += badges.filter((task) => orphanedIds.has(task.id)).length;
+    renderedDeferred += badges.filter((task) => !orphanedIds.has(task.id)).length;
+
+    const next = { ...card };
+    if (chips.length > 0) next.akTasks = chips;
+    if (activeOverflow + badgeOverflow > 0) next.akTaskOverflow = activeOverflow + badgeOverflow;
+    return next;
+  });
+
+  return {
+    cards: joined,
+    orphanedClaimCount: orphanedClaims.length,
+    renderedCounts: {
+      active: renderedActive,
+      orphaned: renderedOrphaned,
+      deferred: renderedDeferred,
+    },
+  };
+}
+
+/**
+ * Convenience summary for the status surface.
+ * @param {{
+ *   claims?: import("./contracts.ts").AkTaskClaim[];
+ *   deferred?: import("./contracts.ts").AkTaskDeferred[];
+ *   liveSessionIds?: Set<string> | string[];
+ *   nowMs: number;
+ * }} options
+ */
+export function summarizeAkTasks({
+  claims = [],
+  deferred = [],
+  liveSessionIds = new Set(),
+  nowMs,
+}) {
+  const liveIds =
+    liveSessionIds instanceof Set ? liveSessionIds : new Set([...liveSessionIds].map(String));
+  const liveClaims = claims.filter((claim) => claimIsLive(claim, nowMs));
+  return {
+    liveClaimCount: liveClaims.length,
+    orphanedClaimCount: liveClaims.filter((claim) => !liveIds.has(claim.sessionId)).length,
+    deferredCount: deferred.length,
+  };
+}

package/src/common/alignment-controller.mjs

@@ -1,35 +1,9 @@
 // ---
-// summary: "coalesces native-window alignment so stale async work cannot overwrite newer geometry"
+// summary: "coalesces asynchronous reconciliation so stale work cannot publish over newer state"
 // read_when:
-//   - "changing Electron/Niri geometry reconciliation or testing rapid expansion transitions"
+//   - "changing latest-only native workspace reconciliation"
 // ---
 
-/**
- * @param {{ is_floating?: boolean, layout?: { tile_pos_in_workspace_view?: unknown } } | null | undefined} window
- */
-export function hasNiriFloatingPosition(window) {
-  const position = window?.layout?.tile_pos_in_workspace_view;
-  return window?.is_floating === true && Array.isArray(position) && position.length >= 2;
-}
-
-/**
- * @param {{ is_floating?: boolean, layout?: { tile_pos_in_workspace_view?: unknown, window_size?: unknown } } | null | undefined} window
- * @param {{x: number, y: number, width: number, height: number}} target
- */
-export function isNiriWindowAligned(window, target) {
-  if (!hasNiriFloatingPosition(window)) return false;
-  const position = window?.layout?.tile_pos_in_workspace_view;
-  const size = window?.layout?.window_size;
-  return Boolean(
-    Array.isArray(position) &&
-      Array.isArray(size) &&
-      Number(size[0]) === target.width &&
-      Number(size[1]) === target.height &&
-      Math.abs(Number(position[0]) - target.x) < 1 &&
-      Math.abs(Number(position[1]) - target.y) < 1,
-  );
-}
-
 /**
  * @param {(attempt: { generation: number, isCurrent: () => boolean }) => Promise<void>} run
  */
@@ -37,34 +11,42 @@ export function createLatestOnlyRunner(run) {
   if (typeof run !== "function") throw new TypeError("run must be a function");
 
   let requestedGeneration = 0;
+  let completedGeneration = 0;
   /** @type {Promise<void> | null} */
   let worker = null;
 
+  function ensureWorker() {
+    if (!worker) worker = drain();
+  }
+
   async function drain() {
-    while (true) {
-      const generation = requestedGeneration;
-      const isCurrent = () => generation === requestedGeneration;
-      try {
-        await run({ generation, isCurrent });
-      } catch {
-        // Alignment is best effort. A newer request must still be allowed to reconcile the window.
+    try {
+      while (completedGeneration < requestedGeneration) {
+        const generation = requestedGeneration;
+        const isCurrent = () => generation === requestedGeneration;
+        try {
+          await run({ generation, isCurrent });
+        } catch {
+          // Alignment is best effort. A newer request must still be allowed to reconcile the window.
+        }
+        completedGeneration = generation;
       }
-      if (isCurrent()) return;
+    } finally {
+      worker = null;
+      // A request can arrive after the loop condition was checked but before this finally block.
+      // Hand it to a successor synchronously so no requested generation is lost.
+      if (completedGeneration < requestedGeneration) ensureWorker();
     }
   }
 
   function request() {
     requestedGeneration += 1;
-    if (!worker) {
-      worker = drain().finally(() => {
-        worker = null;
-      });
-    }
+    ensureWorker();
     return requestedGeneration;
   }
 
   async function waitForIdle() {
-    await worker;
+    while (worker) await worker;
   }
 
   return {

package/src/common/card-display.mjs

@@ -46,3 +46,8 @@ export function disambiguatedRepoLabel(session, duplicateLabels) {
     ? `${label} · ${String(processId).slice(-4)}`
     : label;
 }
+
+/** @param {{hovered?: boolean; activeElement?: boolean; documentFocused?: boolean}} state */
+export function shouldRetainExpandedCard({ hovered, activeElement, documentFocused }) {
+  return Boolean(hovered || (documentFocused && activeElement));
+}

package/src/common/claude-events.mjs

@@ -0,0 +1,190 @@
+// ---
+// summary: "maps Claude Code hook payloads to activity-strip state and stores one record per session"
+// read_when:
+//   - "changing Claude Code hook events, their state mapping, or the event record on disk"
+// ---
+
+import fs from "node:fs";
+import path from "node:path";
+import { ACTIVITY_STRIP_SOCKET_DIR } from "./constants.mjs";
+
+export const CLAUDE_EVENT_SCHEMA = "pi-activity-strip-claude-event.v1";
+export const CLAUDE_EVENT_DIR = path.join(ACTIVITY_STRIP_SOCKET_DIR, "claude-events");
+/** Hook events older than this are ignored; the transcript remains the fallback. */
+export const CLAUDE_EVENT_MAX_AGE_MS = 6 * 60 * 60_000;
+/**
+ * A session that dies without firing `SessionEnd` leaves its record behind. Such a record can never
+ * produce a card, because a card needs a live process, but the files would accumulate forever. They
+ * are retired once no live session claims them and they have stopped being recent, so a session
+ * that publishes before the scan first sees it is never swept away mid-startup.
+ */
+export const CLAUDE_EVENT_ORPHAN_GRACE_MS = 10 * 60_000;
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DETAIL_LIMIT = 100;
+
+/** @typedef {"idle" | "thinking" | "tool" | "waiting" | "error"} ClaudeEventState */
+
+/** @param {unknown} value */
+function preview(value) {
+  const text = String(value ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return text.length > DETAIL_LIMIT ? `${text.slice(0, DETAIL_LIMIT - 1)}…` : text;
+}
+
+/** @param {unknown} sessionId */
+export function claudeEventPath(sessionId, directory = CLAUDE_EVENT_DIR) {
+  const normalized = String(sessionId ?? "")
+    .trim()
+    .toLowerCase();
+  return SESSION_ID.test(normalized) ? path.join(directory, `${normalized}.json`) : "";
+}
+
+/**
+ * Name what a tool call is acting on, preferring fields that read well on a card.
+ * @param {Record<string, unknown>} toolInput
+ */
+export function describeHookToolTarget(toolInput) {
+  for (const key of ["description", "command", "file_path", "path", "pattern", "query", "url"]) {
+    const value = /** @type {any} */ (toolInput ?? {})[key];
+    if (typeof value === "string" && value.trim()) return preview(value);
+  }
+  return "";
+}
+
+/**
+ * Translate one hook payload into the record the ribbon stores. `null` means the event carries no
+ * usable identity and must be dropped rather than guessed.
+ * @param {Record<string, unknown>} payload
+ * @param {{now?: number; env?: NodeJS.ProcessEnv}} [options]
+ */
+export function claudeEventRecord(payload, { now = Date.now(), env = process.env } = {}) {
+  const sessionId = String(payload?.session_id ?? "")
+    .trim()
+    .toLowerCase();
+  if (!SESSION_ID.test(sessionId)) return null;
+  const event = String(payload?.hook_event_name ?? "").trim();
+  if (!event) return null;
+
+  const toolName = String(payload?.tool_name ?? "").trim();
+  const toolInput = /** @type {Record<string, unknown>} */ (payload?.tool_input ?? {});
+  const notification = String(payload?.notification_type ?? "").trim();
+
+  /** @type {ClaudeEventState} */
+  let state = "thinking";
+  let detail = "";
+  if (event === "PreToolUse") {
+    state = "tool";
+    detail = describeHookToolTarget(toolInput);
+  } else if (event === "PostToolUseFailure") {
+    state = "error";
+    detail = `${toolName || "tool"} failed`;
+  } else if (event === "PostToolUse") {
+    state = "thinking";
+  } else if (event === "Notification") {
+    state = "waiting";
+    detail =
+      notification === "permission_prompt"
+        ? "waiting for approval"
+        : notification === "idle_prompt" || notification === "agent_needs_input"
+          ? "waiting for input"
+          : preview(notification) || "waiting";
+  } else if (event === "Stop" || event === "SubagentStop") {
+    state = "idle";
+    detail = preview(payload?.last_assistant_message);
+  } else if (event === "UserPromptSubmit") {
+    state = "thinking";
+  } else if (event === "SessionStart") {
+    state = "idle";
+  } else if (event === "SessionEnd") {
+    state = "idle";
+  }
+
+  return {
+    schema: CLAUDE_EVENT_SCHEMA,
+    sessionId,
+    event,
+    state,
+    toolName: state === "tool" || state === "error" ? toolName : "",
+    toolTarget: state === "tool" ? detail : "",
+    detail,
+    notificationType: notification,
+    cwd: String(payload?.cwd ?? ""),
+    transcriptPath: String(payload?.transcript_path ?? ""),
+    surfaceId: String(env.GHOSTTY_SURFACE_ID ?? ""),
+    processId: Number(env.PI_ACTIVITY_STRIP_HOOK_PID ?? 0) || 0,
+    at: now,
+  };
+}
+
+/**
+ * `SessionEnd` retires a session, so its record is removed rather than left behind.
+ * @param {{event?: unknown} | null} record
+ */
+export function isSessionEndEvent(record) {
+  return record?.event === "SessionEnd";
+}
+
+/**
+ * Fold a stored hook record into transcript telemetry. The newer of the two wins, so a live hook
+ * event overrides a stale transcript read and a transcript that moved after the last hook still
+ * shows current work.
+ * @param {import("./claude-transcript.mjs").ClaudeTelemetry} telemetry
+ * @param {ReturnType<typeof claudeEventRecord>} record
+ * @param {number} [now]
+ */
+export function mergeClaudeEvent(telemetry, record, now = Date.now()) {
+  if (!record || record.schema !== CLAUDE_EVENT_SCHEMA) return telemetry;
+  const at = Number(record.at ?? 0);
+  if (!Number.isFinite(at) || at <= 0 || now - at > CLAUDE_EVENT_MAX_AGE_MS) return telemetry;
+  if (at <= Number(telemetry?.lastEventAt ?? 0)) return telemetry;
+  return {
+    ...telemetry,
+    state: /** @type {any} */ (record.state),
+    toolName: String(record.toolName ?? ""),
+    toolTarget: String(record.toolTarget ?? ""),
+    assistantPreview: record.detail || telemetry.assistantPreview,
+    lastEventAt: at,
+  };
+}
+
+/**
+ * Remove hook records that no live session claims. Returns the retired session ids.
+ * @param {Iterable<string>} activeSessionIds
+ * @param {{fs?: Pick<typeof fs, "readdirSync" | "readFileSync" | "unlinkSync">; directory?: string; now?: number}} [options]
+ */
+export function pruneClaudeEventRecords(
+  activeSessionIds,
+  { fs: fsImpl = fs, directory = CLAUDE_EVENT_DIR, now = Date.now() } = {},
+) {
+  const active = new Set(activeSessionIds ?? []);
+  /** @type {string[]} */
+  const retired = [];
+  let entries;
+  try {
+    entries = fsImpl.readdirSync(directory);
+  } catch {
+    return retired;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    const sessionId = entry.slice(0, -".json".length);
+    if (active.has(sessionId)) continue;
+    let publishedAt = 0;
+    try {
+      publishedAt = Number(
+        JSON.parse(String(fsImpl.readFileSync(path.join(directory, entry), "utf8"))).at ?? 0,
+      );
+    } catch {
+      publishedAt = 0;
+    }
+    if (publishedAt > 0 && now - publishedAt < CLAUDE_EVENT_ORPHAN_GRACE_MS) continue;
+    try {
+      fsImpl.unlinkSync(path.join(directory, entry));
+      retired.push(sessionId);
+    } catch {
+      // Another writer removed it first.
+    }
+  }
+  return retired;
+}