@blackbelt-technology/pi-agent-dashboard 0.5.3 → 0.5.4

package/packages/shared/src/browser-protocol.ts

@@ -1,6 +1,10 @@
 /**
  * Server ↔ Browser WebSocket protocol messages.
  */
+import type {
+  PluginIntentsMessage,
+  PluginActionMessage,
+} from "./dashboard-plugin/intent-types.js";
 import type {
   DashboardSession,
   DashboardEvent,
@@ -277,6 +281,28 @@ export interface PinnedDirsUpdatedMessage {
   paths: string[];
 }
 
+// ── Workspaces (folder-workspaces) ───────────────────────────────────
+
+/**
+ * Named, server-persisted, collapsible container grouping one or more
+ * folders. Membership is authoritative and orthogonal to pinning — a
+ * folder may be in `folders[]` and `pinnedDirectories` independently.
+ * Single-membership: a folder belongs to ≤1 workspace.
+ * See change: folder-workspaces.
+ */
+export interface Workspace {
+  id: string;
+  name: string;
+  collapsed: boolean;
+  folders: string[];
+}
+
+/** Server → browser: full workspace list snapshot (sent on subscribe + every mutation). */
+export interface WorkspacesUpdatedMessage {
+  type: "workspaces_updated";
+  workspaces: Workspace[];
+}
+
 export interface TerminalAddedMessage {
   type: "terminal_added";
   terminal: TerminalSession;
@@ -551,6 +577,7 @@ export type ServerToBrowserMessage =
   | SessionsReorderedMessage
   | SessionsSnapshotMessage
   | PinnedDirsUpdatedMessage
+  | WorkspacesUpdatedMessage
   | TerminalAddedMessage
   | TerminalRemovedMessage
   | TerminalUpdatedMessage
@@ -574,7 +601,9 @@ export type ServerToBrowserMessage =
   | BrowserUiModulesListMessage
   | BrowserUiDataListMessage
   | BrowserExtUiDecoratorMessage
-  | BrowserAssetRegisterMessage;
+  | BrowserAssetRegisterMessage
+  | PluginIntentsMessage
+  | QueueUpdateToBrowserMessage;
 
 // ── Browser → Server ────────────────────────────────────────────────
 
@@ -594,6 +623,8 @@ export interface SendPromptToBrowserMessage {
   sessionId: string;
   text: string;
   images?: ImageContent[];
+  /** Delivery mode: "steer" (after current turn) or "followUp" (after agent finishes). Defaults to "followUp" when absent. See change: add-steering-message. */
+  delivery?: "steer" | "followUp";
 }
 
 export interface AbortToBrowserMessage {
@@ -601,6 +632,86 @@ export interface AbortToBrowserMessage {
   sessionId: string;
 }
 
+/**
+ * Browser -> server: clear pi's steering queue for the given session.
+ * Server forwards as `clear_steering_queue`; bridge calls `pi.clearSteeringQueue()`.
+ * Pi emits a fresh `queue_update` reflecting the empty array, which the server
+ * caches + broadcasts. Idempotent on empty queue.
+ * See change: add-followup-edit-and-steer-cancel.
+ */
+export interface ClearSteeringQueueFromBrowserMessage {
+  type: "clear_steering_queue";
+  sessionId: string;
+}
+
+/**
+ * Browser -> server: clear pi's follow-up slot for the given session.
+ * Server forwards as `clear_followup_slot`; bridge calls `pi.clearFollowUpQueue()`.
+ * Idempotent on empty slot.
+ * See change: add-followup-edit-and-steer-cancel.
+ */
+export interface ClearFollowupSlotFromBrowserMessage {
+  type: "clear_followup_slot";
+  sessionId: string;
+}
+
+/**
+ * Browser -> server (v1, deprecated): replace pi's follow-up slot atomically.
+ * v2 prefers `edit_followup_entry { index: 0 }`. Bridge still accepts both
+ * for backward compatibility.
+ * See change: add-followup-edit-and-steer-cancel.
+ */
+export interface EditFollowupSlotFromBrowserMessage {
+  type: "edit_followup_slot";
+  sessionId: string;
+  text: string;
+  images?: ImageContent[];
+}
+
+/**
+ * Browser -> server (v2): move follow-up entry at `index` to position 0.
+ * See change: add-followup-edit-and-steer-cancel.
+ */
+export interface PromoteFollowupEntryFromBrowserMessage {
+  type: "promote_followup_entry";
+  sessionId: string;
+  index: number;
+}
+
+/**
+ * Browser -> server (v2): remove follow-up entry at `index`.
+ * See change: add-followup-edit-and-steer-cancel.
+ */
+export interface RemoveFollowupEntryFromBrowserMessage {
+  type: "remove_followup_entry";
+  sessionId: string;
+  index: number;
+}
+
+/**
+ * Browser -> server (v2): replace follow-up entry at `index`.
+ * See change: add-followup-edit-and-steer-cancel.
+ */
+export interface EditFollowupEntryFromBrowserMessage {
+  type: "edit_followup_entry";
+  sessionId: string;
+  index: number;
+  text: string;
+  images?: ImageContent[];
+}
+
+/**
+ * Server -> browser: broadcast pi's queue mirror after a `queue_update`
+ * arrives from the bridge. Drives `Session.pendingQueues`.
+ * See change: add-followup-edit-and-steer-cancel.
+ */
+export interface QueueUpdateToBrowserMessage {
+  type: "queue_update";
+  sessionId: string;
+  steering: string[];
+  followUp: string[];
+}
+
 export interface RequestCommandsToBrowserMessage {
   type: "request_commands";
   sessionId: string;
@@ -803,6 +914,54 @@ export interface ReorderPinnedDirsMessage {
   paths: string[];
 }
 
+// ── Workspace mutation messages (browser → server) ───────────────────
+// See change: folder-workspaces. Verb-first to match pin_directory family.
+
+export interface CreateWorkspaceMessage {
+  type: "create_workspace";
+  name: string;
+}
+
+export interface RenameWorkspaceMessage {
+  type: "rename_workspace";
+  id: string;
+  name: string;
+}
+
+export interface DeleteWorkspaceMessage {
+  type: "delete_workspace";
+  id: string;
+}
+
+export interface SetWorkspaceCollapsedMessage {
+  type: "set_workspace_collapsed";
+  id: string;
+  collapsed: boolean;
+}
+
+export interface AddFolderToWorkspaceMessage {
+  type: "add_folder_to_workspace";
+  id: string;
+  path: string;
+}
+
+export interface RemoveFolderFromWorkspaceMessage {
+  type: "remove_folder_from_workspace";
+  id: string;
+  path: string;
+}
+
+export interface ReorderWorkspaceFoldersMessage {
+  type: "reorder_workspace_folders";
+  id: string;
+  paths: string[];
+}
+
+export interface ReorderWorkspacesMessage {
+  type: "reorder_workspaces";
+  ids: string[];
+}
+
 export interface OpenSpecBulkArchiveBrowserMessage {
   type: "openspec_bulk_archive";
   cwd: string;
@@ -964,6 +1123,14 @@ export type BrowserToServerMessage =
   | PinDirectoryMessage
   | UnpinDirectoryMessage
   | ReorderPinnedDirsMessage
+  | CreateWorkspaceMessage
+  | RenameWorkspaceMessage
+  | DeleteWorkspaceMessage
+  | SetWorkspaceCollapsedMessage
+  | AddFolderToWorkspaceMessage
+  | RemoveFolderFromWorkspaceMessage
+  | ReorderWorkspaceFoldersMessage
+  | ReorderWorkspacesMessage
   | OpenSpecBulkArchiveBrowserMessage
   | CreateTerminalBrowserMessage
   | KillTerminalBrowserMessage
@@ -981,4 +1148,11 @@ export type BrowserToServerMessage =
   | UiManagementBrowserMessage
   | SessionViewBrowserMessage
   | SessionUnviewBrowserMessage
-  | KillProcessBrowserMessage;
+  | KillProcessBrowserMessage
+  | ClearSteeringQueueFromBrowserMessage
+  | ClearFollowupSlotFromBrowserMessage
+  | EditFollowupSlotFromBrowserMessage
+  | PromoteFollowupEntryFromBrowserMessage
+  | RemoveFollowupEntryFromBrowserMessage
+  | EditFollowupEntryFromBrowserMessage
+  | PluginActionMessage;

package/packages/shared/src/config.ts

@@ -212,6 +212,15 @@ export interface DashboardConfig {
   cors: CorsConfig;
   /** Last-used server address (host:port) for reconnection */
   lastServer?: string;
+  /**
+   * Display name shown as the PWA app label when installed on a home screen
+   * or app drawer. Used as the `<source>` segment of the dynamic
+   * `/manifest.json` `name` field: `"Pi-Dash · <source>"`. Trimmed; blank /
+   * whitespace-only values are treated as unset and the server falls back to
+   * the request `Host` header (port stripped) → `os.hostname()` → literal
+   * `"Pi-Dash"`. See change: add-dynamic-pwa-manifest-naming.
+   */
+  dashboardName?: string;
   /** Whether the server was launched by the Electron app */
   electronMode: boolean;
   /**
@@ -574,6 +583,9 @@ export function loadConfig(): DashboardConfig {
           : defaults.cors.allowedOrigins,
       },
       ...(typeof parsed.lastServer === "string" ? { lastServer: parsed.lastServer } : {}),
+      ...(typeof parsed.dashboardName === "string" && parsed.dashboardName.trim()
+        ? { dashboardName: parsed.dashboardName }
+        : {}),
       electronMode: parsed.electronMode === true,
       knownServers: parseKnownServers(parsed.knownServers),
       reattachPlacement: parseReattachPlacement(parsed.reattachPlacement),

package/packages/shared/src/dashboard-paths.ts

@@ -0,0 +1,69 @@
+/**
+ * Single source of truth for filesystem paths the dashboard touches at runtime.
+ *
+ * Why this file exists
+ * --------------------
+ * Two distinct directories were historically conflated by `~/`-anchored
+ * `path.join` calls scattered across packages:
+ *
+ *   ~/.pi/dashboard/   — config + the *server* log (`server.log`)
+ *   ~/.pi-dashboard/   — the *managed* install dir (npm packages, etc.)
+ *                        Older bootstrap code also wrote an *installer*
+ *                        log to `~/.pi-dashboard/server.log` (note: same
+ *                        filename, different dir). That file is now
+ *                        legacy/dead in the V2 launch path.
+ *
+ * Loading-page recovery surfaced this on 2026-05-17: the IPC handler
+ * read `~/.pi-dashboard/server.log` (stale installer log from May 8)
+ * while the live server wrote to `~/.pi/dashboard/server.log`.
+ *
+ * All path math lives here. Every $HOME override goes through `env.homedir`
+ * so tests can re-root without mutating `os.homedir()`.
+ *
+ * See change: harvest-bootstrap-survivor-fixes (cherry-pick 1).
+ */
+import path from "node:path";
+import os from "node:os";
+import { getManagedDir as getManagedDirInternal, type ManagedPathsEnv } from "./managed-paths.js";
+
+/** Shared env override surface — `homedir` only, mirrors `ManagedPathsEnv`. */
+export type DashboardPathsEnv = ManagedPathsEnv;
+
+/** `~/.pi/dashboard/` — config dir for `config.json`, `server.log`, etc. */
+export function getDashboardConfigDir(env?: DashboardPathsEnv): string {
+  return path.join(env?.homedir ?? os.homedir(), ".pi", "dashboard");
+}
+
+/** `~/.pi/dashboard/server.log` — the live dashboard server's stdout/stderr log. */
+export function getDashboardServerLogPath(env?: DashboardPathsEnv): string {
+  return path.join(getDashboardConfigDir(env), "server.log");
+}
+
+/**
+ * `~/.pi/dashboard/first-run-done` — sentinel file written by the Electron
+ * wizard on completion. Presence means the one-step welcome was shown and
+ * acknowledged; subsequent launches skip the wizard.
+ *
+ * Lives under `~/.pi/dashboard/` (not the legacy `~/.pi-dashboard/`) so it
+ * survives Electron whole-app updates and remains the same path across
+ * all install layouts.
+ *
+ * See change: eliminate-electron-runtime-install (Q2 ratification).
+ */
+export function getFirstRunMarkerPath(env?: DashboardPathsEnv): string {
+  return path.join(getDashboardConfigDir(env), "first-run-done");
+}
+
+/** `~/.pi-dashboard/` — managed-install root (npm packages, etc.). Re-export. */
+export function getManagedDir(env?: DashboardPathsEnv): string {
+  return getManagedDirInternal(env);
+}
+
+/**
+ * `~/.pi-dashboard/server.log` — the legacy *installer* log. Distinct from
+ * the server log; left here so callers can be explicit about which file
+ * they want and the grep tooling has a single canonical reference.
+ */
+export function getInstallerLogPath(env?: DashboardPathsEnv): string {
+  return path.join(getManagedDir(env), "server.log");
+}

package/packages/shared/src/dashboard-plugin/index.ts

@@ -9,3 +9,5 @@ export * from "./slot-types.js";
 export * from "./manifest-types.js";
 export * from "./slot-props.js";
 export * from "./plugin-status.js";
+export * from "./ui-primitives.js";
+export * from "./intent-types.js";

package/packages/shared/src/dashboard-plugin/intent-types.ts

@@ -0,0 +1,93 @@
+/**
+ * Plugin intent protocol — wire-format types.
+ *
+ * Plugins describe per-session UI contributions as `IntentNode` JSON trees
+ * and broadcast them via `ServerPluginContext.broadcastToSubscribers`. The
+ * shell on every connected client receives the broadcast, looks up the
+ * referenced primitive name in its local UI primitive registry, and renders
+ * the resulting React component with the JSON-serializable props.
+ *
+ * Function references SHALL NOT cross the wire. Action handlers (onClick,
+ * onSubmit, etc.) are declared as `ActionDescriptor` objects; the client's
+ * IntentRenderer wires them to send `PluginActionMessage` back over the
+ * WebSocket when triggered.
+ *
+ * See change: adopt-server-driven-intent-rendering.
+ */
+import type { SlotId } from "./slot-types.js";
+
+/**
+ * A node in an intent tree.
+ *
+ * The plugin describes WHAT to render by primitive name. The client's
+ * IntentRenderer resolves the name to a `ComponentType` from its local
+ * primitive registry.
+ */
+export interface IntentNode {
+  /** Stable primitive name. Resolved by useUiPrimitive on the client. */
+  primitive: string;
+  /**
+   * Props passed to the resolved component. Values may be primitives,
+   * serializable structures, OR nested IntentNodes (rendered recursively
+   * as React elements by IntentRenderer).
+   */
+  props?: Record<string, unknown>;
+  /** Optional stable React key for reconciliation. Required for items in lists. */
+  key?: string;
+  /**
+   * Optional action descriptors. The IntentRenderer wires these to send
+   * `PluginActionMessage` to the server when the user triggers them.
+   */
+  actions?: Record<string, ActionDescriptor>;
+}
+
+/**
+ * What to send back to the server when the user triggers an action.
+ *
+ * Function references SHALL NOT cross the wire. This is what does instead.
+ */
+export interface ActionDescriptor {
+  /** The plugin to dispatch the action to (matches manifest id). */
+  pluginId: string;
+  /** Plugin-defined action name. */
+  action: string;
+  /** Optional payload. Must be JSON-serializable. */
+  payload?: Record<string, unknown>;
+}
+
+/**
+ * Server → Browser envelope. One message per (slot, session) change from
+ * a plugin. The shell on every connected client receives it via the bridge
+ * fanout.
+ */
+export interface PluginIntentsMessage {
+  type: "plugin_intents";
+  /** The plugin emitting this intent. */
+  pluginId: string;
+  /**
+   * The session this intent applies to. `null` for global slots like
+   * `settings-section` that aren't bound to a single session.
+   */
+  sessionId: string | null;
+  /** The slot this intent occupies. */
+  slot: SlotId;
+  /** The intent tree. `null` means "clear my contribution to this slot". */
+  intent: IntentNode | null;
+}
+
+/**
+ * Browser → Server envelope. Emitted by the IntentRenderer when the user
+ * triggers an `ActionDescriptor` (e.g. a button click) inside a rendered
+ * intent tree.
+ */
+export interface PluginActionMessage {
+  type: "plugin_action";
+  /** Matches `ActionDescriptor.pluginId` on the originating intent. */
+  pluginId: string;
+  /** The session context this action originated in (may be `null`). */
+  sessionId: string | null;
+  /** Plugin-defined action name. */
+  action: string;
+  /** Optional payload. */
+  payload?: Record<string, unknown>;
+}

package/packages/shared/src/dashboard-plugin/manifest-types.ts

@@ -19,7 +19,24 @@ export interface PluginClaim {
    * Defaults to "general" if omitted.
    */
   tab?: SettingsTab;
-  /** Slot-specific extra config. */
+  /**
+   * URL path pattern (wouter syntax, must start with "/") for the
+   * `shell-overlay-route` slot. First-class field so the slot consumer
+   * has a typed contract instead of digging through `config`.
+   * Example: "/session/:sid/flow/:flowId/agent/:agentId".
+   *
+   * See change: fix-flows-plugin-polish (path-as-first-class-claim-field).
+   */
+  path?: string;
+  /**
+   * For `shell-overlay-route` claims: which URL parameter holds the session
+   * id. The slot consumer uses this to resolve the parent session metadata
+   * via `useShellSession`. Defaults to "sid" when omitted.
+   *
+   * See change: fix-flows-plugin-polish (path-as-first-class-claim-field).
+   */
+  sessionParam?: string;
+  /** Slot-specific extra config (escape hatch — prefer first-class fields). */
   config?: Record<string, unknown>;
   /**
    * Optional exported predicate function name for filtering contributions.
@@ -40,6 +57,27 @@ export interface PluginClaim {
   shouldRender?: string;
 }
 
+/**
+ * Declarative requirements a plugin has on its environment.
+ * Probed by the dashboard-plugin-runtime; surfaced in PluginStatus.requirements.
+ *
+ * Names are matched against pi extensions (via /api/packages/installed),
+ * binaries (via the shared ToolRegistry), and named service probes from a
+ * closed built-in registry. Plugins SHALL NOT register additional service
+ * names in V1.
+ *
+ * See change: add-plugin-activation-ui (Layer 1.5).
+ */
+export interface PluginRequirements {
+  /** pi extension package identifiers (matched via the same logic
+      RECOMMENDED_EXTENSIONS uses: name / id / source / displayName). */
+  piExtensions?: string[];
+  /** Binaries that must resolve on PATH via the tool-registry. */
+  binaries?: string[];
+  /** Named service probes (closed built-in registry; "pi-model-proxy" only in V1). */
+  services?: string[];
+}
+
 /**
  * The pi-dashboard-plugin manifest.
  * Declared as the `pi-dashboard-plugin` field in a package.json,
@@ -65,6 +103,22 @@ export interface PluginManifest {
   configSchema?: string;
   /** Slot claims. */
   claims: PluginClaim[];
+  /**
+   * Optional declarative requirements probed by the runtime and surfaced as
+   * `PluginStatus.requirements` / `missingRequirements`.
+   * See change: add-plugin-activation-ui (Layer 1.5).
+   */
+  requires?: PluginRequirements;
+  /**
+   * Other plugin ids this plugin requires (hard, transitive). When a
+   * dependency is missing from discovery or disabled in config, the loader
+   * SHALL skip this plugin's server entry and surface the gap via
+   * `PluginStatus.missingDeps`. Cycles soft-fail at discovery (loaded: false
+   * for every plugin in the cycle).
+   *
+   * See change: add-plugin-activation-ui (Layer 2 — dependency graph).
+   */
+  dependsOn?: string[];
   /**
    * When true, the plugin is a test fixture and SHALL be excluded from
    * production bundles (NODE_ENV=production).

package/packages/shared/src/dashboard-plugin/plugin-status.ts

@@ -2,15 +2,97 @@
  * Plugin status types used in /api/health.plugins[] and WebSocket broadcasts.
  */
 
+/**
+ * Where pi-coding-agent's loader will (or won't) find this plugin's bridge.
+ *
+ * - `"packages[]"`     — bridge path present in `settings.json#packages[]`
+ *                         (pi reads this; bridge will load on session start)
+ * - `"dashboardPluginBridges"` — only present in the legacy key pi ignores
+ *                         (loaded: false expected)
+ * - `"none"`           — plugin has no bridge entry or registration failed
+ *
+ * See change: fix-pi-flows-end-to-end (Group 2).
+ */
+export type BridgeLoadSource = "packages[]" | "dashboardPluginBridges" | "none";
+
+/**
+ * Structured probe report for a plugin's declarative `requires`.
+ * See change: add-plugin-activation-ui (Layer 1.5).
+ */
+export interface PluginRequirementReport {
+  piExtensions: { name: string; satisfied: boolean }[];
+  binaries: { name: string; satisfied: boolean; resolvedPath?: string }[];
+  services: { name: string; satisfied: boolean; error?: string }[];
+}
+
+/**
+ * Latest bridge-status probe forwarded from the pi-side extension (for
+ * status-emitting bridges like flows-anthropic-bridge). Omitted when the
+ * plugin has no bridge or hasn't reported yet.
+ */
+export interface BridgeProbeSnapshot {
+  status: "probing" | "waiting_peers" | "active" | "degraded";
+  /** Per-peer probe results keyed by the peer spec (e.g. "@pi/anthropic-messages"). */
+  peers: Record<string, { ok: boolean; reason?: string }>;
+  /** Unix-ms timestamp when the bridge emitted this snapshot. */
+  at: number;
+}
+
 /** Status of a single discovered plugin, reported by /api/health. */
 export interface PluginStatus {
   id: string;
+  /**
+   * Human-readable name from the manifest. Used by the Plugins activation
+   * UI. Falls back to `id` at the consumer if absent on legacy payloads.
+   * See change: add-plugin-activation-ui.
+   */
+  displayName: string;
   enabled: boolean;
   loaded: boolean;
   /** Error message if the plugin failed to load or has a conflict. */
   error?: string;
   /** Number of slot claims declared in the plugin's manifest. */
   claims: number;
+  /**
+   * Where the bridge entry is registered, classified at health-check time.
+   * See change: fix-pi-flows-end-to-end Group 2.
+   */
+  bridgeLoadedFrom?: BridgeLoadSource;
+  /** Latest bridge-status probe (only present for status-emitting bridges). */
+  lastProbe?: BridgeProbeSnapshot;
+  /**
+   * Structured probe report against the plugin's declarative `requires`.
+   * Populated by the loader after `loadServerEntries` and refreshed on every
+   * successful `package_operation_complete` and at most every 30 seconds.
+   * Absent when the plugin declares no `requires`.
+   * See change: add-plugin-activation-ui.
+   */
+  requirements?: PluginRequirementReport;
+  /**
+   * Flat list of unsatisfied requirement names across all three categories.
+   * Always `[]` when every requirement is satisfied or the plugin declares
+   * no `requires`. Never `undefined`.
+   * See change: add-plugin-activation-ui.
+   */
+  missingRequirements?: string[];
+  /**
+   * `dependsOn` array verbatim from the manifest. Empty when the plugin
+   * has no inter-plugin dependencies.
+   * See change: add-plugin-activation-ui (Layer 2 — dependency graph).
+   */
+  dependsOn?: string[];
+  /**
+   * Plugin ids that declare THIS plugin in their `dependsOn`. Computed
+   * by the loader by inverting the graph. Empty when nothing depends on
+   * this plugin.
+   */
+  dependents?: string[];
+  /**
+   * Plugin ids from `dependsOn` that are either missing from discovery or
+   * disabled in config. Non-empty implies the loader skipped this plugin's
+   * server entry (`loaded: false`).
+   */
+  missingDeps?: string[];
 }
 
 /** WebSocket broadcast sent to all browsers when a plugin's config changes. */

package/packages/shared/src/dashboard-plugin/slot-props.ts

@@ -42,6 +42,10 @@ export interface SlotPropsMap {
     session: DashboardSession;
     pluginContext: AnyPluginContext;
   };
+  "session-card-flows": {
+    session: DashboardSession;
+    pluginContext: AnyPluginContext;
+  };
   "workspace-action-bar": {
     session: DashboardSession;
     pluginContext: AnyPluginContext;
@@ -71,6 +75,13 @@ export interface SlotPropsMap {
     onClose: () => void;
     pluginContext: AnyPluginContext;
   };
+  "shell-overlay-route": {
+    params: Record<string, string>;
+    /** DashboardSession metadata resolved from the URL’s session param (`config.sessionParam`, default `"sid"`). Undefined when the URL has no session id or no matching session. */
+    session?: DashboardSession;
+    onBack: () => void;
+    pluginContext: AnyPluginContext;
+  };
   "settings-section": {
     pluginContext: AnyPluginContext;
   };

package/packages/shared/src/dashboard-plugin/slot-types.ts

@@ -15,13 +15,15 @@ export type SlotId =
   | "sidebar-folder-section"
   | "session-card-action-bar"
   | "workspace-action-bar"
-  // (session-card-memory is also react-only; declared below for ordering)
+  | "shell-overlay-route"
+  // (session-card-memory and session-card-flows are also react-only; declared below for ordering)
   | "content-inline-footer"
   | "anchored-popover"
   | "command-route"
   | "tool-renderer"
   // React-or-descriptor slots
   | "session-card-memory"
+  | "session-card-flows"
   | "session-card-badge"
   | "content-view"
   | "content-header-sticky"
@@ -54,6 +56,11 @@ export const SLOT_DEFINITIONS: Record<SlotId, SlotDefinition> = {
     payloadTier: "react-only",
     description: "Collapsible block above session list per workspace folder",
   },
+  "shell-overlay-route": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Plugin-owned full-screen route mounted at top of the shell (desktop + mobile). Each claim ships a wouter path pattern via `config.path` and a React component receiving { params, onBack, session? }.",
+  },
   "session-card-badge": {
     multiplicity: "many",
     payloadTier: "react-or-descriptor",
@@ -69,6 +76,11 @@ export const SLOT_DEFINITIONS: Record<SlotId, SlotDefinition> = {
     payloadTier: "react-only",
     description: "Memory/Honcho contributions inside the MEMORY subcard of a session card",
   },
+  "session-card-flows": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Flow contributions inside the FLOWS subcard of a session card",
+  },
   "workspace-action-bar": {
     multiplicity: "many",
     payloadTier: "react-only",
@@ -179,11 +191,13 @@ type SessionScopedSlot =
   | "session-card-badge"
   | "session-card-action-bar"
   | "session-card-memory"
+  | "session-card-flows"
   | "workspace-action-bar"
   | "content-view"
   | "content-header-sticky"
   | "content-inline-footer"
-  | "command-route";
+  | "command-route"
+  | "shell-overlay-route";
 
 /** Slot ids whose predicates receive a folder descriptor. */
 type FolderScopedSlot = "sidebar-folder-section";