@tryinget/pi-activity-strip 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryinget/pi-activity-strip",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "pi extension package for activity-strip workflows in monorepo runtime",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -26,6 +26,12 @@
   "engines": {
     "node": ">=22.19.0"
   },
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
   "scripts": {
     "fix": "bash ./scripts/quality-gate.sh fix",
     "lint": "bash ./scripts/quality-gate.sh lint",
@@ -40,6 +46,8 @@
     "docs:list:json": "node ~/ai-society/core/agent-scripts/scripts/docs-list.mjs --json",
     "release:check": "bash ./scripts/release-check.sh",
     "release:check:quick": "SKIP_PI_SMOKE=1 bash ./scripts/release-check.sh",
+    "native:check": "cd native/panel && RUSTUP_TOOLCHAIN=stable cargo fmt --check && RUSTUP_TOOLCHAIN=stable cargo test",
+    "native:build": "bash ./scripts/build-native-panel.sh",
     "strip:open": "node ./bin/pi-activity-strip.mjs open",
     "strip:status": "node ./bin/pi-activity-strip.mjs status",
     "strip:doctor": "node ./bin/pi-activity-strip.mjs doctor",
@@ -56,6 +64,10 @@
     "extensions/activity-strip.js",
     "extensions/activity-strip.ts",
     "src",
+    "native/bin",
+    "native/panel/Cargo.toml",
+    "native/panel/Cargo.lock",
+    "native/panel/src",
     "prompts",
     "examples",
     "policy/security-policy.json"
@@ -76,9 +88,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.4",
-    "@earendil-works/pi-agent-core": "0.84.3",
-    "@earendil-works/pi-ai": "0.84.3",
-    "@earendil-works/pi-coding-agent": "0.84.3",
+    "@earendil-works/pi-agent-core": "0.84.4",
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
     "@types/node": "22.14.0",
     "@typescript/native-preview": "7.0.0-dev.20260417.1",
     "typebox": "1.3.7",

package/src/broker/server.mjs

@@ -10,6 +10,8 @@ import net from "node:net";
 /** @typedef {import("../common/contracts.ts").ActivityStripBrokerOptions} ActivityStripBrokerOptions */
 import {
   ACTIVITY_STRIP_BROADCAST_TICK_MS,
+  ACTIVITY_STRIP_CLIENT_IDLE_TIMEOUT_MS,
+  ACTIVITY_STRIP_MAX_MESSAGE_BYTES,
   ACTIVITY_STRIP_SOCKET_DIR,
   ACTIVITY_STRIP_SOCKET_PATH,
 } from "../common/constants.mjs";
@@ -49,6 +51,8 @@ export class ActivityStripBroker extends EventEmitter {
     this.getRuntimeStatus = options.getRuntimeStatus ?? (() => undefined);
     this.focusSession =
       options.focusSession ?? (async () => ({ ok: false, error: "Focus unavailable" }));
+    this.focusStrip =
+      options.focusStrip ?? (async () => ({ ok: false, error: "Strip focus unavailable" }));
     this.server = net.createServer((socket) => this.handleConnection(socket));
     this.tick = null;
   }
@@ -98,12 +102,18 @@ export class ActivityStripBroker extends EventEmitter {
   handleConnection(socket) {
     let buffer = "";
     socket.setEncoding("utf8");
+    socket.setTimeout?.(ACTIVITY_STRIP_CLIENT_IDLE_TIMEOUT_MS, () => socket.destroy());
     socket.on("error", (error) => {
       if (!isExpectedClientDisconnect(error)) this.emit("client-error", error);
     });
 
     socket.on("data", (chunk) => {
       buffer += chunk;
+      if (Buffer.byteLength(buffer, "utf8") > ACTIVITY_STRIP_MAX_MESSAGE_BYTES) {
+        this.reply(socket, { ok: false, error: "Activity strip broker message is too large." });
+        socket.destroy();
+        return;
+      }
       let newlineIndex = buffer.indexOf("\n");
       while (newlineIndex >= 0) {
         const line = buffer.slice(0, newlineIndex);
@@ -139,26 +149,52 @@ export class ActivityStripBroker extends EventEmitter {
         });
         return;
       case "focus":
-        Promise.resolve(this.focusSession(String(message.sessionId ?? "")))
+        Promise.resolve(this.focusSession(String(message.cardId ?? message.sessionId ?? "")))
           .then((result) => this.reply(socket, { type: "focus", ...result }))
           .catch(() =>
             this.reply(socket, { ok: false, type: "focus", error: "Focus failed closed." }),
           );
         return;
+      case "focus-strip":
+        Promise.resolve(this.focusStrip())
+          .then((result) => this.reply(socket, { type: "focus-strip", ...result }))
+          .catch(() =>
+            this.reply(socket, {
+              ok: false,
+              type: "focus-strip",
+              error: "Strip focus failed closed.",
+            }),
+          );
+        return;
       case "shutdown":
         this.reply(socket, { ok: true, type: "shutdown" });
         setTimeout(() => {
           this.emit("shutdown-requested");
         }, 20);
         return;
-      case "remove":
-        this.store.remove(String(message.sessionId ?? ""), String(message.publisherId ?? ""));
-        this.emitSnapshot();
+      case "remove": {
+        const accepted = this.store.remove(
+          String(message.sessionId ?? ""),
+          String(message.publisherId ?? ""),
+        );
+        if (accepted) this.emitSnapshot();
+        this.reply(socket, {
+          ok: accepted,
+          type: "remove",
+          ...(accepted ? {} : { error: "Activity strip broker rejected remove." }),
+        });
         return;
-      case "upsert":
-        this.store.upsert(message.session);
-        this.emitSnapshot();
+      }
+      case "upsert": {
+        const accepted = this.store.upsert(message.session);
+        if (accepted) this.emitSnapshot();
+        this.reply(socket, {
+          ok: accepted,
+          type: "upsert",
+          ...(accepted ? {} : { error: "Activity strip broker rejected upsert." }),
+        });
         return;
+      }
       default:
         this.reply(socket, { ok: false, error: `Unsupported message type: ${message.type}` });
     }

package/src/broker/session-store.mjs

@@ -4,7 +4,10 @@
 //   - "changing session retention, upsert semantics, or broker snapshot ordering"
 // ---
 
-import { ACTIVITY_STRIP_STALE_AFTER_MS } from "../common/constants.mjs";
+import {
+  ACTIVITY_STRIP_MAX_SESSIONS,
+  ACTIVITY_STRIP_STALE_AFTER_MS,
+} from "../common/constants.mjs";
 import { normalizeSessionSnapshot, sortSessions } from "../common/protocol.mjs";
 
 /** @typedef {import("../common/contracts.ts").SessionSnapshot} SessionSnapshot */
@@ -25,36 +28,61 @@ export class SessionStore {
   /** @param {SessionStoreOptions} [options] */
   constructor(options = {}) {
     this.staleAfterMs = options.staleAfterMs ?? ACTIVITY_STRIP_STALE_AFTER_MS;
-    /** @type {Map<string, SessionSnapshot>} */
+    this.maxSessions = options.maxSessions ?? ACTIVITY_STRIP_MAX_SESSIONS;
+    /** @type {Map<string, {session: SessionSnapshot; receivedAt: number}>} */
     this.sessions = new Map();
+    /** @type {Map<string, number>} */
+    this.tombstones = new Map();
   }
 
-  /** @param {Partial<SessionSnapshot> | Record<string, unknown>} session */
-  upsert(session) {
+  /** @param {Partial<SessionSnapshot> | Record<string, unknown>} session @param {number} [receivedAt] */
+  upsert(session, receivedAt = Date.now()) {
+    if (!session || typeof session !== "object") return false;
+    this.purge(receivedAt);
     const normalized = normalizeSessionSnapshot(session);
     if (!normalized.sessionId) return false;
-    this.sessions.set(sessionKey(normalized), normalized);
+    const key = sessionKey(normalized);
+    if (this.tombstones.has(key)) return false;
+    const current = this.sessions.get(key);
+    if (
+      current &&
+      current.session.publisherSequence > 0 &&
+      (normalized.publisherSequence === 0 ||
+        normalized.publisherSequence <= current.session.publisherSequence)
+    ) {
+      return false;
+    }
+    if (!current && this.sessions.size >= this.maxSessions) return false;
+    this.sessions.set(key, { session: normalized, receivedAt });
     return true;
   }
 
-  /** @param {string} sessionId @param {string} [publisherId] */
-  remove(sessionId, publisherId) {
+  /** @param {string} sessionId @param {string} [publisherId] @param {number} [removedAt] */
+  remove(sessionId, publisherId, removedAt = Date.now()) {
     const id = String(sessionId ?? "");
     if (!id) return false;
-    return publisherId
-      ? this.sessions.delete(`${id}|${String(publisherId)}`)
-      : this.sessions.delete(id);
+    if (!publisherId) return this.sessions.delete(id);
+    const key = `${id}|${String(publisherId)}`;
+    this.purge(removedAt);
+    if (!this.sessions.has(key)) return false;
+    if (!this.tombstones.has(key) && this.tombstones.size >= this.maxSessions) return false;
+    this.sessions.delete(key);
+    this.tombstones.set(key, removedAt);
+    return true;
   }
 
   /** @param {number} [now] */
   purge(now = Date.now()) {
     let changed = false;
-    for (const [sessionId, session] of this.sessions.entries()) {
-      if (now - session.updatedAt > this.staleAfterMs) {
+    for (const [sessionId, entry] of this.sessions.entries()) {
+      if (now - entry.receivedAt > this.staleAfterMs) {
         this.sessions.delete(sessionId);
         changed = true;
       }
     }
+    for (const [sessionId, removedAt] of this.tombstones.entries()) {
+      if (now - removedAt > this.staleAfterMs) this.tombstones.delete(sessionId);
+    }
     return changed;
   }
 
@@ -63,7 +91,7 @@ export class SessionStore {
     this.purge(now);
     return {
       generatedAt: now,
-      sessions: sortSessions([...this.sessions.values()]),
+      sessions: sortSessions([...this.sessions.values()].map((entry) => entry.session)),
     };
   }
 }

package/src/client/broker-client.mjs

@@ -112,7 +112,12 @@ export async function requestBrokerShutdown(options = {}) {
 
 /** @param {SessionSnapshot} session @param {BrokerClientOptions} [options] */
 export async function publishSessionSnapshot(session, options = {}) {
-  await sendBrokerMessage(makeMessage("upsert", { session }), options);
+  const result = await sendBrokerMessage(makeMessage("upsert", { session }), {
+    ...options,
+    expectReply: true,
+  });
+  if (result?.ok !== true)
+    throw new Error(result?.error || "Activity strip broker rejected upsert.");
 }
 
 /** @param {{ sessionId: string; publisherId: string }} session @param {BrokerClientOptions} [options] */
@@ -125,11 +130,13 @@ export async function removeSession(session, options = {}) {
   } else {
     fallbackId = String(session ?? "");
   }
-  await sendBrokerMessage(
+  const result = await sendBrokerMessage(
     makeMessage("remove", {
       sessionId: String(record.sessionId ?? fallbackId),
       publisherId: String(record.publisherId ?? ""),
     }),
-    options,
+    { ...options, expectReply: true },
   );
+  if (result?.ok !== true)
+    throw new Error(result?.error || "Activity strip broker rejected remove.");
 }

package/src/client/session-telemetry.mjs

@@ -30,6 +30,7 @@ import {
   extractToolResultText,
   summarizeToolResult,
 } from "../common/telemetry.mjs";
+import { resolveTerminalIdentity as resolveTerminalIdentityDefault } from "../common/terminal-identity.mjs";
 import { publishSessionSnapshot, removeSession } from "./broker-client.mjs";
 
 function now() {
@@ -47,6 +48,9 @@ export function createSessionTelemetry({
   pi,
   cwd = process.cwd(),
   sessionName = "",
+  env = process.env,
+  stdinIsTTY = Boolean(process.stdin.isTTY),
+  resolveTerminalIdentity = resolveTerminalIdentityDefault,
   transport,
 } = {}) {
   const publish = transport?.publish ?? publishSessionSnapshot;
@@ -62,6 +66,9 @@ export function createSessionTelemetry({
   let lastStopReason = "";
   let confirmedSignature = "";
   let retryIndex = 0;
+  /** @type {Promise<void> | null} */
+  let flushPromise = null;
+  let flushAgain = false;
 
   /** Signature of the display-relevant fields, used to detect lost transitions. */
   function publishSignature() {
@@ -75,15 +82,20 @@ export function createSessionTelemetry({
       snapshot.toolName,
       snapshot.toolTarget,
       snapshot.errorMessage,
+      snapshot.terminalKey,
     ].join("\u001f");
   }
 
-  async function flush() {
+  function clearScheduledFlush() {
+    if (!flushTimer) return;
+    clearTimeout(flushTimer);
     flushTimer = null;
-    if (disposed) return;
-    // Heartbeat republish refreshes transport liveness only; lastEventAt stays
-    // pinned to the last real lifecycle event so stalled streams stay visible.
+  }
+
+  async function publishLatest() {
+    // Heartbeats refresh transport liveness only; lastEventAt remains the last real event.
     snapshot.updatedAt = now();
+    snapshot.publisherSequence += 1;
     snapshot.repoLabel = formatRepoLabel(
       snapshot.cwd,
       pi?.getSessionName?.() ?? snapshot.sessionName,
@@ -91,29 +103,48 @@ export function createSessionTelemetry({
     snapshot.sessionName = compactWhitespace(pi?.getSessionName?.() ?? snapshot.sessionName);
     const signature = publishSignature();
     try {
-      await publish(snapshot);
+      await publish({ ...snapshot });
       confirmedSignature = signature;
       retryIndex = 0;
     } catch {
-      // Broker is optional at runtime; silent failure keeps pi stable. Retry a
-      // bounded number of times when a state transition may not have landed so
-      // a transient connect failure cannot freeze the displayed state.
       if (
+        !disposed &&
         signature !== confirmedSignature &&
         retryIndex < ACTIVITY_STRIP_FLUSH_RETRY_DELAYS_MS.length
       ) {
-        scheduleFlush(ACTIVITY_STRIP_FLUSH_RETRY_DELAYS_MS[retryIndex]);
+        const delayMs = ACTIVITY_STRIP_FLUSH_RETRY_DELAYS_MS[retryIndex];
         retryIndex += 1;
+        scheduleFlush(delayMs);
       }
     }
   }
 
-  function scheduleFlush(delayMs = ACTIVITY_STRIP_SEND_THROTTLE_MS) {
+  async function flush() {
+    clearScheduledFlush();
     if (disposed) return;
-    if (flushTimer) return;
+    if (flushPromise) {
+      flushAgain = true;
+      return flushPromise;
+    }
+    flushPromise = (async () => {
+      do {
+        flushAgain = false;
+        if (disposed) break;
+        await publishLatest();
+      } while (flushAgain && !disposed);
+    })().finally(() => {
+      flushPromise = null;
+    });
+    return flushPromise;
+  }
+
+  function scheduleFlush(delayMs = ACTIVITY_STRIP_SEND_THROTTLE_MS) {
+    if (disposed || flushTimer) return;
     flushTimer = setTimeout(() => {
+      flushTimer = null;
       flush().catch(() => {});
     }, delayMs);
+    flushTimer.unref?.();
   }
 
   function startHeartbeat() {
@@ -149,8 +180,15 @@ export function createSessionTelemetry({
     async onSessionStart(ctx) {
       const exactSessionId = String(ctx?.sessionManager?.getSessionId?.() ?? "").trim();
       const nextCwd = ctx?.cwd ?? snapshot.cwd;
+      const terminalIdentity = resolveTerminalIdentity({
+        env,
+        hasUI: Boolean(ctx?.hasUI),
+        stdinIsTTY,
+        processId: process.pid,
+      });
       update({
         ...(exactSessionId ? { sessionId: exactSessionId } : {}),
+        ...terminalIdentity,
         cwd: nextCwd,
         sessionName: pi?.getSessionName?.() ?? snapshot.sessionName,
         detail: previewPath(nextCwd, 72) || "Ready",
@@ -276,9 +314,11 @@ export function createSessionTelemetry({
     async shutdown() {
       disposed = true;
       stopHeartbeat();
-      if (flushTimer) {
-        clearTimeout(flushTimer);
-        flushTimer = null;
+      clearScheduledFlush();
+      try {
+        await flushPromise;
+      } catch {
+        // Broker absence remains non-fatal; publisher removal is still attempted below.
       }
       try {
         await removePublisher({

package/src/common/activity-order.mjs

@@ -6,6 +6,11 @@
 
 const ACTIVE_STATES = new Set(["thinking", "tool", "waiting"]);
 
+/** @param {{cardId?: string; sessionId?: string}} session */
+export function activityCardKey(session) {
+  return String(session?.cardId ?? session?.sessionId ?? "");
+}
+
 /** @param {{ state?: string; agentActive?: boolean }} session */
 export function isActiveSession(session) {
   return Boolean(session?.agentActive || ACTIVE_STATES.has(String(session?.state ?? "")));
@@ -24,18 +29,19 @@ export function isMonitoringSession(session) {
  * Reconcile at the calm clock: green settled/monitoring cards first, then active cards,
  * then other inactive cards. Preserve previous/manual order inside each group and append
  * new cards deterministically.
- * @param {Array<{ sessionId: string; state?: string; agentActive?: boolean; toolName?: string; toolTarget?: string; updatedAt?: number }>} sessions
+ * @param {Array<{ sessionId: string; cardId?: string; state?: string; agentActive?: boolean; toolName?: string; toolTarget?: string; updatedAt?: number }>} sessions
  * @param {string[]} previousOrder
  * @param {{ regroup?: boolean }} [options]
  */
 export function reconcileActivityOrder(sessions, previousOrder = [], { regroup = true } = {}) {
-  const byId = new Map(sessions.map((session) => [session.sessionId, session]));
+  const byId = new Map(sessions.map((session) => [activityCardKey(session), session]));
   const surviving = previousOrder.filter((id) => byId.has(id));
   const known = new Set(surviving);
   for (const session of sessions) {
-    if (!session.sessionId || known.has(session.sessionId)) continue;
-    surviving.push(session.sessionId);
-    known.add(session.sessionId);
+    const id = activityCardKey(session);
+    if (!id || known.has(id)) continue;
+    surviving.push(id);
+    known.add(id);
   }
   if (!regroup) return surviving;
 
@@ -45,16 +51,16 @@ export function reconcileActivityOrder(sessions, previousOrder = [], { regroup =
     const rightPriority = isMonitoringSession(right) ? 2 : isActiveSession(right) ? 1 : 0;
     const groupDelta = rightPriority - leftPriority;
     if (groupDelta) return groupDelta;
-    const leftPrior = priorIndex.get(left.sessionId);
-    const rightPrior = priorIndex.get(right.sessionId);
+    const leftPrior = priorIndex.get(activityCardKey(left));
+    const rightPrior = priorIndex.get(activityCardKey(right));
     if (leftPrior != null || rightPrior != null) {
       return (leftPrior ?? Number.MAX_SAFE_INTEGER) - (rightPrior ?? Number.MAX_SAFE_INTEGER);
     }
     const updateDelta = Number(right.updatedAt ?? 0) - Number(left.updatedAt ?? 0);
     if (updateDelta) return updateDelta;
-    return left.sessionId.localeCompare(right.sessionId);
+    return activityCardKey(left).localeCompare(activityCardKey(right));
   });
-  return ordered.map((session) => session.sessionId).filter((id) => byId.has(id));
+  return ordered.map(activityCardKey).filter((id) => byId.has(id));
 }
 
 /** @param {string[]} order @param {string} sessionId @param {-1 | 1} delta */

package/src/common/agent-identity.mjs

@@ -0,0 +1,163 @@
+// ---
+// summary: "recognizes terminal-based coding agents and shapes them into activity-strip session records"
+// read_when:
+//   - "adding an agent CLI, changing agent card fields, or changing agent title matching"
+// ---
+
+import path from "node:path";
+
+/**
+ * Terminal-based coding agents that occupy a Ghostty tab the way Pi does. Recognition is by the
+ * executable name of the process that owns the terminal, never by a window title, so a tab is
+ * admitted on process evidence alone.
+ * @type {ReadonlyArray<{kind: string; label: string; commands: readonly string[]}>}
+ */
+export const AGENT_CATALOG = Object.freeze([
+  { kind: "claude", label: "Claude Code", commands: Object.freeze(["claude"]) },
+  { kind: "codex", label: "Codex", commands: Object.freeze(["codex"]) },
+  { kind: "gemini", label: "Gemini", commands: Object.freeze(["gemini"]) },
+  { kind: "amp", label: "Amp", commands: Object.freeze(["amp"]) },
+  { kind: "aider", label: "Aider", commands: Object.freeze(["aider"]) },
+  { kind: "opencode", label: "opencode", commands: Object.freeze(["opencode"]) },
+  { kind: "crush", label: "Crush", commands: Object.freeze(["crush"]) },
+  { kind: "goose", label: "Goose", commands: Object.freeze(["goose"]) },
+  { kind: "cursor", label: "Cursor Agent", commands: Object.freeze(["cursor-agent"]) },
+  { kind: "zcode", label: "zcode", commands: Object.freeze(["zcode"]) },
+]);
+
+/** Pi publishes its own telemetry, so its processes are never discovered this way. */
+const EXCLUDED_COMMANDS = new Set(["pi", "node", "bash", "sh", "zsh", "fish", "python3"]);
+/**
+ * Executables that only ever host another program. When one of these is the process name, the
+ * command line names the real agent, so it is worth the extra read to look.
+ */
+const RUNTIME_COMMANDS = [/^node/i, /^python/i, /^(bash|sh|zsh|fish|dash|env)$/i, /^(deno|bun)$/i];
+
+/** @param {unknown} command */
+export function isRuntimeCommand(command) {
+  const name = path.basename(String(command ?? "").trim());
+  return name.length > 0 && RUNTIME_COMMANDS.some((pattern) => pattern.test(name));
+}
+export const AGENT_ACTIVE_WINDOW_MS = 45_000;
+
+/** @param {NodeJS.ProcessEnv} [env] */
+export function agentCatalogFor(env = process.env) {
+  const disabled = new Set(
+    String(env.PI_ACTIVITY_STRIP_AGENT_KINDS_DISABLED ?? "")
+      .split(",")
+      .map((value) => value.trim().toLowerCase())
+      .filter(Boolean),
+  );
+  return AGENT_CATALOG.filter((agent) => !disabled.has(agent.kind));
+}
+
+/**
+ * Classify one process by the executable it runs. `command` is the kernel's comm value, which the
+ * kernel truncates to 15 characters and which names the runtime rather than the agent when the
+ * agent is launched through one; the command line entries name the agent in that case.
+ * @param {{command?: unknown; argv0?: unknown; argv1?: unknown; env?: NodeJS.ProcessEnv}} process
+ */
+export function classifyAgentProcess({ command, argv0, argv1, env = process.env } = {}) {
+  const names = [command, argv0, argv1]
+    .map((value) => path.basename(String(value ?? "").trim()).toLowerCase())
+    .filter(Boolean);
+  if (names.length === 0 || names.every((name) => EXCLUDED_COMMANDS.has(name))) return null;
+  for (const agent of agentCatalogFor(env)) {
+    if (agent.commands.some((candidate) => names.includes(candidate))) return agent;
+  }
+  return null;
+}
+
+/** @param {unknown} cwd */
+export function repoLabelFor(cwd) {
+  const normalized = String(cwd ?? "").trim();
+  if (!normalized || normalized === "/") return "";
+  return path.basename(normalized);
+}
+
+/**
+ * Shape one discovered agent tab into the record the card projection consumes. The record carries a
+ * terminal identity, so it groups and places exactly like a Pi terminal card, but its session id is
+ * namespaced by agent kind and can never be mistaken for a Pi session id.
+ * @param {{
+ *   kind: string;
+ *   label: string;
+ *   processId: number;
+ *   cwd: string;
+ *   terminalKey: string;
+ *   terminalFamily: string;
+ *   terminalSurfaceId: string;
+ *   sessionKey?: string;
+ *   titleSuffix?: string;
+ *   startedAt: number;
+ *   lastEventAt?: number;
+ *   now?: number;
+ *   telemetry?: Partial<import("./claude-transcript.mjs").ClaudeTelemetry> | null;
+ * }} tab
+ */
+export function agentSessionRecord({
+  kind,
+  label,
+  processId,
+  cwd,
+  terminalKey,
+  terminalFamily,
+  terminalSurfaceId,
+  sessionKey = "",
+  titleSuffix = "",
+  startedAt,
+  lastEventAt = 0,
+  now = Date.now(),
+  telemetry = null,
+}) {
+  // Process start times and file modification times are fractional milliseconds, while the panel
+  // protocol carries whole-millisecond integers, so every timestamp is rounded at the boundary.
+  const startedAtMs = Math.round(startedAt) || 0;
+  const lastEventMs = Math.round(lastEventAt) || 0;
+  const nowMs = Math.round(now) || 0;
+  const activity = lastEventMs > 0 ? lastEventMs : startedAtMs;
+  // Reported activity decides liveness. A published state only counts while the transcript is
+  // still moving; a stale "tool" record is not evidence that a tool is running right now.
+  const recent = lastEventMs > 0 && nowMs - lastEventMs <= AGENT_ACTIVE_WINDOW_MS;
+  const reported = String(telemetry?.state ?? "");
+  // "waiting" and "error" describe a session that is stopped on purpose, so they survive the
+  // liveness window: a permission prompt can sit unanswered for a long time and is still true.
+  const sticky = reported === "waiting" || reported === "error";
+  const busy = reported === "tool" || reported === "thinking";
+  const active = sticky || (recent && (busy || !reported));
+  const state = sticky ? reported : active ? (busy ? reported : "thinking") : "idle";
+  const toolName = active ? String(telemetry?.toolName ?? "") : "";
+  const toolTarget = active ? String(telemetry?.toolTarget ?? "") : "";
+  const detail = [toolTarget, String(telemetry?.assistantPreview ?? ""), cwd].find(Boolean) ?? "";
+  return {
+    sessionId: `agent:${kind}:${sessionKey || processId}`,
+    publisherId: `agent-scan:${processId}`,
+    publisherSequence: 0,
+    processId,
+    agentKind: kind,
+    agentSessionKey: sessionKey,
+    terminalKind: "ghostty-surface",
+    terminalKey,
+    terminalFamily,
+    terminalSurfaceId,
+    titleSuffix,
+    cwd,
+    repoLabel: repoLabelFor(cwd),
+    sessionName: "",
+    agentLabel: label,
+    phase: String(telemetry?.title ?? "").trim() || label,
+    detail,
+    assistantPreview: String(telemetry?.assistantPreview ?? ""),
+    toolName,
+    toolTarget,
+    state,
+    turnIndex: Number(telemetry?.turnIndex ?? 0) || 0,
+    updatedAt: nowMs,
+    lastEventAt: activity,
+    startedAt: startedAtMs,
+    agentStartedAt: active ? activity : null,
+    agentActive: active,
+    lastPromptPreview: String(telemetry?.lastPrompt ?? ""),
+    errorMessage: "",
+  };
+}