@tryinget/pi-activity-strip 0.2.0 → 0.3.0

package/README.md

@@ -24,7 +24,7 @@ This package is designed for the exact workflow you asked for:
 
 - auto-starts a local top-row overlay when Pi starts in a TUI session
 - tracks each active Pi session independently
-- shows one card per live session
+- on Niri, shows one card per tracked live Pi terminal on only the focused workspace; non-Niri desktops retain the global live-session view
 - surfaces:
   - repo/session label
   - current phase
@@ -33,6 +33,11 @@ This package is designed for the exact workflow you asked for:
   - elapsed time plus last-seen freshness
   - state color (`thinking`, `tool`, `waiting`, `done`, `error`)
 - keeps a local broker so multiple Pi processes can report into one strip
+- marks the Pi session in the currently focused Niri/Ghostty terminal with a stronger border and left rail, without adding another label
+- keeps green `done`/`monitoring` cards directly beside the Activity tile, followed by active work and then other settled sessions, on a calm 15-second ordering clock
+- reveals prompt, response, path, and full activity detail on hover or keyboard focus
+- focuses the exact matching Ghostty/Niri window on click or Enter, failing closed when identity is missing or ambiguous
+- keeps an aligned strip resident on its Niri workspace while that workspace still has tracked terminals, so visiting an empty workspace does not unmap or reposition it
 
 ## Architecture
 
@@ -51,14 +56,16 @@ It does not require moving your workflow onto `pi-server` first.
 Implemented now:
 - local per-host broker
 - primary-display top-row strip
-- one card per active Pi session
+- one card per tracked live Pi terminal on the focused Niri workspace, regardless of activity state
 - headless-safe telemetry publishing
-- explicit open/status/doctor/snapshot/fix-top/stop commands
+- explicit open/focus-strip/focus-session/status/doctor/snapshot/fix-top/stop commands
+- focus-scoped Left/Right navigation and Shift+Left/Right manual card movement
 - local visual capture helpers so the agent can inspect the strip directly
 
 Not implemented yet:
 - multi-monitor strip replication
-- historical timeline / expand-on-hover detail
+- historical timeline
+- persisted manual card order across strip restarts
 - remote observers via `pi-server`
 
 ## Installation in Pi
@@ -93,6 +100,8 @@ or directly:
 
 ```bash
 node ./bin/pi-activity-strip.mjs open
+node ./bin/pi-activity-strip.mjs focus-strip
+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
@@ -116,6 +125,27 @@ In Pi with UI support:
 - `/activity-strip status` opens a detailed runtime status report when an editor surface is available
 - `/activity-strip doctor` opens the host-compatibility report
 
+## Interaction model
+
+- **Workspace locality:** one strip follows the Niri workspace selected with Up/Down and renders only tracked Pi terminals whose exact Ghostty windows are on that workspace. Focused-workspace events trigger reconciliation immediately, with polling retained as a fallback. When an empty workspace is visited, an aligned strip whose resident workspace still has tracked terminals remains rendered on that prior workspace; Niri keeps it off the empty workspace and returning brings the already-positioned strip back with its row. If its resident terminals disappear, the renderer is concealed and input-disabled. When an actual remap or floating correction is unavoidable, reveal waits beyond Niri's compositor movement animation and then re-verifies placement and membership. The broker remains global and non-Niri desktops retain the global card view.
+- **Ordering:** green `done` cards whose footer reads `monitoring` stay at the far left beside the Activity tile. Active tool/thinking/waiting cards follow, then other settled cards. The group order refreshes every 15 seconds rather than on every telemetry packet; text and timers still update live.
+- **Current terminal:** on Niri, the card matching the focused Ghostty window gets a stronger border and left rail without an extra label. Matching uses the same exact session-title identity seam as click-to-focus and fails closed when focus or identity is missing or ambiguous.
+- **Pointer:** hover expands the strip and reveals detail, last prompt, assistant preview, and path. Leaving the strip or activating another window collapses it immediately. Single click asks Niri to focus the one Ghostty title carrying that exact Pi session-id suffix.
+- **Keyboard inside the strip:** Left/Right changes card focus, Enter activates the focused card, and Shift+Left/Right manually moves it. Manual movement lasts until a later activity regroup or runtime restart.
+- **Fail-closed focus:** current telemetry uses the exact Pi identity directly. For already-running tabs that still publish a legacy broker id, the strip may recover only the process-bound `pi-session-presence` sidecar when its source, PID, and cwd all agree; this is not repo-name guessing or arbitrary-PID focusing. If identity still matches zero or multiple Ghostty windows, focus does nothing and asks for one `/reload`.
+
+### Keyboard-only entry on Niri
+
+The package deliberately does not reserve a global Electron shortcut. Bind one compositor key to the fail-closed CLI entrypoint instead:
+
+```kdl
+binds {
+    Mod+Shift+A { spawn "node" "/home/tryinget/ai-society/softwareco/owned/pi-extensions/packages/pi-activity-strip/bin/pi-activity-strip.mjs" "focus-strip"; }
+}
+```
+
+`focus-strip` gives keyboard focus only to the unique strip already resident on the currently focused workspace; it never moves a strip between workspaces. When the focused workspace has no tracked live Pi terminals, the command fails closed rather than forcing an empty bar into view. This keeps shortcut ownership explicit in Niri and avoids application-level global-key collisions.
+
 ## Verification commands
 
 ### Package checks
@@ -179,8 +209,8 @@ Use `doctor` before opening the strip when the host/display assumptions are unce
 
 - `PI_ACTIVITY_STRIP_AUTO_START=0`
   - disable automatic strip opening on Pi session start
-- `PI_ACTIVITY_STRIP_CLICK_THROUGH=0`
-  - make the overlay clickable instead of mouse-transparent
+- `PI_ACTIVITY_STRIP_CLICK_THROUGH=1`
+  - opt out of interaction and restore a mouse-transparent overlay; interactive hover/click/keyboard behavior is the default
 - `PI_ACTIVITY_STRIP_ELECTRON_BIN=/path/to/electron`
   - override Electron binary discovery
 - `GLIMPSE_ELECTRON_BIN=/path/to/electron`
@@ -194,6 +224,7 @@ If you want this for all current tabs:
 2. run `/reload` inside each already-open Pi tab
 3. open the strip once with `/activity-strip` or `npm run strip:open`
 4. from then on, every loaded Pi session should report into the same top-row ribbon
+5. ensure `pi-little-helpers` session presence is loaded when you want exact click-to-Ghostty focus; its `· <full-32-hex-session-id-token>` title suffix is the preferred fail-closed identity seam (an 8-hex legacy title remains usable only when no legacy duplicate or migrated full title shares its prefix)
 
 ## References
 

package/bin/pi-activity-strip.mjs

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
+// ---
+// summary: "command-line entrypoint for opening, inspecting, repairing, and stopping the activity strip runtime"
+// read_when:
+//   - "operating or diagnosing the activity strip from a terminal"
+// ---
+
 import { execFile, spawn } from "node:child_process";
 import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
@@ -16,6 +22,7 @@ import {
 } from "../src/common/compatibility.mjs";
 import { ACTIVITY_STRIP_START_TIMEOUT_MS } from "../src/common/constants.mjs";
 import { locateElectron } from "../src/common/electron.mjs";
+import { focusNiriStrip, resolveActivityStripWindow } from "../src/common/niri-focus.mjs";
 import { makeMessage } from "../src/common/protocol.mjs";
 import { formatBrokerRuntimeStatus } from "../src/common/status-report.mjs";
 
@@ -26,7 +33,7 @@ const execFileAsync = promisify(execFile);
 
 function usage() {
   console.log(
-    `Usage: pi-activity-strip <open|status|doctor|snapshot|fix-top|stop|serve> [--json]\n\nCommands:\n  open      Start the top-row activity strip if it is not already running\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   Move the strip window flush to the top edge in Niri\n  stop      Ask the running strip to shut down\n  serve     Internal helper; starts the Electron shell in the foreground\n`,
+    `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           Move the strip window flush to the top edge in Niri\n  stop              Ask the running strip to shut down\n  serve             Internal helper; starts the Electron shell in the foreground\n`,
   );
 }
 
@@ -39,12 +46,15 @@ async function moveStripToTop() {
     throw new Error("Unexpected niri windows payload");
   }
 
-  const stripWindow = windows.find((window) => window?.title === "Pi Activity Strip");
-  if (!stripWindow?.id) {
-    throw new Error("Could not find Pi Activity Strip window in niri");
+  const stripWindow = resolveActivityStripWindow(windows);
+  if (!stripWindow) {
+    throw new Error("Could not find one unique Pi Activity Strip window in niri");
   }
 
-  const currentY = Number(stripWindow.layout?.tile_pos_in_workspace_view?.[1] ?? 0);
+  const layout = /** @type {{ tile_pos_in_workspace_view?: unknown[] }} */ (
+    stripWindow.layout ?? {}
+  );
+  const currentY = Number(layout.tile_pos_in_workspace_view?.[1] ?? 0);
   if (Math.abs(currentY) < 1) {
     return 0;
   }
@@ -137,6 +147,9 @@ async function openStrip({ detached = true } = {}) {
 async function main() {
   const command = process.argv[2] ?? "open";
   const jsonOutput = process.argv.includes("--json");
+  if (process.argv.includes("--click-through")) {
+    process.env.PI_ACTIVITY_STRIP_CLICK_THROUGH = "1";
+  }
 
   switch (command) {
     case "open":
@@ -145,6 +158,43 @@ async function main() {
     case "serve":
       process.exitCode = await openStrip({ detached: false });
       return;
+    case "focus-strip": {
+      try {
+        const status = await getBrokerStatus({ expectReply: true });
+        if (status?.runtimeStatus?.windowVisible !== true) {
+          console.error("No visible strip exists on the focused workspace; focus did nothing.");
+          process.exitCode = 1;
+          return;
+        }
+        const result = await focusNiriStrip(execFileAsync, process.env, status?.snapshot?.sessions);
+        if (!result.ok) console.error(result.error || "Strip focus did nothing.");
+        process.exitCode = result.ok ? 0 : 1;
+      } catch {
+        console.error("Activity strip is not running; focus did nothing.");
+        process.exitCode = 1;
+      }
+      return;
+    }
+    case "focus":
+    case "focus-session": {
+      const sessionId = String(process.argv[3] ?? "").trim();
+      if (!sessionId) {
+        console.error("focus-session requires the full Pi session id");
+        process.exitCode = 2;
+        return;
+      }
+      try {
+        const result = await sendBrokerMessage(makeMessage("focus", { sessionId }), {
+          expectReply: true,
+        });
+        if (!result?.ok) console.error(result?.error || "Focus did nothing.");
+        process.exitCode = result?.ok ? 0 : 1;
+      } catch {
+        console.error("Activity strip is not running; focus did nothing.");
+        process.exitCode = 1;
+      }
+      return;
+    }
     case "status": {
       try {
         const result = await getBrokerStatus({ expectReply: true });

package/examples/simulate-sessions.mjs

@@ -1,3 +1,8 @@
+/**
+summary: "Publishes a timed sequence of simulated activity-strip session snapshots, updates, and removals."
+read_when:
+  - "Changing the example session labels, lifecycle transitions, timing, or broker publication flow."
+*/
 import { setTimeout as delay } from "node:timers/promises";
 import { publishSessionSnapshot, removeSession } from "../src/client/broker-client.mjs";
 import { createInitialSnapshot } from "../src/common/telemetry.mjs";

package/extensions/activity-strip.js

@@ -1,3 +1,9 @@
+// ---
+// summary: "registers activity-strip commands and forwards Pi lifecycle telemetry to the local broker"
+// read_when:
+//   - "changing extension commands, autostart behavior, or telemetry event wiring"
+// ---
+
 import { execFile } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";

package/extensions/activity-strip.ts

@@ -1 +1,7 @@
+// ---
+// summary: "typed extension entrypoint that re-exports the JavaScript activity-strip implementation"
+// read_when:
+//   - "resolving the TypeScript-facing extension module boundary"
+// ---
+
 export { default } from "./activity-strip.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryinget/pi-activity-strip",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "pi extension package for activity-strip workflows in monorepo runtime",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -76,11 +76,11 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.4",
-    "@earendil-works/pi-ai": "^0.80.6",
-    "@earendil-works/pi-coding-agent": "^0.80.6",
+    "@earendil-works/pi-ai": "0.83.0",
+    "@earendil-works/pi-coding-agent": "0.83.0",
     "@types/node": "22.14.0",
     "@typescript/native-preview": "7.0.0-dev.20260417.1",
-    "typebox": "^1.0.0",
+    "typebox": "1.3.7",
     "typescript": "5.9.2"
   },
   "overrides": {

package/src/broker/server.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: "hosts the Unix-socket broker that accepts session updates and broadcasts activity snapshots"
+// read_when:
+//   - "changing broker lifecycle, socket message handling, or snapshot emission"
+// ---
+
 import { EventEmitter } from "node:events";
 import fs from "node:fs";
 import net from "node:net";
@@ -41,19 +47,27 @@ export class ActivityStripBroker extends EventEmitter {
     this.socketDir = options.socketDir ?? ACTIVITY_STRIP_SOCKET_DIR;
     this.store = options.store ?? new SessionStore();
     this.getRuntimeStatus = options.getRuntimeStatus ?? (() => undefined);
+    this.focusSession =
+      options.focusSession ?? (async () => ({ ok: false, error: "Focus unavailable" }));
     this.server = net.createServer((socket) => this.handleConnection(socket));
     this.tick = null;
   }
 
   async start() {
-    fs.mkdirSync(this.socketDir, { recursive: true });
+    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);
-        resolve(undefined);
+        try {
+          fs.chmodSync(this.socketPath, 0o600);
+          resolve(undefined);
+        } catch (error) {
+          reject(error);
+        }
       });
     });
 
@@ -124,6 +138,13 @@ export class ActivityStripBroker extends EventEmitter {
           runtimeStatus: this.getRuntimeStatus(),
         });
         return;
+      case "focus":
+        Promise.resolve(this.focusSession(String(message.sessionId ?? "")))
+          .then((result) => this.reply(socket, { type: "focus", ...result }))
+          .catch(() =>
+            this.reply(socket, { ok: false, type: "focus", error: "Focus failed closed." }),
+          );
+        return;
       case "shutdown":
         this.reply(socket, { ok: true, type: "shutdown" });
         setTimeout(() => {

package/src/broker/session-store.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: "stores normalized session snapshots, expires stale entries, and returns display-ready ordering"
+// read_when:
+//   - "changing session retention, upsert semantics, or broker snapshot ordering"
+// ---
+
 import { ACTIVITY_STRIP_STALE_AFTER_MS } from "../common/constants.mjs";
 import { normalizeSessionSnapshot, sortSessions } from "../common/protocol.mjs";
 

package/src/client/broker-client.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: "sends newline-delimited broker requests for status, shutdown, session publication, and removal"
+// read_when:
+//   - "changing client socket transport, reply timeouts, or broker request helpers"
+// ---
+
 import net from "node:net";
 /** @typedef {import("../common/contracts.ts").BrokerClientOptions} BrokerClientOptions */
 /** @typedef {import("../common/contracts.ts").BrokerResponse} BrokerResponse */

package/src/client/launcher.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: "ensures a compatible activity-strip process is launched and waits for overlay readiness"
+// read_when:
+//   - "changing autostart compatibility gates, process spawning, or readiness polling"
+// ---
+
 import { spawn } from "node:child_process";
 import { setTimeout as delay } from "node:timers/promises";
 import { assessActivityStripCompatibility } from "../common/compatibility.mjs";

package/src/client/session-telemetry.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: "converts Pi lifecycle and tool events into throttled session snapshots for the broker"
+// read_when:
+//   - "changing session state transitions, heartbeat delivery, or event-derived telemetry"
+// ---
+
 /** @typedef {import("../common/contracts.ts").SessionSnapshot} SessionSnapshot */
 /** @typedef {import("../common/contracts.ts").SessionTelemetryOptions} SessionTelemetryOptions */
 /** @typedef {import("../common/contracts.ts").SessionStartContextLike} SessionStartContextLike */
@@ -99,10 +105,13 @@ export function createSessionTelemetry({ pi, cwd = process.cwd(), sessionName =
     },
     /** @param {SessionStartContextLike} ctx */
     async onSessionStart(ctx) {
+      const exactSessionId = String(ctx?.sessionManager?.getSessionId?.() ?? "").trim();
+      const nextCwd = ctx?.cwd ?? snapshot.cwd;
       update({
-        cwd: ctx?.cwd ?? snapshot.cwd,
+        ...(exactSessionId ? { sessionId: exactSessionId } : {}),
+        cwd: nextCwd,
         sessionName: pi?.getSessionName?.() ?? snapshot.sessionName,
-        detail: previewPath(ctx?.cwd ?? snapshot.cwd, 72) || "Ready",
+        detail: previewPath(nextCwd, 72) || "Ready",
       });
       startHeartbeat();
       await flush();

package/src/common/activity-order.mjs

@@ -0,0 +1,68 @@
+// ---
+// summary: "provides deterministic monitoring-first strip ordering while preserving operator-defined order"
+// read_when:
+//   - "changing activity grouping, calm-cadence reconciliation, or manual card order"
+// ---
+
+const ACTIVE_STATES = new Set(["thinking", "tool", "waiting"]);
+
+/** @param {{ state?: string; agentActive?: boolean }} session */
+export function isActiveSession(session) {
+  return Boolean(session?.agentActive || ACTIVE_STATES.has(String(session?.state ?? "")));
+}
+
+/** @param {{ state?: string; toolName?: string; toolTarget?: string }} session */
+export function isMonitoringSession(session) {
+  return Boolean(
+    session?.state === "success" &&
+      !String(session?.toolName ?? "").trim() &&
+      !String(session?.toolTarget ?? "").trim(),
+  );
+}
+
+/**
+ * Reconcile at the calm clock: green settled/monitoring cards first, then active cards,
+ * then other inactive cards. Preserve previous/manual order inside each group and append
+ * new cards deterministically.
+ * @param {Array<{ sessionId: string; state?: string; agentActive?: boolean; toolName?: string; toolTarget?: string; updatedAt?: number }>} sessions
+ * @param {string[]} previousOrder
+ * @param {{ regroup?: boolean }} [options]
+ */
+export function reconcileActivityOrder(sessions, previousOrder = [], { regroup = true } = {}) {
+  const byId = new Map(sessions.map((session) => [session.sessionId, session]));
+  const surviving = previousOrder.filter((id) => byId.has(id));
+  const known = new Set(surviving);
+  for (const session of sessions) {
+    if (!session.sessionId || known.has(session.sessionId)) continue;
+    surviving.push(session.sessionId);
+    known.add(session.sessionId);
+  }
+  if (!regroup) return surviving;
+
+  const priorIndex = new Map(surviving.map((id, index) => [id, index]));
+  const ordered = [...sessions].sort((left, right) => {
+    const leftPriority = isMonitoringSession(left) ? 2 : isActiveSession(left) ? 1 : 0;
+    const rightPriority = isMonitoringSession(right) ? 2 : isActiveSession(right) ? 1 : 0;
+    const groupDelta = rightPriority - leftPriority;
+    if (groupDelta) return groupDelta;
+    const leftPrior = priorIndex.get(left.sessionId);
+    const rightPrior = priorIndex.get(right.sessionId);
+    if (leftPrior != null || rightPrior != null) {
+      return (leftPrior ?? Number.MAX_SAFE_INTEGER) - (rightPrior ?? Number.MAX_SAFE_INTEGER);
+    }
+    const updateDelta = Number(right.updatedAt ?? 0) - Number(left.updatedAt ?? 0);
+    if (updateDelta) return updateDelta;
+    return left.sessionId.localeCompare(right.sessionId);
+  });
+  return ordered.map((session) => session.sessionId).filter((id) => byId.has(id));
+}
+
+/** @param {string[]} order @param {string} sessionId @param {-1 | 1} delta */
+export function moveOrderItem(order, sessionId, delta) {
+  const next = [...order];
+  const from = next.indexOf(sessionId);
+  const to = from + delta;
+  if (from < 0 || to < 0 || to >= next.length) return next;
+  [next[from], next[to]] = [next[to], next[from]];
+  return next;
+}

package/src/common/alignment-controller.mjs

@@ -0,0 +1,74 @@
+// ---
+// summary: "coalesces native-window alignment so stale async work cannot overwrite newer geometry"
+// read_when:
+//   - "changing Electron/Niri geometry reconciliation or testing rapid expansion transitions"
+// ---
+
+/**
+ * @param {{ is_floating?: boolean, layout?: { tile_pos_in_workspace_view?: unknown } } | null | undefined} window
+ */
+export function hasNiriFloatingPosition(window) {
+  const position = window?.layout?.tile_pos_in_workspace_view;
+  return window?.is_floating === true && Array.isArray(position) && position.length >= 2;
+}
+
+/**
+ * @param {{ is_floating?: boolean, layout?: { tile_pos_in_workspace_view?: unknown, window_size?: unknown } } | null | undefined} window
+ * @param {{x: number, y: number, width: number, height: number}} target
+ */
+export function isNiriWindowAligned(window, target) {
+  if (!hasNiriFloatingPosition(window)) return false;
+  const position = window?.layout?.tile_pos_in_workspace_view;
+  const size = window?.layout?.window_size;
+  return Boolean(
+    Array.isArray(position) &&
+      Array.isArray(size) &&
+      Number(size[0]) === target.width &&
+      Number(size[1]) === target.height &&
+      Math.abs(Number(position[0]) - target.x) < 1 &&
+      Math.abs(Number(position[1]) - target.y) < 1,
+  );
+}
+
+/**
+ * @param {(attempt: { generation: number, isCurrent: () => boolean }) => Promise<void>} run
+ */
+export function createLatestOnlyRunner(run) {
+  if (typeof run !== "function") throw new TypeError("run must be a function");
+
+  let requestedGeneration = 0;
+  /** @type {Promise<void> | null} */
+  let worker = null;
+
+  async function drain() {
+    while (true) {
+      const generation = requestedGeneration;
+      const isCurrent = () => generation === requestedGeneration;
+      try {
+        await run({ generation, isCurrent });
+      } catch {
+        // Alignment is best effort. A newer request must still be allowed to reconcile the window.
+      }
+      if (isCurrent()) return;
+    }
+  }
+
+  function request() {
+    requestedGeneration += 1;
+    if (!worker) {
+      worker = drain().finally(() => {
+        worker = null;
+      });
+    }
+    return requestedGeneration;
+  }
+
+  async function waitForIdle() {
+    await worker;
+  }
+
+  return {
+    request,
+    waitForIdle,
+  };
+}

package/src/common/compatibility.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: "detects desktop and Electron prerequisites and formats actionable activity-strip compatibility reports"
+// read_when:
+//   - "changing host detection, compatibility blockers, warnings, or doctor output"
+// ---
+
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { locateElectron } from "./electron.mjs";
@@ -85,6 +91,12 @@ export async function assessActivityStripCompatibility(options = {}) {
     );
   }
 
+  if (windowManager === "niri" && displayCount === 0) {
+    blockers.push(
+      "Niri reports no connected display outputs. Turn on or reconnect the monitor before opening the activity strip.",
+    );
+  }
+
   try {
     electronPath = await locateElectronImpl();
   } catch (error) {
@@ -111,7 +123,7 @@ export async function assessActivityStripCompatibility(options = {}) {
     displayCount,
     alignmentMode: windowManager === "niri" ? "niri" : "generic",
     primaryDisplayOnly: true,
-    clickThroughDefault: env.PI_ACTIVITY_STRIP_CLICK_THROUGH !== "0",
+    clickThroughDefault: env.PI_ACTIVITY_STRIP_CLICK_THROUGH === "1",
     blockers,
     warnings,
   };
@@ -128,7 +140,7 @@ export function formatCompatibilityReport(report) {
     `Electron: ${report.electronPath || "not found"}`,
     `Alignment mode: ${report.alignmentMode}`,
     `Primary-display only: ${report.primaryDisplayOnly ? "yes" : "no"}`,
-    `Click-through default: ${report.clickThroughDefault ? "yes" : "no"}`,
+    `Click-through mode: ${report.clickThroughDefault ? "enabled by environment" : "disabled (interactive default)"}`,
   ];
 
   if (typeof report.displayCount === "number") {

package/src/common/constants.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: "defines shared socket paths, window dimensions, timing thresholds, and Electron binary candidates"
+// read_when:
+//   - "tuning activity-strip runtime defaults or locating shared configuration values"
+// ---
+
 import os from "node:os";
 import path from "node:path";
 
@@ -15,6 +21,10 @@ export const ACTIVITY_STRIP_SOCKET_PATH = path.join(
 );
 export const ACTIVITY_STRIP_WIDTH_PADDING = 16;
 export const ACTIVITY_STRIP_HEIGHT = 84;
+export const ACTIVITY_STRIP_EXPANDED_HEIGHT = 252;
+export const ACTIVITY_STRIP_ORDER_REFRESH_MS = 15_000;
+export const ACTIVITY_STRIP_WORKSPACE_SYNC_MS = 1500;
+export const ACTIVITY_STRIP_NIRI_ANIMATION_SETTLE_MS = 450;
 export const ACTIVITY_STRIP_HEARTBEAT_MS = 2500;
 export const ACTIVITY_STRIP_STALE_AFTER_MS = 12000;
 export const ACTIVITY_STRIP_BROADCAST_TICK_MS = 1000;

package/src/common/contracts.d.ts

@@ -1,3 +1,9 @@
+// ---
+// summary: "declares the public TypeScript shapes shared by activity-strip runtime and JavaScript consumers"
+// read_when:
+//   - "checking emitted declaration contracts for sessions, broker messages, telemetry, or compatibility"
+// ---
+
 export type SessionState = "idle" | "thinking" | "tool" | "waiting" | "success" | "error";
 
 export interface SessionSnapshot {
@@ -68,6 +74,7 @@ export interface ActivityStripBrokerOptions {
     remove(sessionId: string): boolean;
   };
   getRuntimeStatus?: () => ActivityStripRuntimeStatus | undefined;
+  focusSession?: (sessionId: string) => Promise<{ ok: boolean; error?: string; windowId?: number }>;
 }
 
 export interface ToolCallDescription {
@@ -95,6 +102,9 @@ export interface SessionStartContextLike {
     notify?: (message: string, level?: "info" | "warning" | "error") => void;
     editor?: (title: string, text: string) => Promise<unknown>;
   };
+  sessionManager?: {
+    getSessionId?: () => string;
+  };
 }
 
 export interface BeforeAgentStartEventLike {

package/src/common/contracts.ts

@@ -1,3 +1,9 @@
+// ---
+// summary: "defines source TypeScript contracts for session telemetry, broker transport, and runtime compatibility"
+// read_when:
+//   - "changing shared activity-strip types or the interfaces consumed through JSDoc imports"
+// ---
+
 export type SessionState = "idle" | "thinking" | "tool" | "waiting" | "success" | "error";
 
 export interface SessionSnapshot {
@@ -68,6 +74,7 @@ export interface ActivityStripBrokerOptions {
     remove(sessionId: string): boolean;
   };
   getRuntimeStatus?: () => ActivityStripRuntimeStatus | undefined;
+  focusSession?: (sessionId: string) => Promise<{ ok: boolean; error?: string; windowId?: number }>;
 }
 
 export interface ToolCallDescription {
@@ -95,6 +102,9 @@ export interface SessionStartContextLike {
     notify?: (message: string, level?: "info" | "warning" | "error") => void;
     editor?: (title: string, text: string) => Promise<unknown>;
   };
+  sessionManager?: {
+    getSessionId?: () => string;
+  };
 }
 
 export interface BeforeAgentStartEventLike {

package/src/common/electron.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: "resolves an executable Electron binary from explicit settings, local dependencies, or PATH candidates"
+// read_when:
+//   - "changing Electron discovery order, environment overrides, or executable checks"
+// ---
+
 import { constants } from "node:fs";
 import { access } from "node:fs/promises";
 import path from "node:path";

package/src/common/format.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: "provides ANSI-safe truncation, whitespace compaction, and concise path, command, and session labels"
+// read_when:
+//   - "changing text previews or labels displayed in activity-strip telemetry"
+// ---
+
 import path from "node:path";
 
 // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape stripping requires an ESC control character pattern.