@blackbelt-technology/pi-agent-dashboard 0.5.0 → 0.5.2

package/packages/server/src/config-api.ts

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { loadConfig, type DashboardConfig, type AuthConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { refreshModelRegistry } from "./model-proxy/registry-singleton.js";
 
 const REDACTED = "***";
 
@@ -114,9 +115,17 @@ export function writeConfigPartial(partial: Record<string, any>): WriteConfigRes
       partial.auth = mergedAuth;
     }
 
-    // Merge tunnel sub-object
+    // Merge tunnel sub-object (deep-merge nested watchdog)
     if (partial.tunnel) {
-      partial.tunnel = { ...existing.tunnel, ...partial.tunnel };
+      const existingTunnel = existing.tunnel ?? {};
+      const mergedWatchdog = partial.tunnel.watchdog
+        ? { ...(existingTunnel.watchdog ?? {}), ...partial.tunnel.watchdog }
+        : existingTunnel.watchdog;
+      partial.tunnel = {
+        ...existingTunnel,
+        ...partial.tunnel,
+        ...(mergedWatchdog ? { watchdog: mergedWatchdog } : {}),
+      };
     }
 
     // Merge memoryLimits sub-object
@@ -139,6 +148,9 @@ export function writeConfigPartial(partial: Record<string, any>): WriteConfigRes
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(file, JSON.stringify(merged, null, 2) + "\n");
 
+    // Eager-refresh model proxy registry (config may affect proxy settings).
+    refreshModelRegistry().catch(() => {});
+
     return { success: true, restartRequired };
   } catch (err: any) {
     return { success: false, restartRequired: false, error: err.message };

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

@@ -76,6 +76,23 @@ export function hasOpenSpecDir(cwd: string): boolean {
   }
 }
 
+/**
+ * `true` iff `<cwd>/openspec/` exists and is a directory. Strictly weaker than
+ * `hasOpenSpecDir` (which also requires the `changes/` subdir). Used by the
+ * WS on-connect snapshot to emit the new `hasOpenspecDir` field on every
+ * payload so freshly-initialized projects without `changes/` yet still surface
+ * the OPENSPEC subcard as an init/attach affordance on the client.
+ *
+ * See change: auto-hide-empty-session-subcards.
+ */
+export function hasOpenSpecRoot(cwd: string): boolean {
+  try {
+    return fs.statSync(path.join(cwd, "openspec")).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 export interface DirectoryService {
   knownDirectories(): string[];
   discoverSessions(cwd: string): DiscoveredSession[];
@@ -199,12 +216,25 @@ function emptyDirCache(): DirCache {
   return { listMtimeMs: undefined, listResult: undefined, changes: new Map(), data: undefined };
 }
 
+export interface DirectoryServiceOptions {
+  /**
+   * Optional async post-processor applied to `OpenSpecData` after
+   * `buildOpenSpecData` and before caching. Used to inject the per-cwd
+   * `groupId` join from the OpenSpec change-grouping store.
+   * Errors propagate as a logged warning + the unenriched data.
+   * See change: add-openspec-change-grouping.
+   */
+  enrichOpenSpecData?: (cwd: string, data: OpenSpecData) => Promise<OpenSpecData> | OpenSpecData;
+}
+
 export function createDirectoryService(
   preferencesStore: PreferencesStore,
   sessionManager: SessionManager,
   initialConfig?: Partial<OpenSpecPollConfig>,
+  options: DirectoryServiceOptions = {},
 ): DirectoryService {
   let cfg: OpenSpecPollConfig = { ...DEFAULT_OPENSPEC_POLL, ...(initialConfig ?? {}) };
+  const enrichOpenSpecData = options.enrichOpenSpecData;
 
   const caches = new Map<string, DirCache>();
   const piResourcesCache = new Map<string, PiResourcesResult>();
@@ -261,12 +291,22 @@ export function createDirectoryService(
     const cache = caches.get(cwd) ?? emptyDirCache();
     const gateEnabled = cfg.changeDetection === "mtime" && !force;
 
+    const openspecRoot = path.join(cwd, "openspec");
     const changesRoot = path.join(cwd, "openspec", "changes");
+    // `hasOpenspecDir` is strictly weaker than `initialized`: it's true when
+    // the project is OpenSpec-initialized (`openspec/` dir exists) even if no
+    // proposals are authored yet (no `openspec/changes/` subdir). The session
+    // card visibility gate uses this signal so a fresh `openspec init` project
+    // still shows the OPENSPEC subcard as an init/attach affordance.
+    // See change: auto-hide-empty-session-subcards.
+    const hasOpenspecDir = statMtimeOr(openspecRoot) !== undefined;
     const rootMtime = statMtimeOr(changesRoot);
 
-    // If the directory doesn't exist, short-circuit (matches old behavior).
+    // If the changes/ subdirectory doesn't exist, short-circuit (matches old
+    // behavior re: list polling). `hasOpenspecDir` still carries the broader
+    // "is this an OpenSpec project?" signal for the client.
     if (rootMtime === undefined) {
-      const empty: OpenSpecData = { initialized: false, changes: [] };
+      const empty: OpenSpecData = { initialized: false, changes: [], hasOpenspecDir };
       cache.data = empty;
       cache.listMtimeMs = undefined;
       cache.listResult = undefined;
@@ -294,7 +334,7 @@ export function createDirectoryService(
     if (!listCacheValid) {
       const raw = await semaphore.run(() => runOpenSpecList(cwd));
       if (!raw || !Array.isArray(raw.changes)) {
-        const empty: OpenSpecData = { initialized: false, changes: [] };
+        const empty: OpenSpecData = { initialized: false, changes: [], hasOpenspecDir };
         cache.data = empty;
         cache.listMtimeMs = rootMtime;
         cache.listResult = undefined;
@@ -377,12 +417,30 @@ export function createDirectoryService(
     }));
 
     // ── Step 3: build + cache + return ──
-    const data = buildOpenSpecData(
+    let data = buildOpenSpecData(
       { changes: listResult ?? [] },
       statusResults,
       createFsProbeFactory(cwd),
       createFsSpecsProbeFactory(cwd),
     );
+    // `hasOpenspecDir` is true here by definition: we only reach Step 3 when
+    // `<cwd>/openspec/changes/` exists, which implies `<cwd>/openspec/` exists.
+    // See change: auto-hide-empty-session-subcards.
+    data = { ...data, hasOpenspecDir };
+    if (enrichOpenSpecData) {
+      try {
+        data = await enrichOpenSpecData(cwd, data);
+      } catch (err) {
+        // Don\'t fail the whole poll if the enricher (e.g. group-store read)
+        // throws — log and continue with the unenriched data. See change:
+        // add-openspec-change-grouping.
+        // eslint-disable-next-line no-console
+        if (typeof process !== "undefined" && /pi-dashboard|openspec-poll/.test(process.env?.DEBUG ?? "")) {
+          // eslint-disable-next-line no-console
+          console.warn(`[directory-service] enrichOpenSpecData(${cwd}) threw:`, err);
+        }
+      }
+    }
 
     // Stamp the cache with the pre-call mtime — i.e. the mtime that
     // demonstrably reflects the file state observed by the CLI. Skip racy
@@ -401,6 +459,20 @@ export function createDirectoryService(
   }
 
   async function refreshOpenSpec(cwd: string): Promise<OpenSpecData> {
+    // Master gate: when `openspec.enabled` is false, every refresh path is a
+    // no-op. Return the cleared-state shape so callers (including
+    // `openspec_refresh` browser handler) converge to the disabled UX.
+    // See change: auto-hide-empty-session-subcards.
+    if (cfg.enabled === false) {
+      // Disabled state: `hasOpenspecDir: false` ensures the client wrapper
+      // hides the OPENSPEC subcard for every cwd. See change:
+      // auto-hide-empty-session-subcards.
+      const cleared: OpenSpecData = { initialized: false, pending: false, changes: [], hasOpenspecDir: false };
+      const cache = caches.get(cwd) ?? emptyDirCache();
+      cache.data = cleared;
+      caches.set(cwd, cache);
+      return cleared;
+    }
     try {
       // User-initiated refresh bypasses the gate. The gate is heuristic; the
       // CLI is authoritative. When the user clicks the OpenSpec refresh icon
@@ -422,6 +494,15 @@ export function createDirectoryService(
   }
 
   async function pollDirectoryGated(cwd: string): Promise<OpenSpecData> {
+    // Master gate: when `openspec.enabled` is false, never spawn a CLI for the
+    // periodic poll path either. See change: auto-hide-empty-session-subcards.
+    if (cfg.enabled === false) {
+      const cleared: OpenSpecData = { initialized: false, pending: false, changes: [], hasOpenspecDir: false };
+      const cache = caches.get(cwd) ?? emptyDirCache();
+      cache.data = cleared;
+      caches.set(cwd, cache);
+      return cleared;
+    }
     return pollOne(cwd, false);
   }
 
@@ -439,6 +520,9 @@ export function createDirectoryService(
   let openspecTickInFlight = false;
   async function scheduleOpenSpecTick() {
     if (openspecTickInFlight) return;
+    // Master gate: when `openspec.enabled` is false, the tick is a no-op.
+    // No CLI spawns. See change: auto-hide-empty-session-subcards.
+    if (cfg.enabled === false) return;
     openspecTickInFlight = true;
     const tickStart = Date.now();
     let spawnsBefore = 0;
@@ -542,12 +626,30 @@ export function createDirectoryService(
 
     reconfigurePolling(newCfg: OpenSpecPollConfig) {
       const oldInterval = cfg.pollIntervalSeconds;
+      const wasEnabled = cfg.enabled;
       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();
       }
+      // On the `true → false` transition, clear every per-cwd `OpenSpecData`
+      // cache and notify the broadcast channel so connected browsers converge
+      // to the disabled-state shape. The `false → true` transition is a
+      // no-op here — the next regular poll tick will re-populate caches.
+      // See change: auto-hide-empty-session-subcards.
+      if (wasEnabled !== false && cfg.enabled === false) {
+        const cleared: OpenSpecData = { initialized: false, pending: false, changes: [], hasOpenspecDir: false };
+        for (const [cwd, cache] of caches.entries()) {
+          cache.data = cleared;
+          caches.set(cwd, cache);
+          try {
+            onChangeCallback?.(cwd, cleared);
+          } catch (err) {
+            console.warn(`[openspec-poll] onChange after disable failed for ${cwd}:`, err);
+          }
+        }
+      }
     },
 
     async onDirectoryAdded(cwd: string): Promise<DirectoryAddedResult> {

package/packages/server/src/event-wiring.ts

@@ -19,6 +19,8 @@ import type { DashboardSession } from "@blackbelt-technology/pi-dashboard-shared
 import { detectOpenSpecActivity, isValidOpenSpecChangeSlug } from "@blackbelt-technology/pi-dashboard-shared/openspec-activity-detector.js";
 import { extractTurnStats } from "@blackbelt-technology/pi-dashboard-shared/stats-extractor.js";
 import { attachRenameTarget, isNameAutoSetFromAttachment } from "./proposal-attach-naming.js";
+import { handleDispatchExtensionCommand } from "./rpc-keeper/dispatch-router.js";
+import { keeperOptsFromSpawnResult } from "./headless-pid-registry.js";
 
 export interface EventWiringDeps {
   sessionManager: SessionManager;
@@ -43,6 +45,14 @@ export interface EventWiringDeps {
    * See change: session-card-unread-stripes.
    */
   viewedSessionTracker?: ViewedSessionTracker;
+  /**
+   * Optional client-correlation registry. When provided, the wiring
+   * consumes the requestId for the resolved spawnToken after a successful
+   * three-tier link and surfaces it on `session_added` as `spawnRequestId`,
+   * letting the client auto-select / dismiss its placeholder by exact
+   * correlation. See change: spawn-correlation-token.
+   */
+  pendingClientCorrelations?: import("./pending-client-correlations.js").PendingClientCorrelations;
 }
 
 /**
@@ -62,6 +72,7 @@ export function wireEvents(deps: EventWiringDeps): void {
     pendingDashboardSpawns,
     pendingAttachRegistry,
     viewedSessionTracker,
+    pendingClientCorrelations,
   } = deps;
 
   // Broadcast placeholder session to browsers when auto-created from early events
@@ -452,7 +463,34 @@ export function wireEvents(deps: EventWiringDeps): void {
         }
       }
 
-      browserGateway.headlessPidRegistry.linkSession(sessionId, msg.cwd);
+      // Three-tier link: token → pid → cwd-FIFO. Each tier is independently
+      // correct; `linkByToken` is the strong identity introduced by
+      // `spawn-correlation-token`. cwd-FIFO is the legacy fallback for old
+      // bridges that send neither token nor pid (and is logged so we can see
+      // when it actually triggers).
+      let linked = false;
+      if (msg.spawnToken) {
+        linked = browserGateway.headlessPidRegistry.linkByToken(msg.spawnToken, sessionId, msg.pid);
+      }
+      if (!linked && msg.pid !== undefined) {
+        linked = browserGateway.headlessPidRegistry.linkByPid(sessionId, msg.pid);
+      }
+      if (!linked) {
+        if (msg.spawnToken || msg.pid !== undefined) {
+          console.error(
+            `[event-wiring] cwd-FIFO fallback for session ${sessionId} — token=${msg.spawnToken ?? ""} pid=${msg.pid ?? ""} cwd=${msg.cwd}`,
+          );
+        }
+        browserGateway.headlessPidRegistry.linkSession(sessionId, msg.cwd);
+      }
+
+      // Resolve the originating browser `requestId` (when known) so the
+      // upcoming session_added broadcast can carry spawnRequestId and the
+      // client can auto-select / dismiss its placeholder.
+      // See change: spawn-correlation-token.
+      const spawnRequestId = (msg.spawnToken && pendingClientCorrelations)
+        ? pendingClientCorrelations.consume(msg.spawnToken)
+        : undefined;
 
       const isNewSession = !knownSessionIds.has(sessionId);
       knownSessionIds.add(sessionId);
@@ -469,7 +507,11 @@ export function wireEvents(deps: EventWiringDeps): void {
         }
       }
 
-      const forkParent = pendingForkRegistry.consumeFork(msg.cwd);
+      // Fork-parent lookup is keyed by spawn token (was: cwd, racy on
+      // multi-fork-in-same-cwd). See change: spawn-correlation-token.
+      const forkParent = msg.spawnToken
+        ? pendingForkRegistry.consumeFork(msg.spawnToken)
+        : undefined;
       sessionOrderManager.insert(msg.cwd, sessionId);
 
       if (forkParent) {
@@ -489,7 +531,7 @@ export function wireEvents(deps: EventWiringDeps): void {
 
       const updatedSession = sessionManager.get(sessionId);
       if (updatedSession) {
-        browserGateway.broadcastSessionAdded(updatedSession);
+        browserGateway.broadcastSessionAdded(updatedSession, spawnRequestId ? { spawnRequestId } : undefined);
       }
 
       const isNewCwd = !sessionManager.listAll().some(
@@ -623,9 +665,23 @@ export function wireEvents(deps: EventWiringDeps): void {
     if (msg.type === "providers_list") {
       // Cache the bridge-pushed catalogue. Browsers don't subscribe to it
       // directly; they read via GET /api/provider-auth/status.
-      // See change: replace-hardcoded-provider-lists.
+      // Broadcast `models_refreshed` ONLY when the catalogue contents
+      // actually changed. Routine state-syncs (every fork/resume/reconnect/
+      // subscribe) re-send identical content; broadcasting unconditionally
+      // wipes every browser's modelsMap and — because App.tsx's
+      // auto-subscribe effect skips re-requesting models for any session
+      // that's already in `subscribedRef`, leaves previously-visited
+      // sessions with an empty model selector until reconnect.
+      //
+      // The catalogue cache is now a pure read consumer for the Settings
+      // UI (`GET /api/provider-auth/status`). No broadcast: the model-
+      // selector dropdown lives on the independent `models_list` channel
+      // which is per-session-broadcast already; per-session updates are
+      // self-healing without a global wipe.
+      // See changes: replace-hardcoded-provider-lists,
+      //              fix-providers-list-spurious-models-refreshed,
+      //              simplify-model-selection-channels.
       setCatalogueForSession(sessionId, msg.providers);
-      browserGateway.broadcastToAll({ type: "models_refreshed" } as any);
     }
 
     if (msg.type === "roles_list") {
@@ -757,7 +813,13 @@ export function wireEvents(deps: EventWiringDeps): void {
     if (msg.type === "spawn_new_session") {
       spawnPiSession(msg.cwd, { strategy: loadConfig().spawnStrategy }).then((result) => {
         if (result.process && result.pid) {
-          browserGateway.headlessPidRegistry.register(result.pid, msg.cwd, result.process);
+          browserGateway.headlessPidRegistry.register(
+            result.pid,
+            msg.cwd,
+            result.process,
+            result.spawnToken,
+            keeperOptsFromSpawnResult(result),
+          );
         }
         browserGateway.broadcastToAll({
           type: "spawn_result",
@@ -808,5 +870,27 @@ export function wireEvents(deps: EventWiringDeps): void {
       });
     }
 
+    // RPC keeper dispatch: bridge → server slash command forward.
+    // Fire-and-forget; the handler itself emits browser-bound
+    // `command_feedback` events on success and on every failure path.
+    // The terminal event is persisted via eventStore.insertEvent so it
+    // survives browser reattach (otherwise the chat pill stays "in progress").
+    // See change: add-rpc-stdin-dispatch-with-keeper-sidecar (Phase 8).
+    if (msg.type === "dispatch_extension_command") {
+      void handleDispatchExtensionCommand(msg, {
+        headlessPidRegistry: browserGateway.headlessPidRegistry,
+        emitCommandFeedback: (sid, command, status, message) => {
+          const event = {
+            eventType: "command_feedback",
+            timestamp: Date.now(),
+            data: message === undefined ? { command, status } : { command, status, message },
+          };
+          const seq = eventStore.insertEvent(sid, event);
+          const stored = eventStore.getEvent(sid, seq) ?? event;
+          browserGateway.broadcastEvent(sid, seq, stored);
+        },
+      });
+    }
+
   };
 }