@tryinget/pi-activity-strip 0.6.0 → 0.8.0

package/src/client/runtime-lock.mjs

@@ -0,0 +1,140 @@
+// ---
+// summary: "waits on the native runtime flock so stop returns only after the controller exits, and open can name a held lock"
+// read_when:
+//   - "changing how stop waits for shutdown or how open reports a runtime that failed to start"
+// ---
+
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+import {
+  ACTIVITY_STRIP_SOCKET_DIR,
+  ACTIVITY_STRIP_START_TIMEOUT_MS,
+  ACTIVITY_STRIP_STOP_TIMEOUT_MS,
+} from "../common/constants.mjs";
+import { requestBrokerShutdown } from "./broker-client.mjs";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * The exit status `flock` uses for a held lock. It differs from every status the controller or
+ * `flock` itself can return, so a held lock is never confused with a failure to check it.
+ */
+export const RUNTIME_LOCK_CONFLICT_EXIT_CODE = 75;
+
+/** The controller holds this lock for its whole lifetime. */
+export const RUNTIME_LOCK_PATH = path.join(ACTIVITY_STRIP_SOCKET_DIR, "runtime.lock");
+
+/** @typedef {import("../common/contracts.ts").BrokerResponse} BrokerResponse */
+/** @typedef {{exitCode: number | null | undefined}} ControllerHandle */
+
+/**
+ * Take and release the lock once, reporting whether it was held.
+ * @param {string} lockPath
+ * @param {string[]} mode
+ * @returns {Promise<"free" | "held" | {error: string}>}
+ */
+async function tryRuntimeLock(lockPath, mode) {
+  const conflict = String(RUNTIME_LOCK_CONFLICT_EXIT_CODE);
+  try {
+    await execFileAsync("flock", [...mode, "--conflict-exit-code", conflict, lockPath, "true"]);
+    return "free";
+  } catch (error) {
+    const failure = /** @type {{code?: unknown; message?: string}} */ (error ?? {});
+    if (failure.code === RUNTIME_LOCK_CONFLICT_EXIT_CODE) return "held";
+    return {
+      error: `Could not check the activity-strip runtime lock: ${failure.message ?? String(error)}`,
+    };
+  }
+}
+
+/**
+ * Wait until the controller holding the runtime lock has exited. The controller holds the lock for
+ * its whole lifetime and closes its broker before it lets go, so a closed broker alone does not
+ * prove it is gone. `waited` says whether a runtime was still there.
+ * @param {string} lockPath
+ * @param {{timeoutMs: number}} options
+ * @returns {Promise<{released: boolean; waited?: boolean; error?: string}>}
+ */
+export async function waitForRuntimeExit(lockPath, { timeoutMs }) {
+  const now = await tryRuntimeLock(lockPath, ["--nonblock"]);
+  if (now === "free") return { released: true, waited: false };
+  if (now !== "held") return { released: false, error: now.error };
+  const later = await tryRuntimeLock(lockPath, ["--wait", String(timeoutMs / 1000)]);
+  if (later === "free") return { released: true, waited: true };
+  if (later === "held") return { released: false, waited: true };
+  return { released: false, error: later.error };
+}
+
+/**
+ * Stop the runtime and return once it has exited. Every stop path, the CLI and Pi's commands, goes
+ * through here, so a following open can never race a runtime that is still shutting down. The lock
+ * is waited on even when no broker answers: a runtime whose broker has closed still holds it.
+ * @param {{
+ *   requestShutdown?: () => Promise<{ok?: boolean} | null | undefined>;
+ *   waitForExit?: typeof waitForRuntimeExit;
+ *   lockPath?: string;
+ *   timeoutMs?: number;
+ * }} [options]
+ * @returns {Promise<{outcome: "stopped" | "not-running" | "still-stopping"} | {outcome: "error"; error: string}>}
+ */
+export async function stopRuntime({
+  requestShutdown = requestBrokerShutdown,
+  waitForExit = waitForRuntimeExit,
+  lockPath = RUNTIME_LOCK_PATH,
+  timeoutMs = ACTIVITY_STRIP_STOP_TIMEOUT_MS,
+} = {}) {
+  let accepted = false;
+  try {
+    accepted = (await requestShutdown())?.ok === true;
+  } catch {
+    accepted = false;
+  }
+  const exit = await waitForExit(lockPath, { timeoutMs });
+  if (exit.error) return { outcome: "error", error: exit.error };
+  if (!exit.released) return { outcome: "still-stopping" };
+  return { outcome: accepted || exit.waited ? "stopped" : "not-running" };
+}
+
+/**
+ * Wait for the controller `open` just spawned under the runtime lock to become ready. A spawn that
+ * finds the lock held exits with the conflict status. The wait still continues, because the holder
+ * may be a controller another `open` is starting; the held lock is reported only if nothing
+ * becomes ready in time.
+ * @param {{
+ *   controller: ControllerHandle;
+ *   getStatus: () => Promise<BrokerResponse | null>;
+ *   timeoutMs?: number;
+ *   retryMs?: number;
+ *   now?: () => number;
+ *   sleep?: (ms: number) => Promise<unknown>;
+ * }} options
+ * @returns {Promise<{ok: true; started: boolean} | {ok: false; reason: "error" | "exited" | "lock-held" | "timeout"; status: BrokerResponse | null; exitCode?: number | null}>}
+ */
+export async function waitForStartedRuntime({
+  controller,
+  getStatus,
+  timeoutMs = ACTIVITY_STRIP_START_TIMEOUT_MS,
+  retryMs = 125,
+  now = Date.now,
+  sleep = delay,
+}) {
+  const deadline = now() + timeoutMs;
+  while (true) {
+    const status = await getStatus();
+    if (status?.ok && (!status.runtimeStatus || status.runtimeStatus.state === "ready")) {
+      return { ok: true, started: controller.exitCode === undefined };
+    }
+    if (status?.runtimeStatus?.state === "error") return { ok: false, reason: "error", status };
+    const exitCode = controller.exitCode;
+    if (exitCode !== undefined && exitCode !== RUNTIME_LOCK_CONFLICT_EXIT_CODE) {
+      return { ok: false, reason: "exited", status, exitCode };
+    }
+    if (now() >= deadline) {
+      const reason = exitCode === RUNTIME_LOCK_CONFLICT_EXIT_CODE ? "lock-held" : "timeout";
+      return { ok: false, reason, status };
+    }
+    await sleep(retryMs);
+  }
+}

package/src/common/claude-events.mjs

@@ -46,7 +46,7 @@ export function claudeEventPath(sessionId, directory = CLAUDE_EVENT_DIR) {
  */
 export function describeHookToolTarget(toolInput) {
   for (const key of ["description", "command", "file_path", "path", "pattern", "query", "url"]) {
-    const value = /** @type {any} */ (toolInput ?? {})[key];
+    const value = /** @type {any} */ (toolInput)?.[key];
     if (typeof value === "string" && value.trim()) return preview(value);
   }
   return "";

package/src/common/constants.mjs

@@ -25,5 +25,7 @@ export const ACTIVITY_STRIP_BROADCAST_TICK_MS = 1000;
 export const ACTIVITY_STRIP_SEND_THROTTLE_MS = 120;
 export const ACTIVITY_STRIP_CONNECT_TIMEOUT_MS = 450;
 export const ACTIVITY_STRIP_START_TIMEOUT_MS = 5000;
+/** How long `stop` waits for the runtime to exit; an in-flight read-only `ak` query can take 8 s. */
+export const ACTIVITY_STRIP_STOP_TIMEOUT_MS = 15_000;
 export const ACTIVITY_STRIP_EVENT_STALL_MS = 15 * 60_000;
 export const ACTIVITY_STRIP_FLUSH_RETRY_DELAYS_MS = [250, 750];

package/src/common/contracts.d.ts

@@ -19,6 +19,15 @@ export interface SessionSnapshot {
   publisherCount?: number;
   publisherIds?: string[];
   publisherRecordKeys?: string[];
+  publisherSessionIds?: string[];
+  akTasks?: AkTaskChip[];
+  akTaskOverflow?: number;
+  /** Niri window id; for a hidden tab, the window hosting it. */
+  windowId?: number | null;
+  /** Niri workspace `idx`, the number the operator sees, never the internal workspace id. */
+  workspaceIdx?: number | null;
+  placement?: "title" | "host" | "binding";
+  surfaceVisible?: boolean;
   cwd: string;
   repoLabel: string;
   sessionName: string;

package/src/common/contracts.ts

@@ -22,7 +22,10 @@ export interface SessionSnapshot {
   publisherSessionIds?: string[];
   akTasks?: AkTaskChip[];
   akTaskOverflow?: number;
+  /** Niri window id; for a hidden tab, the window hosting it. */
   windowId?: number | null;
+  /** Niri workspace `idx`, the number the operator sees, never the internal workspace id. */
+  workspaceIdx?: number | null;
   placement?: "title" | "host" | "binding";
   surfaceVisible?: boolean;
   cwd: string;

package/src/common/niri-focus.mjs

@@ -7,8 +7,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { presentGhosttySurface } from "./ghostty-present.mjs";
-import { projectSessionCards, sessionCardId } from "./session-cards.mjs";
-import { parseTerminalTitleBinding } from "./surface-bindings.mjs";
+import { sessionCardId } from "./session-cards.mjs";
 import {
   appIdForGhosttyFamily,
   canonicalGhosttyTerminalKey,

package/src/common/workspace-view.mjs

@@ -4,11 +4,7 @@
 //   - "changing workspace card membership, card visibility, or focused-card selection"
 // ---
 
-import {
-  canVerifyTabVisibility,
-  placeSessionWindow,
-  resolvePiSessionIdentity,
-} from "./niri-focus.mjs";
+import { canVerifyTabVisibility, placeSessionWindow } from "./niri-focus.mjs";
 import { projectSessionCards, sessionCardId } from "./session-cards.mjs";
 import { parseTerminalTitleBinding } from "./surface-bindings.mjs";
 import { canonicalGhosttyTerminalKey } from "./terminal-identity.mjs";
@@ -96,6 +92,8 @@ export function resolveWorkspaceView(windows, workspace, sessions, options = {})
     groups.set(candidate.cardId, group);
   }
 
+  // The number the operator sees in the workspace list, not Niri's internal workspace id.
+  const workspaceIdx = Number.isInteger(workspace.idx) ? Number(workspace.idx) : null;
   const projectedSessions = [];
   for (const [cardId, group] of groups) {
     const windowIds = new Set(group.map((candidate) => candidate.window.id));
@@ -115,7 +113,9 @@ export function resolveWorkspaceView(windows, workspace, sessions, options = {})
     projectedSessions.push({
       ...card,
       cardId,
+      // A hidden tab has no window of its own, so this is the window hosting it.
       windowId: window?.id,
+      workspaceIdx,
       placement,
       // Only a tab proven to sit behind another one is marked hidden.
       surfaceVisible: visibility !== "hidden",

package/src/native/main.mjs

@@ -6,10 +6,6 @@
 // ---
 
 import { execFile, spawn } from "node:child_process";
-import { createHash } from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { createActivityStripBroker } from "../broker/server.mjs";
 import { createLatestOnlyRunner } from "../common/alignment-controller.mjs";
@@ -21,6 +17,7 @@ import { resolveFocusedWorkspaceView } from "../common/workspace-view.mjs";
 import { discoverAgentTabs } from "./agent-discovery.mjs";
 import { startAkTaskProjection } from "./ak-runtime.mjs";
 import { createHeightRepair } from "./height-repair.mjs";
+import { resolvePanelBinary } from "./panel-binary.mjs";
 import { createNativePanelProjection } from "./panel-projection.mjs";
 import { createPlacementRuntime } from "./placement.mjs";
 import { createThemeRuntime, THEME_POLL_INTERVAL_MS } from "./theme-runtime.mjs";
@@ -30,8 +27,6 @@ import { createNiriWorkspaceEventWatcher } from "./workspace-events.mjs";
 /** @typedef {import("node:child_process").ChildProcessWithoutNullStreams & {_activityBuffer?: string; _readyTimer?: NodeJS.Timeout; _stableTimer?: NodeJS.Timeout}} PanelChild */
 /** @typedef {{type: string; protocol?: number; revision?: number; visible?: boolean; sessions?: Array<Record<string, unknown>>; [key: string]: unknown}} PanelMessage */
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const packageRoot = path.resolve(__dirname, "..", "..");
 const execFileAsync = promisify(execFile);
 
 /** @type {import("../broker/server.mjs").ActivityStripBroker | null} */
@@ -94,49 +89,6 @@ const placement = createPlacementRuntime({
   onBindingsLearned: () => reconcileRunner.request(),
 });
 
-function panelBinaryPath() {
-  const override = process.env.PI_ACTIVITY_STRIP_NATIVE_PANEL_BIN?.trim();
-  const allowUnverified = process.env.PI_ACTIVITY_STRIP_ALLOW_UNVERIFIED_PANEL === "1";
-  const candidates = [
-    ...(override ? [override] : []),
-    path.join(packageRoot, "native", "bin", "linux-x64-gnu", "pi-activity-strip-panel"),
-    ...(allowUnverified
-      ? [path.join(packageRoot, "native", "panel", "target", "release", "pi-activity-strip-panel")]
-      : []),
-  ].filter(Boolean);
-  const binary = candidates.find((candidate) => {
-    try {
-      fs.accessSync(candidate, fs.constants.X_OK);
-      return true;
-    } catch {
-      return false;
-    }
-  });
-  if (!binary) {
-    throw new Error(`Native panel binary is unavailable. Checked: ${candidates.join(", ")}`);
-  }
-  if (allowUnverified) return binary;
-  if (process.platform !== "linux" || process.arch !== "x64") {
-    throw new Error(`Native panel requires Linux x64, got ${process.platform} ${process.arch}.`);
-  }
-  const artifactPath = path.join(path.dirname(binary), "artifact.json");
-  let artifact;
-  try {
-    artifact = JSON.parse(fs.readFileSync(artifactPath, "utf8"));
-  } catch {
-    throw new Error(`Native panel receipt is unavailable: ${artifactPath}`);
-  }
-  const digest = createHash("sha256").update(fs.readFileSync(binary)).digest("hex");
-  if (
-    artifact.schema !== "pi-activity-strip-native-artifact.v1" ||
-    artifact.target !== "x86_64-unknown-linux-gnu" ||
-    artifact.sha256 !== digest
-  ) {
-    throw new Error("Native panel binary does not match its reviewed artifact receipt.");
-  }
-  return binary;
-}
-
 /** @param {PanelMessage} message */
 function writePanel(message) {
   if (!panelReady || !panelWriteReady || !panel?.stdin?.writable) {
@@ -297,9 +249,8 @@ function consumePanelEvents(child, chunk) {
 
 function startPanel() {
   if (shuttingDown) return;
-  const binary = panelBinaryPath();
   /** @type {PanelChild} */
-  const child = spawn(binary, [], {
+  const child = spawn(resolvePanelBinary(process.env), [], {
     env: process.env,
     stdio: ["pipe", "pipe", "pipe"],
   });
@@ -475,6 +426,7 @@ async function main() {
         if (placement.forgetWindow(windowId)) reconcileRunner.request();
       },
       onWindowFocusChanged: () => reconcileRunner.request(),
+      onWorkspacesChanged: () => reconcileRunner.request(),
       fallbackMs: ACTIVITY_STRIP_WORKSPACE_SYNC_MS,
     });
   }

package/src/native/panel-binary.mjs

@@ -0,0 +1,56 @@
+// ---
+// summary: "locates the native panel binary and verifies it against its reviewed artifact receipt"
+// read_when:
+//   - "changing which panel binary the controller starts or how its receipt is checked"
+// ---
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** @param {NodeJS.ProcessEnv} env */
+export function resolvePanelBinary(env) {
+  const override = env.PI_ACTIVITY_STRIP_NATIVE_PANEL_BIN?.trim();
+  const allowUnverified = env.PI_ACTIVITY_STRIP_ALLOW_UNVERIFIED_PANEL === "1";
+  const candidates = [
+    ...(override ? [override] : []),
+    path.join(packageRoot, "native", "bin", "linux-x64-gnu", "pi-activity-strip-panel"),
+    ...(allowUnverified
+      ? [path.join(packageRoot, "native", "panel", "target", "release", "pi-activity-strip-panel")]
+      : []),
+  ].filter(Boolean);
+  const binary = candidates.find((candidate) => {
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  if (!binary) {
+    throw new Error(`Native panel binary is unavailable. Checked: ${candidates.join(", ")}`);
+  }
+  if (allowUnverified) return binary;
+  if (process.platform !== "linux" || process.arch !== "x64") {
+    throw new Error(`Native panel requires Linux x64, got ${process.platform} ${process.arch}.`);
+  }
+  const artifactPath = path.join(path.dirname(binary), "artifact.json");
+  let artifact;
+  try {
+    artifact = JSON.parse(fs.readFileSync(artifactPath, "utf8"));
+  } catch {
+    throw new Error(`Native panel receipt is unavailable: ${artifactPath}`);
+  }
+  const digest = createHash("sha256").update(fs.readFileSync(binary)).digest("hex");
+  if (
+    artifact.schema !== "pi-activity-strip-native-artifact.v1" ||
+    artifact.target !== "x86_64-unknown-linux-gnu" ||
+    artifact.sha256 !== digest
+  ) {
+    throw new Error("Native panel binary does not match its reviewed artifact receipt.");
+  }
+  return binary;
+}

package/src/native/panel-projection.mjs

@@ -11,7 +11,7 @@ import { projectSessionCards, sessionRecordKey } from "../common/session-cards.m
 /** @typedef {Record<string, unknown>} SessionRecord */
 /** @typedef {{generatedAt: number; sessions: SessionRecord[]}} Snapshot */
 /** @typedef {{workspace: Record<string, unknown> | null; sessions: SessionRecord[]; focusedSessionId: string | null; focusedCardId?: string | null}} WorkspaceView */
-/** @typedef {{placement: string; surfaceVisible: boolean; windowId: number | null}} CardPlacement */
+/** @typedef {{placement: string; surfaceVisible: boolean; windowId: number | null; workspaceIdx: number | null}} CardPlacement */
 /** @typedef {{isNiriSession: () => boolean; publish: (view: Record<string, unknown> & {type: string; sessions: SessionRecord[]}) => void}} NativePanelProjectionOptions */
 
 /** @param {NativePanelProjectionOptions} options */
@@ -137,6 +137,9 @@ export function createNativePanelProjection({ isNiriSession, publish }) {
             placement: String(session.placement ?? "title"),
             surfaceVisible: session.surfaceVisible !== false,
             windowId: Number.isInteger(session.windowId) ? Number(session.windowId) : null,
+            workspaceIdx: Number.isInteger(session.workspaceIdx)
+              ? Number(session.workspaceIdx)
+              : null,
           },
         ]),
       );

package/src/native/workspace-events.mjs

@@ -9,6 +9,8 @@
  * stream while retaining the slower poll as a fail-closed fallback. Window
  * open/change/close and focus events are forwarded so title changes that reveal
  * a Ghostty tab, or windows moving between workspaces, are seen between polls.
+ * Workspace list changes are forwarded too, because reordering or removing a
+ * workspace renumbers the focused one without activating anything.
  * @param {{
  *   spawn: typeof import("node:child_process").spawn;
  *   env: NodeJS.ProcessEnv;
@@ -17,6 +19,7 @@
  *   onWindowChanged?: (window: Record<string, unknown>) => void;
  *   onWindowClosed?: (windowId: number) => void;
  *   onWindowFocusChanged?: (windowId: number | null) => void;
+ *   onWorkspacesChanged?: () => void;
  *   fallbackMs: number;
  *   setIntervalFn?: typeof setInterval;
  *   clearIntervalFn?: typeof clearInterval;
@@ -57,6 +60,9 @@ export function createNiriWorkspaceEventWatcher(options) {
             lastFocusedWorkspaceId = activation.id;
             options.onFocusedWorkspace(activation.id);
           }
+          if (event && typeof event === "object" && "WorkspacesChanged" in event) {
+            options.onWorkspacesChanged?.();
+          }
           const changedWindow = event?.WindowOpenedOrChanged?.window;
           if (changedWindow && typeof changedWindow === "object") {
             options.onWindowChanged?.(changedWindow);