@tryinget/pi-activity-strip 0.8.0 → 0.10.0

package/README.md

@@ -20,7 +20,7 @@ The runtime is Electron-free. A Node controller retains the tested telemetry, id
 
 - auto-starts with interactive Pi TUI sessions
 - shows one card per admitted Ghostty terminal on the focused Niri workspace, including tabs hidden behind another tab of their Ghostty window
-- covers Pi sessions and other terminal agents (Claude Code, Codex, Gemini and more) found in Ghostty tabs
+- covers Pi sessions and other terminal agents (Claude Code, Codex, Gemini, Cursor's `agent`, nodecode, angel and more) found in Ghostty tabs
 - restores tiled windows left at the wrong height when its reserved band appears or disappears
 - draws itself in Ghostty's own theme and follows the desktop between light and dark
 - sits on the same gap rhythm and corner radius as tiled windows, rather than as a bar on the screen edge
@@ -30,10 +30,12 @@ The runtime is Electron-free. A Node controller retains the tested telemetry, id
 - marks the exact currently focused terminal card and prefixes hidden-tab cards with `⧉`
 - labels each card with its Niri window id (`#43`), so a window an agent or tool names by id can be found on the ribbon
 - keeps monitoring-success cards beside the Activity tile, then active and settled cards
-- expands rich details on hover or keyboard focus
+- expands rich details only on actual pointer hover or explicit keyboard-mode entry
 - supports Left/Right navigation and Shift+Left/Right manual movement
 - focuses the exact matching Ghostty window on click or Enter, presenting a hidden tab first
-- hides completely on workspaces without tracked cards
+- stays present across browser, Obsidian and other app focus, competing overlays, and empty focused workspaces; its reserved band stays constant instead of resizing the desktop
+- keeps presentation separate from keyboard permission: the existing agent/presence-app admission still guards keyboard entry and hover typing; other apps and overlays retain their input
+- teaches its own keyboard shortcut progressively: every card and brand tooltip names it, the window list says what the keyboard would do right now, and keyboard mode shows its key map in the brand block
 - releases its 84px exclusive zone automatically when hidden or crashed
 
 ## Architecture
@@ -47,7 +49,7 @@ Pi publisher streams
   -> wlr-layer-shell top surface with an 84px exclusive zone
 ```
 
-Every child-protocol message carries `protocol: 1`, and the panel drops any view carrying another version. A new card field is therefore added as an optional field: a panel that does not know it ignores it, and a panel talking to a controller that does not send it falls back to a default. The version changes only for a change an existing panel would misread.
+The **private controller/panel** NDJSON protocol is now `protocol: 2`; this does not change Pi publisher or broker message envelopes. The controller requires `panelProtocol: 2` in the artifact receipt and checks the actual child readiness/event version before sending any view or command. The panel rejects incompatible input with a diagnostic and exit 1. Separately receipted older overrides therefore fail closed rather than silently misreading ownership claim ids as data revisions. Optional card fields remain additive; incompatible private changes require a version change.
 
 Layer-shell replaces the old floating Electron window and dynamic Niri-config strut helper. The package no longer edits `~/.config/niri/config.kdl`, resets tiled heights, or requires Electron.
 
@@ -99,6 +101,7 @@ node ./bin/pi-activity-strip.mjs focus-session <full-pi-session-id>
 node ./bin/pi-activity-strip.mjs status
 node ./bin/pi-activity-strip.mjs doctor
 node ./bin/pi-activity-strip.mjs snapshot
+node ./bin/pi-activity-strip.mjs manifest
 node ./bin/pi-activity-strip.mjs claude-hooks
 node ./bin/pi-activity-strip.mjs stop
 ```
@@ -107,6 +110,36 @@ node ./bin/pi-activity-strip.mjs stop
 
 `fix-top` is now a compatibility no-op: layer-shell placement is compositor-owned.
 
+A broker pong alone does not establish overlay readiness. Launcher/startup waiting and CLI
+`status` succeed only with explicit `runtimeStatus.state: ready`. CLI `open` reports unknown
+or starting readiness as non-success without stopping or replacing that live runtime. In the optional focus-visibility mode, a ready
+ribbon may correctly be hidden while a non-agent window is focused; visibility is not startup
+readiness. This check does not itself approve the controller/panel artifact pair.
+
+`manifest` is a separate read-only recovery inventory CLI: it includes registry/process observations
+missing from the broker-only `snapshot`, per-link provenance, uncertainty and coverage counts.
+Paths are redacted by default; no transcript body, title or prompt text is emitted. Process-only
+rows are not counted as established session identities. It never starts the ribbon or reopens a
+session. See the [schema, invocation and evidence limits](docs/project/recovery-manifest.md).
+The panel's existing discovery and AK-chip behavior is unchanged.
+
+### Read-only ribbon diagnostics
+
+`status` also explains controller focus eligibility and reserved keyboard authorization
+(`none`, `hover`, `explicit`), flags expansion reports as stale on hidden surfaces, and
+shows sampled panel-PID executable/receipt/protocol hashes. Samples run asynchronously;
+`pending`, unavailable, incompatible and changed-during-observation states are explicit.
+The controller startup-source fingerprint is a source-tree observation, not proof of every
+loaded byte; a matched receipt is integrity metadata, not approval or original-child custody.
+Older controllers report missing diagnostics rather than guessed facts.
+
+This optional broker observation is separate from the recovery `manifest`: it creates no AK
+claim or custody. It emits no typed query, prompt, credential or executable path. A reserved
+grant is not proof of actual capture. Exact expiry remains **not observed** because private
+protocol2 does not report GTK's monotonic deadline; expansion cause is likewise not inferred
+from an expanded bit alone. Nothing in diagnostics authorizes restart, repair or activation.
+
+
 ## Keyboard-only entry
 
 Bind a Niri key to the fail-closed CLI entrypoint:
@@ -117,36 +150,47 @@ binds {
 }
 ```
 
-The shortcut toggles exclusive keyboard mode. On entry, the first card is selected. Left/Right wraps through cards, Shift+Left/Right moves the selected card with wraparound, Enter focuses its exact Ghostty terminal and exits, and Escape or a second shortcut press exits without activation. Space does not activate a card. Pointer hover expands detail but deliberately does not capture keyboard input. Empty workspaces and click-through mode reject keyboard entry.
+The shortcut enters explicit exclusive keyboard mode (or upgrades an existing hover grab); a second shortcut exits. On entry the card under the pointer is selected, else the focused window's card, else the first card fully in view, so entering never scrolls the row away from what you are looking at. Left/Right wraps through cards, Shift+Left/Right moves the selected card with wraparound, Enter focuses its exact Ghostty terminal and exits, and Escape exits without activation. Space does not activate a card. Hover-and-type navigation is also available below; it does not inherit explicit mode's arrow navigation or ability to jump to unlisted windows. Empty workspaces and click-through mode reject both entry paths.
+
+The ribbon reads the bound chord from the Niri config (`$NIRI_CONFIG`, else `$XDG_CONFIG_HOME/niri/config.kdl`, else `~/.config/niri/config.kdl`), finds the bind that spawns `focus-strip`, and shows it as `Super+Shift+A`; `PI_ACTIVITY_STRIP_HOTKEY` overrides it. If no bind is found, the hints name keyboard mode without inventing a chord. The hints come in three steps, each shown once you are already doing the step before it:
+
+1. **Hovering anything:** card and brand tooltips end with the shortcut (`Super+Shift+A drives the strip from the keyboard`); the brand tooltip also carries the whole key map.
+2. **Hovering the expanded ribbon:** the window list's status line says what the keyboard can do now — `Click or Super+Shift+A to type` before it may capture keys, `Type a name or number · ⏎ go` once it may.
+3. **In keyboard mode:** the brand block shows `⌨ KEYBOARD MODE` and `←→ move · ⏎ open · Esc` where the project and folder normally are, and returns to them on exit.
 
 ## Interaction contract
 
 - **Workspace locality:** Niri focus events and workspace list changes trigger immediate reprojection; bounded polling remains a fallback.
-- **Hide/reclaim:** zero cards unmaps the layer surface. Niri then removes its exclusive zone as part of normal Wayland surface lifecycle.
+- **Persistent presentation:** by default, once a focused Niri workspace is known, the compact surface stays mapped even without cards or a focused application window. Switching apps or opening another overlay does not change its reservation. Compositor stacking remains normal: the strip uses the Top layer, not Overlay. Presence does not grant keyboard access, and losing an interaction source still releases input immediately. `PI_ACTIVITY_STRIP_VISIBILITY=focus` restores the earlier hide/reclaim policy below.
+- **Keyboard admission / optional hide/reclaim:** the ribbon is eligible for keyboard interaction while the focused window on the focused workspace is either exactly one admitted agent card's window or a presence app (`PI_ACTIVITY_STRIP_PRESENCE_APP_IDS`, default every Ghostty window and 1Password). A presence app is a neutral source: the strip stays up, accepts the shortcut and hover typing, and a jump from it is checked against that same window, but no card is claimed as "you are here". Other non-agent focus, missing/ambiguous ownership, or zero cards revokes keyboard eligibility; only in focus-visibility mode does this unmap the surface and release its exclusive zone. A controller-reserved hover or explicit keyboard request may preserve eligibility through Niri's transient NULL focused window on that same workspace; a known non-agent focus always revokes it, even if an old panel acknowledgement arrives later. Returning starts compact, unless there is actual pointer hover or a new explicit shortcut. Hiding, losing keyboard ownership, and pointer leave outside explicit keyboard mode clear stale hover, brand, search and keyboard engagement and revoke delayed callbacks.
 - **Crash behavior:** panel lifetime is bound to the Node controller through Linux parent-death signaling and stdin EOF. Unexpected panel exits are restarted with bounded backoff; a dead surface cannot retain an exclusive zone.
 - **Exact focus:** card activation returns to Node, which performs existing fail-closed terminal identity resolution and Niri focus.
 - **Hidden tabs:** a Ghostty window title only names its active tab. A bound surface whose title is not visible is placed through its Ghostty host process: one host window is exact containment; several host windows use the window remembered for that tab. Memory comes from titles seen while the strip runs and from a read-only AT-SPI inventory of tab labels, and is persisted per Niri instance under `~/.pi/agent/state/pi-activity-strip/surface-bindings.json`. A tab whose window has never been observed stays unplaced rather than guessed; `status` reports that count. Activating a hidden-tab card calls the host process's `present-surface` action on the session bus, then focuses the window, and reports success only after the title proves the tab is visible.
-- **Window ids:** agents and tools name windows by their Niri window id (`claude-window` prints `window_id`, continuity receipts carry it). Each card shows that id as a quiet `#43` chip at the start of its footer; a hidden tab has no window of its own, so its chip shows the window hosting it. Hover or keyboard detail adds a `window` row with the workspace number the operator sees, Niri's workspace `idx` and never its internal workspace id, for example `#43 · workspace 2` or `host #43 · workspace 2` for a hidden tab. The tooltip and accessible label name the window too. Off Niri there is no window id, so no chip is drawn.
+- **Window ids:** agents and tools name windows by their Niri window id (`agent-window` prints `window_id`, continuity receipts carry it). Each card shows that id as a quiet `#43` chip at the start of its footer; a hidden tab has no window of its own, so its chip shows the window hosting it. Hover or keyboard detail adds a `window` row with the workspace number the operator sees, Niri's workspace `idx` and never its internal workspace id, for example `#43 · workspace 2` or `host #43 · workspace 2` for a hidden tab. The tooltip and accessible label name the window too. Off Niri there is no window id, so no chip is drawn.
 - **Agent tabs:** a tab is admitted as an agent when the process owning its terminal is a recognized agent CLI, never on a window title alone, so plain terminal programs are not cards. Claude Code tabs are identified exactly through the per-session scratchpad the process holds open, which yields the session id and the title Claude Code put on the terminal; that title places the tab in its window and is remembered so the tab stays placed once hidden.
-- **AK task references:** cards can show the Agent Kernel task their session is working on. The controller reads the read-only `ak` CLI (`ak task list --status claimed --format json --all --verbose` and `ak task deferred --format json --all`) on a calm 15-second clock and joins claims by exact Pi session id under the AK5700 claim semantics: only `session-<uuid>` claims count, and an expired lease is vacant custody that renders nothing. Chips sit in the card's footer as bare task numbers (`AK5701`, title in the tooltip and the expanded inspector), one per card with the rest folded into a `+N` count, so the folder name keeps the header. A card whose session holds a live claim shows a clickable chip that reuses the card's own activation, so clicking it focuses the exact Ghostty window of the claiming session, presenting hidden tabs first. Claims whose lease has not lapsed but whose claiming session no longer exists ("claim outlives session") and tasks carrying an active deferral are joined by task repo onto cards working inside that repo and render as inert badges, never buttons — there is no live window to focus and no AK action is ever offered. Ambiguous session matches (one logical session resumed into two terminals), a missing `ak` binary, or malformed output bind nothing: fail closed, no chip, no invented state, strip behavior unchanged. The strip never writes AK state and never touches the society database directly.
+- **AK task references:** cards can show the Agent Kernel task their session is working on. The controller reads the read-only `ak` CLI (`ak task list --status claimed --format json --all --verbose` every 15 seconds, then `ak task deferred --format json --all` at most every 5 minutes, since every AK call holds one workstation-wide lock and the full deferral list held it 3 s of every 15; AK7943) and joins claims by exact Pi session id under the AK5700 claim semantics: only `session-<uuid>` claims count, and an expired lease is vacant custody that renders nothing. Chips sit in the card's footer as bare task numbers (`AK5701`, title in the tooltip and the expanded inspector), one per card with the rest folded into a `+N` count, so the folder name keeps the header. A card whose session holds a live claim shows a clickable chip that reuses the card's own activation, so clicking it focuses the exact Ghostty window of the claiming session, presenting hidden tabs first. Claims whose lease has not lapsed but whose claiming session no longer exists ("claim outlives session") and tasks carrying an active deferral are joined by task repo onto cards working inside that repo and render as inert badges, never buttons — there is no live window to focus and no AK action is ever offered. Because the deferral list is reused, a new deferral badge can appear, or a resumed task's badge linger, up to about five minutes late; a resumed task that a Pi session claims again rereads the list within one claim tick, since AK never lets a deferred task be claimed. `status` shows when the list was read. Ambiguous session matches (one logical session resumed into two terminals), a missing `ak` binary, or malformed output bind nothing: fail closed, no chip, no invented state, strip behavior unchanged. The strip never writes AK state and never touches the society database directly.
 - **Codex telemetry:** Codex keeps a thread index naming every session's rollout file, working directory and title. A process binds to its thread by an open rollout descriptor, or, before any task has run, by being the only session created in that directory after the process started; anything ambiguous binds nothing. The rollout tail then reports the running tool and its command, turn count, approval and sandbox policy, prompt and reply. Reading the index needs the runtime's built-in SQLite, and a host without it degrades to a process-only card.
 - **Claude Code telemetry:** cards read live state from the tail of the session transcript, giving the topic, current tool and its target, last prompt, latest reply, turn count and activity clock with no configuration. That format is internal to Claude Code and can change between releases, so a transcript that no longer parses degrades to a process-only card rather than inventing activity. Optional hooks add the one state a transcript cannot express, that a session is blocked waiting for you; run `claude-hooks` for the settings fragment. Only low-frequency events are hooked, so nothing runs per tool call. OpenTelemetry is deliberately not used: it reports aggregate usage and cost, not which tool a session is running now.
-- **You are here:** the block at the ribbon's left names the focused window's project in large type with its folder beneath (home written as `~`, cut from the front so the deepest folder stays visible), and the matching card carries a solid accent ring. With no agent window focused it shows the session counts instead.
+- **You are here:** the block at the ribbon's left names the focused window's project in large type with its folder beneath (home written as `~`, cut from the front so the deepest folder stays visible), and the matching card carries a solid accent ring. When the panel itself takes the keyboard, Niri briefly reports no focused window; the ring and the block keep the last focused window on that same workspace instead of blanking, so nothing reflows under the pointer. A workspace change still clears them.
+- **Window list and jump by number:** while expanded, the brand column lists every admitted agent window across workspaces, alphabetically by project, with its workspace (`ws2`) and Niri window number (`#432`). The current window is ringed and its card scrolls into view once the pointer has left the ribbon and it no longer holds the keyboard; while you point at or type into the row it never scrolls on its own. Brand hover opens every card's details; card hover opens only that card. **Hover, type a project name or listed agent window number, then Enter** to focus that exact target. Matching is case-insensitive and Backspace edits. Real pointer entry requests permission from the controller before the panel captures keys; GTK focus alone cannot authorize capture. Body, card, brand and directory crossings form one interaction region. Hover cannot jump to an unlisted window. Leaving the region, Escape, activation/jump, or loss of eligible focus ends the engagement: keyboard, query and list are released and the ribbon collapses. About three seconds without relevant typing releases only the keyboard and clears the query—even a nonempty query—while the card or list under a still pointer stays open. Periodic telemetry cannot recapture it: leave/re-enter or click for fresh intent. An unsupported key (including an arrow/shortcut) interrupts hover: it releases the keyboard and leaves whatever is open under the pointer open; that interrupting key is **not replayed** to another application, but subsequent typing goes there. The explicit shortcut (`focus-strip`) upgrades hover and retains Left/Right and Shift+Left/Right card navigation/manual movement; only explicit mode can jump to an existing unlisted number. Clicks still activate exact cards or directory entries, including hidden tabs. Every activation/jump returns the keyboard immediately.
 - **Appearance:** the ribbon reads the same theme files Ghostty reads. It resolves the `theme` setting for the desktop's current colour scheme, including the `light:…,dark:…` form, and takes colours set directly in the config over the theme file, exactly as Ghostty layers them. State colours reuse the terminal's own meanings, so green is settled, yellow is working, red failed, and the cursor colour marks a session waiting for you. The panel derives every shade from eight named colours, so a theme change is a handful of values and one stylesheet reload rather than a restart. A theme that cannot be read falls back to a neutral palette.
 - **Height repair:** showing or hiding the ribbon changes the output working area, and a window whose height is not automatic keeps the old value. After each change the strip compares window heights before and after, and resets to automatic only those windows still sitting at a height the moving windows just vacated. A height nobody vacated is never touched, each window is reset at most once per height, and a pass is bounded.
 - **Two identity keys:** a Ghostty surface id is a per-process handle that can drift away from the value a long-lived Pi process captured at startup, while the 32-hex session token in the same title never does. Memory therefore stores both, and lookups prefer the exact surface. A session token that two windows claim is ambiguous and binds nothing; two terminals resuming one logical session in the same window are both placed there.
-- **Ordering:** monitoring, active, and settled groups refresh on a calm 15-second clock. Manual moves survive until regroup or restart.
+- **Ordering:** monitoring, active, and settled groups refresh on a calm 15-second clock. A regroup waits while the pointer is over the ribbon or it holds the keyboard, so cards never trade places under the pointer. Manual moves survive until regroup or restart.
 - **Accessibility:** cards expose native GTK labels, selected/expanded state, activation descriptions, and GTK accessible announcements.
 
 ## Environment controls
 
 - `PI_ACTIVITY_STRIP_AUTO_START=0` disables extension autostart.
+- `PI_ACTIVITY_STRIP_VISIBILITY=focus` opts into the earlier focus-dependent hide/reclaim behavior. Default is persistent presentation, including empty focused workspaces. Environment controls are read by the controller at startup; restart the strip to apply a change.
 - `PI_ACTIVITY_STRIP_CLICK_THROUGH=1` installs an empty Wayland input region and disables keyboard entry.
-- `PI_ACTIVITY_STRIP_NATIVE_PANEL_BIN=/absolute/path` selects another receipted panel artifact.
+- `PI_ACTIVITY_STRIP_NATIVE_PANEL_BIN=/absolute/path` selects another receipted panel artifact. A nonempty selection is binding: if missing or nonexecutable, startup fails instead of silently falling back to the packaged panel, including with the development escape hatch.
 - `PI_ACTIVITY_STRIP_SOCKET_DIR` and `PI_ACTIVITY_STRIP_SOCKET_PATH` isolate broker fixtures and nested-compositor tests.
 - `PI_ACTIVITY_STRIP_TAB_INVENTORY=0` disables the read-only AT-SPI tab inventory; hidden tabs are then placed only from titles seen while the strip runs.
 - `PI_ACTIVITY_STRIP_AK_TASKS=0` disables AK task reference joining.
 - `PI_ACTIVITY_STRIP_AK_BIN=/absolute/path` selects the `ak` binary used for the read-only task queries (default `ak` on `PATH`).
+- `PI_ACTIVITY_STRIP_PRESENCE_APP_IDS` edits which Niri apps admit keyboard interaction (and keep the ribbon up in optional focus-visibility mode). A comma-separated list adds ids to the defaults (`com.mitchellh.ghostty`, `com.tryinget.ghosttysidequest`, `com.onepassword.OnePassword`, `1Password`), `-id` removes one, `none` empties the set (strict agent-only behaviour), and `*` admits every app as a keyboard interaction source. The wildcard is unnecessary for persistent visibility; it also broadens which apps keep the ribbon up in focus-visibility mode.
+- `PI_ACTIVITY_STRIP_HOTKEY="Super+Shift+A"` sets the shortcut the hints name, instead of reading it from the Niri config.
 - `PI_ACTIVITY_STRIP_AGENT_TABS=0` disables discovery of non-Pi agent tabs.
 - `PI_ACTIVITY_STRIP_AGENT_KINDS_DISABLED=claude,codex` excludes named agent kinds from discovery.
 - `CODEX_HOME` selects a non-default Codex home when reading its thread index (default `~/.codex`).
@@ -154,7 +198,7 @@ The shortcut toggles exclusive keyboard mode. On entry, the first card is select
 - `PI_ACTIVITY_STRIP_HEIGHT_REPAIR=0` disables restoring windows stranded at the previous working-area height.
 - `PI_ACTIVITY_STRIP_COLOR_SCHEME=light|dark` pins the ribbon to one scheme instead of following the desktop.
 
-Unverified native binaries are rejected unless `PI_ACTIVITY_STRIP_ALLOW_UNVERIFIED_PANEL=1` is explicitly set for development fixtures.
+Unverified native binaries are rejected unless `PI_ACTIVITY_STRIP_ALLOW_UNVERIFIED_PANEL=1` is explicitly set for development fixtures. That flag does **not** bypass the private-protocol receipt or actual readiness version checks.
 
 ## Verification
 
@@ -174,15 +218,9 @@ The staged artifact receipt binds:
 - glibc symbol floor
 - required shared libraries
 
-To see the panel without touching the live ribbon, run its built-in demo cards in a nested Niri with a config that spawns nothing:
-
-```bash
-printf 'prefer-no-csd\nhotkey-overlay {\n    skip-at-startup\n}\n' >/tmp/pi-activity-preview.kdl
-niri -c /tmp/pi-activity-preview.kdl -- env PI_ACTIVITY_STRIP_PANEL_DEMO=1 \
-  "$PWD/native/bin/linux-x64-gnu/pi-activity-strip-panel"
-```
+For isolated GUI checks, use the canonical `nested-niri-gui-isolation` skill's helper (`up`, `env`, `check`, `down`) with an owned state directory under `$TMPDIR`, never a bare compositor/terminal helper. Scope every client and IPC call to that nested display/socket; never address operator windows. The panel is unique per Wayland display.
 
-The panel is unique per Wayland display: this demo runs beside the live ribbon, while a second panel on the live display is refused with an error rather than reserving a second band. Never run the panel under a private session bus such as `dbus-run-session`: GTK then starts a second accessibility bus that takes over the desktop's AT-SPI socket and leaves it dead when it exits.
+Do not run GTK under a private session bus while sharing the host AT-SPI runtime socket: a second accessibility bus can take it over and leave the desktop's bridge dead. The isolated fixture in `tests/support/isolated-niri-check.mjs` instead uses a private `XDG_RUNTIME_DIR` and session bus **and** disables the bridge with `GTK_A11Y=none` / `NO_AT_BRIDGE=1`; accessibility is explicitly untested there. It requires the owned helper's `state.json` and matching nested environment before launching any GUI. See [independent-review repair evidence](docs/project/2026-10-16-ak7114-independent-review-repair.md) for current commands and coverage limits; the [prior focus/hover record](docs/project/2026-10-15-ak7114-focus-hover.md) preserves the superseded pointer-only choice.
 
 Live verification must inspect Niri layers rather than regular windows:
 
@@ -197,7 +235,7 @@ Implemented:
 - local broker and telemetry publishers
 - native GTK4 layer-shell rendering
 - workspace-local Niri projection
-- hide/reclaim and restore
+- persistent presentation with stable reserved space; optional focus-dependent hide/reclaim
 - pointer and keyboard card interaction
 - exact Ghostty activation, including hidden tabs via `present-surface`
 - hidden Ghostty tab placement through host process containment and learned window memory

package/bin/pi-activity-strip.mjs

@@ -31,6 +31,7 @@ import {
   ACTIVITY_STRIP_START_TIMEOUT_MS,
   ACTIVITY_STRIP_STOP_TIMEOUT_MS,
 } from "../src/common/constants.mjs";
+import { isOverlayReady } from "../src/common/overlay-readiness.mjs";
 import { makeMessage } from "../src/common/protocol.mjs";
 import { formatBrokerRuntimeStatus } from "../src/common/status-report.mjs";
 
@@ -45,7 +46,7 @@ const STOP_MESSAGES = {
 
 function usage() {
   console.log(
-    `Usage: pi-activity-strip <open|focus-strip|focus-session|status|doctor|snapshot|claude-hooks|fix-top|stop|serve> [options]\n\nCommands:\n  open              Start the interactive top-row activity strip (--click-through opts out)\n  focus-strip       Focus the visible strip already resident on the focused Niri workspace\n  focus-session ID  Focus the one Ghostty/Niri window matching an exact Pi session identity\n  status            Check broker + overlay readiness and surface runtime warnings\n  doctor            Inspect host compatibility assumptions before opening the strip\n  snapshot          Print the current broker snapshot as JSON\n  claude-hooks      Print the Claude Code settings fragment for live agent telemetry\n  fix-top           Confirm compositor-owned layer-shell placement\n  stop              Ask the running strip to shut down\n  serve             Internal helper; starts the native runtime in the foreground\n`,
+    `Usage: pi-activity-strip <open|focus-strip|focus-session|status|doctor|snapshot|manifest|claude-hooks|fix-top|stop|serve> [options]\n\nCommands:\n  open              Start the interactive top-row activity strip (--click-through opts out)\n  focus-strip       Focus the visible strip already resident on the focused Niri workspace\n  focus-session ID  Focus the one Ghostty/Niri window matching an exact Pi session identity\n  status            Check broker + overlay readiness and surface runtime warnings\n  doctor            Inspect host compatibility assumptions before opening the strip\n  snapshot          Print the current broker snapshot as JSON\n  manifest          Read-only recovery inventory JSON (no autostart; paths redacted by default)\n                    [--include-paths] [--pi-session-root PATH] [--no-ak]\n  claude-hooks      Print the Claude Code settings fragment for live agent telemetry\n  fix-top           Confirm compositor-owned layer-shell placement\n  stop              Ask the running strip to shut down\n  serve             Internal helper; starts the native runtime in the foreground\n`,
   );
 }
 
@@ -53,10 +54,14 @@ function usage() {
 async function openStrip({ detached = true } = {}) {
   if (await isBrokerAlive()) {
     const status = await getBrokerStatus({ expectReply: true }).catch(() => null);
-    if (status?.runtimeStatus?.state !== "error") {
+    if (isOverlayReady(status)) {
       console.log("Activity strip is already running.");
       return 0;
     }
+    if (status?.runtimeStatus?.state !== "error") {
+      console.error(formatBrokerRuntimeStatus(status));
+      return 1; // Unknown/starting is not success and does not authorize replacement.
+    }
     await requestBrokerShutdown().catch(() => null);
     // Its broker closes before it exits; starting before the lock is released would lose it.
     const exit = await waitForRuntimeExit(runtimeLockPath, {
@@ -141,6 +146,30 @@ async function main() {
   }
 
   switch (command) {
+    case "manifest": {
+      let includePaths = false;
+      let noAk = false;
+      let piSessionRoot;
+      const args = process.argv.slice(3);
+      for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--include-paths") includePaths = true;
+        else if (args[i] === "--no-ak") noAk = true;
+        else if (args[i] === "--json") {
+          /* JSON is always emitted. */
+        } else if (args[i] === "--pi-session-root" && args[i + 1]?.startsWith("/"))
+          piSessionRoot = args[++i];
+        else throw new Error("manifest: unsupported option or missing absolute --pi-session-root");
+      }
+      const { collectRecoveryManifest } = await import("../src/native/recovery-inventory.mjs");
+      console.log(
+        JSON.stringify(
+          await collectRecoveryManifest({ includePaths, noAk, piSessionRoot }),
+          null,
+          2,
+        ),
+      );
+      return;
+    }
     case "open":
       process.exitCode = await openStrip({ detached: true });
       return;
@@ -194,8 +223,7 @@ async function main() {
         } else {
           console.log(formatBrokerRuntimeStatus(result));
         }
-        process.exitCode =
-          result?.ok && (!result.runtimeStatus || result.runtimeStatus.state === "ready") ? 0 : 1;
+        process.exitCode = isOverlayReady(result) ? 0 : 1;
       } catch {
         console.log(
           jsonOutput ? JSON.stringify({ ok: false, state: "stopped" }, null, 2) : "stopped",

package/native/bin/linux-x64-gnu/artifact.json

@@ -1,15 +1,17 @@
 {
   "schema": "pi-activity-strip-native-artifact.v1",
   "target": "x86_64-unknown-linux-gnu",
-  "sha256": "99b6f36e858b9c241c5aa73f7517c0f5f418673f54d9fa245156272c39bf004b",
+  "panelProtocol": 2,
+  "sha256": "fb39af413e44b9bb28976c60752d883201735ef7b490164d5054fd87a224d279",
   "cargoLockSha256": "f8ebc11bc721c569af982169e448a5ea4fed15bc06001017d97acda22b1c890b",
-  "sourceSha256": "b272f4f3131cc4335ed6324ad051042fbd3d577b16944189fcdeaed7e776628f",
+  "sourceSha256": "17b10a2894b0377e7502feeb798462d74a5b427633bc75f20dd4044dde43291c",
   "rustc": "rustc 1.98.0 (88d9e12ae 2026-08-18)",
   "glibcFloor": "GLIBC_2.34",
   "neededSonames": [
     "libgtk4-layer-shell.so.0",
     "libgtk-4.so.1",
     "libcairo.so.2",
+    "libgraphene-1.0.so.0",
     "libgio-2.0.so.0",
     "libgobject-2.0.so.0",
     "libglib-2.0.so.0",