@tryinget/pi-activity-strip 0.9.0 → 0.10.0

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

package/src/native/main.mjs

@@ -17,14 +17,26 @@ import { resolveFocusedWorkspaceView, resolveWindowDirectory } from "../common/w
 import { discoverAgentTabs } from "./agent-discovery.mjs";
 import { startAkTaskProjection } from "./ak-runtime.mjs";
 import { createHeightRepair } from "./height-repair.mjs";
+import { createHoverKeyboard } from "./hover-keyboard.mjs";
+import { createKeyboardEntry } from "./keyboard-entry.mjs";
 import { resolvePanelBinary } from "./panel-binary.mjs";
 import { createNativePanelProjection } from "./panel-projection.mjs";
+import { admitPanelEvent, PANEL_PROTOCOL } from "./panel-protocol.mjs";
+import { createPanelWindowJump } from "./panel-window-jump.mjs";
 import { createPlacementRuntime } from "./placement.mjs";
+import {
+  createRuntimeStatusReader,
+  recordNativeKeyboardObservation,
+} from "./runtime-diagnostics.mjs";
+import { resolveStripHotkey } from "./strip-hotkey.mjs";
 import { createThemeRuntime, THEME_POLL_INTERVAL_MS } from "./theme-runtime.mjs";
-import { createNiriWorkspaceEventWatcher } from "./workspace-events.mjs";
+import {
+  createNiriWorkspaceEventWatcher,
+  createWorkspaceProjectionHandlers,
+} from "./workspace-events.mjs";
 
 /** @typedef {import("../common/contracts.ts").ActivityStripRuntimeStatus} ActivityStripRuntimeStatus */
-/** @typedef {import("node:child_process").ChildProcessWithoutNullStreams & {_activityBuffer?: string; _readyTimer?: NodeJS.Timeout; _stableTimer?: NodeJS.Timeout}} PanelChild */
+/** @typedef {import("node:child_process").ChildProcessWithoutNullStreams & {_protocolError?: string; _activityBuffer?: string; _readyTimer?: NodeJS.Timeout; _stableTimer?: NodeJS.Timeout}} PanelChild */
 /** @typedef {{type: string; protocol?: number; revision?: number; visible?: boolean; sessions?: Array<Record<string, unknown>>; [key: string]: unknown}} PanelMessage */
 
 const execFileAsync = promisify(execFile);
@@ -80,8 +92,6 @@ function isNiriSession() {
   return Boolean(process.env.NIRI_SOCKET);
 }
 
-// Hidden Ghostty tabs are placed by their own runtime: host-process containment plus the window
-// memory learned from visible titles and the bounded AT-SPI tab inventory.
 const placement = createPlacementRuntime({
   env: process.env,
   runtimeStatus,
@@ -96,7 +106,9 @@ function writePanel(message) {
     return false;
   }
   try {
-    const accepted = panel.stdin.write(`${JSON.stringify(message)}\n`);
+    const accepted = panel.stdin.write(
+      `${JSON.stringify({ ...message, protocol: PANEL_PROTOCOL })}\n`,
+    );
     if (!accepted) {
       panelWriteReady = false;
       const child = panel;
@@ -119,6 +131,11 @@ function writePanel(message) {
 
 const projection = createNativePanelProjection({
   isNiriSession,
+  // Presence ("neutral") focus needs the focused window's app id from the event cache.
+  getWindowFacts: (id) => placement.getObservedWindow(id),
+  env: process.env,
+  // Read once: the panel's progressive hints name the shortcut the compositor really binds.
+  hotkey: resolveStripHotkey({ env: process.env }),
   publish(view) {
     runtimeStatus.rendererCardCount = view.sessions.length;
     runtimeStatus.rendererCardIds = view.sessions.map((session) => String(session.cardId ?? ""));
@@ -133,8 +150,7 @@ const projection = createNativePanelProjection({
   },
 });
 
-// AK task references are a read-only projection of claims held by live sessions; the strip
-// never writes AK state and renders nothing when the read fails.
+// Read-only AK task projection: never writes AK state or invents tasks on read failure.
 startAkTaskProjection({ execFileAsync, env: process.env, runtimeStatus, projection });
 
 /** @param {string} targetId @returns {Promise<{ok: boolean; error?: string; windowId?: number; presented?: boolean; verified?: boolean}>} */
@@ -158,48 +174,27 @@ async function focusSession(targetId) {
   return result;
 }
 
-/**
- * Jump to a window by the number Niri gives it, as typed into the window list. Only a window that
- * exists right now is focused; any other number does nothing.
- * @param {number} windowId
- * @returns {Promise<{ok: boolean; error?: string}>}
- */
-async function jumpToWindow(windowId) {
-  if (!isNiriSession()) return { ok: false, error: "Niri is not available; nothing moved." };
-  if (!Number.isInteger(windowId) || windowId < 0) {
-    return { ok: false, error: "Not a window number; nothing moved." };
-  }
-  let windows;
-  try {
-    windows = await getNiriWindows();
-  } catch {
-    return { ok: false, error: "Could not read Niri windows; nothing moved." };
-  }
-  if (!windows.some((window) => window?.id === windowId)) {
-    return { ok: false, error: `No window #${windowId}; nothing moved.` };
-  }
-  try {
-    await execFileAsync("niri", ["msg", "action", "focus-window", "--id", String(windowId)], {
+const requestWindowJump = createPanelWindowJump({
+  projection,
+  placementOptions: placement.options,
+  getWindowFacts: placement.getObservedWindow,
+  isNiriSession,
+  readWindows: () => getNiriWindows(),
+  readWorkspaces: () => getNiriWorkspaces(),
+  focusWindow: (id) =>
+    execFileAsync("niri", ["msg", "action", "focus-window", "--id", String(id)], {
       env: process.env,
-    });
-  } catch {
-    return { ok: false, error: `Niri refused to focus #${windowId}; nothing moved.` };
-  }
-  reconcileRunner.request();
-  return { ok: true };
-}
+    }),
+  reconcile: () => reconcileRunner.request(),
+});
 
-async function focusStrip() {
-  if (runtimeStatus.clickThrough) {
-    return { ok: false, error: "Keyboard entry is disabled in click-through mode." };
-  }
-  if (!runtimeStatus.windowVisible || runtimeStatus.rendererCardCount === 0) {
-    return { ok: false, error: "No visible native strip exists on this workspace." };
-  }
-  return writePanel({ type: "focus-strip" })
-    ? { ok: true }
-    : { ok: false, error: "Native panel is not ready for keyboard entry." };
-}
+const requestKeyboardEntry = createKeyboardEntry({
+  projection,
+  runtimeStatus,
+  writePanel,
+});
+const focusStrip = async () => requestKeyboardEntry();
+let hoverKeyboard = createHoverKeyboard({ projection, runtimeStatus, writePanel });
 
 /** @param {PanelChild} child @param {unknown} chunk */
 function consumePanelEvents(child, chunk) {
@@ -212,13 +207,14 @@ function consumePanelEvents(child, chunk) {
     if (line) {
       try {
         const event = JSON.parse(line);
-        if (event.protocol !== 1) throw new Error("unsupported native panel protocol");
+        if (!admitPanelEvent(child, event, runtimeStatus, () => projection.cancelKeyboard()))
+          return;
         if (event.type === "ready") {
           clearTimeout(child._readyTimer);
           panelReady = true;
           runtimeStatus.state = "ready";
           runtimeStatus.readyAt = Date.now();
-          runtimeStatus.panelPid = Number(event.pid) || child.pid || null;
+          runtimeStatus.panelPid = child.pid ?? null; // Supervised child, never a reported PID.
           runtimeStatus.error = null;
           clearTimeout(child._stableTimer);
           child._stableTimer = setTimeout(() => {
@@ -240,9 +236,20 @@ function consumePanelEvents(child, chunk) {
           const visible = event.visible === true;
           const changed = runtimeStatus.windowVisible !== visible;
           runtimeStatus.windowVisible = visible;
-          // Showing or hiding the surface is the only moment the exclusive zone changes, so it is
-          // the only moment a tiled window can be left at the previous working area's height.
+          // Zone changes can leave tiled window heights stale.
           if (changed) void heightRepair.repairAfterZoneChange();
+        } else if (event.type === "hover-request") {
+          hoverKeyboard.request(Number(event.token), Number(event.epoch));
+        } else if (event.type === "hover-cancel") {
+          if (hoverKeyboard.cancel(Number(event.token))) reconcileRunner.request();
+        } else if (event.type === "keyboard-observation") {
+          recordNativeKeyboardObservation(runtimeStatus, event, child.pid);
+        } else if (event.type === "keyboard-active") {
+          const accepted = projection.keyboardChanged(
+            Number(event.revision),
+            event.active === true,
+          );
+          if (accepted && event.active !== true) reconcileRunner.request();
         } else if (event.type === "expanded") {
           runtimeStatus.panelExpanded = event.expanded === true;
         } else if (event.type === "activate") {
@@ -265,7 +272,7 @@ function consumePanelEvents(child, chunk) {
         } else if (event.type === "jump") {
           runtimeStatus.panelJumpCount = (runtimeStatus.panelJumpCount ?? 0) + 1;
           const windowId = Number(event.windowId);
-          void jumpToWindow(windowId).then((result) =>
+          void requestWindowJump(event).then((result) =>
             writePanel({
               type: "jump-result",
               windowId,
@@ -297,10 +304,12 @@ function startPanel() {
     stdio: ["pipe", "pipe", "pipe"],
   });
   panel = child;
+  hoverKeyboard = createHoverKeyboard({ projection, runtimeStatus, writePanel });
   panelReady = false;
   panelWriteReady = true;
   panelStderr = "";
   runtimeStatus.panelPid = child.pid ?? null;
+  runtimeStatus.nativeKeyboardObservation = null; // New supervised child, new native clock domain.
   runtimeStatus.state = "starting";
   child.stdout.setEncoding("utf8");
   child.stdin.on("error", () => {
@@ -323,9 +332,15 @@ function startPanel() {
     clearTimeout(child._stableTimer);
     if (panel !== child) return;
     panelReady = false;
+    projection.cancelKeyboard();
     runtimeStatus.windowVisible = false;
     runtimeStatus.panelPid = null;
     if (shuttingDown) return;
+    if (child._protocolError) {
+      runtimeStatus.state = "error";
+      runtimeStatus.error = child._protocolError;
+      return;
+    }
     if (panelRestartCount < 3) {
       panelRestartCount += 1;
       runtimeStatus.panelRestartCount = panelRestartCount;
@@ -379,7 +394,7 @@ const theme = createThemeRuntime({
   execFileAsync,
   env: process.env,
   runtimeStatus,
-  publish: (definitions) => writePanel({ protocol: 1, type: "theme", definitions }),
+  publish: (definitions) => writePanel({ protocol: PANEL_PROTOCOL, type: "theme", definitions }),
 });
 
 const heightRepair = createHeightRepair({
@@ -403,7 +418,7 @@ const reconcileRunner = createLatestOnlyRunner(async ({ isCurrent }) => {
   const sessions = projection.getRawSessions();
   runtimeStatus.unplacedSurfaceCount = placement.countUnplaced(windows, sessions);
   const view = resolveFocusedWorkspaceView(windows, workspaces, sessions, placement.options);
-  if (view) placement.learnFromPlacements(view.sessions, windows);
+  placement.learnFromPlacements(view?.sessions ?? [], windows, sessions);
   projection.setDirectory(resolveWindowDirectory(windows, workspaces, sessions, placement.options));
   projection.publishWorkspaceView(
     view ?? { workspace: null, sessions: [], focusedSessionId: null, focusedCardId: null },
@@ -417,7 +432,7 @@ async function shutdown(exitCode = 0) {
   watcher?.stop();
   placement.persist();
   writePanel({
-    protocol: 1,
+    protocol: PANEL_PROTOCOL,
     type: "view",
     revision: Number.MAX_SAFE_INTEGER,
     visible: false,
@@ -437,14 +452,10 @@ async function main() {
   broker = await createActivityStripBroker({
     focusSession,
     focusStrip,
-    getRuntimeStatus: () => ({
-      ...runtimeStatus,
-      warnings: [...(runtimeStatus.warnings ?? [])],
-    }),
+    getRuntimeStatus: createRuntimeStatusReader({ runtimeStatus, projection }),
   });
   broker.on("snapshot", (snapshot) => {
-    // Compare like with like: the raw set also holds discovered agent tabs, which the broker
-    // never publishes, so comparing it to a broker snapshot would always differ and reconcile.
+    // Compare broker-only membership; discovered agent tabs must not force reconciliation.
     const membershipChanged = !haveSameRecordMembership(
       projection.getBrokerSessions(),
       snapshot.sessions,
@@ -460,16 +471,11 @@ async function main() {
     watcher = createNiriWorkspaceEventWatcher({
       spawn,
       env: process.env,
-      onFocusedWorkspace: () => reconcileRunner.request(),
-      onFallback: () => reconcileRunner.request(),
-      onWindowChanged: (window) => {
-        if (placement.observeWindowEvent(window)) reconcileRunner.request();
-      },
-      onWindowClosed: (windowId) => {
-        if (placement.forgetWindow(windowId)) reconcileRunner.request();
-      },
-      onWindowFocusChanged: () => reconcileRunner.request(),
-      onWorkspacesChanged: () => reconcileRunner.request(),
+      ...createWorkspaceProjectionHandlers({
+        projection,
+        placement,
+        reconcile: () => reconcileRunner.request(),
+      }),
       fallbackMs: ACTIVITY_STRIP_WORKSPACE_SYNC_MS,
     });
   }