@tryinget/pi-activity-strip 0.4.0 → 0.6.0

package/src/common/workspace-view.mjs

@@ -0,0 +1,161 @@
+// ---
+// summary: "projects tracked sessions onto one Niri workspace as cards with known visibility"
+// read_when:
+//   - "changing workspace card membership, card visibility, or focused-card selection"
+// ---
+
+import {
+  canVerifyTabVisibility,
+  placeSessionWindow,
+  resolvePiSessionIdentity,
+} from "./niri-focus.mjs";
+import { projectSessionCards, sessionCardId } from "./session-cards.mjs";
+import { parseTerminalTitleBinding } from "./surface-bindings.mjs";
+import { canonicalGhosttyTerminalKey } from "./terminal-identity.mjs";
+
+/** @typedef {import("./window-placement.mjs").PlacementOptions} PlacementOptions */
+/**
+ * @typedef {PlacementOptions & {
+ *   env?: NodeJS.ProcessEnv;
+ *   readFileSync?: typeof import("node:fs").readFileSync;
+ *   existsSync?: typeof import("node:fs").existsSync;
+ * }} ResolveOptions
+ */
+
+/**
+ * Decide whether a placed tab is the one its window is currently showing. A window title naming a
+ * different terminal surface, or missing a title this session is known to set, is proof the tab is
+ * hidden. Without either signal visibility is unknown, and an unknown tab is never marked hidden:
+ * an agent that sets no recognizable title would otherwise look permanently buried.
+ * @param {Record<string, unknown>} window
+ * @param {Record<string, unknown>} session
+ * @param {string} placement
+ * @param {ResolveOptions} [options]
+ * @returns {"visible" | "hidden" | "unknown"}
+ */
+export function resolveSurfaceVisibility(window, session, placement, options = {}) {
+  if (placement === "title") return "visible";
+  // A session that writes its own identity into the terminal title was already matched against
+  // every window title. Reaching here means no title matched, so this tab is not the one shown.
+  if (canVerifyTabVisibility(session, options)) return "hidden";
+  const terminalKey = canonicalGhosttyTerminalKey(session);
+  const titled = parseTerminalTitleBinding(window?.title);
+  if (titled && terminalKey && titled.terminalKey !== terminalKey) return "hidden";
+  return "unknown";
+}
+
+/**
+ * Project the global broker snapshot onto one exact Niri workspace. Membership requires an exact
+ * window placement: a visible title, or a hidden tab attributed through its Ghostty host process.
+ * Multiple publisher streams bound to the same terminal are aggregated into one stable card; a
+ * window may carry several terminal cards because each tab is its own surface, but a card claimed
+ * by distinct windows still fails closed. Only a visible tab in the focused window is "current".
+ * @param {Array<Record<string, unknown>>} windows
+ * @param {Record<string, unknown>} workspace
+ * @param {Array<Record<string, unknown>>} sessions
+ * @param {ResolveOptions} [options]
+ */
+export function resolveWorkspaceView(windows, workspace, sessions, options = {}) {
+  if (!Number.isInteger(workspace?.id)) return null;
+  /** @type {Array<{cardId: string; session: Record<string, unknown>; window: Record<string, unknown>; placement: string}>} */
+  const candidates = [];
+  for (const session of sessions) {
+    const placed = placeSessionWindow(windows, session, options);
+    if (!placed || placed.window.workspace_id !== workspace.id) continue;
+    const cardId = sessionCardId(session);
+    if (!cardId) continue;
+    candidates.push({
+      cardId,
+      session: { ...session, cardId },
+      window: placed.window,
+      placement: placed.placement,
+    });
+  }
+
+  /** @type {Map<unknown, Set<string>>} */
+  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);
+  }
+  /** @type {Map<unknown, Set<string>>} */
+  const allowedCardsByWindow = new Map();
+  for (const [windowId, ids] of cardIdsByWindow) {
+    const terminalIds = [...ids].filter((cardId) => cardId.startsWith("terminal:"));
+    if (terminalIds.length > 0) allowedCardsByWindow.set(windowId, new Set(terminalIds));
+    else if (ids.size === 1) allowedCardsByWindow.set(windowId, ids);
+  }
+
+  /** @type {Map<string, Array<{session: Record<string, unknown>; window: Record<string, unknown>; placement: string}>>} */
+  const groups = new Map();
+  for (const candidate of candidates) {
+    if (!allowedCardsByWindow.get(candidate.window.id)?.has(candidate.cardId)) continue;
+    const group = groups.get(candidate.cardId) ?? [];
+    group.push(candidate);
+    groups.set(candidate.cardId, group);
+  }
+
+  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;
+    const placement = group.some((candidate) => candidate.placement === "title")
+      ? "title"
+      : (group[0]?.placement ?? "title");
+    const visibility = resolveSurfaceVisibility(
+      window,
+      group[0]?.session ?? card,
+      placement,
+      options,
+    );
+    projectedSessions.push({
+      ...card,
+      cardId,
+      windowId: window?.id,
+      placement,
+      // Only a tab proven to sit behind another one is marked hidden.
+      surfaceVisible: visibility !== "hidden",
+    });
+  }
+  // The focused window shows exactly one tab. Several candidates mean the compositor cannot tell
+  // us which, so nothing is marked current rather than marking the wrong one.
+  const focusedCandidates = projectedSessions.filter(
+    (session) =>
+      session.surfaceVisible &&
+      windows.some((window) => window?.id === session.windowId && window?.is_focused === true),
+  );
+  const focusedCard = focusedCandidates.length === 1 ? focusedCandidates[0] : null;
+  return {
+    workspace,
+    sessions: projectedSessions,
+    focusedSessionId: focusedCard ? String(focusedCard.sessionId ?? "") || null : null,
+    focusedCardId: focusedCard ? String(focusedCard.cardId ?? "") || null : null,
+  };
+}
+
+/**
+ * Project the global broker snapshot onto the one focused Niri workspace.
+ * @param {Array<Record<string, unknown>>} windows
+ * @param {Array<Record<string, unknown>>} workspaces
+ * @param {Array<Record<string, unknown>>} sessions
+ * @param {ResolveOptions} [options]
+ */
+export function resolveFocusedWorkspaceView(windows, workspaces, sessions, options = {}) {
+  const workspace = resolveFocusedNiriWorkspace(workspaces);
+  return workspace ? resolveWorkspaceView(windows, workspace, sessions, options) : null;
+}
+
+/** @param {Array<Record<string, unknown>>} workspaces */
+export function resolveFocusedNiriWorkspace(workspaces) {
+  const matches = workspaces.filter(
+    (workspace) =>
+      workspace?.is_focused === true &&
+      Number.isInteger(workspace?.id) &&
+      (typeof workspace?.name === "string" || Number.isInteger(workspace?.idx)),
+  );
+  return matches.length === 1 ? matches[0] : null;
+}

package/src/native/agent-discovery.mjs

@@ -0,0 +1,294 @@
+// ---
+// summary: "scans procfs for terminal-based agent tabs and reads the Claude Code title that identifies their window"
+// read_when:
+//   - "changing agent tab discovery, its procfs evidence, or the Claude Code title adapter"
+// ---
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  agentSessionRecord,
+  classifyAgentProcess,
+  isRuntimeCommand,
+} from "../common/agent-identity.mjs";
+import { claudeEventPath, mergeClaudeEvent } from "../common/claude-events.mjs";
+import { parseClaudeTranscriptTail } from "../common/claude-transcript.mjs";
+import { parseCodexRolloutTail } from "../common/codex-transcript.mjs";
+import {
+  classifyGhosttyFamily,
+  findGhosttyAncestor,
+  normalizeGhosttySurfaceId,
+  readProcessStartTime,
+} from "../common/terminal-identity.mjs";
+import {
+  bindCodexThread,
+  openRolloutPaths,
+  readCodexThreads,
+  resolveCodexStateDb,
+} from "./codex-discovery.mjs";
+
+const CLOCK_TICKS_PER_SECOND = 100;
+const CLAUDE_SCRATCHPAD =
+  /\/claude-\d+\/([^/]+)\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?:\/|$)/;
+const CLAUDE_TITLE_TAIL_BYTES = 256 * 1024;
+/** A title short enough to collide with an unrelated window is never used for placement. */
+const MIN_PLACEABLE_TITLE_LENGTH = 6;
+const TELEMETRY_CACHE_LIMIT = 64;
+/** Parsed transcripts keyed by path and modification time, so an idle session is parsed once. */
+const telemetryCache = new Map();
+
+/** @typedef {{readFile: (filePath: string) => string; readLink: (filePath: string) => string; readDir: (filePath: string) => string[]; statMtimeMs: (filePath: string) => number; readTail: (filePath: string, bytes: number) => string}} Procfs */
+
+/** @type {Procfs} */
+export const nodeProcfs = {
+  readFile(filePath) {
+    try {
+      return fs.readFileSync(filePath, "utf8");
+    } catch {
+      return "";
+    }
+  },
+  readLink(filePath) {
+    try {
+      return fs.readlinkSync(filePath);
+    } catch {
+      return "";
+    }
+  },
+  readDir(filePath) {
+    try {
+      return fs.readdirSync(filePath);
+    } catch {
+      return [];
+    }
+  },
+  statMtimeMs(filePath) {
+    try {
+      return fs.statSync(filePath).mtimeMs;
+    } catch {
+      return 0;
+    }
+  },
+  readTail(filePath, bytes) {
+    let handle;
+    try {
+      handle = fs.openSync(filePath, "r");
+      const size = fs.fstatSync(handle).size;
+      const length = Math.min(size, bytes);
+      const buffer = Buffer.alloc(length);
+      fs.readSync(handle, buffer, 0, length, Math.max(0, size - length));
+      return buffer.toString("utf8");
+    } catch {
+      return "";
+    } finally {
+      if (handle !== undefined) {
+        try {
+          fs.closeSync(handle);
+        } catch {
+          // The descriptor is already gone.
+        }
+      }
+    }
+  },
+};
+
+/** @param {string} raw */
+function parseEnviron(raw) {
+  /** @type {Record<string, string>} */
+  const env = {};
+  for (const entry of raw.split("\0")) {
+    const index = entry.indexOf("=");
+    if (index > 0) env[entry.slice(0, index)] = entry.slice(index + 1);
+  }
+  return env;
+}
+
+/**
+ * Read live session state from the tail of a Claude Code transcript. Results are cached against the
+ * file's modification time, so a session that is not writing costs one stat call per scan.
+ * @param {string} transcriptPath
+ * @param {Procfs} procfs
+ * @param {Map<string, {mtime: number; telemetry: import("../common/claude-transcript.mjs").ClaudeTelemetry}>} [cache]
+ */
+export function readClaudeTelemetry(transcriptPath, procfs = nodeProcfs, cache = telemetryCache) {
+  const mtime = procfs.statMtimeMs(transcriptPath);
+  const cached = cache.get(transcriptPath);
+  if (cached && cached.mtime === mtime) return cached.telemetry;
+  const telemetry = parseClaudeTranscriptTail(
+    procfs.readTail(transcriptPath, CLAUDE_TITLE_TAIL_BYTES),
+  );
+  if (mtime > 0) {
+    if (cache.size >= TELEMETRY_CACHE_LIMIT) cache.clear();
+    cache.set(transcriptPath, { mtime, telemetry });
+  }
+  return telemetry;
+}
+
+/**
+ * Live state for one Codex tab. The thread index names the session and its rollout; the rollout
+ * tail reports what that session is doing now.
+ * @param {{processId: number; cwd: string; startedAt: number}} process
+ * @param {import("./codex-discovery.mjs").CodexThread[]} threads
+ * @param {Procfs} procfs
+ * @param {Map<string, any>} cache
+ */
+export function readCodexSession(process, threads, procfs, cache) {
+  const thread = bindCodexThread(
+    { ...process, openPaths: openRolloutPaths(process.processId, procfs) },
+    threads,
+  );
+  if (!thread) return null;
+  const mtime = procfs.statMtimeMs(thread.rolloutPath);
+  const cached = cache.get(thread.rolloutPath);
+  const telemetry =
+    cached && cached.mtime === mtime
+      ? cached.telemetry
+      : parseCodexRolloutTail(procfs.readTail(thread.rolloutPath, CLAUDE_TITLE_TAIL_BYTES));
+  if (mtime > 0 && (!cached || cached.mtime !== mtime)) {
+    if (cache.size >= TELEMETRY_CACHE_LIMIT) cache.clear();
+    cache.set(thread.rolloutPath, { mtime, telemetry });
+  }
+  return { thread, telemetry: { ...telemetry, title: thread.title || telemetry.title } };
+}
+
+/**
+ * Read the newest hook record a Claude Code session published, if any. Hooks are the documented,
+ * real-time source; the transcript remains the fallback for sessions started before hooks existed.
+ * @param {string} sessionId
+ * @param {Procfs} procfs
+ */
+export function readClaudeHookEvent(sessionId, procfs = nodeProcfs) {
+  const filePath = claudeEventPath(sessionId);
+  if (!filePath) return null;
+  try {
+    const parsed = JSON.parse(procfs.readFile(filePath));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Claude Code opens its per-session scratchpad, whose path carries the encoded working directory
+ * and the session id. That is exact process-bound evidence of which conversation a tab is running.
+ * @param {number} processId
+ * @param {Procfs} procfs
+ * @param {string} [homeDir]
+ */
+export function resolveClaudeSession(processId, procfs = nodeProcfs, homeDir = os.homedir()) {
+  const fdDir = path.join("/proc", String(processId), "fd");
+  for (const entry of procfs.readDir(fdDir)) {
+    const target = procfs.readLink(path.join(fdDir, entry));
+    const match = target.match(CLAUDE_SCRATCHPAD);
+    if (!match) continue;
+    const [, encodedCwd, sessionId] = match;
+    const transcript = path.join(homeDir, ".claude", "projects", encodedCwd, `${sessionId}.jsonl`);
+    return { sessionId, encodedCwd, transcript };
+  }
+  return null;
+}
+
+/** @param {Procfs} procfs */
+function bootTimeMs(procfs) {
+  const uptimeSeconds = Number.parseFloat(procfs.readFile("/proc/uptime").split(/\s+/)[0] ?? "");
+  return Number.isFinite(uptimeSeconds) ? Date.now() - uptimeSeconds * 1000 : 0;
+}
+
+/**
+ * Discover every Ghostty tab running a recognized agent. A tab is admitted only with a bounded
+ * Ghostty surface id, a live Ghostty ancestor of a known build family, and a recognized executable.
+ * @param {{procfs?: Procfs; env?: NodeJS.ProcessEnv; homeDir?: string; now?: () => number; telemetryCache?: Map<string, any>}} [options]
+ */
+export function discoverAgentTabs(options = {}) {
+  const {
+    procfs = nodeProcfs,
+    env = process.env,
+    homeDir = os.homedir(),
+    now = Date.now,
+    telemetryCache: cache = telemetryCache,
+  } = options;
+  const boot = bootTimeMs(procfs);
+  // The Codex thread index is read once per scan and only when a Codex tab is actually present.
+  /** @type {import("./codex-discovery.mjs").CodexThread[] | null} */
+  let codexThreads = null;
+  const codexHome = String(env.CODEX_HOME ?? "").trim() || path.join(homeDir, ".codex");
+  const records = [];
+  for (const entry of procfs.readDir("/proc")) {
+    if (!/^\d+$/.test(entry)) continue;
+    const processId = Number(entry);
+    // The executable name is one tiny read, so it gates the far more expensive reads below. An
+    // agent started through a runtime reports that runtime as its name, so those names — and only
+    // those — are worth the second read of the command line.
+    const command = procfs.readFile(path.join("/proc", entry, "comm")).trim();
+    let agent = classifyAgentProcess({ command, env });
+    if (!agent && (!command || isRuntimeCommand(command))) {
+      const argv = procfs.readFile(path.join("/proc", entry, "cmdline")).split("\0");
+      agent = classifyAgentProcess({ command, argv0: argv[0], argv1: argv[1], env });
+    }
+    if (!agent) continue;
+    const processEnv = parseEnviron(procfs.readFile(path.join("/proc", entry, "environ")));
+    if (String(processEnv.TERM_PROGRAM ?? "").toLowerCase() !== "ghostty") continue;
+    const surfaceId = normalizeGhosttySurfaceId(processEnv.GHOSTTY_SURFACE_ID);
+    if (!surfaceId) continue;
+    const ancestor = findGhosttyAncestor(processId, procfs);
+    const family = classifyGhosttyFamily(ancestor?.executable);
+    if (!family) continue;
+
+    const startTicks = Number(readProcessStartTime(processId, procfs) || 0);
+    const startedAt =
+      boot > 0 && startTicks > 0 ? boot + (startTicks / CLOCK_TICKS_PER_SECOND) * 1000 : now();
+    const cwd = procfs.readLink(path.join("/proc", entry, "cwd"));
+    let sessionKey = "";
+    let titleSuffix = "";
+    let lastEventAt = 0;
+    /** @type {import("../common/claude-transcript.mjs").ClaudeTelemetry | null} */
+    let telemetry = null;
+    if (agent.kind === "codex") {
+      if (codexThreads === null) codexThreads = readCodexThreads(resolveCodexStateDb(codexHome));
+      const session = readCodexSession({ processId, cwd, startedAt }, codexThreads, procfs, cache);
+      if (session) {
+        sessionKey = session.thread.id;
+        telemetry = session.telemetry;
+        lastEventAt =
+          session.telemetry.lastEventAt || procfs.statMtimeMs(session.thread.rolloutPath);
+      }
+    } else if (agent.kind === "claude") {
+      const claude = resolveClaudeSession(processId, procfs, homeDir);
+      if (claude) {
+        sessionKey = claude.sessionId;
+        telemetry = mergeClaudeEvent(
+          readClaudeTelemetry(claude.transcript, procfs, cache),
+          readClaudeHookEvent(claude.sessionId, procfs),
+          now(),
+        );
+        titleSuffix = telemetry.title;
+
+        // The transcript's own newest timestamp is the true activity clock; its modification time
+        // also moves for the latched records Claude Code rewrites without one.
+        lastEventAt = telemetry.lastEventAt || procfs.statMtimeMs(claude.transcript);
+      }
+    }
+    const discoveredTitle = String(telemetry?.title ?? "");
+    if (discoveredTitle.length < MIN_PLACEABLE_TITLE_LENGTH) titleSuffix = "";
+    else if (!titleSuffix) titleSuffix = discoveredTitle;
+    records.push(
+      agentSessionRecord({
+        kind: agent.kind,
+        label: agent.label,
+        processId,
+        cwd,
+        terminalKey: `ghostty:${family}:${surfaceId}`,
+        terminalFamily: family,
+        terminalSurfaceId: surfaceId,
+        sessionKey,
+        titleSuffix,
+        startedAt,
+        lastEventAt,
+        now: now(),
+        telemetry,
+      }),
+    );
+  }
+  return records;
+}

package/src/native/ak-runtime.mjs

@@ -0,0 +1,164 @@
+// ---
+// summary: "polls read-only ak CLI output and hands parsed claims to the card projection"
+// read_when:
+//   - "changing AK polling cadence, fail-closed behavior, or the ak CLI read surface"
+// ---
+
+import {
+  claimIsLive,
+  parseAkClaimList,
+  parseAkDeferredList,
+  summarizeAkTasks,
+} from "../common/ak-tasks.mjs";
+
+/** AK state changes are rare; a calm clock keeps the ribbon cheap. */
+export const AK_TASK_REFRESH_MS = 15_000;
+const AK_EXEC_TIMEOUT_MS = 8000;
+const AK_EXEC_MAX_BUFFER = 4 * 1024 * 1024;
+
+/**
+ * The strip reads AK strictly through the read-only CLI (`ak task list` / `ak task deferred`);
+ * it never opens the society database and never writes. Any failure (missing binary, non-zero
+ * exit, malformed output) fails closed: chips are dropped rather than guessed.
+ * @param {{
+ *   execFileAsync: (file: string, args: string[], options: object) => Promise<{stdout?: string}>;
+ *   env?: NodeJS.ProcessEnv;
+ *   now?: () => number;
+ *   runtimeStatus: import("../common/contracts.ts").ActivityStripRuntimeStatus;
+ *   onChange: (state: {claims: import("../common/contracts.ts").AkTaskClaim[]; deferred: import("../common/contracts.ts").AkTaskDeferred[]}) => void;
+ * }} options
+ */
+export function createAkTaskRuntime({
+  execFileAsync,
+  env = process.env,
+  now = Date.now,
+  runtimeStatus,
+  onChange,
+}) {
+  const disabled = env.PI_ACTIVITY_STRIP_AK_TASKS === "0";
+  const akBinary = env.PI_ACTIVITY_STRIP_AK_BIN?.trim() || "ak";
+  /** @type {NodeJS.Timeout | null} */
+  let timer = null;
+  let inFlight = false;
+
+  runtimeStatus.akTaskState = disabled ? "disabled" : (runtimeStatus.akTaskState ?? "pending");
+  runtimeStatus.akTaskError = runtimeStatus.akTaskError ?? null;
+  runtimeStatus.akTaskClaimCount = runtimeStatus.akTaskClaimCount ?? 0;
+  runtimeStatus.akTaskDeferredCount = runtimeStatus.akTaskDeferredCount ?? 0;
+  runtimeStatus.akTaskOrphanCount = runtimeStatus.akTaskOrphanCount ?? 0;
+  runtimeStatus.akTaskRenderedCount = runtimeStatus.akTaskRenderedCount ?? 0;
+
+  /**
+   * @param {string[]} args
+   * @returns {Promise<string>}
+   */
+  async function readCli(args) {
+    const { stdout } = await execFileAsync(akBinary, args, {
+      timeout: AK_EXEC_TIMEOUT_MS,
+      maxBuffer: AK_EXEC_MAX_BUFFER,
+    });
+    return String(stdout ?? "");
+  }
+
+  /**
+   * @param {string} error
+   */
+  function failClosed(error) {
+    runtimeStatus.akTaskState = "unavailable";
+    runtimeStatus.akTaskError = error;
+    runtimeStatus.akTaskClaimCount = 0;
+    runtimeStatus.akTaskDeferredCount = 0;
+    onChange({ claims: [], deferred: [] });
+  }
+
+  async function refresh() {
+    if (disabled || inFlight) return false;
+    inFlight = true;
+    try {
+      const [claimRaw, deferredRaw] = await Promise.all([
+        readCli(["task", "list", "--status", "claimed", "--format", "json", "--all", "--verbose"]),
+        readCli(["task", "deferred", "--format", "json", "--all"]),
+      ]);
+      const claims = parseAkClaimList(claimRaw);
+      const deferred = parseAkDeferredList(deferredRaw);
+      if (!claims.ok) {
+        failClosed(claims.error);
+        return false;
+      }
+      if (!deferred.ok) {
+        failClosed(deferred.error);
+        return false;
+      }
+      runtimeStatus.akTaskState = "ok";
+      runtimeStatus.akTaskError = null;
+      runtimeStatus.akTaskClaimCount = claims.claims.filter((claim) =>
+        claimIsLive(claim, now()),
+      ).length;
+      runtimeStatus.akTaskDeferredCount = deferred.deferred.length;
+      onChange({ claims: claims.claims, deferred: deferred.deferred });
+      return true;
+    } catch (error) {
+      failClosed(`ak CLI unavailable: ${error instanceof Error ? error.message : String(error)}`);
+      return false;
+    } finally {
+      inFlight = false;
+    }
+  }
+
+  return {
+    refresh,
+    get disabled() {
+      return disabled;
+    },
+    start() {
+      if (disabled || timer) return;
+      void refresh();
+      timer = setInterval(() => void refresh(), AK_TASK_REFRESH_MS);
+      timer.unref?.();
+    },
+  };
+}
+
+/**
+ * Wire the AK read loop into the card projection: parsed claims become chips, and orphaned
+ * custody is counted against every live session so a claim is only orphaned when no live
+ * session anywhere still holds it.
+ * @param {{
+ *   execFileAsync: (file: string, args: string[], options: object) => Promise<{stdout?: string}>;
+ *   env?: NodeJS.ProcessEnv;
+ *   runtimeStatus: import("../common/contracts.ts").ActivityStripRuntimeStatus;
+ *   projection: {
+ *     setAkTasks: (state: {claims: import("../common/contracts.ts").AkTaskClaim[]; deferred: import("../common/contracts.ts").AkTaskDeferred[]} | null) => void;
+ *     getRawSessions: () => Array<Record<string, unknown>>;
+ *   };
+ * }} options
+ */
+export function startAkTaskProjection({
+  execFileAsync,
+  env = process.env,
+  runtimeStatus,
+  projection,
+}) {
+  const runtime = createAkTaskRuntime({
+    execFileAsync,
+    env,
+    runtimeStatus,
+    onChange: (state) => {
+      projection.setAkTasks(state);
+      const summary = summarizeAkTasks({
+        claims: state.claims,
+        deferred: state.deferred,
+        liveSessionIds: new Set(
+          projection
+            .getRawSessions()
+            .map((session) => String(session.sessionId ?? ""))
+            .filter(Boolean),
+        ),
+        nowMs: Date.now(),
+      });
+      runtimeStatus.akTaskOrphanCount = summary.orphanedClaimCount;
+    },
+  });
+  runtime.start();
+  return runtime;
+}