@tryinget/pi-activity-strip 0.5.0 → 0.7.0

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

package/src/native/codex-discovery.mjs

@@ -0,0 +1,128 @@
+// ---
+// summary: "binds a running Codex process to its session thread and rollout file"
+// read_when:
+//   - "changing Codex session identification or its thread-index reader"
+// ---
+
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const requireBuiltin = createRequire(import.meta.url);
+
+/**
+ * Codex keeps an index of its sessions in a versioned SQLite database under its home, one row per
+ * thread with the rollout path, working directory and title. It only opens the rollout once a task
+ * runs, so the index is what links a live process to its session before any work starts.
+ */
+
+export const CODEX_STATE_DB = /^state_(\d+)\.sqlite$/;
+export const CODEX_THREAD_LIMIT = 400;
+/** A thread is created moments after its process starts; allow for clock and rounding slack. */
+export const CODEX_THREAD_START_SLACK_MS = 5000;
+
+/** @typedef {{id: string; rolloutPath: string; cwd: string; title: string; createdAtMs: number; updatedAtMs: number}} CodexThread */
+
+/**
+ * Newest thread-index database in a Codex home. The suffix is a schema version, so the highest one
+ * is current; a home with none yields "".
+ * @param {string} codexHome
+ * @param {Pick<typeof fs, "readdirSync">} [fsImpl]
+ */
+export function resolveCodexStateDb(codexHome, fsImpl = fs) {
+  let best = { version: -1, file: "" };
+  let entries = [];
+  try {
+    entries = fsImpl.readdirSync(codexHome);
+  } catch {
+    return "";
+  }
+  for (const entry of entries) {
+    const match = CODEX_STATE_DB.exec(entry);
+    if (!match) continue;
+    const version = Number.parseInt(match[1] ?? "", 10);
+    if (Number.isInteger(version) && version > best.version) best = { version, file: entry };
+  }
+  return best.file ? path.join(codexHome, best.file) : "";
+}
+
+/**
+ * Read the thread index. The database belongs to a running application, so it is opened read-only
+ * and every failure — a missing file, a locked database, or a runtime without `node:sqlite` —
+ * yields an empty index rather than an error.
+ * @param {string} databasePath
+ * @returns {CodexThread[]}
+ */
+export function readCodexThreads(databasePath) {
+  if (!databasePath) return [];
+  try {
+    // Loaded here so a runtime without the built-in SQLite module simply reports no threads.
+    const { DatabaseSync } = requireBuiltin("node:sqlite");
+    const db = new DatabaseSync(databasePath, { readOnly: true });
+    try {
+      const rows = db
+        .prepare(
+          "SELECT id, rollout_path, cwd, title, created_at_ms, updated_at_ms FROM threads WHERE archived = 0 ORDER BY created_at_ms DESC LIMIT ?",
+        )
+        .all(CODEX_THREAD_LIMIT);
+      return rows.map(
+        /** @param {any} row */ (row) => ({
+          id: String(row.id ?? ""),
+          rolloutPath: String(row.rollout_path ?? ""),
+          cwd: String(row.cwd ?? ""),
+          title: String(row.title ?? ""),
+          createdAtMs: Number(row.created_at_ms ?? 0),
+          updatedAtMs: Number(row.updated_at_ms ?? 0),
+        }),
+      );
+    } finally {
+      db.close();
+    }
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Bind one Codex process to its thread. An open rollout descriptor is exact proof and wins. With
+ * no descriptor, a thread qualifies only when it was created after the process started and in the
+ * same directory; anything ambiguous binds nothing rather than guessing.
+ * @param {{processId: number; cwd: string; startedAt: number; openPaths?: string[]}} process
+ * @param {CodexThread[]} threads
+ * @returns {CodexThread | null}
+ */
+export function bindCodexThread({ cwd, startedAt, openPaths = [] }, threads) {
+  const open = new Set(openPaths.filter(Boolean));
+  if (open.size > 0) {
+    const byRollout = threads.filter(
+      (thread) => thread.rolloutPath && open.has(thread.rolloutPath),
+    );
+    if (byRollout.length === 1) return byRollout[0];
+    if (byRollout.length > 1) return null;
+  }
+  const normalizedCwd = String(cwd ?? "").trim();
+  if (!normalizedCwd || !Number.isFinite(startedAt) || startedAt <= 0) return null;
+  const candidates = threads.filter(
+    (thread) =>
+      thread.cwd === normalizedCwd &&
+      thread.createdAtMs > 0 &&
+      thread.createdAtMs >= startedAt - CODEX_THREAD_START_SLACK_MS,
+  );
+  return candidates.length === 1 ? candidates[0] : null;
+}
+
+/**
+ * Rollout files a process currently holds open, which is exact evidence of the session it is
+ * running.
+ * @param {number} processId
+ * @param {{readDir: (path: string) => string[]; readLink: (path: string) => string}} procfs
+ */
+export function openRolloutPaths(processId, procfs) {
+  const fdDir = path.join("/proc", String(processId), "fd");
+  const paths = [];
+  for (const entry of procfs.readDir(fdDir)) {
+    const target = procfs.readLink(path.join(fdDir, entry));
+    if (target.includes("/sessions/") && target.endsWith(".jsonl")) paths.push(target);
+  }
+  return paths;
+}

package/src/native/ghostty-tab-inventory.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+# ---
+# summary: "enumerates Ghostty windows and their tab labels through AT-SPI for hidden-tab placement"
+# read_when:
+#   - "changing how the activity strip discovers tabs hidden behind another Ghostty tab"
+# ---
+"""Print one JSON document describing every AT-SPI frame of the given process ids.
+
+Usage: ghostty-tab-inventory.py <pid> [<pid> ...]
+
+Output: {"ok": true, "frames": [{"pid": int, "name": str, "tabs": [str, ...]}, ...]}
+Exit 3 with {"ok": false, "error": ...} when the AT-SPI Python bindings are unavailable.
+The script only reads accessibility state; it never activates, selects, or focuses anything.
+"""
+
+import json
+import sys
+
+MAX_NODES_PER_FRAME = 20000
+MAX_DEPTH = 40
+
+
+def main() -> int:
+    try:
+        import gi
+
+        gi.require_version("Atspi", "2.0")
+        from gi.repository import Atspi
+    except Exception as error:  # noqa: BLE001 - any import failure means the capability is absent
+        print(json.dumps({"ok": False, "error": f"AT-SPI bindings unavailable: {error}"}))
+        return 3
+
+    pids = {int(argument) for argument in sys.argv[1:] if argument.isdigit()}
+    if not pids:
+        print(json.dumps({"ok": True, "frames": []}))
+        return 0
+
+    def tab_labels(frame):
+        labels = []
+        stack = [(frame, 0)]
+        seen = 0
+        while stack and seen < MAX_NODES_PER_FRAME:
+            node, depth = stack.pop()
+            seen += 1
+            try:
+                role = node.get_role()
+            except Exception:  # noqa: BLE001 - a vanished node is skipped
+                continue
+            if role == Atspi.Role.PAGE_TAB:
+                try:
+                    labels.append(node.get_name() or "")
+                except Exception:  # noqa: BLE001
+                    pass
+                continue
+            if depth >= MAX_DEPTH:
+                continue
+            try:
+                count = node.get_child_count()
+            except Exception:  # noqa: BLE001
+                continue
+            for index in range(count):
+                try:
+                    child = node.get_child_at_index(index)
+                except Exception:  # noqa: BLE001
+                    continue
+                if child is not None:
+                    stack.append((child, depth + 1))
+        return labels
+
+    frames = []
+    desktop = Atspi.get_desktop(0)
+    for index in range(desktop.get_child_count()):
+        application = desktop.get_child_at_index(index)
+        if application is None:
+            continue
+        try:
+            pid = application.get_process_id()
+        except Exception:  # noqa: BLE001
+            continue
+        if pid not in pids:
+            continue
+        for window_index in range(application.get_child_count()):
+            frame = application.get_child_at_index(window_index)
+            if frame is None:
+                continue
+            try:
+                if frame.get_role() != Atspi.Role.FRAME:
+                    continue
+                name = frame.get_name() or ""
+            except Exception:  # noqa: BLE001
+                continue
+            frames.append({"pid": pid, "name": name, "tabs": tab_labels(frame)})
+
+    print(json.dumps({"ok": True, "frames": frames}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())