@tryinget/pi-activity-strip 0.8.0 → 0.10.0

package/native/panel/src/main.rs

@@ -1,5 +1,10 @@
 mod app;
 mod card_view;
+mod directory_view;
+mod hints;
+mod hover_keyboard;
+mod interaction;
+mod keyboard_observation;
 mod protocol;
 mod runtime;
 

package/native/panel/src/protocol.rs

@@ -134,20 +134,57 @@ pub struct ViewMessage {
     #[serde(rename = "type")]
     pub message_type: String,
     pub revision: u64,
+    /// Changes only when exact controller admission/visibility context changes, not on telemetry.
+    #[serde(default)]
+    pub interaction_epoch: u64,
     #[serde(default)]
     pub visible: bool,
     #[serde(default)]
     pub focused_card_id: Option<String>,
     #[serde(default)]
     pub sessions: Vec<Card>,
+    /// Every agent window on every workspace, for the brand block's window list.
+    #[serde(default)]
+    pub windows: Vec<WindowEntry>,
+    /// The compositor shortcut that enters keyboard mode, as the operator's config binds it.
+    #[serde(default)]
+    pub hotkey: Option<String>,
+}
+
+/// One entry of the window list: the card's first line and the Niri window number to jump to.
+#[derive(Clone, Debug, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct WindowEntry {
+    #[serde(default)]
+    pub card_id: String,
+    #[serde(default)]
+    pub label: String,
+    pub window_id: i64,
+    /// Niri's workspace id: the grouping key, since workspace numbers repeat across monitors.
+    #[serde(default, deserialize_with = "lenient_integer")]
+    pub workspace_id: Option<i64>,
+    #[serde(default, deserialize_with = "lenient_integer")]
+    pub workspace_idx: Option<i64>,
+    #[serde(default)]
+    pub workspace_name: Option<String>,
+    #[serde(default)]
+    pub hidden_tab: bool,
+    #[serde(default)]
+    pub current: bool,
 }
 
 fn protocol_version() -> u8 {
-    1
+    2
 }
 
 static OUTPUT: OnceLock<Mutex<io::Stdout>> = OnceLock::new();
 static READY: AtomicBool = AtomicBool::new(false);
+/// Do not rely on closing a never-mapped GTK window to end its application hold.
+/// A fatal private-protocol mismatch drops the Wayland connection (and any grab) immediately.
+pub fn reject_protocol(message: impl Into<String>) -> ! {
+    emit_error(message);
+    std::process::exit(1);
+}
 
 pub fn emit(event: Value) {
     let stdout = OUTPUT.get_or_init(|| Mutex::new(io::stdout()));
@@ -167,7 +204,7 @@ pub fn was_ready() -> bool {
 pub fn emit_ready() {
     READY.store(true, Ordering::SeqCst);
     emit(json!({
-        "protocol": 1,
+        "protocol": 2,
         "type": "ready",
         "pid": std::process::id(),
         "namespace": "pi-activity-strip"
@@ -175,7 +212,7 @@ pub fn emit_ready() {
 }
 
 pub fn emit_error(message: impl Into<String>) {
-    emit(json!({ "protocol": 1, "type": "error", "message": message.into() }));
+    emit(json!({ "protocol": 2, "type": "error", "message": message.into() }));
 }
 
 pub fn demo_view() -> ViewMessage {
@@ -184,11 +221,13 @@ pub fn demo_view() -> ViewMessage {
         .unwrap_or_default()
         .as_millis() as i64;
     ViewMessage {
-        protocol: 1,
+        protocol: 2,
         message_type: "view".into(),
         revision: 1,
+        interaction_epoch: 1,
         visible: true,
         focused_card_id: Some("demo-tool".into()),
+        hotkey: Some("Super+Shift+A".into()),
         sessions: vec![
             Card {
                 card_id: "demo-monitor".into(),
@@ -252,6 +291,33 @@ pub fn demo_view() -> ViewMessage {
                 ..empty_card()
             },
         ],
+        windows: vec![
+            demo_window("demo-monitor", "activity-strip", 36, 2, false, false),
+            demo_window("demo-tool", "native-dogfood", 43, 2, false, true),
+            demo_window("demo-hidden", "pi-extensions", 43, 2, true, false),
+            demo_window("demo-other", "dep-surgeon", 344, 3, false, false),
+            demo_window("demo-far", "niri-desktop-continuity", 1048, 5, false, false),
+        ],
+    }
+}
+
+fn demo_window(
+    card_id: &str,
+    label: &str,
+    window_id: i64,
+    workspace_idx: i64,
+    hidden_tab: bool,
+    current: bool,
+) -> WindowEntry {
+    WindowEntry {
+        card_id: card_id.into(),
+        label: label.into(),
+        window_id,
+        workspace_id: Some(workspace_idx + 100),
+        workspace_idx: Some(workspace_idx),
+        workspace_name: None,
+        hidden_tab,
+        current,
     }
 }
 
@@ -290,7 +356,7 @@ mod tests {
     #[test]
     fn view_messages_accept_current_node_projection_shape() {
         let view: ViewMessage = serde_json::from_str(
-            r#"{"protocol":1,"type":"view","revision":7,"visible":true,"focusedCardId":"card-a","sessions":[{"cardId":"card-a","sessionId":"session-a","state":"tool","agentActive":true,"agentStartedAt":null,"processId":4242}]}"#,
+            r#"{"protocol":2,"type":"view","revision":7,"visible":true,"focusedCardId":"card-a","sessions":[{"cardId":"card-a","sessionId":"session-a","state":"tool","agentActive":true,"agentStartedAt":null,"processId":4242}]}"#,
         )
         .expect("view should parse");
         assert_eq!(view.revision, 7);
@@ -300,12 +366,31 @@ mod tests {
         assert_eq!(view.sessions[0].pid, 4242);
         assert!(view.sessions[0].ak_tasks.is_empty());
         assert_eq!(view.sessions[0].ak_task_overflow, 0);
+        assert!(
+            view.windows.is_empty(),
+            "controllers without a window list still parse"
+        );
+    }
+
+    #[test]
+    fn view_messages_carry_the_window_list() {
+        let view: ViewMessage = serde_json::from_str(
+            r#"{"type":"view","revision":1,"windows":[{"cardId":"terminal:a","label":"pi-extensions","windowId":432,"workspaceIdx":"x","workspaceName":null,"hiddenTab":true,"current":false}]}"#,
+        )
+        .expect("view should parse");
+        assert_eq!(view.windows.len(), 1);
+        assert_eq!(view.windows[0].window_id, 432);
+        assert_eq!(
+            view.windows[0].workspace_idx, None,
+            "a malformed workspace number drops only that field"
+        );
+        assert!(view.windows[0].hidden_tab);
     }
 
     #[test]
     fn window_and_workspace_numbers_are_optional_card_fields() {
         let view: ViewMessage = serde_json::from_str(
-            r#"{"protocol":1,"type":"view","revision":9,"sessions":[{"cardId":"card-a","windowId":43,"workspaceIdx":2},{"cardId":"card-b","windowId":null,"workspaceIdx":null},{"cardId":"card-c"}]}"#,
+            r#"{"protocol":2,"type":"view","revision":9,"sessions":[{"cardId":"card-a","windowId":43,"workspaceIdx":2},{"cardId":"card-b","windowId":null,"workspaceIdx":null},{"cardId":"card-c"}]}"#,
         )
         .expect("view should parse");
         assert_eq!(view.sessions[0].window_id, Some(43));
@@ -322,7 +407,7 @@ mod tests {
     #[test]
     fn a_malformed_window_or_workspace_number_drops_only_that_field() {
         let view: ViewMessage = serde_json::from_str(
-            r#"{"protocol":1,"type":"view","revision":10,"sessions":[{"cardId":"card-a","windowId":"43","workspaceIdx":2.5},{"cardId":"card-b","windowId":44,"workspaceIdx":3}]}"#,
+            r#"{"protocol":2,"type":"view","revision":10,"sessions":[{"cardId":"card-a","windowId":"43","workspaceIdx":2.5},{"cardId":"card-b","windowId":44,"workspaceIdx":3}]}"#,
         )
         .expect("a bad optional field must not reject the whole view");
         assert_eq!(view.sessions.len(), 2);
@@ -335,7 +420,7 @@ mod tests {
     #[test]
     fn ak_task_chips_parse_with_states() {
         let view: ViewMessage = serde_json::from_str(
-            r#"{"protocol":1,"type":"view","revision":8,"sessions":[{"cardId":"card-a","akTasks":[{"id":5701,"title":"Show clickable AK-task references","state":"active"},{"id":5432,"title":"Preserve safe NEXUS recovery reasons","state":"orphaned"},{"id":4220,"title":"Control Decision 77 epoch admissions","state":"deferred"}],"akTaskOverflow":3}]}"#,
+            r#"{"protocol":2,"type":"view","revision":8,"sessions":[{"cardId":"card-a","akTasks":[{"id":5701,"title":"Show clickable AK-task references","state":"active"},{"id":5432,"title":"Preserve safe NEXUS recovery reasons","state":"orphaned"},{"id":4220,"title":"Control Decision 77 epoch admissions","state":"deferred"}],"akTaskOverflow":3}]}"#,
         )
         .expect("view should parse");
         let card = &view.sessions[0];

package/native/panel/src/runtime.rs

@@ -45,20 +45,38 @@ pub fn apply_theme(definitions: &str) {
     THEME_PROVIDER.with(|provider| provider.load_from_data(&css));
 }
 
+/// Read controller messages from stdin on their own thread. The thread is detached on purpose: it
+/// lives exactly as long as stdin, and on EOF it reports the parent gone, which closes the panel.
 pub fn start_input_reader(sender: relm4::Sender<AppMsg>) {
-    std::thread::spawn(move || {
-        for line in BufReader::new(std::io::stdin()).lines() {
-            match line {
-                Ok(line) if !line.trim().is_empty() => consume_line(&sender, &line),
-                Ok(_) => {}
-                Err(error) => {
-                    let _ = sender.send(AppMsg::InputError(format!("panel input failed: {error}")));
-                    break;
-                }
+    let reader_sender = sender.clone();
+    let spawned = std::thread::Builder::new()
+        .name("panel-input".into())
+        .spawn(move || read_input(reader_sender));
+    match spawned {
+        Ok(handle) => drop(handle),
+        Err(error) => {
+            let _ = sender.send(AppMsg::InputError(format!(
+                "could not start the panel input reader: {error}"
+            )));
+            let _ = sender.send(AppMsg::ParentGone);
+        }
+    }
+}
+
+fn read_input(sender: relm4::Sender<AppMsg>) {
+    for line in BufReader::new(std::io::stdin()).lines() {
+        match line {
+            Ok(line) if !line.trim().is_empty() => {
+                consume_line(&sender, &line);
+            }
+            Ok(_) => {}
+            Err(error) => {
+                let _ = sender.send(AppMsg::InputError(format!("panel input failed: {error}")));
+                break;
             }
         }
-        let _ = sender.send(AppMsg::ParentGone);
-    });
+    }
+    let _ = sender.send(AppMsg::ParentGone);
 }
 
 fn consume_line(sender: &relm4::Sender<AppMsg>, line: &str) {
@@ -71,6 +89,12 @@ fn consume_line(sender: &relm4::Sender<AppMsg>, line: &str) {
             return;
         }
     };
+    if value.get("protocol").and_then(|p| p.as_u64()) != Some(2) {
+        crate::protocol::reject_protocol(format!(
+            "Native panel private protocol mismatch: expected 2, received {}",
+            value.get("protocol").unwrap_or(&serde_json::Value::Null)
+        ));
+    }
     match value.get("type").and_then(|kind| kind.as_str()) {
         Some("view") => match serde_json::from_value::<ViewMessage>(value) {
             Ok(view) => {
@@ -95,7 +119,40 @@ fn consume_line(sender: &relm4::Sender<AppMsg>, line: &str) {
             }
         }
         Some("focus-strip") => {
-            let _ = sender.send(AppMsg::FocusStrip);
+            let _ = sender.send(AppMsg::FocusStrip(
+                value
+                    .get("revision")
+                    .and_then(|item| item.as_u64())
+                    .unwrap_or(0),
+                value
+                    .get("epoch")
+                    .and_then(|item| item.as_u64())
+                    .unwrap_or(0),
+            ));
+        }
+        Some("hover-grant") => {
+            let _ = sender.send(AppMsg::HoverGrant(
+                value
+                    .get("token")
+                    .and_then(|item| item.as_u64())
+                    .unwrap_or(0),
+                value
+                    .get("epoch")
+                    .and_then(|item| item.as_u64())
+                    .unwrap_or(0),
+                value
+                    .get("request")
+                    .and_then(|item| item.as_u64())
+                    .unwrap_or(0),
+            ));
+        }
+        Some("hover-denied") => {
+            let _ = sender.send(AppMsg::HoverDenied(
+                value
+                    .get("token")
+                    .and_then(|item| item.as_u64())
+                    .unwrap_or(0),
+            ));
         }
         Some("collapse") => {
             let _ = sender.send(AppMsg::Collapse);
@@ -121,6 +178,22 @@ fn consume_line(sender: &relm4::Sender<AppMsg>, line: &str) {
                 .to_owned();
             let _ = sender.send(AppMsg::ActivationResult(card_id, ok, message));
         }
+        Some("jump-result") => {
+            let ok = value
+                .get("ok")
+                .and_then(|item| item.as_bool())
+                .unwrap_or(false);
+            let message = value
+                .get("message")
+                .and_then(|item| item.as_str())
+                .unwrap_or(if ok { "Jumped." } else { "Nothing moved." })
+                .to_owned();
+            let window_id = value
+                .get("windowId")
+                .and_then(|item| item.as_i64())
+                .unwrap_or(-1);
+            let _ = sender.send(AppMsg::JumpResult(window_id, ok, message));
+        }
         Some(kind) => {
             let _ = sender.send(AppMsg::InputError(format!(
                 "unsupported panel message: {kind}"

package/native/panel/src/style.css

@@ -265,3 +265,88 @@ window {
   font-family: "IBM Plex Mono", "JetBrains Mono", monospace;
   font-size: 8px;
 }
+
+/*
+ * The brand block's window list: every agent window on every workspace, as its card's first line
+ * and its Niri window number. The number is the thing you type, so it carries the accent.
+ */
+.directory {
+  border-top: 1px solid alpha(@pi_foreground, 0.12);
+  padding-top: 7px;
+}
+
+.jump-line {
+  color: @pi_accent;
+  font-family: "IBM Plex Mono", "JetBrains Mono", monospace;
+  font-size: 10px;
+  font-weight: 600;
+}
+
+/* biome-ignore lint/correctness/noUnknownTypeSelector: GTK CSS uses widget node names. */
+.directory-scroller,
+.directory-scroller > viewport {
+  background: transparent;
+}
+
+/* Same as the card row: scrolls by wheel or touchpad without a visible bar. */
+/* biome-ignore lint/correctness/noUnknownTypeSelector: GTK CSS uses widget node names. */
+.directory-scroller scrollbar {
+  opacity: 0;
+  min-width: 0;
+  min-height: 0;
+}
+
+.directory-header {
+  color: alpha(@pi_foreground, 0.5);
+  font-family: "IBM Plex Mono", "JetBrains Mono", monospace;
+  font-size: 8px;
+  letter-spacing: 1px;
+  margin-top: 5px;
+}
+
+.directory-row {
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: 6px;
+  color: @pi_foreground;
+  min-height: 0;
+  padding: 2px 6px;
+}
+
+.directory-row:hover,
+.directory-row:focus-visible {
+  background: mix(@pi_background, @pi_foreground, 0.1);
+}
+
+/* The window you are in: the same accent ring as its card. */
+.directory-row.current {
+  border-color: @pi_accent;
+}
+
+.directory-label {
+  font-size: 11px;
+}
+
+.directory-id {
+  color: @pi_accent;
+  font-family: "IBM Plex Mono", "JetBrains Mono", monospace;
+  font-size: 10px;
+  font-weight: 600;
+}
+
+.directory-empty {
+  color: alpha(@pi_foreground, 0.5);
+  font-size: 10px;
+}
+
+/* Which workspace a row's window is on; quieter than the number you type. */
+.directory-workspace {
+  color: alpha(@pi_foreground, 0.5);
+  font-family: "IBM Plex Mono", "JetBrains Mono", monospace;
+  font-size: 9px;
+}
+
+/* The row Enter would open: a typed name always shows where it leads. */
+.directory-row.chosen {
+  background: alpha(@pi_accent, 0.16);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryinget/pi-activity-strip",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "pi extension package for activity-strip workflows in monorepo runtime",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -46,7 +46,7 @@
     "docs:list:json": "node ~/ai-society/core/agent-scripts/scripts/docs-list.mjs --json",
     "release:check": "bash ./scripts/release-check.sh",
     "release:check:quick": "SKIP_PI_SMOKE=1 bash ./scripts/release-check.sh",
-    "native:check": "cd native/panel && RUSTUP_TOOLCHAIN=stable cargo fmt --check && RUSTUP_TOOLCHAIN=stable cargo test",
+    "native:check": "cd native/panel && RUSTUP_TOOLCHAIN=1.98.0 cargo fmt --check && RUSTUP_TOOLCHAIN=1.98.0 cargo test --locked",
     "native:build": "bash ./scripts/build-native-panel.sh",
     "strip:open": "node ./bin/pi-activity-strip.mjs open",
     "strip:status": "node ./bin/pi-activity-strip.mjs status",
@@ -88,13 +88,12 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.4",
-    "@earendil-works/pi-agent-core": "0.84.4",
-    "@earendil-works/pi-ai": "0.84.4",
-    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-agent-core": "1.4.0",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
     "@types/node": "22.14.0",
-    "@typescript/native-preview": "7.0.0-dev.20260417.1",
     "typebox": "1.3.7",
-    "typescript": "5.9.2"
+    "typescript": "7.0.2"
   },
   "overrides": {
     "fast-xml-parser": "5.7.0"

package/src/broker/server.mjs

@@ -58,28 +58,45 @@ export class ActivityStripBroker extends EventEmitter {
   }
 
   async start() {
+    // Linux sun_path has 108 bytes including the trailing NUL. Node can silently
+    // bind a truncated path, so reject before chmod/unlink can change the filesystem.
+    if (Buffer.byteLength(this.socketPath, "utf8") > 107) {
+      throw new RangeError("Activity strip socket path must not exceed 107 UTF-8 bytes.");
+    }
+
     fs.mkdirSync(this.socketDir, { recursive: true, mode: 0o700 });
     fs.chmodSync(this.socketDir, 0o700);
     safeUnlink(this.socketPath);
 
-    await new Promise((resolve, reject) => {
-      this.server.once("error", reject);
-      this.server.listen(this.socketPath, () => {
-        this.server.off("error", reject);
-        try {
-          fs.chmodSync(this.socketPath, 0o600);
+    let bound = false;
+    try {
+      await new Promise((resolve, reject) => {
+        this.server.once("error", reject);
+        this.server.listen(this.socketPath, () => {
+          this.server.off("error", reject);
+          bound = true;
           resolve(undefined);
-        } catch (error) {
-          reject(error);
-        }
+        });
       });
-    });
+      fs.chmodSync(this.socketPath, 0o600);
 
-    this.tick = setInterval(() => {
+      this.tick = setInterval(() => {
+        this.emitSnapshot();
+      }, ACTIVITY_STRIP_BROADCAST_TICK_MS);
+      this.tick.unref?.();
       this.emitSnapshot();
-    }, ACTIVITY_STRIP_BROADCAST_TICK_MS);
-    this.tick.unref?.();
-    this.emitSnapshot();
+    } catch (error) {
+      // Only a successful bind gives us a socket to clean up. On a failed bind,
+      // stop() could unlink the address of the listener that beat us to it.
+      if (bound) {
+        try {
+          await this.stop();
+        } catch {
+          // Preserve the startup failure even if cleanup also fails.
+        }
+      }
+      throw error;
+    }
   }
 
   emitSnapshot() {

package/src/client/launcher.mjs

@@ -8,13 +8,9 @@ import { spawn } from "node:child_process";
 import { setTimeout as delay } from "node:timers/promises";
 import { assessActivityStripCompatibility } from "../common/compatibility.mjs";
 import { ACTIVITY_STRIP_START_TIMEOUT_MS } from "../common/constants.mjs";
+import { isOverlayReady } from "../common/overlay-readiness.mjs";
 import { getBrokerStatus } from "./broker-client.mjs";
 
-/** @param {import("../common/contracts.ts").BrokerResponse | null | undefined} result */
-function isBrokerReady(result) {
-  return Boolean(result?.ok && (!result.runtimeStatus || result.runtimeStatus.state === "ready"));
-}
-
 /** @param {import("../common/contracts.ts").BrokerResponse | null | undefined} result */
 function describeBrokerWait(result) {
   if (!result?.ok) return "Activity strip broker did not answer.";
@@ -64,7 +60,7 @@ export async function ensureActivityStripRunning(binPath, options = {}) {
     latestStatus = null;
   }
 
-  if (isBrokerReady(latestStatus)) {
+  if (isOverlayReady(latestStatus)) {
     return { ok: true, started: false };
   }
 
@@ -101,7 +97,7 @@ export async function ensureActivityStripRunning(binPath, options = {}) {
     } catch {
       latestStatus = null;
     }
-    if (isBrokerReady(latestStatus)) {
+    if (isOverlayReady(latestStatus)) {
       return { ok: true, started };
     }
     if (latestStatus?.runtimeStatus?.state === "error") {

package/src/client/runtime-lock.mjs

@@ -13,6 +13,7 @@ import {
   ACTIVITY_STRIP_START_TIMEOUT_MS,
   ACTIVITY_STRIP_STOP_TIMEOUT_MS,
 } from "../common/constants.mjs";
+import { isOverlayReady } from "../common/overlay-readiness.mjs";
 import { requestBrokerShutdown } from "./broker-client.mjs";
 
 const execFileAsync = promisify(execFile);
@@ -123,7 +124,7 @@ export async function waitForStartedRuntime({
   const deadline = now() + timeoutMs;
   while (true) {
     const status = await getStatus();
-    if (status?.ok && (!status.runtimeStatus || status.runtimeStatus.state === "ready")) {
+    if (isOverlayReady(status)) {
       return { ok: true, started: controller.exitCode === undefined };
     }
     if (status?.runtimeStatus?.state === "error") return { ok: false, reason: "error", status };

package/src/common/agent-identity.mjs

@@ -21,8 +21,13 @@ export const AGENT_CATALOG = Object.freeze([
   { kind: "opencode", label: "opencode", commands: Object.freeze(["opencode"]) },
   { kind: "crush", label: "Crush", commands: Object.freeze(["crush"]) },
   { kind: "goose", label: "Goose", commands: Object.freeze(["goose"]) },
-  { kind: "cursor", label: "Cursor Agent", commands: Object.freeze(["cursor-agent"]) },
+  // Cursor's CLI installs both names; `agent` is the one its docs now lead with.
+  { kind: "cursor", label: "Cursor Agent", commands: Object.freeze(["cursor-agent", "agent"]) },
   { kind: "zcode", label: "zcode", commands: Object.freeze(["zcode"]) },
+  // The nodecode TUI; its gateway runs outside any terminal, so tab admission never sees it.
+  { kind: "nodecode", label: "Nodecode", commands: Object.freeze(["nodecode"]) },
+  // angelx is a Python launcher; the cockpit binary it starts, `angel`, is what holds the tab.
+  { kind: "angel", label: "angelx", commands: Object.freeze(["angel"]) },
 ]);
 
 /** Pi publishes its own telemetry, so its processes are never discovered this way. */

package/src/common/contracts.d.ts

@@ -99,6 +99,7 @@ export interface ActivityStripRuntimeStatus {
   clickThrough?: boolean;
   panelMoveCount?: number;
   panelActivationCount?: number;
+  panelJumpCount?: number;
   panelRestartCount?: number;
   lastMovedCardId?: string | null;
   warnings?: string[];
@@ -168,6 +169,7 @@ export interface SessionStartContextLike {
 }
 
 export interface BeforeAgentStartEventLike {
+  messageType?: "user" | "custom";
   prompt?: string;
 }
 

package/src/common/contracts.ts

@@ -80,6 +80,17 @@ export interface BrokerSnapshot {
 
 export type ActivityStripRuntimeState = "starting" | "ready" | "error";
 
+/** A last native observation, not current capture/authorization or a cross-clock timer. */
+export interface NativeKeyboardObservation {
+  panelPid: number;
+  request: number;
+  origin: "hover" | "explicit";
+  reason: "acquired" | "activity" | "idle-expired" | "source-revoked";
+  nativeMs: number;
+  deadlineMs: number | null;
+  captured: boolean;
+}
+
 export interface ActivityStripRuntimeStatus {
   state: ActivityStripRuntimeState;
   backend?: "native-layer-shell";
@@ -114,15 +125,42 @@ export interface ActivityStripRuntimeStatus {
   akTaskError?: string | null;
   akTaskClaimCount?: number;
   akTaskDeferredCount?: number;
+  /** When the deferral list was last read; it is reused for up to AK_DEFERRED_REFRESH_MS (AK7943). */
+  akTaskDeferredReadAt?: number | null;
+  /** How long that list may be reused (AK_DEFERRED_REFRESH_MS). */
+  akTaskDeferredMaxAgeMs?: number;
   akTaskOrphanCount?: number;
   akTaskRenderedCount?: number;
   rendererVisibilityTransitionCount?: number;
   controllerPid?: number;
   panelPid?: number | null;
   panelExpanded?: boolean;
+  nativeKeyboardObservation?: NativeKeyboardObservation | null;
+  /** Optional observational extension; absent on older controllers, never input/AK authority. */
+  ribbonDiagnostics?: {
+    controllerStartupSourceSha256: string | null;
+    expectedPrivateProtocol: number;
+    panelBuild: {
+      state: string;
+      binarySha256?: string;
+      processStartTicks?: string;
+      privateProtocol?: number | null;
+      receiptedSourceSha256?: string | null;
+    };
+    visibilityReason: string;
+    panelBuildObservedAt?: number | null;
+    focus: string;
+    contextValid: boolean;
+    eligible: boolean;
+    interactionEpoch: number;
+    keyboardAuthorization: "none" | "hover" | "explicit";
+    captureExpiry: string;
+    nativeKeyboardObservation?: NativeKeyboardObservation | null;
+  };
   clickThrough?: boolean;
   panelMoveCount?: number;
   panelActivationCount?: number;
+  panelJumpCount?: number;
   panelRestartCount?: number;
   lastMovedCardId?: string | null;
   warnings?: string[];
@@ -198,6 +236,7 @@ export interface SessionStartContextLike {
 }
 
 export interface BeforeAgentStartEventLike {
+  messageType?: "user" | "custom";
   prompt?: string;
 }