@blackbelt-technology/pi-agent-dashboard 0.2.9 → 0.4.0

package/packages/server/src/directory-service.ts

@@ -1,19 +1,34 @@
 /**
  * DirectoryService — server-side directory-scoped operations.
- * Handles session discovery, event loading, and OpenSpec polling
- * directly on the server without requiring bridge connections.
+ *
+ * Responsibilities:
+ *   - Session discovery and event loading (unchanged).
+ *   - OpenSpec polling with an mtime-gated cache, configurable interval,
+ *     concurrency cap (semaphore), and deterministic per-cwd jitter to
+ *     flatten the CPU envelope.
+ *   - Pi resources scanning on its own slower cadence (5× openspec interval)
+ *     so it does not stack onto the openspec burst.
+ *
+ * See change: optimize-openspec-poll-burst for the cost model.
  */
-import { pollOpenSpecAsync } from "@blackbelt-technology/pi-dashboard-shared/openspec-poller.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  buildOpenSpecData,
+  pollOpenSpecAsync,
+  runOpenSpecList,
+  runOpenSpecStatus,
+} from "@blackbelt-technology/pi-dashboard-shared/openspec-poller.js";
+import { DEFAULT_OPENSPEC_POLL, type OpenSpecPollConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { createSemaphore, type Semaphore } from "@blackbelt-technology/pi-dashboard-shared/semaphore.js";
 import { discoverSessionsForCwd } from "./session-discovery.js";
 import { replayEntriesAsEvents } from "@blackbelt-technology/pi-dashboard-shared/state-replay.js";
 import { scanPiResources } from "./pi-resource-scanner.js";
-import type { OpenSpecData } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import type { OpenSpecData, OpenSpecChange } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import type { PiResourcesResult } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
 import type { PreferencesStore } from "./preferences-store.js";
 import type { SessionManager } from "./memory-session-manager.js";
 
-const POLL_INTERVAL = 30_000;
-
 import type { DiscoveredSession } from "./session-discovery.js";
 export type { DiscoveredSession } from "./session-discovery.js";
 
@@ -33,34 +48,88 @@ export interface DirectoryService {
   discoverSessions(cwd: string): DiscoveredSession[];
   loadSessionEvents(sessionId: string, sessionFile: string): Promise<LoadResult>;
   getOpenSpecData(cwd: string): OpenSpecData | undefined;
+  /** Force refresh: bypasses the mtime gate. Still honors the semaphore. */
   refreshOpenSpec(cwd: string): Promise<OpenSpecData>;
+  /** Gated poll: respects `changeDetection` config and the semaphore. Returns cached data. */
+  pollDirectoryGated(cwd: string): Promise<OpenSpecData>;
   getPiResources(cwd: string): PiResourcesResult | undefined;
   refreshPiResources(cwd: string): Promise<PiResourcesResult>;
   startPolling(onChange: (cwd: string, data: OpenSpecData) => void): void;
   stopPolling(): void;
+  /** Apply a new OpenSpecPollConfig without losing cache. Safe to call mid-stream. */
+  reconfigurePolling(config: OpenSpecPollConfig): void;
   onDirectoryAdded(cwd: string): Promise<DirectoryAddedResult>;
 }
 
+// ── Jitter ─────────────────────────────────────────────────────────
+// 32-bit FNV-1a hash — cheap, stable, well-distributed for short strings.
+export function fnv1a32(s: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+export function phaseOffsetMs(cwd: string, jitterSeconds: number): number {
+  if (!Number.isFinite(jitterSeconds) || jitterSeconds <= 0) return 0;
+  return fnv1a32(cwd) % (jitterSeconds * 1000);
+}
+
+// ── mtime helpers ──────────────────────────────────────────────────
+function statMtimeOr(p: string): number | undefined {
+  try {
+    return fs.statSync(p).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
+// ── Per-directory cache ────────────────────────────────────────────
+type PerChangeEntry = {
+  mtimeMs: number | undefined;
+  change: OpenSpecChange;
+};
+
+type DirCache = {
+  /** mtime of `<cwd>/openspec/changes/` when we last ran `openspec list`. */
+  listMtimeMs: number | undefined;
+  /** Cached list-result entries (raw shape from openspec list). */
+  listResult: Array<{ name: string; status: string; completedTasks: number; totalTasks: number }> | undefined;
+  changes: Map<string, PerChangeEntry>;
+  /** Last built OpenSpecData (what we broadcast). */
+  data: OpenSpecData | undefined;
+};
+
+function emptyDirCache(): DirCache {
+  return { listMtimeMs: undefined, listResult: undefined, changes: new Map(), data: undefined };
+}
+
 export function createDirectoryService(
   preferencesStore: PreferencesStore,
   sessionManager: SessionManager,
+  initialConfig?: Partial<OpenSpecPollConfig>,
 ): DirectoryService {
-  const openspecCache = new Map<string, OpenSpecData>();
+  let cfg: OpenSpecPollConfig = { ...DEFAULT_OPENSPEC_POLL, ...(initialConfig ?? {}) };
+
+  const caches = new Map<string, DirCache>();
   const piResourcesCache = new Map<string, PiResourcesResult>();
+
+  let semaphore: Semaphore = createSemaphore(cfg.maxConcurrentSpawns);
+
   let pollTimer: ReturnType<typeof setInterval> | null = null;
+  let piResourcesTimer: ReturnType<typeof setInterval> | null = null;
   let onChangeCallback: ((cwd: string, data: OpenSpecData) => void) | null = null;
+  const scheduledPhaseTimers = new Set<ReturnType<typeof setTimeout>>();
 
   // In-progress session loads for dedup
   const loadingSet = new Set<string>();
 
   function computeKnownDirectories(): string[] {
     const dirs = new Set<string>();
-    for (const dir of preferencesStore.getPinnedDirectories()) {
-      dirs.add(dir);
-    }
-    for (const session of sessionManager.listAll()) {
-      dirs.add(session.cwd);
-    }
+    for (const dir of preferencesStore.getPinnedDirectories()) dirs.add(dir);
+    for (const session of sessionManager.listAll()) dirs.add(session.cwd);
     return Array.from(dirs);
   }
 
@@ -69,7 +138,6 @@ export function createDirectoryService(
   }
 
   async function loadSessionEvents(sessionId: string, sessionFile: string): Promise<LoadResult> {
-    // Dedup: wait if already loading
     if (loadingSet.has(sessionId)) {
       return { success: false, events: [], error: "already_loading" };
     }
@@ -88,34 +156,190 @@ export function createDirectoryService(
     }
   }
 
-  async function refreshOpenSpec(cwd: string): Promise<OpenSpecData> {
-    const data = await pollOpenSpecAsync(cwd);
-    openspecCache.set(cwd, data);
+  // ── Core gated poll ──────────────────────────────────────────────
+  // Contract:
+  //   - `force=true` bypasses both the list-mtime and per-change-mtime gates.
+  //   - Every CLI spawn goes through the shared semaphore.
+  //   - Cache is updated atomically per directory: on any failure the
+  //     old cache stays intact.
+  async function pollOne(cwd: string, force: boolean): Promise<OpenSpecData> {
+    const cache = caches.get(cwd) ?? emptyDirCache();
+    const gateEnabled = cfg.changeDetection === "mtime" && !force;
+
+    const changesRoot = path.join(cwd, "openspec", "changes");
+    const rootMtime = statMtimeOr(changesRoot);
+
+    // If the directory doesn't exist, short-circuit (matches old behavior).
+    if (rootMtime === undefined) {
+      const empty: OpenSpecData = { initialized: false, changes: [] };
+      cache.data = empty;
+      cache.listMtimeMs = undefined;
+      cache.listResult = undefined;
+      cache.changes.clear();
+      caches.set(cwd, cache);
+      return empty;
+    }
+
+    // ── Step 1: list (gated) ──
+    let listResult: typeof cache.listResult = cache.listResult;
+    const listCacheValid = gateEnabled && cache.listMtimeMs === rootMtime && cache.listResult !== undefined;
+    if (!listCacheValid) {
+      const raw = await semaphore.run(() => runOpenSpecList(cwd));
+      if (!raw || !Array.isArray(raw.changes)) {
+        const empty: OpenSpecData = { initialized: false, changes: [] };
+        cache.data = empty;
+        cache.listMtimeMs = rootMtime;
+        cache.listResult = undefined;
+        cache.changes.clear();
+        caches.set(cwd, cache);
+        return empty;
+      }
+      listResult = raw.changes;
+      cache.listMtimeMs = rootMtime;
+      cache.listResult = listResult;
+    }
+
+    // Prune cache for changes no longer present.
+    const liveNames = new Set((listResult ?? []).map((c) => c.name));
+    for (const key of Array.from(cache.changes.keys())) {
+      if (!liveNames.has(key)) cache.changes.delete(key);
+    }
+
+    // ── Step 2: per-change status (gated) ──
+    const statusResults = new Map<string, { artifacts?: Array<{ id: string; status: string }>; isComplete?: boolean } | null>();
+
+    await Promise.all((listResult ?? []).map(async (c) => {
+      const changeDir = path.join(changesRoot, c.name);
+      const changeMtime = statMtimeOr(changeDir);
+      const cached = cache.changes.get(c.name);
+
+      if (gateEnabled && cached && cached.mtimeMs !== undefined && cached.mtimeMs === changeMtime) {
+        // Cache hit. Reuse the artifacts/isComplete from the cached OpenSpecChange.
+        statusResults.set(c.name, {
+          artifacts: cached.change.artifacts.map((a) => ({ id: a.id, status: a.status })),
+          ...(cached.change.isComplete !== undefined ? { isComplete: cached.change.isComplete } : {}),
+        });
+        return;
+      }
+
+      const status = await semaphore.run(() => runOpenSpecStatus(cwd, c.name));
+      statusResults.set(c.name, status);
+    }));
+
+    // ── Step 3: build + cache + return ──
+    const data = buildOpenSpecData({ changes: listResult ?? [] }, statusResults);
+
+    // Update per-change cache with the mtimes we just observed.
+    for (const change of data.changes) {
+      const changeDir = path.join(changesRoot, change.name);
+      const changeMtime = statMtimeOr(changeDir);
+      cache.changes.set(change.name, { mtimeMs: changeMtime, change });
+    }
+    cache.data = data;
+    caches.set(cwd, cache);
     return data;
   }
 
+  async function refreshOpenSpec(cwd: string): Promise<OpenSpecData> {
+    try {
+      return await pollOne(cwd, true);
+    } catch {
+      // Fall back to the legacy monolithic path so "refresh" never silently fails.
+      const data = await pollOpenSpecAsync(cwd);
+      const cache = caches.get(cwd) ?? emptyDirCache();
+      cache.data = data;
+      caches.set(cwd, cache);
+      return data;
+    }
+  }
+
+  async function pollDirectoryGated(cwd: string): Promise<OpenSpecData> {
+    return pollOne(cwd, false);
+  }
+
   async function refreshPiResourcesInternal(cwd: string): Promise<PiResourcesResult> {
     const data = await scanPiResources(cwd);
     piResourcesCache.set(cwd, data);
     return data;
   }
 
-  async function pollAllDirectories() {
-    const dirs = computeKnownDirectories();
-    // Poll all directories in parallel, non-blocking
-    await Promise.all(dirs.map(async (cwd) => {
-      const [data] = await Promise.all([
-        pollOpenSpecAsync(cwd),
-        refreshPiResourcesInternal(cwd),
-      ]);
-      const prev = openspecCache.get(cwd);
-      const prevJson = prev ? JSON.stringify(prev) : undefined;
-      const newJson = JSON.stringify(data);
-      openspecCache.set(cwd, data);
-      if (newJson !== prevJson) {
-        onChangeCallback?.(cwd, data);
+  // ── Scheduler ────────────────────────────────────────────────────
+  const TICK_SLOW_WARN_MS = 5000;
+  const DEBUG_ENABLED =
+    typeof process !== "undefined" && typeof process.env?.DEBUG === "string" && /pi-dashboard|openspec-poll/.test(process.env.DEBUG);
+
+  let openspecTickInFlight = false;
+  async function scheduleOpenSpecTick() {
+    if (openspecTickInFlight) return;
+    openspecTickInFlight = true;
+    const tickStart = Date.now();
+    let spawnsBefore = 0;
+    let spawnsAfter = 0;
+    try {
+      const dirs = computeKnownDirectories();
+      // Track spawn count by hooking the semaphore's size(). Approximation.
+      spawnsBefore = semaphore.size();
+      await Promise.all(dirs.map((cwd) => new Promise<void>((resolve) => {
+        const delay = phaseOffsetMs(cwd, cfg.jitterSeconds);
+        const timer = setTimeout(async () => {
+          scheduledPhaseTimers.delete(timer);
+          try {
+            const prev = caches.get(cwd)?.data;
+            const prevJson = prev ? JSON.stringify(prev) : undefined;
+            const next = await pollDirectoryGated(cwd);
+            const nextJson = JSON.stringify(next);
+            if (nextJson !== prevJson) onChangeCallback?.(cwd, next);
+          } catch (err) {
+            // Swallow — the next tick will retry.
+            console.error(`[openspec-poll] tick failed for ${cwd}:`, err);
+          } finally {
+            resolve();
+          }
+        }, delay);
+        scheduledPhaseTimers.add(timer);
+      })));
+      spawnsAfter = semaphore.size();
+    } finally {
+      openspecTickInFlight = false;
+      const durationMs = Date.now() - tickStart;
+      if (DEBUG_ENABLED) {
+        const dirs = computeKnownDirectories().length;
+        // eslint-disable-next-line no-console
+        console.log(`[openspec-poll] tick dirs=${dirs} queueBefore=${spawnsBefore} queueAfter=${spawnsAfter} durationMs=${durationMs}`);
       }
-    }));
+      if (durationMs > TICK_SLOW_WARN_MS) {
+        console.warn(`[openspec-poll] slow tick: ${durationMs}ms (threshold ${TICK_SLOW_WARN_MS}ms). Consider raising pollIntervalSeconds or lowering maxConcurrentSpawns.`);
+      }
+    }
+  }
+
+  let piResourcesInFlight = false;
+  async function schedulePiResourcesTick() {
+    if (piResourcesInFlight) return;
+    piResourcesInFlight = true;
+    try {
+      await Promise.all(computeKnownDirectories().map(async (cwd) => {
+        try { await refreshPiResourcesInternal(cwd); }
+        catch { /* ignore, next tick retries */ }
+      }));
+    } finally {
+      piResourcesInFlight = false;
+    }
+  }
+
+  function installTimers() {
+    if (pollTimer) clearInterval(pollTimer);
+    if (piResourcesTimer) clearInterval(piResourcesTimer);
+    pollTimer = setInterval(scheduleOpenSpecTick, cfg.pollIntervalSeconds * 1000);
+    // Pi resources change far less often; poll at 5× the openspec interval.
+    piResourcesTimer = setInterval(schedulePiResourcesTick, cfg.pollIntervalSeconds * 5 * 1000);
+  }
+
+  function stopTimers() {
+    if (pollTimer) { clearInterval(pollTimer); pollTimer = null; }
+    if (piResourcesTimer) { clearInterval(piResourcesTimer); piResourcesTimer = null; }
+    for (const t of scheduledPhaseTimers) clearTimeout(t);
+    scheduledPhaseTimers.clear();
   }
 
   return {
@@ -124,10 +348,11 @@ export function createDirectoryService(
     loadSessionEvents,
 
     getOpenSpecData(cwd: string): OpenSpecData | undefined {
-      return openspecCache.get(cwd);
+      return caches.get(cwd)?.data;
     },
 
     refreshOpenSpec,
+    pollDirectoryGated,
 
     getPiResources(cwd: string): PiResourcesResult | undefined {
       return piResourcesCache.get(cwd);
@@ -139,18 +364,24 @@ export function createDirectoryService(
 
     startPolling(onChange: (cwd: string, data: OpenSpecData) => void) {
       onChangeCallback = onChange;
-      if (pollTimer) clearInterval(pollTimer);
-      pollTimer = setInterval(pollAllDirectories, POLL_INTERVAL);
+      installTimers();
     },
 
     stopPolling() {
-      if (pollTimer) {
-        clearInterval(pollTimer);
-        pollTimer = null;
-      }
+      stopTimers();
       onChangeCallback = null;
     },
 
+    reconfigurePolling(newCfg: OpenSpecPollConfig) {
+      const oldInterval = cfg.pollIntervalSeconds;
+      cfg = { ...newCfg };
+      semaphore.setMax(cfg.maxConcurrentSpawns);
+      // Only re-install timers if they were running and the interval actually changed.
+      if (pollTimer && oldInterval !== cfg.pollIntervalSeconds) {
+        installTimers();
+      }
+    },
+
     async onDirectoryAdded(cwd: string): Promise<DirectoryAddedResult> {
       const [sessions, openspecData] = await Promise.all([
         discoverSessions(cwd),

package/packages/server/src/editor-detection.ts

@@ -2,21 +2,24 @@
  * Auto-detection of code-server / openvscode-server binary.
  * Checks config override first, then PATH.
  */
-import { execSync } from "node:child_process";
 import type { EditorDetectionResult } from "@blackbelt-technology/pi-dashboard-shared/editor-types.js";
 import type { EditorConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
-import { buildSpawnEnv } from "./process-manager.js";
+import { ToolResolver } from "@blackbelt-technology/pi-dashboard-shared/platform/binary-lookup.js";
 
 export const BINARIES_TO_CHECK = ["code-server", "openvscode-server"] as const;
 
+/**
+ * Look up a binary using the unified ToolResolver, which handles the
+ * where/which split (Windows vs Unix), managed-bin paths, and login-shell
+ * fallback for GUI apps. Previously used raw `which` which silently failed
+ * on Windows. See change: fix-windows-server-parity.
+ */
 export function whichBinary(name: string): string | null {
-  try {
-    // Use buildSpawnEnv to include ~/.local/bin and other user dirs
-    // that Electron apps miss (no shell profile sourced)
-    return execSync(`which ${name}`, { stdio: "pipe", encoding: "utf-8", env: buildSpawnEnv() }).trim() || null;
-  } catch {
-    return null;
-  }
+  const resolver = new ToolResolver({
+    processExecPath: process.execPath,
+    useLoginShell: true,
+  });
+  return resolver.which(name);
 }
 
 let cachedResult: EditorDetectionResult | null = null;

package/packages/server/src/editor-manager.ts

@@ -2,7 +2,8 @@
  * Server-side lifecycle manager for code-server child processes.
  * Spawns per-folder instances, tracks heartbeats, enforces idle timeout and max instances.
  */
-import { spawn, type ChildProcess } from "node:child_process";
+import { spawn, type ChildProcess } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
+import { killPidWithGroup, killProcess } from "@blackbelt-technology/pi-dashboard-shared/platform/process.js";
 import { createServer as createNetServer, Socket as NetSocket } from "node:net";
 import { createHash, randomBytes } from "node:crypto";
 import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
@@ -12,6 +13,7 @@ import type { EditorInstanceStatus, EditorDetectionResult } from "@blackbelt-tec
 import type { EditorConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import { detectCodeServerBinary, resetDetectionCache } from "./editor-detection.js";
 import { buildSpawnEnv } from "./process-manager.js";
+import type { EditorPidRegistry } from "./editor-pid-registry.js";
 
 export interface EditorInstanceInfo {
   id: string;
@@ -37,6 +39,8 @@ export interface EditorManagerOptions {
   onStatusChange?: (cwd: string, id: string, status: EditorInstanceStatus) => void;
   /** Override re-detection (for testing). When false, skip runtime re-detection. */
   allowRedetection?: boolean;
+  /** Optional persistent PID registry for orphan cleanup across restarts. */
+  pidRegistry?: EditorPidRegistry;
 }
 
 export interface EditorManager {
@@ -141,7 +145,7 @@ function toInfo(inst: InternalInstance): EditorInstanceInfo {
 }
 
 export function createEditorManager(options: EditorManagerOptions): EditorManager {
-  const { config, detection, onStatusChange, allowRedetection = true } = options;
+  const { config, detection, onStatusChange, allowRedetection = true, pidRegistry } = options;
   const instances = new Map<string, InternalInstance>();
   const cwdIndex = new Map<string, string>(); // cwd → id
   const idleTimeoutMs = (config.idleTimeoutMinutes ?? 10) * 60 * 1000;
@@ -279,6 +283,7 @@ export function createEditorManager(options: EditorManagerOptions): EditorManage
     child.on("error", (err) => {
       console.error(`[editor-manager] code-server error for ${cwd}:`, err.message);
       setStatus(inst, "stopped");
+      pidRegistry?.remove(id);
       cleanup(id);
     });
 
@@ -287,6 +292,7 @@ export function createEditorManager(options: EditorManagerOptions): EditorManage
         console.log(`[editor-manager] code-server exited (code=${code}) for ${cwd}`);
         setStatus(inst, "stopped");
       }
+      pidRegistry?.remove(id);
       cleanup(id);
     });
 
@@ -298,6 +304,16 @@ export function createEditorManager(options: EditorManagerOptions): EditorManage
     }
 
     setStatus(inst, "ready");
+    if (pidRegistry && typeof child.pid === "number") {
+      pidRegistry.register({
+        id,
+        pid: child.pid,
+        port,
+        cwd,
+        dataDir,
+        spawnedAt: inst.lastHeartbeat,
+      });
+    }
     startIdleTimer(inst);
     return toInfo(inst);
   }
@@ -306,13 +322,31 @@ export function createEditorManager(options: EditorManagerOptions): EditorManage
     const inst = instances.get(id);
     if (!inst) return;
 
+    // Remove from persistent registry FIRST so a crash mid-stop
+    // leaves the registry consistent on the next boot.
+    pidRegistry?.remove(id);
+
     clearIdleTimer(inst);
     setStatus(inst, "stopped");
 
     if (inst.process && !inst.process.killed) {
-      try {
-        inst.process.kill("SIGTERM");
-      } catch {}
+      const pid = inst.process.pid;
+      if (pid != null) {
+        // Tree-kill the code-server subtree. On Windows this becomes
+        // `taskkill /F /T /PID` (async); on POSIX it's SIGTERM → 2s → SIGKILL
+        // of the process group. Fire-and-forget: `stop()` is synchronous
+        // by convention and callers don't await. See change:
+        // route-kill-paths-through-platform.
+        void killProcess(pid, { timeoutMs: 2000 }).catch(() => {
+          // Fallback to a direct pgroup SIGTERM if the platform helper
+          // couldn't complete (rare; mostly for already-dead processes).
+          try { killPidWithGroup(pid, "SIGTERM"); } catch { /* already dead */ }
+        });
+      } else {
+        // No PID yet (process hasn't started). Fall back to the raw
+        // ChildProcess.kill() which only signals the leaf.
+        try { inst.process.kill("SIGTERM"); } catch { /* already dead */ }
+      }
     }
 
     cleanup(id);