@tryinget/pi-activity-strip 0.5.0 → 0.7.0

package/src/client/runtime-lock.mjs

@@ -0,0 +1,140 @@
+// ---
+// summary: "waits on the native runtime flock so stop returns only after the controller exits, and open can name a held lock"
+// read_when:
+//   - "changing how stop waits for shutdown or how open reports a runtime that failed to start"
+// ---
+
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+import {
+  ACTIVITY_STRIP_SOCKET_DIR,
+  ACTIVITY_STRIP_START_TIMEOUT_MS,
+  ACTIVITY_STRIP_STOP_TIMEOUT_MS,
+} from "../common/constants.mjs";
+import { requestBrokerShutdown } from "./broker-client.mjs";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * The exit status `flock` uses for a held lock. It differs from every status the controller or
+ * `flock` itself can return, so a held lock is never confused with a failure to check it.
+ */
+export const RUNTIME_LOCK_CONFLICT_EXIT_CODE = 75;
+
+/** The controller holds this lock for its whole lifetime. */
+export const RUNTIME_LOCK_PATH = path.join(ACTIVITY_STRIP_SOCKET_DIR, "runtime.lock");
+
+/** @typedef {import("../common/contracts.ts").BrokerResponse} BrokerResponse */
+/** @typedef {{exitCode: number | null | undefined}} ControllerHandle */
+
+/**
+ * Take and release the lock once, reporting whether it was held.
+ * @param {string} lockPath
+ * @param {string[]} mode
+ * @returns {Promise<"free" | "held" | {error: string}>}
+ */
+async function tryRuntimeLock(lockPath, mode) {
+  const conflict = String(RUNTIME_LOCK_CONFLICT_EXIT_CODE);
+  try {
+    await execFileAsync("flock", [...mode, "--conflict-exit-code", conflict, lockPath, "true"]);
+    return "free";
+  } catch (error) {
+    const failure = /** @type {{code?: unknown; message?: string}} */ (error ?? {});
+    if (failure.code === RUNTIME_LOCK_CONFLICT_EXIT_CODE) return "held";
+    return {
+      error: `Could not check the activity-strip runtime lock: ${failure.message ?? String(error)}`,
+    };
+  }
+}
+
+/**
+ * Wait until the controller holding the runtime lock has exited. The controller holds the lock for
+ * its whole lifetime and closes its broker before it lets go, so a closed broker alone does not
+ * prove it is gone. `waited` says whether a runtime was still there.
+ * @param {string} lockPath
+ * @param {{timeoutMs: number}} options
+ * @returns {Promise<{released: boolean; waited?: boolean; error?: string}>}
+ */
+export async function waitForRuntimeExit(lockPath, { timeoutMs }) {
+  const now = await tryRuntimeLock(lockPath, ["--nonblock"]);
+  if (now === "free") return { released: true, waited: false };
+  if (now !== "held") return { released: false, error: now.error };
+  const later = await tryRuntimeLock(lockPath, ["--wait", String(timeoutMs / 1000)]);
+  if (later === "free") return { released: true, waited: true };
+  if (later === "held") return { released: false, waited: true };
+  return { released: false, error: later.error };
+}
+
+/**
+ * Stop the runtime and return once it has exited. Every stop path, the CLI and Pi's commands, goes
+ * through here, so a following open can never race a runtime that is still shutting down. The lock
+ * is waited on even when no broker answers: a runtime whose broker has closed still holds it.
+ * @param {{
+ *   requestShutdown?: () => Promise<{ok?: boolean} | null | undefined>;
+ *   waitForExit?: typeof waitForRuntimeExit;
+ *   lockPath?: string;
+ *   timeoutMs?: number;
+ * }} [options]
+ * @returns {Promise<{outcome: "stopped" | "not-running" | "still-stopping"} | {outcome: "error"; error: string}>}
+ */
+export async function stopRuntime({
+  requestShutdown = requestBrokerShutdown,
+  waitForExit = waitForRuntimeExit,
+  lockPath = RUNTIME_LOCK_PATH,
+  timeoutMs = ACTIVITY_STRIP_STOP_TIMEOUT_MS,
+} = {}) {
+  let accepted = false;
+  try {
+    accepted = (await requestShutdown())?.ok === true;
+  } catch {
+    accepted = false;
+  }
+  const exit = await waitForExit(lockPath, { timeoutMs });
+  if (exit.error) return { outcome: "error", error: exit.error };
+  if (!exit.released) return { outcome: "still-stopping" };
+  return { outcome: accepted || exit.waited ? "stopped" : "not-running" };
+}
+
+/**
+ * Wait for the controller `open` just spawned under the runtime lock to become ready. A spawn that
+ * finds the lock held exits with the conflict status. The wait still continues, because the holder
+ * may be a controller another `open` is starting; the held lock is reported only if nothing
+ * becomes ready in time.
+ * @param {{
+ *   controller: ControllerHandle;
+ *   getStatus: () => Promise<BrokerResponse | null>;
+ *   timeoutMs?: number;
+ *   retryMs?: number;
+ *   now?: () => number;
+ *   sleep?: (ms: number) => Promise<unknown>;
+ * }} options
+ * @returns {Promise<{ok: true; started: boolean} | {ok: false; reason: "error" | "exited" | "lock-held" | "timeout"; status: BrokerResponse | null; exitCode?: number | null}>}
+ */
+export async function waitForStartedRuntime({
+  controller,
+  getStatus,
+  timeoutMs = ACTIVITY_STRIP_START_TIMEOUT_MS,
+  retryMs = 125,
+  now = Date.now,
+  sleep = delay,
+}) {
+  const deadline = now() + timeoutMs;
+  while (true) {
+    const status = await getStatus();
+    if (status?.ok && (!status.runtimeStatus || status.runtimeStatus.state === "ready")) {
+      return { ok: true, started: controller.exitCode === undefined };
+    }
+    if (status?.runtimeStatus?.state === "error") return { ok: false, reason: "error", status };
+    const exitCode = controller.exitCode;
+    if (exitCode !== undefined && exitCode !== RUNTIME_LOCK_CONFLICT_EXIT_CODE) {
+      return { ok: false, reason: "exited", status, exitCode };
+    }
+    if (now() >= deadline) {
+      const reason = exitCode === RUNTIME_LOCK_CONFLICT_EXIT_CODE ? "lock-held" : "timeout";
+      return { ok: false, reason, status };
+    }
+    await sleep(retryMs);
+  }
+}

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: "",
+  };
+}

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,
+  };
+}