@tryinget/pi-activity-strip 0.8.0 → 0.10.0

package/src/common/ribbon-status.mjs

@@ -0,0 +1,41 @@
+// ---
+// summary: "renders only allowlisted ribbon observation fields, never arbitrary diagnostic text"
+// read_when:
+//   - "changing diagnostic output or its redaction boundary"
+// ---
+
+import { normalizeKeyboardObservation } from "./keyboard-observation.mjs";
+
+/** @param {unknown} value @param {string[]} allowed */
+const enumValue = (value, allowed) =>
+  typeof value === "string" && allowed.includes(value) ? value : "unknown";
+/** @param {unknown} value */
+const hashValue = (value) =>
+  typeof value === "string" && /^[a-f0-9]{64}$/.test(value) ? value : "unknown";
+
+/** @param {import("./contracts.ts").ActivityStripRuntimeStatus["ribbonDiagnostics"]} diagnostics */
+export function formatRibbonDiagnostics(diagnostics) {
+  if (!diagnostics) return ["ribbon diagnostics: not reported by this controller"];
+  const build = diagnostics.panelBuild;
+  const native = normalizeKeyboardObservation({
+    ...diagnostics.nativeKeyboardObservation,
+    protocol: 2,
+    type: "keyboard-observation",
+  });
+  return [
+    `visibility reason: ${enumValue(diagnostics.visibilityReason, ["starting", "error", "unproven-focus", "non-agent-focus", "no-admitted-owner", "awaiting-panel-visibility", "eligible-agent-context", "eligible-presence-context", "persistent-workspace"])}`,
+    `keyboard authorization: ${enumValue(diagnostics.keyboardAuthorization, ["none", "hover", "explicit"])} (not proof of capture)`,
+    ...(native
+      ? [
+          `capture expiry: last native observation (${native.origin}; ${native.reason}), not current authority`,
+          `native monotonic ms: ${native.nativeMs}; idle deadline ms: ${native.deadlineMs ?? "not applicable (explicit)"}; request: ${native.request} (same native process clock only; not a countdown)`,
+        ]
+      : ["capture expiry: not observed (native monotonic clock)"]),
+    `private protocol: expected ${Number.isSafeInteger(diagnostics.expectedPrivateProtocol) ? diagnostics.expectedPrivateProtocol : "unknown"}, receipt ${Number.isSafeInteger(build?.privateProtocol) ? build.privateProtocol : "unknown"}`,
+    `panel receipt: ${enumValue(build?.state, ["pending", "unavailable", "changed-during-observation", "incompatible", "receipt-matched", "receipt-mismatch"])}`,
+    `panel PID executable sha256: ${hashValue(build?.binarySha256)} (sampled; not custody proof)`,
+    `panel build sampled at: ${Number.isSafeInteger(diagnostics.panelBuildObservedAt) ? diagnostics.panelBuildObservedAt : "unknown"} (stale after process changes)`,
+    `receipted native source sha256: ${hashValue(build?.receiptedSourceSha256)}`,
+    `controller startup source sha256: ${hashValue(diagnostics.controllerStartupSourceSha256)} (observation, not loaded-byte proof)`,
+  ];
+}

package/src/common/status-report.mjs

@@ -6,6 +6,24 @@
 
 /** @typedef {import("./contracts.ts").BrokerResponse} BrokerResponse */
 
+import { formatRibbonDiagnostics } from "./ribbon-status.mjs";
+
+/**
+ * When the AK deferral list was read and how long it may be reused; empty for unusable values.
+ * @param {{akTaskDeferredReadAt?: number | null; akTaskDeferredMaxAgeMs?: number}} runtime
+ */
+function deferralListAge(runtime) {
+  const readAt = runtime.akTaskDeferredReadAt;
+  if (typeof readAt !== "number" || !Number.isFinite(readAt) || Math.abs(readAt) > 8.64e15)
+    return "";
+  const maxAge = runtime.akTaskDeferredMaxAgeMs;
+  const reuse =
+    typeof maxAge === "number" && Number.isFinite(maxAge) && maxAge > 0
+      ? `, reused up to ${Math.round(maxAge / 1000)} s`
+      : "";
+  return `; deferral list read ${new Date(readAt).toISOString()}${reuse}`;
+}
+
 /** @param {BrokerResponse | null | undefined} result */
 export function formatBrokerRuntimeStatus(result) {
   if (!result?.ok) return "stopped";
@@ -26,6 +44,14 @@ export function formatBrokerRuntimeStatus(result) {
   if (typeof runtime.windowVisible === "boolean") {
     lines.push(`surface visible: ${runtime.windowVisible ? "yes" : "no"}`);
   }
+  if (typeof runtime.panelExpanded === "boolean") {
+    lines.push(
+      runtime.panelExpanded && runtime.windowVisible === false
+        ? "expansion: stale (hidden surface)"
+        : `expansion: ${runtime.panelExpanded ? "expanded" : "compact"} (reported; cause not observed)`,
+    );
+  }
+  lines.push(...formatRibbonDiagnostics(runtime.ribbonDiagnostics));
   if (typeof runtime.rendererCardCount === "number") {
     const hidden =
       typeof runtime.rendererHiddenTabCardCount === "number"
@@ -64,7 +90,7 @@ export function formatBrokerRuntimeStatus(result) {
     if (runtime.akTaskState === "ok") {
       const orphaned = Number(runtime.akTaskOrphanCount ?? 0);
       lines.push(
-        `AK task refs: ok (${runtime.akTaskClaimCount ?? 0} live claims, ${runtime.akTaskDeferredCount ?? 0} deferred${orphaned > 0 ? `, ${orphaned} orphaned claims` : ""})`,
+        `AK task refs: ok (${runtime.akTaskClaimCount ?? 0} live claims, ${runtime.akTaskDeferredCount ?? 0} deferred${orphaned > 0 ? `, ${orphaned} orphaned claims` : ""}${deferralListAge(runtime)})`,
       );
     } else if (runtime.akTaskState !== "disabled") {
       lines.push(
@@ -101,10 +127,19 @@ export function summarizeBrokerRuntimeStatus(result) {
 
   const runtime = result.runtimeStatus;
   if (!runtime) {
-    return { headline: "Activity strip is running", level: "info" };
+    return {
+      headline: "Activity strip broker is running; overlay readiness is unknown",
+      level: "warning",
+    };
   }
 
   if (runtime.state === "ready") {
+    if (runtime.tabInventoryState === "failed" || runtime.tabInventoryState === "unavailable") {
+      return {
+        headline: `Activity strip overlay is ready; tab inventory ${runtime.tabInventoryState}`,
+        level: "warning",
+      };
+    }
     return { headline: "Activity strip is running and ready", level: "info" };
   }
 

package/src/common/workspace-view.mjs

@@ -5,6 +5,7 @@
 // ---
 
 import { canVerifyTabVisibility, placeSessionWindow } from "./niri-focus.mjs";
+import { isPresenceApp } from "./presence-apps.mjs";
 import { projectSessionCards, sessionCardId } from "./session-cards.mjs";
 import { parseTerminalTitleBinding } from "./surface-bindings.mjs";
 import { canonicalGhosttyTerminalKey } from "./terminal-identity.mjs";
@@ -40,6 +41,50 @@ export function resolveSurfaceVisibility(window, session, placement, options = {
   return "unknown";
 }
 
+/** @typedef {"agent" | "neutral" | "non-agent" | "unknown" | "none"} FocusKind */
+/**
+ * Classify exact admitted Niri ownership, never app-id/title heuristics. Card ownership alone
+ * makes a window "agent"; a focused presence application that owns no exact card is "neutral":
+ * the strip stays on screen over it and the window itself, not a card, is the interaction source.
+ * @param {Array<Record<string, unknown>>} windows
+ * @param {Record<string, unknown>} workspace
+ * @param {Array<Record<string, unknown>>} cards
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {FocusKind}
+ */
+export function classifyWorkspaceFocus(windows, workspace, cards, env = process.env) {
+  if (
+    windows.some(
+      (window) => !Number.isInteger(window?.id) || typeof window?.is_focused !== "boolean",
+    )
+  )
+    return "unknown";
+  const focused = windows.filter((window) => window.is_focused === true);
+  // Niri retains an active window while an exclusive layer surface owns the keyboard. NULL
+  // alone is not ownership: only the controller's pending explicit request can admit it.
+  if (focused.length === 0) return windows.length > 0 ? "none" : "unknown";
+  if (focused.length !== 1) return "unknown";
+  const window = focused[0];
+  if (!Number.isInteger(window.id) || window.workspace_id !== workspace.id) return "unknown";
+  return classifyAdmittedWindowFocus(Number(window.id), cards, window, env);
+}
+
+/** Exact Niri focus events may update eligibility before a slower full projection finishes.
+ * Without the window's own facts presence cannot be proven, so the strict result stands.
+ * @param {number} windowId @param {Array<Record<string, unknown>>} cards
+ * @param {Record<string, unknown> | null} [window] @param {NodeJS.ProcessEnv} [env]
+ * @returns {FocusKind}
+ */
+export function classifyAdmittedWindowFocus(windowId, cards, window = null, env = process.env) {
+  if (!Number.isInteger(windowId)) return "unknown";
+  const visible = cards.filter(
+    (card) => card.windowId === windowId && card.surfaceVisible !== false,
+  ).length;
+  if (visible === 1) return "agent";
+  if (window?.id === windowId && isPresenceApp(window.app_id, env)) return "neutral";
+  return visible === 0 ? "non-agent" : "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.
@@ -129,8 +174,17 @@ export function resolveWorkspaceView(windows, workspace, sessions, options = {})
       windows.some((window) => window?.id === session.windowId && window?.is_focused === true),
   );
   const focusedCard = focusedCandidates.length === 1 ? focusedCandidates[0] : null;
+  const focusedWindows = windows.filter((window) => window?.is_focused === true);
+  const focusWindow =
+    focusedWindows.length === 1 &&
+    Number.isInteger(focusedWindows[0]?.id) &&
+    focusedWindows[0].workspace_id === workspace.id
+      ? Number(focusedWindows[0].id)
+      : null;
   return {
     workspace,
+    focusKind: classifyWorkspaceFocus(windows, workspace, projectedSessions, options.env),
+    focusWindowId: focusWindow,
     sessions: projectedSessions,
     focusedSessionId: focusedCard ? String(focusedCard.sessionId ?? "") || null : null,
     focusedCardId: focusedCard ? String(focusedCard.cardId ?? "") || null : null,
@@ -149,6 +203,70 @@ export function resolveFocusedWorkspaceView(windows, workspaces, sessions, optio
   return workspace ? resolveWorkspaceView(windows, workspace, sessions, options) : null;
 }
 
+/**
+ * @typedef {{
+ *   cardId: string;
+ *   label: string;
+ *   windowId: number;
+ *   workspaceId: number;
+ *   workspaceIdx: number | null;
+ *   workspaceName: string | null;
+ *   hiddenTab: boolean;
+ *   current: boolean;
+ * }} WindowDirectoryEntry
+ */
+
+/**
+ * Every agent window on every workspace, for the ribbon's window list. It reuses the per-workspace
+ * card projection, so an entry exists exactly when that workspace would show the card. Ordered
+ * alphabetically by project name, then by window number; each entry carries its workspace.
+ * @param {Array<Record<string, unknown>>} windows
+ * @param {Array<Record<string, unknown>>} workspaces
+ * @param {Array<Record<string, unknown>>} sessions
+ * @param {ResolveOptions} [options]
+ * @returns {{entries: WindowDirectoryEntry[]; cards: Map<string, Record<string, unknown>>}}
+ */
+export function resolveWindowDirectory(windows, workspaces, sessions, options = {}) {
+  const ordered = workspaces
+    .filter((workspace) => Number.isInteger(workspace?.id))
+    .sort(
+      (a, b) =>
+        String(a.output ?? "").localeCompare(String(b.output ?? "")) ||
+        Number(a.idx ?? 0) - Number(b.idx ?? 0),
+    );
+  /** @type {WindowDirectoryEntry[]} */
+  const entries = [];
+  /** @type {Map<string, Record<string, unknown>>} */
+  const cards = new Map();
+  for (const workspace of ordered) {
+    const view = resolveWorkspaceView(windows, workspace, sessions, options);
+    if (!view) continue;
+    const placed = view.sessions
+      .filter((card) => Number.isInteger(card.windowId))
+      .sort((a, b) => Number(a.windowId) - Number(b.windowId));
+    for (const card of placed) {
+      const cardId = String(card.cardId ?? "");
+      if (!cardId || cards.has(cardId)) continue;
+      cards.set(cardId, card);
+      entries.push({
+        cardId,
+        label: String(card.repoLabel || "session"),
+        windowId: Number(card.windowId),
+        workspaceId: Number(workspace.id),
+        workspaceIdx: Number.isInteger(card.workspaceIdx) ? Number(card.workspaceIdx) : null,
+        workspaceName: typeof workspace.name === "string" ? workspace.name : null,
+        hiddenTab: card.surfaceVisible === false,
+        current: cardId === view.focusedCardId,
+      });
+    }
+  }
+  entries.sort(
+    (a, b) =>
+      a.label.localeCompare(b.label, undefined, { sensitivity: "base" }) || a.windowId - b.windowId,
+  );
+  return { entries, cards };
+}
+
 /** @param {Array<Record<string, unknown>>} workspaces */
 export function resolveFocusedNiriWorkspace(workspaces) {
   const matches = workspaces.filter(

package/src/native/ak-runtime.mjs

@@ -13,6 +13,14 @@ import {
 
 /** AK state changes are rare; a calm clock keeps the ribbon cheap. */
 export const AK_TASK_REFRESH_MS = 15_000;
+/**
+ * The full deferral list held the workstation-wide AK lock 3.3 s of every 15 s (AK7943): reuse the
+ * last good list for up to five minutes while claims keep the 15 s clock. It is read only after the
+ * claims read succeeds, is dropped when its own read fails, expires when the clock steps back, and is
+ * reread at once when a newer live claim names a task it still holds as deferred (AK refuses to
+ * claim a task with an active deferral, so that claim proves the list stale).
+ */
+export const AK_DEFERRED_REFRESH_MS = 300_000;
 const AK_EXEC_TIMEOUT_MS = 8000;
 const AK_EXEC_MAX_BUFFER = 4 * 1024 * 1024;
 
@@ -40,6 +48,8 @@ export function createAkTaskRuntime({
   /** @type {NodeJS.Timeout | null} */
   let timer = null;
   let inFlight = false;
+  /** @type {{at: number; deferred: import("../common/contracts.ts").AkTaskDeferred[]} | null} */
+  let deferredCache = null;
 
   runtimeStatus.akTaskState = disabled ? "disabled" : (runtimeStatus.akTaskState ?? "pending");
   runtimeStatus.akTaskError = runtimeStatus.akTaskError ?? null;
@@ -63,32 +73,61 @@ export function createAkTaskRuntime({
   /**
    * @param {string} error
    */
-  function failClosed(error) {
+  function failClosed(error, { keepDeferred = false } = {}) {
     runtimeStatus.akTaskState = "unavailable";
     runtimeStatus.akTaskError = error;
     runtimeStatus.akTaskClaimCount = 0;
     runtimeStatus.akTaskDeferredCount = 0;
+    runtimeStatus.akTaskDeferredReadAt = null;
+    if (!keepDeferred) deferredCache = null;
     onChange({ claims: [], deferred: [] });
   }
 
   async function refresh() {
     if (disabled || inFlight) return false;
     inFlight = true;
+    let phase = "claims";
     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);
+      const readAt = now();
+      // Claims first: a failing or contended claim read never also spends the deferral read.
+      const claims = parseAkClaimList(
+        await readCli([
+          "task",
+          "list",
+          "--status",
+          "claimed",
+          "--format",
+          "json",
+          "--all",
+          "--verbose",
+        ]),
+      );
       if (!claims.ok) {
-        failClosed(claims.error);
+        failClosed(claims.error, { keepDeferred: true });
         return false;
       }
+      const cache = deferredCache;
+      const cachedIds = new Set(cache ? cache.deferred.map((task) => task.id) : []);
+      const contradicted =
+        cache !== null &&
+        claims.claims.some(
+          (claim) =>
+            cachedIds.has(claim.id) && claim.claimedAt > cache.at && claimIsLive(claim, readAt),
+        );
+      const age = cache ? readAt - cache.at : Number.NaN;
+      const fresh =
+        cache && !contradicted && age >= 0 && age < AK_DEFERRED_REFRESH_MS ? cache : null;
+      phase = "deferred";
+      const deferred = fresh
+        ? { ok: /** @type {const} */ (true), deferred: fresh.deferred }
+        : parseAkDeferredList(await readCli(["task", "deferred", "--format", "json", "--all"]));
       if (!deferred.ok) {
         failClosed(deferred.error);
         return false;
       }
+      deferredCache = fresh ?? { at: readAt, deferred: deferred.deferred };
+      runtimeStatus.akTaskDeferredReadAt = deferredCache.at;
+      runtimeStatus.akTaskDeferredMaxAgeMs = AK_DEFERRED_REFRESH_MS;
       runtimeStatus.akTaskState = "ok";
       runtimeStatus.akTaskError = null;
       runtimeStatus.akTaskClaimCount = claims.claims.filter((claim) =>
@@ -98,7 +137,9 @@ export function createAkTaskRuntime({
       onChange({ claims: claims.claims, deferred: deferred.deferred });
       return true;
     } catch (error) {
-      failClosed(`ak CLI unavailable: ${error instanceof Error ? error.message : String(error)}`);
+      failClosed(`ak CLI unavailable: ${error instanceof Error ? error.message : String(error)}`, {
+        keepDeferred: phase === "claims",
+      });
       return false;
     } finally {
       inFlight = false;

package/src/native/focus-visibility.mjs

@@ -0,0 +1,67 @@
+/** @typedef {import("../common/workspace-view.mjs").FocusKind} FocusKind */
+/** Controller-authorized hover/explicit ownership across transient Niri NULL focus. */
+export function createFocusVisibility() {
+  /** @type {FocusKind} */
+  let focus = "unknown";
+  /** @type {unknown} */
+  let workspaceId = null;
+  /** @type {number | null} */
+  let keyboardRequest = null;
+  let eligible = false;
+  /** @type {"none" | "hover" | "explicit"} */
+  let mode = "none";
+  /** @type {number | null} */
+  let hoverToken = null;
+  /** A window the strip may stay present over and take an interaction source from. */
+  const isSource = (/** @type {FocusKind} */ kind) => kind === "agent" || kind === "neutral";
+  function reset() {
+    keyboardRequest = null;
+    mode = "none";
+    hoverToken = null;
+    if (!isSource(focus)) eligible = false;
+  }
+  return {
+    /** @param {{workspaceId: unknown; focus: FocusKind; hasCards: boolean}} next */
+    observe(next) {
+      if (
+        next.workspaceId !== workspaceId ||
+        !next.hasCards ||
+        !(isSource(next.focus) || next.focus === "none")
+      )
+        reset();
+      workspaceId = next.workspaceId;
+      focus = next.focus;
+      eligible =
+        next.hasCards && (isSource(focus) || (focus === "none" && keyboardRequest !== null));
+      return eligible;
+    },
+    /** Reserve BEFORE the panel write: NULL may precede the acknowledgement.
+     * @param {number} request @param {boolean} clickThrough
+     * @param {"hover" | "explicit"} [kind] @param {number | null} [token]
+     */
+    requestKeyboard(request, clickThrough, kind = "explicit", token = null) {
+      if (!eligible || clickThrough || (kind === "hover" && mode !== "none")) return false;
+      keyboardRequest = request;
+      mode = kind;
+      hoverToken = kind === "hover" ? token : null;
+      return true;
+    },
+    /** Late acknowledgements cannot revive invalidated ownership. @param {number} request @param {boolean} active */
+    keyboardChanged(request, active) {
+      if (request !== keyboardRequest) return false;
+      if (!active) reset();
+      return true;
+    },
+    resetKeyboard: reset,
+    /** Never cancel a newer hover or explicit upgrade. @param {number} token */
+    cancelHover(token) {
+      if (mode !== "hover" || token !== hoverToken) return false;
+      reset();
+      return true;
+    },
+    keyboardMode: () => mode,
+    /** @param {number} request */
+    ownsRequest: (request) => request === keyboardRequest,
+    isEligible: () => eligible,
+  };
+}

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

@@ -9,7 +9,8 @@
 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.
+Failures emit {"ok": false, "stage": fixed_label, "reason": fixed_label}.
+Exit 3 only when the AT-SPI Python bindings are unavailable; enumeration failures exit 1.
 The script only reads accessibility state; it never activates, selects, or focuses anything.
 """
 
@@ -20,15 +21,19 @@ MAX_NODES_PER_FRAME = 20000
 MAX_DEPTH = 40
 
 
+def fail(stage, reason, code=1):
+    print(json.dumps({"ok": False, "stage": stage, "reason": reason}))
+    return code
+
+
 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
+    except Exception:  # noqa: BLE001 - any import failure means the capability is absent
+        return fail("import", "bindings-unavailable", 3)
 
     pids = {int(argument) for argument in sys.argv[1:] if argument.isdigit()}
     if not pids:
@@ -68,29 +73,41 @@ def main() -> int:
         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:
+    stage = "desktop-lookup"
+    try:
+        desktop = Atspi.get_desktop(0)
+        if desktop is None:
+            return fail(stage, "desktop-unavailable")
+        stage = "desktop-count"
+        application_count = desktop.get_child_count()
+        for index in range(application_count):
+            stage = "desktop-index"
+            application = desktop.get_child_at_index(index)
+            if application is None:
                 continue
             try:
-                if frame.get_role() != Atspi.Role.FRAME:
-                    continue
-                name = frame.get_name() or ""
+                pid = application.get_process_id()
             except Exception:  # noqa: BLE001
                 continue
-            frames.append({"pid": pid, "name": name, "tabs": tab_labels(frame)})
-
+            if pid not in pids:
+                continue
+            stage = "application-count"
+            window_count = application.get_child_count()
+            for window_index in range(window_count):
+                stage = "application-index"
+                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)})
+    except Exception as error:  # noqa: BLE001 - never report a partial top-level inventory
+        reason = "access-denied" if isinstance(error, PermissionError) else "enumeration-failed"
+        return fail(stage, reason)
     print(json.dumps({"ok": True, "frames": frames}))
     return 0
 

package/src/native/hover-keyboard.mjs

@@ -0,0 +1,32 @@
+/** Bounded panel-request/controller-grant handshake, using the production admission state.
+ * No GTK focus signal is an authority source. No deferred command is queued on write failure.
+ * @param {{
+ * projection: ReturnType<typeof import("./panel-projection.mjs").createNativePanelProjection>;
+ * runtimeStatus: {clickThrough?: boolean; windowVisible?: boolean};
+ * writePanel: (message: {type: string; token: number; epoch: number; request?: number}) => boolean;
+ * }} options
+ */
+export function createHoverKeyboard({ projection, runtimeStatus, writePanel }) {
+  // Tokens are unique for the lifetime of one panel. This binding is recreated on panel restart.
+  let lastToken = 0;
+  return {
+    /** @param {number} token @param {number} epoch */
+    request(token, epoch) {
+      if (!Number.isSafeInteger(token) || token <= lastToken) return false;
+      lastToken = token;
+      const request =
+        runtimeStatus.windowVisible && !runtimeStatus.clickThrough
+          ? projection.requestHoverKeyboard(epoch, token, false)
+          : null;
+      if (request !== null) {
+        if (writePanel({ type: "hover-grant", token, epoch, request })) return true;
+        projection.cancelHoverKeyboard(token);
+      } else {
+        writePanel({ type: "hover-denied", token, epoch });
+      }
+      return false;
+    },
+    /** @param {number} token */
+    cancel: (token) => projection.cancelHoverKeyboard(token),
+  };
+}

package/src/native/interaction-context.mjs

@@ -0,0 +1,45 @@
+/** Exact-window ownership cardinality shared by every projection proof.
+ * @param {Record<string, unknown>[]} sessions @param {number | null} windowId */
+export function visibleCardsForWindow(sessions, windowId) {
+  return sessions.filter((card) => card.windowId === windowId && card.surfaceVisible !== false);
+}
+
+/** Recheck the same exact agent card/publisher set against a complete cached view.
+ * @param {Record<string, unknown>[]} sessions
+ * @param {{workspace: Record<string, unknown> | null; sessions: Record<string, unknown>[]} | null} current
+ * @param {unknown} workspaceId @param {number | null} windowId */
+export function agentSourceMatches(sessions, current, workspaceId, windowId) {
+  const established = visibleCardsForWindow(sessions, windowId);
+  const owned = visibleCardsForWindow(current?.sessions ?? [], windowId);
+  return (
+    current?.workspace?.id === workspaceId &&
+    established.length === 1 &&
+    owned.length === 1 &&
+    owned[0]?.cardId === established[0]?.cardId &&
+    JSON.stringify(publisherSet(owned[0])) === JSON.stringify(publisherSet(established[0]))
+  );
+}
+
+/** Layout selection can contradict a retained source but never establish seat focus.
+ * Missing fields support older snapshots; an explicit NULL or malformed id fails closed.
+ * @param {Record<string, unknown> | null} workspace @param {number | null} sourceId */
+export function selectionContradictsSource(workspace, sourceId) {
+  return (
+    sourceId !== null &&
+    Object.hasOwn(workspace ?? {}, "active_window_id") &&
+    workspace?.active_window_id !== sourceId
+  );
+}
+
+/** Publisher order is presentation, never identity. @param {Record<string, unknown> | undefined} card */
+export function publisherSet(card) {
+  return [
+    ...new Set(
+      Array.isArray(card?.publisherRecordKeys) ? card.publisherRecordKeys.map(String) : [],
+    ),
+  ].sort();
+}
+/** @param {unknown} workspaceId @param {number | null} windowId @param {Record<string, unknown> | undefined} card */
+export function sourceIdentity(workspaceId, windowId, card) {
+  return JSON.stringify([workspaceId, windowId, card?.cardId, publisherSet(card)]);
+}

package/src/native/keyboard-entry.mjs

@@ -0,0 +1,32 @@
+/**
+ * Admit against the current compositor projection/event facts, not panel activity or card count.
+ * Reserve before writing: Niri's NULL focus event may arrive before the panel acknowledgement.
+ * No asynchronous queue may take the keyboard after this command has reported failure.
+ * @param {{
+ *   projection: ReturnType<typeof import("./panel-projection.mjs").createNativePanelProjection>;
+ *   runtimeStatus: {clickThrough?: boolean; windowVisible?: boolean};
+ *   writePanel: (message: {type: string; revision: number; epoch: number}) => boolean;
+ * }} options
+ */
+export function createKeyboardEntry({ projection, runtimeStatus, writePanel }) {
+  return function focusStrip() {
+    if (runtimeStatus.clickThrough) {
+      return { ok: false, error: "Keyboard entry is disabled in click-through mode." };
+    }
+    if (!runtimeStatus.windowVisible || !projection.isEligible()) {
+      return { ok: false, error: "No eligible visible native strip exists on this workspace." };
+    }
+    const request = projection.requestKeyboard();
+    if (
+      request !== null &&
+      writePanel({
+        type: "focus-strip",
+        revision: request,
+        epoch: projection.getInteractionEpoch(),
+      })
+    )
+      return { ok: true };
+    projection.cancelKeyboard();
+    return { ok: false, error: "Native panel is not ready for keyboard entry." };
+  };
+}