@tryinget/pi-activity-strip 0.5.0 → 0.7.0

package/README.md

@@ -12,21 +12,27 @@ system4d:
 
 # @tryinget/pi-activity-strip
 
-A screen-top activity ribbon for live Pi sessions running in Ghostty.
+A screen-top activity ribbon for the coding agents running in your Ghostty tabs. Pi sessions publish their own telemetry; other terminal agents such as Claude Code are discovered from the process table.
 
 The runtime is Electron-free. A Node controller retains the tested telemetry, identity, ordering, and exact-focus logic; a small Rust/Relm4/GTK4 panel owns rendering and the Wayland layer-shell surface.
 
 ## What it does
 
 - auto-starts with interactive Pi TUI sessions
-- shows one card per admitted Ghostty terminal on the focused Niri workspace
+- 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
+- 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
 - aggregates independent publishers beneath stable terminal cards
+- shows the AK task a session is working on: read-only `ak` output is joined onto cards, clicking the task reference focuses the claiming terminal, and claims that outlive their session or deferred tasks appear as non-clickable badges
 - displays repo, phase, tool, detail, elapsed time, and freshness
-- marks the exact currently focused terminal card
+- 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
 - supports Left/Right navigation and Shift+Left/Right manual movement
-- focuses the exact matching Ghostty window on click or Enter
+- focuses the exact matching Ghostty window on click or Enter, presenting a hidden tab first
 - hides completely on workspaces without tracked cards
 - releases its 84px exclusive zone automatically when hidden or crashed
 
@@ -41,9 +47,11 @@ 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.
+
 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.
 
-The compact surface is 84px tall. One engaged card expands the surface to 252px while the exclusive zone remains 84px, so detail overlays content without repeatedly resizing tiled windows.
+The compact surface is 84px tall and sits inset by an 8px margin on the top, left and right, matching the compositor's window gaps, with the same 12px corner radius as tiled windows. It therefore reserves 92px in total. One engaged card expands the surface to at least 276px, taller when its detail rows wrap, while the reservation is unchanged, so detail overlays content without repeatedly resizing tiled windows.
 
 ## Supported host
 
@@ -91,9 +99,12 @@ 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 claude-hooks
 node ./bin/pi-activity-strip.mjs stop
 ```
 
+`stop` returns once the runtime has exited and released its lock, waiting up to 15 seconds and exiting non-zero if it has not, so `npm run strip:stop && npm run strip:open` restarts cleanly. Pi's `/activity-strip stop` and `/activity-strip-stop` wait the same way. An `open` that finds the lock still held by a runtime that never answers says so instead of timing out silently.
+
 `fix-top` is now a compatibility no-op: layer-shell placement is compositor-owned.
 
 ## Keyboard-only entry
@@ -110,10 +121,19 @@ The shortcut toggles exclusive keyboard mode. On entry, the first card is select
 
 ## Interaction contract
 
-- **Workspace locality:** Niri focus events trigger immediate reprojection; bounded polling remains a fallback.
+- **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.
 - **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.
+- **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. A card whose session holds a live claim shows a clickable `AK #id · title` 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.
+- **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.
+- **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.
 - **Accessibility:** cards expose native GTK labels, selected/expanded state, activation descriptions, and GTK accessible announcements.
 
@@ -123,6 +143,15 @@ The shortcut toggles exclusive keyboard mode. On entry, the first card is select
 - `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_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_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`).
+- `PI_ACTIVITY_STRIP_PYTHON` selects the interpreter for the tab inventory (default `python3`).
+- `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.
 
@@ -144,6 +173,16 @@ 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"
+```
+
+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.
+
 Live verification must inspect Niri layers rather than regular windows:
 
 ```bash
@@ -159,14 +198,27 @@ Implemented:
 - workspace-local Niri projection
 - hide/reclaim and restore
 - pointer and keyboard card interaction
-- exact Ghostty activation
+- exact Ghostty activation, including hidden tabs via `present-surface`
+- hidden Ghostty tab placement through host process containment and learned window memory
+- clickable AK task references joined from read-only `ak` output, with claim-outlives-session and deferred badges
+- Niri window id on every card, and its workspace number in the detail
+- non-Pi agent tab discovery with an exact Claude Code adapter
+- live Claude Code telemetry from its transcript, with optional hooks for blocked-on-you states
+- live Codex telemetry from its thread index and rollout files
+- Ghostty theme following, light and dark
+- repair of windows stranded at the previous working-area height
 - bounded panel restart and parent-death cleanup
 - click-through input region
 
 Not implemented:
 
+- placement of a tab whose window has never been observed, on a host without the AT-SPI inventory (Ghostty exposes no surface listing of its own)
+- distinguishing two terminals that resume one logical session when only the drifted session token is available; both are placed in the one window that claims that token
+- live phase and tool detail for agents other than Claude Code and Codex, which have no adapter yet; their cards show the agent, directory, elapsed time and pid
+- placement of an agent other than Claude Code whose tab is hidden inside a multi-window Ghostty process, since only Claude Code exposes a per-tab title identity
 - one panel per output
 - historical timeline
+- any AK mutation from the strip (unclaim, land, reconstruct, apply); the ribbon is a read-only projection by construction
 - persisted manual ordering
 - remote observers via `pi-server`
 

package/bin/pi-activity-strip-claude-hook.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// ---
+// summary: "Claude Code hook entrypoint that records one session's live state for the activity ribbon"
+// read_when:
+//   - "changing how Claude Code sessions publish live state to the ribbon"
+// ---
+
+// Claude Code runs this for each configured hook event and waits for it, so it must be cheap and
+// must never fail the session: every path exits 0 and nothing is written to stdout.
+
+import fs from "node:fs";
+import {
+  CLAUDE_EVENT_DIR,
+  claudeEventPath,
+  claudeEventRecord,
+  isSessionEndEvent,
+} from "../src/common/claude-events.mjs";
+
+const STDIN_LIMIT_BYTES = 1024 * 1024;
+
+async function readPayload() {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of process.stdin) {
+    total += chunk.length;
+    if (total > STDIN_LIMIT_BYTES) break;
+    chunks.push(chunk);
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function main() {
+  const payload = await readPayload();
+  if (!payload || typeof payload !== "object") return;
+  const record = claudeEventRecord(payload, { env: process.env });
+  if (!record) return;
+  const filePath = claudeEventPath(record.sessionId);
+  if (!filePath) return;
+
+  if (isSessionEndEvent(record)) {
+    try {
+      fs.unlinkSync(filePath);
+    } catch {
+      // The session never published, or another hook already retired it.
+    }
+    return;
+  }
+
+  const temporaryPath = `${filePath}.tmp.${process.pid}`;
+  try {
+    fs.mkdirSync(CLAUDE_EVENT_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(temporaryPath, JSON.stringify(record), { mode: 0o600 });
+    fs.renameSync(temporaryPath, filePath);
+  } catch {
+    try {
+      fs.unlinkSync(temporaryPath);
+    } catch {
+      // Nothing was staged.
+    }
+  }
+}
+
+main()
+  .catch(() => {})
+  .finally(() => {
+    process.exitCode = 0;
+  });

package/bin/pi-activity-strip.mjs

@@ -8,7 +8,6 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import {
   getBrokerStatus,
@@ -16,6 +15,13 @@ import {
   requestBrokerShutdown,
   sendBrokerMessage,
 } from "../src/client/broker-client.mjs";
+import {
+  RUNTIME_LOCK_CONFLICT_EXIT_CODE,
+  RUNTIME_LOCK_PATH as runtimeLockPath,
+  stopRuntime,
+  waitForRuntimeExit,
+  waitForStartedRuntime,
+} from "../src/client/runtime-lock.mjs";
 import {
   assessActivityStripCompatibility,
   formatCompatibilityReport,
@@ -23,6 +29,7 @@ import {
 import {
   ACTIVITY_STRIP_SOCKET_DIR,
   ACTIVITY_STRIP_START_TIMEOUT_MS,
+  ACTIVITY_STRIP_STOP_TIMEOUT_MS,
 } from "../src/common/constants.mjs";
 import { makeMessage } from "../src/common/protocol.mjs";
 import { formatBrokerRuntimeStatus } from "../src/common/status-report.mjs";
@@ -30,45 +37,18 @@ import { formatBrokerRuntimeStatus } from "../src/common/status-report.mjs";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const nativeEntry = path.resolve(__dirname, "..", "src", "native", "main.mjs");
-const runtimeLockPath = path.join(ACTIVITY_STRIP_SOCKET_DIR, "runtime.lock");
+const STOP_MESSAGES = {
+  stopped: "stopped",
+  "not-running": "not-running",
+  "still-stopping": "stopping (still shutting down)",
+};
 
 function usage() {
   console.log(
-    `Usage: pi-activity-strip <open|focus-strip|focus-session|status|doctor|snapshot|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  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|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`,
   );
 }
 
-async function waitForBrokerReady(timeoutMs = ACTIVITY_STRIP_START_TIMEOUT_MS) {
-  const timeoutAt = Date.now() + timeoutMs;
-  /** @type {import("../src/common/contracts.ts").BrokerResponse | null} */
-  let latestStatus = null;
-
-  while (Date.now() < timeoutAt) {
-    try {
-      latestStatus = await getBrokerStatus();
-    } catch {
-      latestStatus = null;
-    }
-
-    if (
-      latestStatus?.ok &&
-      (!latestStatus.runtimeStatus || latestStatus.runtimeStatus.state === "ready")
-    ) {
-      return { ok: true };
-    }
-    if (latestStatus?.runtimeStatus?.state === "error") {
-      return { ok: false, error: formatBrokerRuntimeStatus(latestStatus) };
-    }
-
-    await delay(125);
-  }
-
-  return {
-    ok: false,
-    error: `${formatBrokerRuntimeStatus(latestStatus || { ok: false })}\nTimeout: ${timeoutMs}ms`,
-  };
-}
-
 /** @param {{ detached?: boolean }} [options] @returns {Promise<number>} */
 async function openStrip({ detached = true } = {}) {
   if (await isBrokerAlive()) {
@@ -78,11 +58,12 @@ async function openStrip({ detached = true } = {}) {
       return 0;
     }
     await requestBrokerShutdown().catch(() => null);
-    for (let attempt = 0; attempt < 20 && (await isBrokerAlive()); attempt += 1) {
-      await delay(50);
-    }
-    if (await isBrokerAlive()) {
-      console.error(formatBrokerRuntimeStatus(status));
+    // Its broker closes before it exits; starting before the lock is released would lose it.
+    const exit = await waitForRuntimeExit(runtimeLockPath, {
+      timeoutMs: ACTIVITY_STRIP_STOP_TIMEOUT_MS,
+    });
+    if (!exit.released) {
+      console.error(exit.error ?? formatBrokerRuntimeStatus(status));
       return 1;
     }
   }
@@ -94,26 +75,62 @@ async function openStrip({ detached = true } = {}) {
   }
 
   fs.mkdirSync(ACTIVITY_STRIP_SOCKET_DIR, { recursive: true, mode: 0o700 });
-  const child = spawn("flock", ["--nonblock", runtimeLockPath, process.execPath, nativeEntry], {
-    detached,
-    stdio: detached ? "ignore" : "inherit",
-    env: { ...process.env, PI_ACTIVITY_STRIP_RUNTIME_LOCK_HELD: "1" },
-  });
-
-  if (detached) {
-    child.unref();
-    const ready = await waitForBrokerReady();
-    if (!ready.ok) {
-      console.error(ready.error || "Activity strip did not become ready.");
-      return 1;
-    }
-    console.log("Started activity strip.");
-    return 0;
+  const child = spawn(
+    "flock",
+    [
+      "--nonblock",
+      "--conflict-exit-code",
+      String(RUNTIME_LOCK_CONFLICT_EXIT_CODE),
+      runtimeLockPath,
+      process.execPath,
+      nativeEntry,
+    ],
+    {
+      detached,
+      stdio: detached ? "ignore" : "inherit",
+      env: { ...process.env, PI_ACTIVITY_STRIP_RUNTIME_LOCK_HELD: "1" },
+    },
+  );
+  if (!detached) {
+    return await new Promise((resolve) => {
+      child.on("exit", (code) => resolve(typeof code === "number" ? code : 0));
+    });
   }
 
-  return await new Promise((resolve) => {
-    child.on("exit", (code) => resolve(typeof code === "number" ? code : 0));
+  /** @type {{exitCode: number | null | undefined; error?: string}} */
+  const controller = { exitCode: undefined };
+  child.once("exit", (code) => {
+    controller.exitCode = code;
+  });
+  child.once("error", (error) => {
+    controller.exitCode = null;
+    controller.error = error.message;
   });
+  child.unref();
+  const result = await waitForStartedRuntime({
+    controller,
+    getStatus: () => getBrokerStatus().catch(() => null),
+  });
+  if (result.ok) {
+    console.log(result.started ? "Started activity strip." : "Activity strip is already running.");
+    return 0;
+  }
+  if (result.reason === "lock-held") {
+    console.error(
+      "Another activity-strip runtime still holds the runtime lock, probably one that is shutting down; nothing was started. `stop` waits for it to exit.",
+    );
+  } else if (result.reason === "exited") {
+    console.error(
+      controller.error
+        ? `The activity-strip runtime could not be started: ${controller.error}`
+        : `The activity-strip runtime exited during startup (code ${result.exitCode}).`,
+    );
+  } else {
+    const timeout =
+      result.reason === "timeout" ? `\nTimeout: ${ACTIVITY_STRIP_START_TIMEOUT_MS}ms` : "";
+    console.error(`${formatBrokerRuntimeStatus(result.status ?? { ok: false })}${timeout}`);
+  }
+  return 1;
 }
 
 async function main() {
@@ -208,19 +225,36 @@ async function main() {
       }
       return;
     }
+    case "claude-hooks": {
+      const { claudeHookSettings } = await import("../src/common/claude-hook-config.mjs");
+      const hookPath = path.join(
+        path.dirname(fileURLToPath(import.meta.url)),
+        "pi-activity-strip-claude-hook.mjs",
+      );
+      const settings = claudeHookSettings(`${process.execPath} ${hookPath}`);
+      if (jsonOutput) {
+        console.log(JSON.stringify(settings, null, 2));
+      } else {
+        console.log(
+          "Merge this into ~/.claude/settings.json so Claude Code sessions report live state:\n",
+        );
+        console.log(JSON.stringify(settings, null, 2));
+        console.log(
+          "\nOnly low-frequency events are hooked, so nothing runs per tool call. Tool and thinking",
+        );
+        console.log("state already come from the transcript without any configuration.");
+      }
+      return;
+    }
     case "fix-top":
       console.log("Native layer-shell placement is compositor-owned; no repair was needed.");
       process.exitCode = 0;
       return;
     case "stop": {
-      try {
-        const result = await requestBrokerShutdown();
-        console.log(result?.ok ? "stopping" : "not-running");
-        process.exitCode = result?.ok ? 0 : 1;
-      } catch {
-        console.log("not-running");
-        process.exitCode = 1;
-      }
+      const result = await stopRuntime();
+      if (result.outcome === "error") console.error(result.error);
+      else console.log(STOP_MESSAGES[result.outcome]);
+      process.exitCode = result.outcome === "stopped" ? 0 : 1;
       return;
     }
     case "-h":

package/extensions/activity-strip.js

@@ -14,8 +14,9 @@ import { promisify } from "node:util";
 /** @typedef {import("../src/common/contracts.ts").SessionStartContextLike} SessionStartContextLike */
 /** @typedef {import("../src/common/contracts.ts").ToolExecutionEventLike} ToolExecutionEventLike */
 /** @typedef {import("../src/common/contracts.ts").TurnStartEventLike} TurnStartEventLike */
-import { getBrokerStatus, requestBrokerShutdown } from "../src/client/broker-client.mjs";
+import { getBrokerStatus } from "../src/client/broker-client.mjs";
 import { ensureActivityStripRunning } from "../src/client/launcher.mjs";
+import { stopRuntime } from "../src/client/runtime-lock.mjs";
 import { createSessionTelemetry } from "../src/client/session-telemetry.mjs";
 import {
   formatBrokerRuntimeStatus,
@@ -34,6 +35,13 @@ function wantsAutostart() {
   return process.env.PI_ACTIVITY_STRIP_AUTO_START !== "0";
 }
 
+/** @type {Record<string, [string, "info" | "warning" | "error"]>} */
+const STOP_NOTICES = {
+  stopped: ["Activity strip stopped", "info"],
+  "not-running": ["Activity strip is not running", "warning"],
+  "still-stopping": ["Activity strip is still shutting down", "warning"],
+};
+
 /** @param {ExtensionAPI} pi */
 export default function activityStripExtension(pi) {
   const telemetry = createSessionTelemetry({
@@ -57,6 +65,20 @@ export default function activityStripExtension(pi) {
     return result;
   }
 
+  /**
+   * Returns once the runtime has exited, so an open right after it cannot race a runtime that is
+   * still shutting down and leave no ribbon running.
+   * @param {UiContextLike} ctx
+   */
+  async function stopStrip(ctx) {
+    const result = await stopRuntime();
+    if (!ctx.hasUI) return;
+    /** @type {[string, "info" | "warning" | "error"]} */
+    const [message, level] =
+      result.outcome === "error" ? [result.error, "error"] : STOP_NOTICES[result.outcome];
+    ctx.ui?.notify?.(message, level);
+  }
+
   pi.registerCommand("activity-strip", {
     description: "Open or check the top-row activity strip",
     /** @param {string} args @param {UiContextLike} ctx */
@@ -122,16 +144,7 @@ export default function activityStripExtension(pi) {
       }
 
       if (action === "stop") {
-        try {
-          const result = await requestBrokerShutdown();
-          if (ctx.hasUI)
-            ctx.ui?.notify?.(
-              result?.ok ? "Stopping activity strip" : "Activity strip is not running",
-              result?.ok ? "info" : "warning",
-            );
-        } catch {
-          if (ctx.hasUI) ctx.ui?.notify?.("Activity strip is not running", "warning");
-        }
+        await stopStrip(ctx);
         return;
       }
 
@@ -143,16 +156,7 @@ export default function activityStripExtension(pi) {
     description: "Stop the running activity strip broker/window",
     /** @param {string} _args @param {UiContextLike} ctx */
     handler: async (_args, ctx) => {
-      try {
-        const result = await requestBrokerShutdown();
-        if (ctx.hasUI)
-          ctx.ui?.notify?.(
-            result?.ok ? "Stopping activity strip" : "Activity strip is not running",
-            result?.ok ? "info" : "warning",
-          );
-      } catch {
-        if (ctx.hasUI) ctx.ui?.notify?.("Activity strip is not running", "warning");
-      }
+      await stopStrip(ctx);
     },
   });
 

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

@@ -1,9 +1,9 @@
 {
   "schema": "pi-activity-strip-native-artifact.v1",
   "target": "x86_64-unknown-linux-gnu",
-  "sha256": "4cc72663dda90369a3a3ad60aabeefc4a609f42c6cc4a4661d2dc052570a3f0a",
+  "sha256": "ebf9743947de5c872c3a5accf11bda013de71d081231d8e0f2fea83668227f74",
   "cargoLockSha256": "f8ebc11bc721c569af982169e448a5ea4fed15bc06001017d97acda22b1c890b",
-  "sourceSha256": "9467e315aa20fef76c25b88d29e69f3ef6960481b55b639c602e77805986f0e1",
+  "sourceSha256": "f11355a34e72715d086297217d9cc3caabb81b6dcf3deb1c0c798f3a890f7a33",
   "rustc": "rustc 1.98.0 (88d9e12ae 2026-08-18)",
   "glibcFloor": "GLIBC_2.34",
   "neededSonames": [

package/native/panel/src/app.rs

@@ -1,6 +1,6 @@
 use crate::card_view::CardView;
 use crate::protocol::{Card, ViewMessage, demo_view, emit, emit_error, emit_ready};
-use crate::runtime::{duplicate_labels, install_css, now_ms, start_input_reader};
+use crate::runtime::{apply_theme, duplicate_labels, install_css, now_ms, start_input_reader};
 use gtk4_layer_shell::{Edge, KeyboardMode, Layer, LayerShell};
 use relm4::gtk;
 use relm4::gtk::glib;
@@ -11,7 +11,10 @@ use std::collections::{HashMap, HashSet};
 use std::time::Duration;
 
 const COMPACT_HEIGHT: i32 = 84;
-const EXPANDED_HEIGHT: i32 = 252;
+/// The ribbon sits on the same rhythm as tiled windows, so it reads as one of them rather than as
+/// a bar bolted to the top edge. Matches `gaps` in the compositor's layout.
+const OUTER_MARGIN: i32 = 8;
+const EXPANDED_HEIGHT: i32 = 276;
 const ORDER_REFRESH_MS: i64 = 15_000;
 
 pub struct AppInit {
@@ -38,6 +41,7 @@ pub struct App {
 #[derive(Debug)]
 pub enum AppMsg {
     View(ViewMessage),
+    Theme(String),
     Tick,
     Hover(String, bool),
     Focus(String, bool),
@@ -69,36 +73,27 @@ impl Component for App {
 
             #[name = "body"]
             gtk::Box {
+                add_css_class: "band",
                 set_orientation: gtk::Orientation::Horizontal,
-                set_spacing: 8,
-                set_margin_top: 4,
-                set_margin_bottom: 6,
-                set_margin_start: 10,
-                set_margin_end: 10,
+                set_spacing: 0,
 
                 #[name = "brand"]
                 gtk::Box {
                     add_css_class: "brand",
                     set_orientation: gtk::Orientation::Vertical,
-                    set_width_request: 146,
-                    set_vexpand: true,
+                    set_width_request: 132,
+                    set_valign: gtk::Align::Center,
 
                     gtk::Label {
                         add_css_class: "brand-eyebrow",
-                        set_label: "π TELEMETRY RIBBON",
+                        set_label: "π ACTIVITY",
                         set_halign: gtk::Align::Start,
                     },
                     gtk::Label {
                         add_css_class: "brand-title",
-                        set_label: "Activity",
-                        set_halign: gtk::Align::Start,
-                    },
-                    gtk::Label {
-                        add_css_class: "brand-subtitle",
-                        set_label: "Calm order · live detail",
+                        set_label: "Sessions",
                         set_halign: gtk::Align::Start,
                     },
-                    gtk::Box { set_vexpand: true },
                     #[name = "meta"]
                     gtk::Label {
                         add_css_class: "meta",
@@ -118,7 +113,9 @@ impl Component for App {
                         set_orientation: gtk::Orientation::Horizontal,
                         set_spacing: 8,
                         set_halign: gtk::Align::Start,
-                        set_valign: gtk::Align::Start,
+                        set_valign: gtk::Align::Center,
+                        set_margin_top: 8,
+                        set_margin_bottom: 8,
                     }
                 }
             }
@@ -141,8 +138,9 @@ impl Component for App {
         root.set_anchor(Edge::Top, true);
         root.set_anchor(Edge::Left, true);
         root.set_anchor(Edge::Right, true);
-        root.set_margin(Edge::Left, 8);
-        root.set_margin(Edge::Right, 8);
+        root.set_margin(Edge::Top, OUTER_MARGIN);
+        root.set_margin(Edge::Left, OUTER_MARGIN);
+        root.set_margin(Edge::Right, OUTER_MARGIN);
         root.set_exclusive_zone(COMPACT_HEIGHT);
         root.set_keyboard_mode(KeyboardMode::None);
         if init.click_through {
@@ -202,6 +200,7 @@ impl Component for App {
     ) {
         match message {
             AppMsg::View(view) => self.apply_view(widgets, root, &sender, view),
+            AppMsg::Theme(definitions) => apply_theme(&definitions),
             AppMsg::Tick => {
                 if now_ms() >= self.next_order_refresh_at {
                     self.regroup();
@@ -407,6 +406,7 @@ impl App {
                 self.end_engagement();
                 root.set_keyboard_mode(KeyboardMode::None);
                 self.apply_expansion(widgets, root, None);
+                root.set_exclusive_zone(-1);
                 root.set_visible(false);
             }
             emit(