@blackbelt-technology/pi-agent-dashboard 0.4.1 → 0.4.3

package/packages/shared/src/openspec-poller.ts

@@ -23,12 +23,47 @@
 import { listOr, statusOr, OPENSPEC_LIST, OPENSPEC_STATUS } from "./platform/openspec.js";
 import { runAsync, unwrap } from "./platform/runner.js";
 import type { OpenSpecData, OpenSpecChange, OpenSpecArtifact } from "./types.js";
+import {
+  evaluateLocalDesignSatisfaction,
+  createFsDesignEvidenceProbe,
+  type DesignEvidenceProbe,
+} from "./openspec-design-evidence.js";
+import {
+  evaluateLocalSpecsSatisfaction,
+  createFsSpecsEvidenceProbe,
+  type SpecsEvidenceProbe,
+} from "./openspec-specs-evidence.js";
+import path from "node:path";
 
 const EMPTY_DATA: OpenSpecData = { initialized: false, changes: [] };
 
+/**
+ * Factory that returns a probe for a given change name. Production callers
+ * pass a closure rooted at `<cwd>/openspec/changes/<name>`. Tests pass an
+ * in-memory factory. When omitted, the design override does NOT fire and
+ * `buildOpenSpecData` matches today's behavior verbatim.
+ *
+ * See change: fix-openspec-design-detection.
+ */
+export type DesignProbeFactory = (changeName: string) => DesignEvidenceProbe;
+
+/**
+ * Factory that returns a specs-evidence probe for a given change name.
+ * Parallel to `DesignProbeFactory` — production callers pass a closure
+ * rooted at `<cwd>/openspec/changes/<name>`; tests pass an in-memory
+ * factory. When omitted, the specs override does NOT fire and
+ * `buildOpenSpecData` matches today's behavior verbatim for the specs
+ * artifact.
+ *
+ * See change: fix-openspec-specs-mtime-gate-blind-spot.
+ */
+export type SpecsProbeFactory = (changeName: string) => SpecsEvidenceProbe;
+
 export function buildOpenSpecData(
   listResult: { changes?: Array<{ name: string; status: string; completedTasks: number; totalTasks: number }> } | null,
   statusResults: Map<string, { artifacts?: Array<{ id: string; status: string }>; isComplete?: boolean } | null>,
+  probeFactory?: DesignProbeFactory,
+  specsProbeFactory?: SpecsProbeFactory,
 ): OpenSpecData {
   if (!listResult || !Array.isArray(listResult.changes)) {
     return EMPTY_DATA;
@@ -41,9 +76,40 @@ export function buildOpenSpecData(
       status: (a.status === "done" ? "done" : a.status === "ready" ? "ready" : "blocked") as OpenSpecArtifact["status"],
     }));
 
-    const isComplete =
+    // Design-artifact override: promote-only, design-only. See change:
+    // fix-openspec-design-detection.
+    if (probeFactory) {
+      const designIdx = artifacts.findIndex((a) => a.id === "design");
+      if (designIdx !== -1 && artifacts[designIdx].status === "ready") {
+        const probe = probeFactory(c.name);
+        if (evaluateLocalDesignSatisfaction("", probe)) {
+          artifacts[designIdx] = { ...artifacts[designIdx], status: "done" };
+        }
+      }
+    }
+
+    // Specs-artifact override: promote-only, specs-only. See change:
+    // fix-openspec-specs-mtime-gate-blind-spot.
+    if (specsProbeFactory) {
+      const specsIdx = artifacts.findIndex((a) => a.id === "specs");
+      if (specsIdx !== -1 && artifacts[specsIdx].status === "ready") {
+        const probe = specsProbeFactory(c.name);
+        if (evaluateLocalSpecsSatisfaction("", probe)) {
+          artifacts[specsIdx] = { ...artifacts[specsIdx], status: "done" };
+        }
+      }
+    }
+
+    const cliIsComplete =
       typeof statusResult?.isComplete === "boolean" ? statusResult.isComplete : undefined;
 
+    // Re-derive isComplete from post-override artifacts. Promote false→true
+    // only when every artifact is done; never demote CLI true.
+    let isComplete = cliIsComplete;
+    if (artifacts.length > 0 && artifacts.every((a) => a.status === "done")) {
+      isComplete = true;
+    }
+
     const change: OpenSpecChange = {
       name: c.name,
       status: (c.status === "complete" ? "complete" : c.status === "in-progress" ? "in-progress" : "no-tasks") as OpenSpecChange["status"],
@@ -58,6 +124,44 @@ export function buildOpenSpecData(
   return { initialized: true, changes };
 }
 
+/**
+ * Build a real-fs probe factory rooted at `<cwd>/openspec/changes/<name>`.
+ * Production callers (`pollOpenSpec`, `pollOpenSpecAsync`,
+ * `directory-service.ts`) use this to wire the override. Tests inject
+ * their own factory.
+ */
+export function createFsProbeFactory(cwd: string): DesignProbeFactory {
+  const probe = createFsDesignEvidenceProbe();
+  const changesRoot = path.join(cwd, "openspec", "changes");
+  return (changeName) => {
+    const changeDir = path.join(changesRoot, changeName);
+    return {
+      hasDesignFile: () => probe.hasDesignFile(changeDir),
+      hasDesignDirWithMd: () => probe.hasDesignDirWithMd(changeDir),
+      tasksHasCheckboxes: () => probe.tasksHasCheckboxes(changeDir),
+    };
+  };
+}
+
+/**
+ * Build a real-fs specs-probe factory rooted at `<cwd>/openspec/changes/<name>`.
+ * Parallel to `createFsProbeFactory` — production callers (`pollOpenSpec`,
+ * `pollOpenSpecAsync`, `directory-service.ts`) use this to wire the specs
+ * override. Tests inject their own factory.
+ *
+ * See change: fix-openspec-specs-mtime-gate-blind-spot.
+ */
+export function createFsSpecsProbeFactory(cwd: string): SpecsProbeFactory {
+  const probe = createFsSpecsEvidenceProbe();
+  const changesRoot = path.join(cwd, "openspec", "changes");
+  return (changeName) => {
+    const changeDir = path.join(changesRoot, changeName);
+    return {
+      hasAnySpecFile: () => probe.hasAnySpecFile(changeDir),
+    };
+  };
+}
+
 /**
  * Synchronous poll — blocks the event loop. Used by the bridge extension
  * where async isn't practical (some pi extension hooks are sync).
@@ -70,7 +174,12 @@ export function pollOpenSpec(cwd: string): OpenSpecData {
   for (const c of listResult.changes) {
     statusResults.set(c.name, statusOr({ cwd, change: c.name }));
   }
-  return buildOpenSpecData(listResult, statusResults);
+  return buildOpenSpecData(
+    listResult,
+    statusResults,
+    createFsProbeFactory(cwd),
+    createFsSpecsProbeFactory(cwd),
+  );
 }
 
 /**
@@ -114,5 +223,10 @@ export async function pollOpenSpecAsync(cwd: string): Promise<OpenSpecData> {
     }),
   );
   const statusResults = new Map<string, any>(statusEntries);
-  return buildOpenSpecData(listResult, statusResults);
+  return buildOpenSpecData(
+    listResult,
+    statusResults,
+    createFsProbeFactory(cwd),
+    createFsSpecsProbeFactory(cwd),
+  );
 }

package/packages/shared/src/openspec-specs-evidence.ts

@@ -0,0 +1,79 @@
+/**
+ * Local-evidence override for the OpenSpec `specs` artifact.
+ *
+ * The `spec-driven` schema declares `specs/**\/*.md` as the `generates`
+ * pattern for the `specs` artifact, and the openspec CLI marks the
+ * artifact `done` whenever that glob matches anything. The dashboard's
+ * mtime-gated cache, however, can momentarily stale on `specs: ready`
+ * for multi-spec changes (see change:
+ * fix-openspec-specs-mtime-gate-blind-spot — the watch set is now
+ * extended to cover `specs/**`, but this override is the second line
+ * of defence).
+ *
+ * This module computes a boolean "is specs satisfied locally?" from
+ * file-system evidence the dashboard's cache might miss between polls.
+ * It is consumed by:
+ *
+ *   1. `buildOpenSpecData` in `openspec-poller.ts` — promotes
+ *      `artifacts[specs].status` from "ready" to "done" when at least
+ *      one `specs/**\/*.md` file exists. Promote-only; specs-only;
+ *      never demotes; never touches other artifacts.
+ *
+ * One rule:
+ *
+ *   any file matching `specs/**\/*.md` exists in the change folder
+ *
+ * The probe walks the `specs/` subtree once and short-circuits on the
+ * first `*.md` it finds. Defensive: every fs call is wrapped in
+ * try/catch and treated as "no match" on error.
+ *
+ * See change: fix-openspec-specs-mtime-gate-blind-spot.
+ */
+
+import { readdirSync } from "node:fs";
+import path from "node:path";
+
+/** Probe surface — kept tiny so unit tests can pass an in-memory stub. */
+export interface SpecsEvidenceProbe {
+  /** Returns true iff at least one `*.md` file exists under `<changeDir>/specs/`. */
+  hasAnySpecFile(changeDir: string): boolean;
+}
+
+/** Pure rule evaluator. Single rule; short-circuits on first match. */
+export function evaluateLocalSpecsSatisfaction(
+  changeDir: string,
+  probe: SpecsEvidenceProbe,
+): boolean {
+  return probe.hasAnySpecFile(changeDir);
+}
+
+/**
+ * Production probe — backed by the real filesystem. Walks `<changeDir>/specs/`
+ * iteratively, short-circuits on the first `*.md` file encountered. Every
+ * `readdirSync` is wrapped in try/catch (handles ENOENT, permission errors,
+ * symlink loops, and any unexpected fs error) and treated as "no match".
+ */
+export function createFsSpecsEvidenceProbe(): SpecsEvidenceProbe {
+  return {
+    hasAnySpecFile(changeDir: string): boolean {
+      const root = path.join(changeDir, "specs");
+      // Iterative DFS — no recursion to avoid stack overflow on pathological trees.
+      const stack: string[] = [root];
+      while (stack.length > 0) {
+        const dir = stack.pop()!;
+        let entries: import("node:fs").Dirent[];
+        try {
+          entries = readdirSync(dir, { withFileTypes: true });
+        } catch {
+          // Missing dir, permission denied, or any other fs error — skip.
+          continue;
+        }
+        for (const e of entries) {
+          if (e.isFile() && e.name.endsWith(".md")) return true;
+          if (e.isDirectory()) stack.push(path.join(dir, e.name));
+        }
+      }
+      return false;
+    },
+  };
+}

package/packages/shared/src/platform/binary-lookup.ts

@@ -4,11 +4,106 @@
  * with a single configurable resolver.
  */
 import { execSync, spawnSync, buildSafeArgv } from "./exec.js";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { MANAGED_BIN, MANAGED_DIR } from "../managed-paths.js";
 
+// ── AppImage self-hit guard (Linux power-user mode safety) ────────────────
+
+/**
+ * Optional environment overrides for {@link isAppImageSelfHit}. Tests
+ * inject explicit values so the helper can exercise both branches
+ * without mutating `process.env` or `process.execPath`. Production
+ * callers omit `opts` and the helper reads from the live process.
+ *
+ * See change: fix-electron-appimage-cli-self-detection (D1).
+ */
+export interface AppImageSelfHitOpts {
+  /** Override `process.execPath`. Default: `process.execPath`. */
+  execPath?: string;
+  /** Override `process.env.APPDIR`. Default: `process.env.APPDIR`. */
+  appDir?: string | undefined;
+  /** Override `process.env.APPIMAGE`. Default: `process.env.APPIMAGE`. */
+  appImage?: string | undefined;
+}
+
+/** Defensive realpath — returns the input on any error (broken symlink / ENOENT). */
+function safeRealpath(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Returns `true` when `candidatePath` is the running process's own
+ * Electron launcher binary — the bug class that motivates this helper:
+ * AppImage's runtime prepends its squashfs mount (`/tmp/.mount_*`) to
+ * `PATH` of the Electron child, and `packagerConfig.executableName =
+ * "pi-dashboard"` makes the launcher a name-collision with the dashboard
+ * CLI. Trusting the first `which pi-dashboard` hit therefore spawns the
+ * Electron app recursively as if it were the CLI.
+ *
+ * A path is considered a self-hit when ANY of the following is true:
+ *   - `realpath(candidatePath) === realpath(execPath)`, OR
+ *   - `candidatePath` lives under the directory named by `appDir`, OR
+ *   - `realpath(candidatePath) === realpath(appImage)`.
+ *
+ * `realpath` calls are wrapped in try/catch so broken symlinks / ENOENT
+ * fall back to literal string comparisons. The helper never throws.
+ *
+ * Production callers (`whereStrategy`, `detectPiDashboardCli`,
+ * `detectPi`, `detectSystemNode`) omit `opts`. Tests pass explicit
+ * overrides via `opts`.
+ *
+ * See change: fix-electron-appimage-cli-self-detection (D1).
+ */
+export function isAppImageSelfHit(
+  candidatePath: string,
+  opts?: AppImageSelfHitOpts,
+): boolean {
+  if (!candidatePath) return false;
+
+  const execPath = opts && "execPath" in opts ? opts.execPath : process.execPath;
+  const appDir = opts && "appDir" in opts ? opts.appDir : process.env.APPDIR;
+  const appImage = opts && "appImage" in opts ? opts.appImage : process.env.APPIMAGE;
+
+  const realCandidate = safeRealpath(candidatePath);
+
+  // Rule 1: realpath equals process.execPath
+  if (execPath) {
+    const realExec = safeRealpath(execPath);
+    if (realCandidate === realExec) return true;
+    if (candidatePath === execPath) return true;
+  }
+
+  // Rule 2: candidate lives under APPDIR (the AppImage squashfs mount).
+  // We compare the candidate's realpath against APPDIR's realpath so a
+  // symlink under the mount is still recognized as a self-hit.
+  if (appDir) {
+    const realAppDir = safeRealpath(appDir);
+    const sep = path.sep;
+    // Append separator so /tmp/.mount_PI doesn't accidentally match
+    // /tmp/.mount_PIxx-elsewhere via prefix.
+    const prefix = realAppDir.endsWith(sep) ? realAppDir : realAppDir + sep;
+    if (realCandidate === realAppDir || realCandidate.startsWith(prefix)) return true;
+    // Literal fallback (broken symlinks / ENOENT keep a useful answer).
+    const litPrefix = appDir.endsWith(sep) ? appDir : appDir + sep;
+    if (candidatePath === appDir || candidatePath.startsWith(litPrefix)) return true;
+  }
+
+  // Rule 3: realpath equals APPIMAGE (the .AppImage file the user clicked).
+  if (appImage) {
+    const realAppImage = safeRealpath(appImage);
+    if (realCandidate === realAppImage) return true;
+    if (candidatePath === appImage) return true;
+  }
+
+  return false;
+}
+
 /**
  * Well-known globalThis symbol for the default `ToolRegistry`.
  *

package/packages/shared/src/plugin-bridge-register.ts

@@ -0,0 +1,139 @@
+/**
+ * Plugin bridge entry management in pi's settings.json.
+ *
+ * Manages `dashboard-<plugin-id>` keys in a dedicated
+ * `dashboardPluginBridges` object inside settings.json.
+ *
+ * Rules:
+ * - Only touches entries under the `dashboardPluginBridges` key.
+ * - NEVER modifies user-owned `packages[]` entries.
+ * - Uses atomic write (tmp + rename) for all updates.
+ * - Detects path conflicts (existing entry with mismatched path).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+export interface PluginBridgeRegisterOptions {
+  homedir?: string;
+}
+
+export type PluginBridgeConflict =
+  | { type: "ok" }
+  | { type: "conflict"; existingPath: string; newPath: string };
+
+function getSettingsPath(homedir?: string): string {
+  const home = homedir ?? process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
+  return path.join(home, ".pi", "agent", "settings.json");
+}
+
+function readSettings(settingsPath: string): Record<string, unknown> {
+  try {
+    if (!fs.existsSync(settingsPath)) return {};
+    const raw = fs.readFileSync(settingsPath, "utf-8").trim();
+    if (!raw) return {};
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function writeSettings(settingsPath: string, settings: Record<string, unknown>): void {
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  const tmp = settingsPath + ".tmp." + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
+  fs.renameSync(tmp, settingsPath);
+}
+
+function getManagedBridges(
+  settings: Record<string, unknown>,
+): Record<string, string> {
+  const val = settings.dashboardPluginBridges;
+  if (val && typeof val === "object" && !Array.isArray(val)) {
+    return val as Record<string, string>;
+  }
+  return {};
+}
+
+const MANAGED_PREFIX = "dashboard-";
+
+/**
+ * Register a plugin's bridge entry in pi's settings.json.
+ *
+ * Returns { type: "conflict", existingPath, newPath } if a
+ * `dashboard-<pluginId>` key already exists but points to a different path.
+ * In that case the settings.json is NOT modified.
+ *
+ * Returns { type: "ok" } on success (including when the entry already matches).
+ */
+export function registerPluginBridge(
+  pluginId: string,
+  bridgePath: string,
+  opts: PluginBridgeRegisterOptions = {},
+): PluginBridgeConflict {
+  const settingsPath = getSettingsPath(opts.homedir);
+  const settings = readSettings(settingsPath);
+  const managed = getManagedBridges(settings);
+  const key = MANAGED_PREFIX + pluginId;
+
+  const existing = managed[key];
+  if (existing) {
+    if (existing === bridgePath) return { type: "ok" }; // already registered
+    return { type: "conflict", existingPath: existing, newPath: bridgePath };
+  }
+
+  managed[key] = bridgePath;
+  settings.dashboardPluginBridges = managed;
+  writeSettings(settingsPath, settings);
+  console.info(`[plugin-bridge] Registered bridge for plugin "${pluginId}": ${bridgePath}`);
+  return { type: "ok" };
+}
+
+/**
+ * Remove a plugin's bridge entry from pi's settings.json.
+ * No-op if the entry does not exist.
+ * NEVER touches entries without the `dashboard-` prefix.
+ */
+export function deregisterPluginBridge(
+  pluginId: string,
+  opts: PluginBridgeRegisterOptions = {},
+): void {
+  const settingsPath = getSettingsPath(opts.homedir);
+  const settings = readSettings(settingsPath);
+  const managed = getManagedBridges(settings);
+  const key = MANAGED_PREFIX + pluginId;
+
+  if (!(key in managed)) return; // nothing to remove
+
+  delete managed[key];
+  settings.dashboardPluginBridges = managed;
+  writeSettings(settingsPath, settings);
+  console.info(`[plugin-bridge] Deregistered bridge for plugin "${pluginId}"`);
+}
+
+/**
+ * Register all plugins with bridge entries from the discovery list.
+ * Returns a map of pluginId → conflict/ok result.
+ * Plugins with conflicts are NOT registered; caller should surface via /api/health.
+ */
+export function registerAllPluginBridges(
+  plugins: Array<{ pluginId: string; bridgePath: string }>,
+  opts: PluginBridgeRegisterOptions = {},
+): Record<string, PluginBridgeConflict> {
+  const results: Record<string, PluginBridgeConflict> = {};
+  for (const { pluginId, bridgePath } of plugins) {
+    results[pluginId] = registerPluginBridge(pluginId, bridgePath, opts);
+  }
+  return results;
+}
+
+/**
+ * List all currently managed plugin bridge entries.
+ */
+export function listManagedBridges(
+  opts: PluginBridgeRegisterOptions = {},
+): Record<string, string> {
+  const settingsPath = getSettingsPath(opts.homedir);
+  const settings = readSettings(settingsPath);
+  return getManagedBridges(settings);
+}

package/packages/shared/src/protocol.ts

@@ -1,7 +1,7 @@
 /**
  * Extension ↔ Server WebSocket protocol messages.
  */
-import type { DashboardEvent, CommandInfo, FlowInfo, SessionSource, ImageContent, FileEntry, TurnUsage, ContextUsage, ModelInfo, PiSessionInfo, OpenSpecPhase, RoleInfo } from "./types.js";
+import type { DashboardEvent, CommandInfo, FlowInfo, SessionSource, ImageContent, FileEntry, TurnUsage, ContextUsage, ModelInfo, PiSessionInfo, OpenSpecPhase, RoleInfo, ExtensionUiModule, DecoratorDescriptor } from "./types.js";
 
 // ── Extension → Server ──────────────────────────────────────────────
 
@@ -228,6 +228,39 @@ export interface ProcessListMessage {
 
 // LoadSessionEventsResultMessage and LoadSessionEventsErrorMessage removed — server loads directly
 
+// ── Extension UI System (Phase 1) ──
+// Pull-discovered, schema-driven UI modules. See change: add-extension-ui-modal.
+
+export interface UiModulesListMessage {
+  type: "ui_modules_list";
+  sessionId: string;
+  modules: ExtensionUiModule[];
+}
+
+export interface UiDataListMessage {
+  type: "ui_data_list";
+  sessionId: string;
+  /** Matches some `module.view.dataEvent`. */
+  event: string;
+  items: unknown[];
+}
+
+// ── Extension UI System (Phase 2: live in-page decorations) ──
+// See change: add-extension-ui-decorations.
+
+/**
+ * Extension → server: a single live decorator descriptor. Cache key
+ * `${kind}:${namespace}:${id}` MUST be unique within a session; `removed: true`
+ * deletes the cache entry instead of upserting.
+ */
+export interface ExtUiDecoratorMessage {
+  type: "ext_ui_decorator";
+  sessionId: string;
+  descriptor: DecoratorDescriptor;
+  /** When true, server deletes the cached descriptor under the matching key. */
+  removed?: boolean;
+}
+
 export type ExtensionToServerMessage =
   | SessionRegisterMessage
   | SessionUnregisterMessage
@@ -250,7 +283,10 @@ export type ExtensionToServerMessage =
   | FirstMessageUpdateMessage
   | RolesListMessage
   | SpawnNewSessionMessage
-  | ProcessListMessage;
+  | ProcessListMessage
+  | UiModulesListMessage
+  | UiDataListMessage
+  | ExtUiDecoratorMessage;
 
 // ── Server → Extension ──────────────────────────────────────────────
 
@@ -401,6 +437,23 @@ export interface ExtensionUiResponseMessage {
   cancelled?: boolean;
 }
 
+/**
+ * Server → extension: a browser invoked an action / requested data on a
+ * Phase-1 management-modal module. The bridge re-emits this on `pi.events`
+ * as `pi.events.emit(msg.event, { ...msg.params, action: msg.action, _reply })`.
+ * Extensions either populate `data.items` synchronously (for `action: "list"`
+ * data fetches) or perform side-effects and emit `ui:invalidate` to refresh.
+ */
+export interface UiManagementMessage {
+  type: "ui_management";
+  sessionId: string;
+  /** Action id (matches some `UiAction.id`) or `"list"` for data fetch. */
+  action: string;
+  /** Event name to emit (matches `view.dataEvent` or `UiAction.event`). */
+  event: string;
+  params?: Record<string, unknown>;
+}
+
 export interface PromptResponseServerMessage {
   type: "prompt_response";
   sessionId: string;
@@ -435,4 +488,5 @@ export type ServerToExtensionMessage =
   | RolePresetSaveExtensionMessage
   | RolePresetDeleteExtensionMessage
   | RequestRolesMessage
+  | UiManagementMessage
   | KillProcessMessage;

package/packages/shared/src/recommended-extensions.ts

@@ -180,7 +180,13 @@ export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
  */
 export const BUNDLED_EXTENSION_IDS: readonly string[] = [
 	"pi-anthropic-messages",
-	"pi-flows",
+	// "pi-flows" is intentionally NOT bundled until the upstream repo declares
+	// an SPDX-conformant license (`LICENSE` file or `package.json#license`).
+	// The bundle-recommended-extensions.sh license allowlist enforcement
+	// (MIT/Apache-2.0/BSD-2-Clause/BSD-3-Clause/ISC) correctly rejects it.
+	// Re-add this entry once https://github.com/BlackBeltTechnology/pi-flows
+	// has a license declared. See: openspec/changes/archive/
+	// 2026-04-21-bundle-first-party-extensions/design.md §"License blockers".
 ];
 
 /** Retrieve a recommended entry by id, or `undefined`. */

package/packages/shared/src/rest-api.ts

@@ -64,17 +64,35 @@ export type FileReadResponse = ApiResponse<FileReadResult>;
 export interface BrowseEntry {
   name: string;
   path: string;
-  isGit: boolean;
-  isPi: boolean;
+  /**
+   * Set only when the request used `detect=1`. When the response was
+   * produced without `detect=1`, this field is absent (undefined) —
+   * meaning "not classified", NOT "classified as not-git". Consumers
+   * that need badges SHOULD call `GET /api/browse/flags` to fill in
+   * the flags lazily.
+   *
+   * See change: split-browse-flags.
+   */
+  isGit?: boolean;
+  /** See `isGit` — same opt-in / detect-gated semantics. */
+  isPi?: boolean;
 }
 
 /**
- * Response shape for `GET /api/browse?path=<dir>&q=<query>`.
+ * Response shape for `GET /api/browse?path=<dir>&q=<query>&detect=<0|1>`.
  *
  * The optional `q` query parameter, when present and non-empty, causes the
  * server to filter entries by case-insensitive substring on `name` and rank
  * them (exact → prefix → word-boundary → substring) before the 200-entry cap.
  * When omitted or whitespace-only, entries are sorted alphabetically.
+ *
+ * The optional `detect` query parameter (only the literal string `"1"` is
+ * truthy) opts into eager `.git` / `.pi` classification on every entry. When
+ * absent (the default), per-entry `isGit` / `isPi` are omitted and no
+ * filesystem probes run — use the bulk `GET /api/browse/flags` endpoint to
+ * classify entries lazily.
+ *
+ * See change: split-browse-flags.
  */
 export interface BrowseResult {
   entries: BrowseEntry[];
@@ -94,6 +112,43 @@ export interface BrowseResult {
 
 export type BrowseResponse = ApiResponse<BrowseResult>;
 
+// ── Browse flags (bulk classifier) ──────────────────────────────────
+
+/**
+ * Per-path classification record returned by `GET /api/browse/flags`.
+ * Booleans only — any probe failure (ENOENT, EACCES, ELOOP, race-on-
+ * deletion, …) maps to `false` for that flag, never an error.
+ *
+ * See change: split-browse-flags.
+ */
+export interface BrowseFlagEntry {
+  isGit: boolean;
+  isPi: boolean;
+}
+
+/**
+ * Wire shape passed via the `paths` query parameter on
+ * `GET /api/browse/flags?paths=<json-array>`. The value MUST be a
+ * URL-encoded JSON array of absolute path strings (length ≤ 100).
+ * Provided here for type-only documentation — the request itself is a
+ * GET, so this interface is not serialized as a body.
+ */
+export interface BrowseFlagsRequest {
+  paths: string[];
+}
+
+/** Successful response payload for `GET /api/browse/flags`. */
+export interface BrowseFlagsResult {
+  /**
+   * Map keyed by the absolute paths that were requested. The key set
+   * SHALL equal the input `paths` set — one classification per input
+   * path, no extras, no omissions.
+   */
+  flags: Record<string, BrowseFlagEntry>;
+}
+
+export type BrowseFlagsResponse = ApiResponse<BrowseFlagsResult>;
+
 /** Request body for `POST /api/browse/mkdir`. */
 export interface MkdirRequest {
   parent: string;
@@ -254,6 +309,16 @@ export interface InstalledPackage {
   installedPath?: string;
   /** Set after check-updates: true if newer version available */
   updateAvailable?: boolean;
+  /** Version read from `<installedPath>/package.json#version`. Undefined if missing/unreadable. */
+  version?: string;
+  /** Description read from `<installedPath>/package.json#description`. */
+  description?: string;
+  /** Friendly name. From RECOMMENDED_EXTENSIONS displayName when matched, else basename of source. */
+  displayName?: string;
+  /** True when this row matches a RECOMMENDED_EXTENSIONS entry (via sourcesMatch). */
+  isRecommended?: boolean;
+  /** True when isRecommended AND id is in BUNDLED_EXTENSION_IDS AND bundle subtree exists. */
+  isBundled?: boolean;
 }
 
 export type InstalledPackagesResponse = ApiResponse<InstalledPackage[]>;