@tryinget/pi-activity-strip 0.5.0 → 0.7.0

package/src/common/claude-events.mjs

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

package/src/common/claude-hook-config.mjs

@@ -0,0 +1,56 @@
+// ---
+// summary: "builds the Claude Code settings fragment that lets sessions publish live ribbon state"
+// read_when:
+//   - "changing which Claude Code hook events the ribbon subscribes to"
+// ---
+
+/**
+ * Only low-frequency events are hooked. Tool, thinking and idle state already come from the
+ * transcript at no cost, so nothing runs per tool call; hooks add exactly what the transcript
+ * cannot express, which is that a session is blocked waiting for the operator.
+ */
+export const CLAUDE_HOOK_EVENTS = Object.freeze([
+  "SessionStart",
+  "UserPromptSubmit",
+  "Notification",
+  "Stop",
+  "SessionEnd",
+]);
+
+/**
+ * @param {string} hookCommand absolute command Claude Code runs for each event
+ * @returns {{hooks: Record<string, Array<{matcher: string; hooks: Array<{type: "command"; command: string}>}>>}}
+ */
+export function claudeHookSettings(hookCommand) {
+  const command = String(hookCommand ?? "").trim();
+  if (!command) throw new Error("A hook command is required.");
+  /** @type {Record<string, Array<{matcher: string; hooks: Array<{type: "command"; command: string}>}>>} */
+  const hooks = {};
+  for (const event of CLAUDE_HOOK_EVENTS) {
+    hooks[event] = [{ matcher: "", hooks: [{ type: "command", command }] }];
+  }
+  return { hooks };
+}
+
+/**
+ * Merge the ribbon's hooks into existing settings without disturbing unrelated configuration or
+ * duplicating an entry that already runs this exact command.
+ * @param {Record<string, any>} settings
+ * @param {string} hookCommand
+ */
+export function mergeClaudeHookSettings(settings, hookCommand) {
+  const desired = claudeHookSettings(hookCommand);
+  const merged = { ...(settings ?? {}) };
+  const existingHooks = { ...(merged.hooks ?? {}) };
+  for (const [event, entries] of Object.entries(desired.hooks)) {
+    const current = Array.isArray(existingHooks[event]) ? [...existingHooks[event]] : [];
+    const alreadyPresent = current.some((entry) =>
+      (entry?.hooks ?? []).some(
+        /** @param {any} hook */ (hook) => String(hook?.command ?? "") === hookCommand,
+      ),
+    );
+    existingHooks[event] = alreadyPresent ? current : [...current, ...entries];
+  }
+  merged.hooks = existingHooks;
+  return merged;
+}

package/src/common/claude-transcript.mjs

@@ -0,0 +1,163 @@
+// ---
+// summary: "derives live Claude Code session state from the tail of its transcript"
+// read_when:
+//   - "changing Claude Code card telemetry or the transcript records it depends on"
+// ---
+
+/**
+ * Claude Code appends newline-delimited records to a per-session transcript. The format is internal
+ * to Claude Code and carries no stability guarantee, so every field is optional here and a record
+ * that does not parse is skipped. When nothing usable is found the caller keeps the process-only
+ * card rather than inventing activity.
+ */
+
+const PREVIEW_LIMIT = 100;
+const DETAIL_LIMIT = 100;
+
+/** @typedef {"idle" | "thinking" | "tool"} ClaudeState */
+/**
+ * @typedef {{
+ *   title: string; lastPrompt: string; assistantPreview: string; state: ClaudeState;
+ *   toolName: string; toolTarget: string; turnIndex: number; lastEventAt: number;
+ *   mode: string; permissionMode: string; sessionId: string; cwd: string; gitBranch: string;
+ * }} ClaudeTelemetry
+ */
+
+/** @param {unknown} value @param {number} limit */
+function preview(value, limit) {
+  const text = String(value ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+
+/** @param {unknown} value */
+function timestampMs(value) {
+  const parsed = Date.parse(String(value ?? ""));
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+/** @param {any} record */
+function contentBlocks(record) {
+  const content = record?.message?.content;
+  return Array.isArray(content) ? content : [];
+}
+
+/**
+ * Name the thing a tool call is acting on, preferring the fields that read well on a card.
+ * @param {any} block
+ */
+export function describeToolTarget(block) {
+  const input = block?.input ?? {};
+  for (const key of ["description", "command", "file_path", "path", "pattern", "query", "url"]) {
+    const value = input?.[key];
+    if (typeof value === "string" && value.trim()) return preview(value, DETAIL_LIMIT);
+  }
+  return "";
+}
+
+/** @returns {ClaudeTelemetry} */
+function emptyTelemetry() {
+  return {
+    title: "",
+    lastPrompt: "",
+    assistantPreview: "",
+    state: "idle",
+    toolName: "",
+    toolTarget: "",
+    turnIndex: 0,
+    lastEventAt: 0,
+    mode: "",
+    permissionMode: "",
+    sessionId: "",
+    cwd: "",
+    gitBranch: "",
+  };
+}
+
+/**
+ * Read the tail of a transcript. The first line is usually a fragment and is skipped by the parse
+ * failure path. State comes from the newest record that carries a timestamp, because the latched
+ * records Claude Code rewrites after every turn have none and would otherwise mask real activity.
+ * @param {string} tail
+ * @returns {ClaudeTelemetry}
+ */
+export function parseClaudeTranscriptTail(tail) {
+  const telemetry = emptyTelemetry();
+  if (!tail) return telemetry;
+
+  /** @type {any[]} */
+  const records = [];
+  for (const line of String(tail).split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{")) continue;
+    try {
+      records.push(JSON.parse(trimmed));
+    } catch {
+      // A truncated first line or a partially written last line is not evidence.
+    }
+  }
+  if (records.length === 0) return telemetry;
+
+  for (const record of records) {
+    switch (record?.type) {
+      case "ai-title":
+        if (typeof record.aiTitle === "string") telemetry.title = record.aiTitle;
+        break;
+      case "last-prompt":
+        telemetry.lastPrompt = preview(record.lastPrompt, PREVIEW_LIMIT);
+        break;
+      case "mode":
+        telemetry.mode = String(record.mode ?? "");
+        break;
+      case "permission-mode":
+        telemetry.permissionMode = String(record.permissionMode ?? "");
+        break;
+      case "system":
+        if (record.subtype === "turn_duration" && Number.isFinite(Number(record.messageCount))) {
+          telemetry.turnIndex = Number(record.messageCount);
+        }
+        break;
+      default:
+        break;
+    }
+    if (typeof record?.sessionId === "string") telemetry.sessionId = record.sessionId;
+    if (typeof record?.cwd === "string") telemetry.cwd = record.cwd;
+    if (typeof record?.gitBranch === "string") telemetry.gitBranch = record.gitBranch;
+    if (record?.type === "assistant") {
+      const text = contentBlocks(record)
+        .filter((block) => block?.type === "text" && typeof block.text === "string")
+        .map((block) => block.text)
+        .join(" ");
+      if (text.trim()) telemetry.assistantPreview = preview(text, PREVIEW_LIMIT);
+    }
+  }
+
+  const timed = records.filter(
+    (record) => record?.type !== "attachment" && timestampMs(record?.timestamp) > 0,
+  );
+  const latest = timed.at(-1);
+  if (!latest) return telemetry;
+  telemetry.lastEventAt = timestampMs(latest.timestamp);
+
+  if (latest.type === "system" && latest.subtype === "turn_duration") {
+    telemetry.state = "idle";
+    return telemetry;
+  }
+  if (latest.type === "assistant") {
+    const toolBlock = contentBlocks(latest).find((block) => block?.type === "tool_use");
+    if (toolBlock) {
+      telemetry.state = "tool";
+      telemetry.toolName = String(toolBlock.name ?? "");
+      telemetry.toolTarget = describeToolTarget(toolBlock);
+      return telemetry;
+    }
+    telemetry.state = latest.message?.stop_reason === "end_turn" ? "idle" : "thinking";
+    return telemetry;
+  }
+  if (latest.type === "user") {
+    telemetry.state = "thinking";
+    return telemetry;
+  }
+  return telemetry;
+}

package/src/common/codex-transcript.mjs

@@ -0,0 +1,153 @@
+// ---
+// summary: "derives live Codex session state from the tail of its rollout file"
+// read_when:
+//   - "changing Codex card telemetry or the rollout records it depends on"
+// ---
+
+/**
+ * Codex appends newline-delimited records to a per-session rollout. Every record carries a
+ * top-level `timestamp`, a `type` of `session_meta`, `turn_context`, `event_msg` or
+ * `response_item`, and a `payload` whose own `type` names the event. The format belongs to Codex
+ * and carries no stability guarantee, so every field is optional here and an unparseable record is
+ * skipped. When nothing usable is found the caller keeps the process-only card.
+ */
+
+const PREVIEW_LIMIT = 100;
+const TOOL_ARGUMENT_KEYS = ["cmd", "command", "query", "path", "file_path", "pattern", "workdir"];
+
+/** @typedef {import("./claude-transcript.mjs").ClaudeTelemetry} AgentTelemetry */
+
+/** @param {unknown} value */
+function preview(value) {
+  const text = String(value ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return text.length > PREVIEW_LIMIT ? `${text.slice(0, PREVIEW_LIMIT - 1)}…` : text;
+}
+
+/** @param {unknown} value */
+function timestampMs(value) {
+  const parsed = Date.parse(String(value ?? ""));
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+/**
+ * Name what a Codex tool call is acting on. Arguments arrive as a JSON string, and a call whose
+ * arguments do not parse still reports its tool name.
+ * @param {any} payload
+ */
+export function describeCodexToolTarget(payload) {
+  let args = payload?.arguments;
+  if (typeof args === "string") {
+    try {
+      args = JSON.parse(args);
+    } catch {
+      return preview(args);
+    }
+  }
+  if (!args || typeof args !== "object") return "";
+  for (const key of TOOL_ARGUMENT_KEYS) {
+    const value = args[key];
+    if (typeof value === "string" && value.trim()) return preview(value);
+    if (Array.isArray(value) && value.length > 0) return preview(value.join(" "));
+  }
+  return "";
+}
+
+/** @param {any} payload */
+function toolNameFor(payload) {
+  const type = String(payload?.type ?? "");
+  if (type === "function_call" || type === "custom_tool_call") {
+    return String(payload?.name ?? "") || "tool";
+  }
+  if (type === "local_shell_call") return "shell";
+  if (type === "web_search_call") return "web_search";
+  return "";
+}
+
+/** @returns {AgentTelemetry} */
+function emptyTelemetry() {
+  return {
+    title: "",
+    lastPrompt: "",
+    assistantPreview: "",
+    state: "idle",
+    toolName: "",
+    toolTarget: "",
+    turnIndex: 0,
+    lastEventAt: 0,
+    mode: "",
+    permissionMode: "",
+    sessionId: "",
+    cwd: "",
+    gitBranch: "",
+  };
+}
+
+/**
+ * Read the tail of a rollout. The first line is usually a fragment and is skipped by the parse
+ * failure path. State comes from the newest record that carries a timestamp, so a tool call is
+ * reported as running only while it is still the newest record; its output lands after it.
+ * @param {string} tail
+ * @returns {AgentTelemetry}
+ */
+export function parseCodexRolloutTail(tail) {
+  const telemetry = emptyTelemetry();
+  if (!tail) return telemetry;
+
+  /** @type {any[]} */
+  const records = [];
+  for (const line of String(tail).split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{")) continue;
+    try {
+      records.push(JSON.parse(trimmed));
+    } catch {
+      // A truncated first or last line is not evidence.
+    }
+  }
+  if (records.length === 0) return telemetry;
+
+  for (const record of records) {
+    const payload = record?.payload;
+    const payloadType = String(payload?.type ?? "");
+    if (record?.type === "session_meta") {
+      telemetry.sessionId = String(payload?.id ?? telemetry.sessionId);
+      telemetry.cwd = String(payload?.cwd ?? telemetry.cwd);
+      const branch = payload?.git?.branch;
+      if (typeof branch === "string") telemetry.gitBranch = branch;
+    } else if (record?.type === "turn_context") {
+      telemetry.cwd = String(payload?.cwd ?? telemetry.cwd);
+      telemetry.mode = String(payload?.approval_policy ?? telemetry.mode);
+      const sandbox = payload?.sandbox_policy?.type;
+      if (typeof sandbox === "string") telemetry.permissionMode = sandbox;
+    } else if (payloadType === "user_message") {
+      telemetry.lastPrompt = preview(payload?.message);
+    } else if (payloadType === "agent_message") {
+      telemetry.assistantPreview = preview(payload?.message);
+    } else if (payloadType === "task_complete") {
+      telemetry.turnIndex += 1;
+      if (payload?.last_agent_message) {
+        telemetry.assistantPreview = preview(payload.last_agent_message);
+      }
+    }
+  }
+
+  const timed = records.filter((record) => timestampMs(record?.timestamp) > 0);
+  const latest = timed.at(-1);
+  if (!latest) return telemetry;
+  telemetry.lastEventAt = timestampMs(latest.timestamp);
+
+  const payload = latest.payload;
+  const payloadType = String(payload?.type ?? "");
+  // A tool call that is the newest record is still running: its output would appear after it.
+  const toolName = toolNameFor(payload);
+  if (toolName) {
+    telemetry.state = "tool";
+    telemetry.toolName = toolName;
+    telemetry.toolTarget = describeCodexToolTarget(payload);
+    return telemetry;
+  }
+  telemetry.state = payloadType === "task_complete" ? "idle" : "thinking";
+  return telemetry;
+}

package/src/common/compatibility.mjs

@@ -6,6 +6,7 @@
 
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { detectTabInventorySupport } from "../native/tab-inventory.mjs";
 
 const execFileAsync = promisify(execFile);
 
@@ -83,6 +84,10 @@ export async function assessActivityStripCompatibility(options = {}) {
     env,
     execFileAsyncImpl: options.execFileAsyncImpl,
   });
+  const tabInventory = await detectTabInventorySupport({
+    execFileAsync: options.execFileAsyncImpl ?? execFileAsync,
+    env,
+  });
   const blockers = [];
   const warnings = [];
 
@@ -117,6 +122,12 @@ export async function assessActivityStripCompatibility(options = {}) {
     );
   }
 
+  if (windowManager === "niri" && !tabInventory.available) {
+    warnings.push(
+      `Hidden Ghostty tabs that were never shown cannot be placed: ${tabInventory.detail}. Tabs shown while the strip runs are still remembered.`,
+    );
+  }
+
   return {
     ok: blockers.length === 0,
     backend,
@@ -126,6 +137,7 @@ export async function assessActivityStripCompatibility(options = {}) {
     alignmentMode: "layer-shell",
     primaryDisplayOnly: true,
     clickThroughDefault: env.PI_ACTIVITY_STRIP_CLICK_THROUGH === "1",
+    tabInventory,
     blockers,
     warnings,
   };
@@ -143,6 +155,7 @@ export function formatCompatibilityReport(report) {
     `Alignment mode: ${report.alignmentMode}`,
     `Primary-display only: ${report.primaryDisplayOnly ? "yes" : "no"}`,
     `Click-through mode: ${report.clickThroughDefault ? "enabled by environment" : "disabled (interactive default)"}`,
+    `Hidden-tab inventory: ${report.tabInventory?.available ? "available" : "unavailable"} (${report.tabInventory?.detail ?? "unknown"})`,
   ];
 
   if (typeof report.displayCount === "number") {

package/src/common/constants.mjs

@@ -25,5 +25,7 @@ export const ACTIVITY_STRIP_BROADCAST_TICK_MS = 1000;
 export const ACTIVITY_STRIP_SEND_THROTTLE_MS = 120;
 export const ACTIVITY_STRIP_CONNECT_TIMEOUT_MS = 450;
 export const ACTIVITY_STRIP_START_TIMEOUT_MS = 5000;
+/** How long `stop` waits for the runtime to exit; an in-flight read-only `ak` query can take 8 s. */
+export const ACTIVITY_STRIP_STOP_TIMEOUT_MS = 15_000;
 export const ACTIVITY_STRIP_EVENT_STALL_MS = 15 * 60_000;
 export const ACTIVITY_STRIP_FLUSH_RETRY_DELAYS_MS = [250, 750];

package/src/common/contracts.d.ts

@@ -19,6 +19,15 @@ export interface SessionSnapshot {
   publisherCount?: number;
   publisherIds?: string[];
   publisherRecordKeys?: string[];
+  publisherSessionIds?: string[];
+  akTasks?: AkTaskChip[];
+  akTaskOverflow?: number;
+  /** Niri window id; for a hidden tab, the window hosting it. */
+  windowId?: number | null;
+  /** Niri workspace `idx`, the number the operator sees, never the internal workspace id. */
+  workspaceIdx?: number | null;
+  placement?: "title" | "host" | "binding";
+  surfaceVisible?: boolean;
   cwd: string;
   repoLabel: string;
   sessionName: string;
@@ -38,6 +47,32 @@ export interface SessionSnapshot {
   errorMessage: string;
 }
 
+export type AkTaskChipState = "active" | "deferred" | "orphaned";
+
+/** One read-only AK task reference joined onto a terminal card by the native projection. */
+export interface AkTaskChip {
+  id: number;
+  title: string;
+  state: AkTaskChipState;
+}
+
+/** A live-lease task claim parsed from read-only `ak task list` output. */
+export interface AkTaskClaim {
+  id: number;
+  title: string;
+  repo: string;
+  sessionId: string;
+  leaseExpiresAt: number;
+  claimedAt: number;
+}
+
+/** A task with an active deferral parsed from read-only `ak task deferred` output. */
+export interface AkTaskDeferred {
+  id: number;
+  title: string;
+  repo: string;
+}
+
 export interface BrokerSnapshot {
   generatedAt: number;
   sessions: SessionSnapshot[];