aidevops 3.27.0 → 3.29.0

package/packages/gui-shared/src/contracts.ts

@@ -1,6 +1,6 @@
 export type GuiRouteClassification = "read" | "write" | "destructive";
 
-export type GuiOperationId = "setup.status.read" | "capabilities.read" | "filesystem.read" | "vault.status.read";
+export type GuiOperationId = "setup.status.read" | "capabilities.read" | "filesystem.read" | "vault.status.read" | "apps.action.run" | "apps.action.status";
 
 export type GuiFileRootId = "agents" | "config" | "localSetup" | "git";
 
@@ -23,7 +23,7 @@ export interface GuiResponseEnvelope<TData> {
 
 export interface GuiRouteManifest {
   route: string;
-  method: "GET";
+  method: "GET" | "POST";
   operation_id: GuiOperationId;
   classification: GuiRouteClassification;
   source_surface: string;
@@ -68,6 +68,44 @@ export interface GuiFileExplorerData {
   entry_limit: number;
 }
 
+export type GuiAppActionId = "install" | "update" | "reinstall" | "remove";
+
+export interface GuiManagedAppActionSummary {
+  id: GuiAppActionId;
+  label: string;
+  enabled: boolean;
+  command_preview: string;
+  confirmation: "none" | "recommended" | "required";
+}
+
+export interface GuiManagedAppSummary {
+  id: string;
+  name: string;
+  description: string;
+  category: string;
+  origin_website_url: string;
+  origin_repo_url: string;
+  aidevops_install: boolean;
+  aidevops_update: boolean;
+  installed_version: string;
+  latest_version: string;
+  install_path_ref: string;
+  status: "found" | "missing" | "unchecked";
+  actions: GuiManagedAppActionSummary[];
+}
+
+export interface GuiAppActionJobSummary {
+  id: string;
+  app_id: string;
+  action: GuiAppActionId;
+  status: "running" | "completed" | "failed" | "rejected";
+  command_preview: string;
+  started_at: string;
+  finished_at: string | null;
+  exit_code: number | null;
+  output: string[];
+}
+
 export interface GuiSecretReference {
   name: string;
   status: "configured" | "missing" | "unchecked";
@@ -318,6 +356,7 @@ export interface GuiStatusData {
   oauth_pool: GuiOAuthPoolSummary;
   setup_targets: GuiSetupTargetSummary[];
   ai_apps: GuiAiAppSummary[];
+  managed_apps: GuiManagedAppSummary[];
   vault: GuiVaultStatusData;
   capabilities: GuiCapabilitySummary[];
   secrets: GuiSecretReference[];
@@ -357,6 +396,28 @@ export const VAULT_STATUS_ROUTE_MANIFEST: GuiRouteManifest = {
   redactions: ["secret_values", "credential_paths", "private_key_material", "vault_passphrases", "recovery_material"],
 };
 
+export const APP_ACTION_ROUTE_MANIFEST: GuiRouteManifest = {
+  route: "/api/apps/:appId/actions/:action",
+  method: "POST",
+  operation_id: "apps.action.run",
+  classification: "write",
+  source_surface: "apps",
+  adapter: "appActions.startAppAction",
+  command_pattern: ["allowlisted", "aidevops", "setup/update", "background-job"],
+  redactions: ["secret_values", "credential_paths", "private_key_material"],
+};
+
+export const APP_ACTION_STATUS_ROUTE_MANIFEST: GuiRouteManifest = {
+  route: "/api/apps/jobs/:jobId",
+  method: "GET",
+  operation_id: "apps.action.status",
+  classification: "read",
+  source_surface: "apps",
+  adapter: "appActions.readAppActionJob",
+  command_pattern: ["background-job", "metadata-and-output-only"],
+  redactions: ["secret_values", "credential_paths", "private_key_material"],
+};
+
 export const GUI_FILE_ROOTS: readonly GuiFileRootDefinition[] = [
   {
     id: "agents",

package/packages/gui-shared/src/fixtures.ts

@@ -162,6 +162,7 @@ export const statusFixture: GuiStatusData = {
       needs_update: false,
     },
   ],
+  managed_apps: [],
   vault: {
     status: "uninitialized",
     setup_state: "uninitialized",

package/packages/gui-web/src/App.tsx

@@ -1,5 +1,5 @@
 import type { GuiResponseEnvelope, GuiStatusData } from "@aidevops/gui-shared";
-import { type ReactElement, useEffect, useState } from "react";
+import { type KeyboardEvent as ReactKeyboardEvent, type MouseEvent as ReactMouseEvent, type ReactElement, useEffect, useState } from "react";
 import { MachineRail, Sidebar } from "./AppNavigation";
 import { Workspace } from "./AppWorkspace";
 import type { ConversationMode, FontPreference, FontSizePreference, ShellMode, SurfaceId, ThemePreference } from "./app-model";
@@ -32,9 +32,14 @@ export const appearanceStorageKeys = {
   machineRail: "aidevops-gui-show-machine-rail",
   showBorders: "aidevops-gui-show-borders",
   showNavCounts: "aidevops-gui-show-nav-counts",
+  sidebarWidth: "aidevops-gui-sidebar-width",
   theme: "aidevops-gui-theme",
 } as const;
 
+const defaultSidebarWidth = 302;
+const minSidebarWidth = 248;
+const maxSidebarWidth = 520;
+
 export interface StoredAppearancePreferences {
   accentHue: number;
   fontPreference: FontPreference;
@@ -76,6 +81,7 @@ export function App(): ReactElement {
   const [shellMode, setShellMode] = useState<ShellMode>("devices");
   const [conversationMode, setConversationMode] = useState<ConversationMode>("ai");
   const [selectedLocalRepoIndex, setSelectedLocalRepoIndex] = useState(0);
+  const [selectedSessionId, setSelectedSessionId] = useState<string | undefined>();
   const [systemTheme, setSystemTheme] = useState<"light" | "dark">("light");
   const resolvedTheme = themePreference === "system" ? systemTheme : themePreference;
   const activeSurface: SurfaceId = navigation.entries[navigation.index] ?? "overview";
@@ -184,12 +190,14 @@ export function App(): ReactElement {
         fontSizePreference={fontSizePreference}
         fontPreference={fontPreference}
         selectedLocalRepoIndex={selectedLocalRepoIndex}
+        selectedSessionId={selectedSessionId}
         setAccentHue={setAccentHue}
         setActiveSurface={setActiveSurface}
         setConversationMode={setConversationMode}
         setFontSizePreference={setFontSizePreference}
         setFontPreference={setFontPreference}
         setSelectedLocalRepoIndex={setSelectedLocalRepoIndex}
+        setSelectedSessionId={setSelectedSessionId}
         setShellMode={setShellMode}
         setShowBorders={setShowBorders}
         setShowNavCounts={setShowNavCounts}
@@ -200,6 +208,7 @@ export function App(): ReactElement {
         status={status.data}
         themePreference={themePreference}
       />
+      <SidebarResizeHandle />
       <Workspace
         activeItem={activeItem}
         activeSectionLabel={activeSectionLabel}
@@ -211,7 +220,12 @@ export function App(): ReactElement {
         goBack={goBack}
         goForward={goForward}
         selectedLocalRepoIndex={selectedLocalRepoIndex}
+        selectedSessionId={selectedSessionId}
         setActiveSurface={setActiveSurface}
+        setConversationMode={setConversationMode}
+        setSelectedLocalRepoIndex={setSelectedLocalRepoIndex}
+        setSelectedSessionId={setSelectedSessionId}
+        setShellMode={setShellMode}
         shellMode={shellMode}
         status={status.data}
       />
@@ -220,6 +234,54 @@ export function App(): ReactElement {
   );
 }
 
+export function clampSidebarWidth(width: number): number {
+  return Math.min(maxSidebarWidth, Math.max(minSidebarWidth, Math.round(width)));
+}
+
+function SidebarResizeHandle(): ReactElement {
+  const [sidebarWidth, setSidebarWidth] = useState(() => readStoredSidebarWidth());
+
+  useEffect(() => {
+    document.documentElement.style.setProperty("--sidebar-width", `${sidebarWidth}px`);
+    persistAppearancePreference(appearanceStorageKeys.sidebarWidth, String(sidebarWidth));
+  }, [sidebarWidth]);
+
+  const startSidebarResize = (event: ReactMouseEvent<HTMLElement>) => {
+    const startX = event.clientX;
+    const startWidth = sidebarWidth;
+    const resizeSidebar = (moveEvent: MouseEvent) => setSidebarWidth(clampSidebarWidth(startWidth + moveEvent.clientX - startX));
+    const stopResize = () => {
+      document.documentElement.classList.remove("resizing-sidebar");
+      window.removeEventListener("mousemove", resizeSidebar);
+      window.removeEventListener("mouseup", stopResize);
+    };
+
+    event.preventDefault();
+    document.documentElement.classList.add("resizing-sidebar");
+    window.addEventListener("mousemove", resizeSidebar);
+    window.addEventListener("mouseup", stopResize);
+  };
+
+  const resizeSidebarWithKeyboard = (event: ReactKeyboardEvent<HTMLElement>) => {
+    if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
+      event.preventDefault();
+      setSidebarWidth((current) => clampSidebarWidth(current + (event.key === "ArrowRight" ? 16 : -16)));
+    }
+
+    if (event.key === "Home" || event.key === "End") {
+      event.preventDefault();
+      setSidebarWidth(event.key === "Home" ? minSidebarWidth : maxSidebarWidth);
+    }
+  };
+
+  return <hr aria-label="Resize sidebar" aria-orientation="vertical" aria-valuemax={maxSidebarWidth} aria-valuemin={minSidebarWidth} aria-valuenow={sidebarWidth} className="sidebar-resize-handle" onKeyDown={resizeSidebarWithKeyboard} onMouseDown={startSidebarResize} tabIndex={0} />;
+}
+
+function readStoredSidebarWidth(storage: ReadableAppearanceStorage | undefined = browserLocalStorage()): number {
+  const savedWidth = Number.parseInt(storage?.getItem(appearanceStorageKeys.sidebarWidth) ?? "", 10);
+  return Number.isFinite(savedWidth) ? clampSidebarWidth(savedWidth) : defaultSidebarWidth;
+}
+
 function sendNativeAccentHue(hue: number): void {
   const webkit = (window as WebKitBridgeWindow).webkit;
   webkit?.messageHandlers?.accentHue?.postMessage(hue);

package/packages/gui-web/src/AppNavigation.tsx

@@ -20,6 +20,7 @@ import {
   FiGrid,
   FiHash,
   FiHardDrive,
+  FiHelpCircle,
   FiLink,
   FiLink2,
   FiList,
@@ -54,6 +55,8 @@ const surfaceIcons: Record<SurfaceIconName, IconType> = {
   globe: FiGlobe,
   grid: FiGrid,
   hardDrive: FiHardDrive,
+  hash: FiHash,
+  help: FiHelpCircle,
   link: FiLink,
   list: FiList,
   lock: FiLock,
@@ -107,19 +110,21 @@ export function MachineRail({ machine }: { machine?: GuiMachineSummary }) {
   );
 }
 
-export function Sidebar({ activeSurface, accentHue, conversationMode, fontPreference, fontSizePreference, selectedLocalRepoIndex, setAccentHue, setActiveSurface, setConversationMode, setFontPreference, setFontSizePreference, setSelectedLocalRepoIndex, setShellMode, setShowBorders, setShowNavCounts, setThemePreference, shellMode, showBorders, showNavCounts, status, themePreference }: {
+export function Sidebar({ activeSurface, accentHue, conversationMode, fontPreference, fontSizePreference, selectedLocalRepoIndex, selectedSessionId, setAccentHue, setActiveSurface, setConversationMode, setFontPreference, setFontSizePreference, setSelectedLocalRepoIndex, setSelectedSessionId, setShellMode, setShowBorders, setShowNavCounts, setThemePreference, shellMode, showBorders, showNavCounts, status, themePreference }: {
   activeSurface: SurfaceId;
   accentHue: number;
   conversationMode: ConversationMode;
   fontPreference: FontPreference;
   fontSizePreference: FontSizePreference;
   selectedLocalRepoIndex: number;
+  selectedSessionId: string | undefined;
   setAccentHue: (hue: number) => void;
   setActiveSurface: (surface: SurfaceId) => void;
   setConversationMode: (mode: ConversationMode) => void;
   setFontPreference: (font: FontPreference) => void;
   setFontSizePreference: (size: FontSizePreference) => void;
   setSelectedLocalRepoIndex: (index: number) => void;
+  setSelectedSessionId: (id: string | undefined) => void;
   setShellMode: (mode: ShellMode) => void;
   setShowBorders: (show: boolean) => void;
   setShowNavCounts: (show: boolean) => void;
@@ -151,8 +156,10 @@ export function Sidebar({ activeSurface, accentHue, conversationMode, fontPrefer
         </> : <ConversationSidebar
           conversationMode={conversationMode}
           selectedLocalRepoIndex={selectedLocalRepoIndex}
+          selectedSessionId={selectedSessionId}
           setConversationMode={setConversationMode}
           setSelectedLocalRepoIndex={setSelectedLocalRepoIndex}
+          setSelectedSessionId={setSelectedSessionId}
           status={status}
         />}
       </nav>
@@ -200,11 +207,13 @@ function IconSwitch<TValue extends string>({ ariaLabel, options, value }: {
   );
 }
 
-function ConversationSidebar({ conversationMode, selectedLocalRepoIndex, setConversationMode, setSelectedLocalRepoIndex, status }: {
+function ConversationSidebar({ conversationMode, selectedLocalRepoIndex, selectedSessionId, setConversationMode, setSelectedLocalRepoIndex, setSelectedSessionId, status }: {
   conversationMode: ConversationMode;
   selectedLocalRepoIndex: number;
+  selectedSessionId: string | undefined;
   setConversationMode: (mode: ConversationMode) => void;
   setSelectedLocalRepoIndex: (index: number) => void;
+  setSelectedSessionId: (id: string | undefined) => void;
   status: GuiStatusData;
 }) {
   const repos = status.local_repos.repos;
@@ -212,6 +221,7 @@ function ConversationSidebar({ conversationMode, selectedLocalRepoIndex, setConv
   const sessions = selectedRepo === undefined
     ? []
     : status.opencode_sessions.sessions.filter((session) => session.repo_path_ref === selectedRepo.path_ref);
+  const activeSessionId = sessions.some((session) => session.id_ref === selectedSessionId) ? selectedSessionId : sessions[0]?.id_ref;
   const canSelectPreviousRepo = selectedLocalRepoIndex > 0;
   const canSelectNextRepo = selectedLocalRepoIndex < repos.length - 1;
 
@@ -223,19 +233,18 @@ function ConversationSidebar({ conversationMode, selectedLocalRepoIndex, setConv
       <section className="repo-session-selector" aria-label={text.localRepoSelector}>
         <span className="repo-selector-heading" id="local-repo-selector-label">{text.localRepos}</span>
         <div className="selector-with-stepper repo-selector-row">
-          <button aria-label="Previous local repo" className="selector-step-button" disabled={!canSelectPreviousRepo} onClick={() => setSelectedLocalRepoIndex(Math.max(0, selectedLocalRepoIndex - 1))} type="button"><FiChevronLeft aria-hidden="true" /></button>
-          <select aria-labelledby="local-repo-selector-label" onChange={(event) => setSelectedLocalRepoIndex(Number.parseInt(event.currentTarget.value, 10))} value={Math.min(selectedLocalRepoIndex, Math.max(0, repos.length - 1))}>
+          <button aria-label="Previous local repo" className="selector-step-button" disabled={!canSelectPreviousRepo} onClick={() => { setSelectedLocalRepoIndex(Math.max(0, selectedLocalRepoIndex - 1)); setSelectedSessionId(undefined); }} type="button"><FiChevronLeft aria-hidden="true" /></button>
+          <select aria-labelledby="local-repo-selector-label" onChange={(event) => { setSelectedLocalRepoIndex(Number.parseInt(event.currentTarget.value, 10)); setSelectedSessionId(undefined); }} value={Math.min(selectedLocalRepoIndex, Math.max(0, repos.length - 1))}>
             {repos.length === 0 ? <option value={0}>No local repos</option> : repos.map((repo, index) => <option key={repo.path_ref} value={index}>{repo.name}</option>)}
           </select>
-          <button aria-label="Next local repo" className="selector-step-button" disabled={!canSelectNextRepo} onClick={() => setSelectedLocalRepoIndex(Math.min(repos.length - 1, selectedLocalRepoIndex + 1))} type="button"><FiChevronRight aria-hidden="true" /></button>
+          <button aria-label="Next local repo" className="selector-step-button" disabled={!canSelectNextRepo} onClick={() => { setSelectedLocalRepoIndex(Math.min(repos.length - 1, selectedLocalRepoIndex + 1)); setSelectedSessionId(undefined); }} type="button"><FiChevronRight aria-hidden="true" /></button>
         </div>
       </section>
       <section className="sidebar-group session-history-list">
-        <h2>{text.sessionHistory}</h2>
         {selectedRepo ? <ul>
           {sessions.length === 0
             ? <li><button className="surface-link active" type="button"><span className="surface-icon" aria-hidden="true"><FiHash /></span><span className="surface-copy"><strong>{selectedRepo.name}</strong><small>No OpenCode sessions found for this repo yet.</small></span><em>{text.planned}</em></button></li>
-            : sessions.map((session, index) => <li key={session.id_ref}><button className={index === 0 ? "surface-link active" : "surface-link"} type="button"><span className="surface-icon" aria-hidden="true"><FiHash /></span><span className="surface-copy"><strong>{session.title}</strong><small>{session.updated_at}</small></span></button></li>)}
+            : sessions.map((session) => <li key={session.id_ref}><button className={activeSessionId === session.id_ref ? "surface-link active" : "surface-link"} onClick={() => setSelectedSessionId(session.id_ref)} type="button"><span className="surface-icon" aria-hidden="true"><FiHash /></span><span className="surface-copy"><strong>{session.title}</strong><small>{session.updated_at}</small></span></button></li>)}
         </ul> : <p className="empty-sidebar-state">No local repos discovered.</p>}
       </section>
       </>}
@@ -248,13 +257,11 @@ function PeopleChannelList() {
     <section aria-label="People channels">
       <div className="notice compact-notice">{text.simplexReady}</div>
       <section className="sidebar-group session-history-list">
-        <h2>{text.teams}</h2>
         <ul>
           {["aidevops", "clients", "ops"].map((team) => <li key={team}><button className="surface-link" type="button"><span className="surface-icon" aria-hidden="true"><FiHash /></span><span className="surface-copy"><strong>{team}</strong><small>SimpleX team channel placeholder</small></span></button></li>)}
         </ul>
       </section>
       <section className="sidebar-group session-history-list">
-        <h2>{text.directMessages}</h2>
         <ul>
           {["Marcus", "AI DevOps"].map((person) => <li key={person}><button className="surface-link" type="button"><span className="surface-icon" aria-hidden="true"><FiMessageSquare /></span><span className="surface-copy"><strong>{person}</strong><small>encrypted DM placeholder</small></span></button></li>)}
         </ul>

package/packages/gui-web/src/AppWorkspace.tsx

@@ -1,11 +1,11 @@
 /* jshint esversion: 11 */
 import { type ReactElement, type ReactNode, useEffect, useState } from "react";
-import { FiBell, FiChevronLeft, FiChevronRight, FiCommand, FiCpu, FiGlobe, FiHash, FiLogOut, FiMessageSquare, FiSearch, FiSettings, FiShield, FiUser } from "react-icons/fi";
+import { FiBell, FiChevronLeft, FiChevronRight, FiCommand, FiGlobe, FiHash, FiHelpCircle, FiLogOut, FiMessageSquare, FiSearch, FiSettings, FiShield, FiTerminal, FiUser } from "react-icons/fi";
 import type { GuiFileRootId, GuiStatusData } from "../../gui-shared/src";
 import { SurfaceGlyph } from "./AppNavigation";
 import type { ConversationMode, ShellMode, SurfaceId, SurfaceNavItem } from "./app-model";
 import { inventorySurfaceConfigs, text } from "./app-model";
-import { CommandPalette, commandPaletteShortcutQuery } from "./CommandPalette";
+import { CommandPalette, type CommandPaletteSelection, commandPaletteShortcutQuery } from "./CommandPalette";
 import { FileExplorerSurface } from "./FileExplorerSurface";
 import { AppsSurface, EditableInventorySurface, InstallationSurface } from "./InventorySurfaces";
 import { AiProvidersSurface, LocalReposSurface, LockedVaultGate, OverviewSurface, PlannedSurface, ProjectsSurface, SecuritySurface, VaultSurface } from "./StatusSurfaces";
@@ -16,7 +16,7 @@ const communityLinks = {
   x: "https://x.com/marcuswquinn",
 } as const;
 
-export function Workspace({ activeItem, activeSectionLabel, activeSurface, canGoBack, canGoForward, conversationMode, fileRoot, goBack, goForward, selectedLocalRepoIndex, setActiveSurface, shellMode, status }: {
+export function Workspace({ activeItem, activeSectionLabel, activeSurface, canGoBack, canGoForward, conversationMode, fileRoot, goBack, goForward, selectedLocalRepoIndex, selectedSessionId, setActiveSurface, setConversationMode, setSelectedLocalRepoIndex, setSelectedSessionId, setShellMode, shellMode, status }: {
   activeItem: SurfaceNavItem;
   activeSectionLabel: string;
   activeSurface: SurfaceId;
@@ -27,23 +27,28 @@ export function Workspace({ activeItem, activeSectionLabel, activeSurface, canGo
   goBack: () => void;
   goForward: () => void;
   selectedLocalRepoIndex: number;
+  selectedSessionId: string | undefined;
   setActiveSurface: (surface: SurfaceId) => void;
+  setConversationMode: (mode: ConversationMode) => void;
+  setSelectedLocalRepoIndex: (index: number) => void;
+  setSelectedSessionId: (id: string | undefined) => void;
+  setShellMode: (mode: ShellMode) => void;
   shellMode: ShellMode;
   status: GuiStatusData;
 }) {
   return (
     <section className="app-inset" aria-label={text.workspaceLabel}>
-      <WorkspaceHeader activeItem={activeItem} activeSectionLabel={activeSectionLabel} activeSurface={activeSurface} canGoBack={canGoBack} canGoForward={canGoForward} goBack={goBack} goForward={goForward} setActiveSurface={setActiveSurface} status={status} />
+      <WorkspaceHeader activeItem={activeItem} activeSectionLabel={activeSectionLabel} activeSurface={activeSurface} canGoBack={canGoBack} canGoForward={canGoForward} goBack={goBack} goForward={goForward} setActiveSurface={setActiveSurface} setConversationMode={setConversationMode} setSelectedLocalRepoIndex={setSelectedLocalRepoIndex} setSelectedSessionId={setSelectedSessionId} setShellMode={setShellMode} status={status} />
       <div className="workspace-scroll">
         {shellMode === "sessions"
-          ? <ConversationWorkspace conversationMode={conversationMode} selectedLocalRepoIndex={selectedLocalRepoIndex} status={status} />
+          ? <ConversationWorkspace conversationMode={conversationMode} selectedLocalRepoIndex={selectedLocalRepoIndex} selectedSessionId={selectedSessionId} status={status} />
           : <SurfaceContent activeItem={activeItem} activeSurface={activeSurface} fileRoot={fileRoot} status={status} />}
       </div>
     </section>
   );
 }
 
-function WorkspaceHeader({ activeItem, activeSectionLabel, activeSurface, canGoBack, canGoForward, goBack, goForward, setActiveSurface, status }: {
+function WorkspaceHeader({ activeItem, activeSectionLabel, activeSurface, canGoBack, canGoForward, goBack, goForward, setActiveSurface, setConversationMode, setSelectedLocalRepoIndex, setSelectedSessionId, setShellMode, status }: {
   activeItem: SurfaceNavItem;
   activeSectionLabel: string;
   activeSurface: SurfaceId;
@@ -52,6 +57,10 @@ function WorkspaceHeader({ activeItem, activeSectionLabel, activeSurface, canGoB
   goBack: () => void;
   goForward: () => void;
   setActiveSurface: (surface: SurfaceId) => void;
+  setConversationMode: (mode: ConversationMode) => void;
+  setSelectedLocalRepoIndex: (index: number) => void;
+  setSelectedSessionId: (id: string | undefined) => void;
+  setShellMode: (mode: ShellMode) => void;
   status: GuiStatusData;
 }): ReactElement {
   const [assistantOpen, setAssistantOpen] = useState(false);
@@ -64,31 +73,35 @@ function WorkspaceHeader({ activeItem, activeSectionLabel, activeSurface, canGoB
 
   useEffect(() => {
     const openCommandPalette = (event: KeyboardEvent) => {
-      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
-        event.preventDefault();
-        setCommandInitialQuery("");
-        setCommandOpen(true);
-        return;
-      }
-
-      const shortcutQuery = commandPaletteShortcutQuery(event);
-      if (shortcutQuery !== undefined && !isEditableShortcutTarget(event.target)) {
-        event.preventDefault();
-        setCommandInitialQuery(shortcutQuery);
-        setCommandOpen(true);
-      }
+      handleWorkspaceShortcut(event, {
+        goBack,
+        goForward,
+        openCommand: (query) => {
+          setCommandInitialQuery(query);
+          setCommandOpen(true);
+        },
+      });
     };
 
     window.addEventListener("keydown", openCommandPalette);
     return () => window.removeEventListener("keydown", openCommandPalette);
-  }, []);
+  }, [goBack, goForward]);
 
   const closeMenus = () => {
     setNotificationsOpen(false);
     setProfileOpen(false);
   };
 
-  const openSurface = (surface: SurfaceId) => {
+  const openItem = ({ conversationMode, repoPathRef, sessionId, shellMode, surface }: CommandPaletteSelection) => {
+    const repoIndex = status.local_repos.repos.findIndex((repo) => repo.path_ref === repoPathRef);
+    setShellMode(shellMode ?? "devices");
+    if (repoIndex >= 0) {
+      setSelectedLocalRepoIndex(repoIndex);
+    }
+    setSelectedSessionId(sessionId);
+    if (conversationMode) {
+      setConversationMode(conversationMode);
+    }
     setActiveSurface(surface);
     closeMenus();
     setCommandOpen(false);
@@ -116,28 +129,45 @@ function WorkspaceHeader({ activeItem, activeSectionLabel, activeSurface, canGoB
       </div>
       <div className="header-actions">
         <div className="header-action-menu">
+          <button aria-label="Open help" className="header-icon-button" onClick={() => openItem({ surface: "help" })} title="Help (?)" type="button">
+            <FiHelpCircle aria-hidden="true" />
+          </button>
           <button aria-expanded={notificationsOpen} aria-label="Open notifications" className="header-icon-button" onClick={() => { setNotificationsOpen((current) => !current); setProfileOpen(false); }} type="button">
             <FiBell aria-hidden="true" />
             <span className="notification-dot" aria-hidden="true" />
           </button>
-          {notificationsOpen ? <NotificationsMenu openSurface={openSurface} /> : null}
+          {notificationsOpen ? <NotificationsMenu openSurface={(surface) => openItem({ surface })} /> : null}
         </div>
-        <button aria-pressed={assistantOpen} aria-label="Toggle AI Assistant" className={assistantOpen ? "header-icon-button active" : "header-icon-button"} onClick={() => setAssistantOpen((current) => !current)} type="button">
-          <FiCpu aria-hidden="true" />
+        <button aria-pressed={assistantOpen} aria-label="Toggle AI Assistant" className={assistantOpen ? "header-icon-button active" : "header-icon-button"} onClick={() => setAssistantOpen((current) => !current)} title="AI sessions (_)" type="button">
+          <FiTerminal aria-hidden="true" />
         </button>
         <div className="header-action-menu">
           <button aria-expanded={profileOpen} aria-label={`Open profile menu for ${userName}`} className="profile-avatar-button" onClick={() => { setProfileOpen((current) => !current); setNotificationsOpen(false); }} title={userName} type="button">
             <span>{userInitials}</span>
           </button>
-          {profileOpen ? <ProfileMenu openSurface={openSurface} userName={userName} /> : null}
+          {profileOpen ? <ProfileMenu openSurface={(surface) => openItem({ surface })} userName={userName} /> : null}
         </div>
       </div>
       {assistantOpen ? <AssistantPanel activeSurface={activeSurface} userName={userName} /> : null}
-      {commandOpen ? <CommandPalette close={() => setCommandOpen(false)} initialQuery={commandInitialQuery} openSurface={openSurface} status={status} /> : null}
+      {commandOpen ? <CommandPalette activeSurface={activeSurface} close={() => setCommandOpen(false)} initialQuery={commandInitialQuery} openItem={openItem} status={status} /> : null}
     </header>
   );
 }
 
+function handleWorkspaceShortcut(event: KeyboardEvent, actions: { goBack: () => void; goForward: () => void; openCommand: (query: string) => void }): void {
+  const shortcutQuery = commandPaletteShortcutQuery(event);
+  const isEditableTarget = isEditableShortcutTarget(event.target);
+  const commandQuery = (event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k" ? "" : shortcutQuery;
+
+  if (commandQuery !== undefined && !isEditableTarget) {
+    event.preventDefault();
+    actions.openCommand(commandQuery);
+  } else if (event.key === "Backspace" && !isEditableTarget) {
+    event.preventDefault();
+    (event.shiftKey ? actions.goForward : actions.goBack)();
+  }
+}
+
 function isEditableShortcutTarget(target: EventTarget | null): boolean {
   if (!(target instanceof HTMLElement)) {
     return false;
@@ -156,15 +186,16 @@ function NotificationsMenu({ openSurface }: { openSurface: (surface: SurfaceId)
   );
 }
 
-function ConversationWorkspace({ conversationMode, selectedLocalRepoIndex, status }: {
+function ConversationWorkspace({ conversationMode, selectedLocalRepoIndex, selectedSessionId, status }: {
   conversationMode: ConversationMode;
   selectedLocalRepoIndex: number;
+  selectedSessionId: string | undefined;
   status: GuiStatusData;
 }) {
   const selectedRepo = status.local_repos.repos[selectedLocalRepoIndex] ?? status.local_repos.repos[0];
   const selectedSession = selectedRepo === undefined
     ? undefined
-    : status.opencode_sessions.sessions.find((session) => session.repo_path_ref === selectedRepo.path_ref);
+    : status.opencode_sessions.sessions.find((session) => session.id_ref === selectedSessionId && session.repo_path_ref === selectedRepo.path_ref) ?? status.opencode_sessions.sessions.find((session) => session.repo_path_ref === selectedRepo.path_ref);
   const title = conversationMode === "ai" ? selectedRepo?.name ?? text.opencodeSessions : text.teams;
 
   return (
@@ -247,6 +278,7 @@ function SurfaceContent({ activeItem, activeSurface, fileRoot, status }: {
   const vaultCollection = vaultCollectionForSurface(status.vault, activeSurface);
   const staticSurfaces: Partial<Record<SurfaceId, ReactNode>> = {
     overview: <OverviewSurface status={status} />,
+    help: <HelpSurface />,
     settings: <SettingsSurface status={status} />,
     notifications: <NotificationsSurface />,
     admin: <AdminSurface />,
@@ -274,7 +306,7 @@ function SurfaceContent({ activeItem, activeSurface, fileRoot, status }: {
     maintenance: <PlannedSurface label={text.maintenance} detail={text.projectWorkIntro} />,
     performance: <PlannedSurface label={text.performance} detail={text.projectWorkIntro} />,
     reports: <PlannedSurface label={text.reports} detail={text.projectWorkIntro} />,
-    apps: <AppsSurface />,
+    apps: <AppsSurface status={status} />,
     installation: <InstallationSurface />,
     projects: <ProjectsSurface status={status} />,
     security: <SecuritySurface status={status} />,
@@ -300,6 +332,40 @@ function SurfaceContent({ activeItem, activeSurface, fileRoot, status }: {
   return staticSurfaces[activeSurface] ?? null;
 }
 
+function HelpSurface(): ReactElement {
+  const shortcuts = [
+    ["#", "Channels"],
+    ["_", "AI sessions"],
+    ["&", "Infrastructure"],
+    ["?", "Help"],
+    [">", "New terminal command"],
+    ["+", "Add commands"],
+    ["-", "Remove commands"],
+    ["/", "Slash commands"],
+    ["=", "Comms"],
+    ["~", "Settings and config"],
+    ["!", "Notifications"],
+    [".", "Agents"],
+    ["*", "Secrets and passwords"],
+    [":", "Emoji picker"],
+    ["^", "Copy current page link"],
+  ];
+
+  return (
+    <section className="settings-surface help-surface">
+      <div className="planned-card">
+        <h2>Help</h2>
+        <p>Use the command palette shortcuts from anywhere outside text inputs. Recent selections appear first until you keep typing to filter.</p>
+      </div>
+      <ul className="shortcut-list">
+        {shortcuts.map(([shortcut, label]) => <li key={shortcut}><kbd>{shortcut}</kbd><span>{label}</span></li>)}
+        <li><kbd>Backspace</kbd><span>Previous page</span></li>
+        <li><kbd>Shift Backspace</kbd><span>Next page</span></li>
+      </ul>
+    </section>
+  );
+}
+
 function SettingsSurface({ status }: { status: GuiStatusData }): ReactElement {
   return (
     <section className="settings-surface">