From 0e12c3492e99e72cde7c7b392f367b779701fb8c Mon Sep 17 00:00:00 2001
From: Benjamin Shafii <ben@prologe.io>
Date: Mon, 4 May 2026 12:21:39 -0700
Subject: [PATCH 1/4] feat: expose UI control MCP bridge

---
 AGENTS.md                                     |   1 +
 ARCHITECTURE.md                               |  36 ++
 .../domains/session/chat/status-bar.tsx       |  39 +-
 .../control/session-control-actions.ts        | 171 +++++++
 .../session/surface/session-surface.tsx       | 186 +++++++-
 apps/app/src/react-app/shell/app-root.tsx     | 100 +++--
 .../shell/control/control-provider.tsx        | 420 ++++++++++++++++++
 .../app/src/react-app/shell/session-route.tsx |  27 ++
 apps/desktop/electron/main.mjs                | 146 +++++-
 docs/mcp-ui-control-profile.md                | 142 ++++++
 packages/openwork-ui-mcp/index.mjs            | 180 ++++++++
 packages/openwork-ui-mcp/package.json         |  16 +
 pnpm-lock.yaml                                |  49 +-
 13 files changed, 1421 insertions(+), 92 deletions(-)
 create mode 100644 apps/app/src/react-app/domains/session/control/session-control-actions.ts
 create mode 100644 apps/app/src/react-app/shell/control/control-provider.tsx
 create mode 100644 docs/mcp-ui-control-profile.md
 create mode 100644 packages/openwork-ui-mcp/index.mjs
 create mode 100644 packages/openwork-ui-mcp/package.json

diff --git a/AGENTS.md b/AGENTS.md
index c80b2be216..9958c15e2b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -57,6 +57,7 @@ Read `ARCHITECTURE.md` for runtime flow, server-vs-shell ownership, and architec
 * **Open source**: keep the repo portable; no secrets committed.
 * **Slick and fluid**: 60fps animations, micro-interactions, premium feel.
 * **Mobile-native**: touch targets, gestures, and layouts optimized for small screens.
+* **Provider-neutral control**: expose app actions through OpenWork-owned control surfaces first; provider-specific controllers should drive those surfaces rather than hardwiring provider logic into the app UI.
 
 ## Task Intake (Required)
 
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 81d6dd1d61..ab75b712c0 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -200,6 +200,42 @@ These are all opencode primitives you can read the docs to find out exactly how
 
 OpenWork is a client experience that consumes OpenWork server surfaces.
 
+### Provider-neutral app control surface
+
+OpenWork app control mode is owned by the UI runtime. The app exposes a
+provider-neutral action registry through `window.__openworkControl` so external
+controllers can inspect the current route, discover visible/safe actions, and
+request an action by ID without depending on DOM scraping or a specific model
+provider.
+
+Guidelines:
+
+- The app owns visible, screen-local state: which actions are available, which
+  element should be spotlighted, and how actions are choreographed so users can
+  see control happen.
+- Controllers such as MCP bridges, test harnesses, or optional external drivers should
+  call the app control surface instead of reaching into app internals.
+- Provider/API secrets and privileged filesystem or server mutations remain
+  server-owned; the app control surface should route those through OpenWork
+  server APIs rather than adding provider-specific behavior to the UI.
+- Raw screenshot or coordinate-based control is a fallback for uninstrumented
+  surfaces, not the default architecture.
+
+### MCP UI Control profile
+
+OpenWork should standardize external app control through MCP where possible. The
+app-local `window.__openworkControl` registry remains the source of current UI
+affordances, but public integrations should expose those affordances as MCP
+tools that follow `docs/mcp-ui-control-profile.md`:
+
+- `ui.snapshot` for current semantic app state
+- `ui.list_actions` for currently available action metadata and input schemas
+- `ui.execute_action` for running one semantic action by ID
+
+Standalone control clients such as HandsFree should be MCP clients first: they
+can connect to any configured MCP server and call generic MCP tools. OpenWork's
+local UI bridge is an implementation detail behind the OpenWork MCP surface.
+
 OpenWork supports two product runtime modes for users:
 
 - desktop
diff --git a/apps/app/src/react-app/domains/session/chat/status-bar.tsx b/apps/app/src/react-app/domains/session/chat/status-bar.tsx
index ce97a3ceb2..f4521e36a9 100644
--- a/apps/app/src/react-app/domains/session/chat/status-bar.tsx
+++ b/apps/app/src/react-app/domains/session/chat/status-bar.tsx
@@ -1,9 +1,10 @@
 /** @jsxImportSource react */
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { BookOpen, MessageCircle, Settings } from "lucide-react";
 
 import { t } from "../../../../i18n";
 import { usePlatform } from "../../../kernel/platform";
+import { useControlAction, type OpenworkControlAction } from "../../../shell/control/control-provider";
 import type { OpenworkServerStatus } from "../../../../app/lib/openwork-server";
 
 const DOCS_URL = "https://openworklabs.com/docs";
@@ -103,6 +104,9 @@ function deriveStatusCopy(props: StatusBarProps): StatusCopy {
 
 export function StatusBar(props: StatusBarProps) {
   const platform = usePlatform();
+  const docsButtonRef = useRef<HTMLButtonElement>(null);
+  const feedbackButtonRef = useRef<HTMLButtonElement>(null);
+  const settingsButtonRef = useRef<HTMLButtonElement>(null);
   const [initializing, setInitializing] = useState(
     () => Date.now() - STATUS_BAR_BOOT_STARTED_AT < STATUS_BAR_INITIALIZING_MS,
   );
@@ -118,6 +122,36 @@ export function StatusBar(props: StatusBarProps) {
   }, [initializing]);
 
   const statusCopy = deriveStatusCopy({ ...props, initializing });
+  const docsControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "status.docs.open",
+    label: "Open OpenWork docs",
+    description: "Open the documentation from the status bar.",
+    sideEffect: "external",
+    targetRef: docsButtonRef,
+    execute: () => platform.openLink(DOCS_URL),
+  }), [platform]);
+  useControlAction(docsControlAction);
+
+  const feedbackControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "status.feedback.open",
+    label: "Send feedback",
+    description: "Open the OpenWork feedback surface from the status bar.",
+    sideEffect: "external",
+    targetRef: feedbackButtonRef,
+    execute: props.onSendFeedback,
+  }), [props.onSendFeedback]);
+  useControlAction(feedbackControlAction);
+
+  const settingsControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "status.settings.open",
+    label: props.settingsOpen ? "Go back from settings" : "Open settings from the status bar",
+    description: "Use the visible settings button in the status bar.",
+    sideEffect: "navigation",
+    disabled: props.showSettingsButton === false,
+    targetRef: settingsButtonRef,
+    execute: props.onOpenSettings,
+  }), [props.onOpenSettings, props.settingsOpen, props.showSettingsButton]);
+  useControlAction(settingsControlAction);
 
   return (
     <div className="border-t border-dls-border bg-dls-surface">
@@ -143,6 +177,7 @@ export function StatusBar(props: StatusBarProps) {
 
         <div className="flex items-center gap-1.5">
           <button
+            ref={docsButtonRef}
             type="button"
             className="inline-flex h-8 items-center gap-1.5 rounded-md px-2 text-dls-secondary transition-colors hover:bg-dls-hover hover:text-dls-text"
             onClick={() => platform.openLink(DOCS_URL)}
@@ -153,6 +188,7 @@ export function StatusBar(props: StatusBarProps) {
             <span className="text-[11px] font-medium">{t("status.docs")}</span>
           </button>
           <button
+            ref={feedbackButtonRef}
             type="button"
             className="inline-flex h-8 items-center gap-1.5 rounded-md px-2 text-dls-secondary transition-colors hover:bg-dls-hover hover:text-dls-text"
             onClick={props.onSendFeedback}
@@ -166,6 +202,7 @@ export function StatusBar(props: StatusBarProps) {
           </button>
           {props.showSettingsButton !== false ? (
             <button
+              ref={settingsButtonRef}
               type="button"
               className="flex h-8 w-8 shrink-0 items-center justify-center rounded-md text-dls-secondary transition-colors hover:bg-dls-hover hover:text-dls-text"
               onClick={props.onOpenSettings}
diff --git a/apps/app/src/react-app/domains/session/control/session-control-actions.ts b/apps/app/src/react-app/domains/session/control/session-control-actions.ts
new file mode 100644
index 0000000000..1783574350
--- /dev/null
+++ b/apps/app/src/react-app/domains/session/control/session-control-actions.ts
@@ -0,0 +1,171 @@
+/** @jsxImportSource react */
+import { useMemo } from "react";
+
+import type { createClient } from "../../../../app/lib/opencode";
+import type { OpenworkServerClient, OpenworkWorkspaceInfo } from "../../../../app/lib/openwork-server";
+import { getDisplaySessionTitle } from "../../../../app/lib/session-title";
+import { useControlAction, type OpenworkControlAction } from "../../../shell/control/control-provider";
+
+type SessionLike = {
+  id?: string;
+  title?: string;
+  time?: {
+    updated?: number;
+    created?: number;
+  };
+};
+
+type SessionControlWorkspace = OpenworkWorkspaceInfo & {
+  displayNameResolved?: string;
+};
+
+type UseSessionControlActionsInput = {
+  workspaces: SessionControlWorkspace[];
+  sessionsByWorkspaceId: Record<string, SessionLike[]>;
+  selectedWorkspaceId: string;
+  selectedWorkspaceRoot: string;
+  selectedSessionId: string | null;
+  canCreateTask: boolean;
+  openworkClient: OpenworkServerClient | null;
+  opencodeClient: ReturnType<typeof createClient> | null;
+  navigateToSession: (sessionId: string) => void;
+  navigateToSessionRoot: () => void;
+  createTaskInWorkspace: (workspaceId: string) => Promise<unknown> | unknown;
+  openModelPicker: () => void;
+  refreshRouteState: () => Promise<unknown> | unknown;
+};
+
+function workspaceLabel(workspace: SessionControlWorkspace) {
+  return workspace.displayName?.trim() || workspace.name?.trim() || workspace.path?.trim() || "workspace";
+}
+
+function findSessionWorkspace(
+  workspaces: SessionControlWorkspace[],
+  sessionsByWorkspaceId: Record<string, SessionLike[]>,
+  sessionId: string,
+) {
+  return workspaces.find((workspace) => (
+    sessionsByWorkspaceId[workspace.id] ?? []
+  ).some((session) => session.id === sessionId));
+}
+
+export function useSessionControlActions(input: UseSessionControlActionsInput) {
+  const createTaskControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "session.create_task",
+    label: "Create a new task",
+    description: "Create a new session in the selected workspace.",
+    sideEffect: "mutation",
+    disabled: !input.canCreateTask || !input.selectedWorkspaceId,
+    execute: async () => {
+      if (!input.selectedWorkspaceId) return false;
+      await input.createTaskInWorkspace(input.selectedWorkspaceId);
+      return true;
+    },
+  }), [input]);
+  useControlAction(createTaskControlAction);
+
+  const listSessionsControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "session.list_sessions",
+    label: "List available sessions",
+    description: "Return the list of sessions across workspaces so the user can ask to open one by name.",
+    sideEffect: "none",
+    execute: () => {
+      const out: { sessionId: string; title: string; workspace: string; updatedAt: number }[] = [];
+      for (const workspace of input.workspaces) {
+        const list = input.sessionsByWorkspaceId[workspace.id] ?? [];
+        for (const session of list) {
+          const sessionId = session.id?.trim() ?? "";
+          if (!sessionId) continue;
+          const title = getDisplaySessionTitle(session.title ?? "");
+          const updatedAt = session.time?.updated ?? session.time?.created ?? 0;
+          out.push({ sessionId, title, workspace: workspaceLabel(workspace), updatedAt });
+        }
+      }
+      out.sort((a, b) => b.updatedAt - a.updatedAt);
+      return out.slice(0, 30);
+    },
+  }), [input]);
+  useControlAction(listSessionsControlAction);
+
+  const openSessionControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "session.open",
+    label: "Open a session by ID",
+    description: "Navigate to a specific session. Use list_sessions first to get the session ID.",
+    sideEffect: "navigation",
+    requiresArgs: true,
+    execute: (args) => {
+      const sessionId = typeof args === "object" && args && "sessionId" in args && typeof (args as { sessionId?: unknown }).sessionId === "string"
+        ? (args as { sessionId: string }).sessionId.trim()
+        : "";
+      if (!sessionId) return { ok: false, error: "sessionId is required" };
+      input.navigateToSession(sessionId);
+      return { ok: true, navigatedTo: sessionId };
+    },
+  }), [input]);
+  useControlAction(openSessionControlAction);
+
+  const renameSessionControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "session.rename",
+    label: "Rename a session",
+    description: "Rename a session by ID. Use list_sessions first to match the title the user said.",
+    sideEffect: "mutation",
+    requiresArgs: true,
+    disabled: !input.opencodeClient,
+    execute: async (args) => {
+      const payload = args && typeof args === "object" ? args as { sessionId?: unknown; title?: unknown } : {};
+      const sessionId = typeof payload.sessionId === "string" ? payload.sessionId.trim() : "";
+      const title = typeof payload.title === "string" ? payload.title.trim() : "";
+      if (!sessionId) return { ok: false, error: "sessionId is required" };
+      if (!title) return { ok: false, error: "title is required" };
+      if (!input.opencodeClient) return { ok: false, error: "OpenCode client is not connected" };
+
+      const targetWorkspace = findSessionWorkspace(input.workspaces, input.sessionsByWorkspaceId, sessionId);
+      await input.opencodeClient.session.update({
+        sessionID: sessionId,
+        title,
+        directory: targetWorkspace?.path || input.selectedWorkspaceRoot || undefined,
+      });
+      await input.refreshRouteState();
+      return { ok: true, sessionId, title };
+    },
+  }), [input]);
+  useControlAction(renameSessionControlAction);
+
+  const deleteSessionControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "session.delete",
+    label: "Delete a session",
+    description: "Delete a session by ID. Destructive: only run after explicit user confirmation.",
+    sideEffect: "mutation",
+    requiresArgs: true,
+    requiresConfirmation: true,
+    disabled: !input.openworkClient,
+    execute: async (args) => {
+      const payload = args && typeof args === "object" ? args as { sessionId?: unknown; confirmed?: unknown } : {};
+      const sessionId = typeof payload.sessionId === "string" ? payload.sessionId.trim() : "";
+      const confirmed = payload.confirmed === true;
+      if (!sessionId) return { ok: false, error: "sessionId is required" };
+      if (!confirmed) return { ok: false, error: "Deletion requires confirmed: true after explicit user confirmation" };
+      if (!input.openworkClient) return { ok: false, error: "OpenWork server is not connected" };
+
+      const targetWorkspace = findSessionWorkspace(input.workspaces, input.sessionsByWorkspaceId, sessionId);
+      if (!targetWorkspace) return { ok: false, error: "Session was not found in the current session list" };
+      await input.openworkClient.deleteSession(targetWorkspace.id, sessionId);
+      if (input.selectedSessionId === sessionId) {
+        input.navigateToSessionRoot();
+      }
+      await input.refreshRouteState();
+      return { ok: true, sessionId, deleted: true };
+    },
+  }), [input]);
+  useControlAction(deleteSessionControlAction);
+
+  const modelPickerControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "session.model_picker.open",
+    label: "Open the model picker",
+    description: "Open the current session model picker.",
+    sideEffect: "none",
+    disabled: !input.selectedWorkspaceId,
+    execute: input.openModelPicker,
+  }), [input]);
+  useControlAction(modelPickerControlAction);
+}
diff --git a/apps/app/src/react-app/domains/session/surface/session-surface.tsx b/apps/app/src/react-app/domains/session/surface/session-surface.tsx
index 8b4aa2e37a..eeb7e114de 100644
--- a/apps/app/src/react-app/domains/session/surface/session-surface.tsx
+++ b/apps/app/src/react-app/domains/session/surface/session-surface.tsx
@@ -23,6 +23,7 @@ import {
   publishInspectorSlice,
   recordInspectorEvent,
 } from "../../../shell/app-inspector";
+import { useControlAction, type OpenworkControlAction } from "../../../shell/control/control-provider";
 import { getReactQueryClient } from "../../../infra/query-client";
 import { ReactSessionComposer } from "./composer/composer";
 import { DevProfiler } from "../../../shell/dev-profiler";
@@ -84,24 +85,26 @@ export type SessionSurfaceProps = {
   onOpenSettingsSection?: ((section: "commands" | "skills" | "mcps" | "plugins") => void) | undefined;
 };
 
+function messageToReadableText(message: UIMessage) {
+  const header = message.role === "user" ? "You" : message.role === "assistant" ? "OpenWork" : message.role;
+  const body = message.parts
+    .flatMap((part) => {
+      if (part.type === "text") return [part.text];
+      if (part.type === "reasoning") return [part.text];
+      if (part.type === "dynamic-tool") {
+        if (part.state === "output-error") return [`[tool:${part.toolName}] ${part.errorText}`];
+        if (part.state === "output-available") return [`[tool:${part.toolName}] ${JSON.stringify(part.output)}`];
+        return [`[tool:${part.toolName}] ${JSON.stringify(part.input)}`];
+      }
+      return [];
+    })
+    .join("\n\n");
+  return `${header}\n${body}`.trim();
+}
+
 function transcriptToText(messages: UIMessage[]) {
   return messages
-    .map((message) => {
-      const header = message.role === "user" ? "You" : message.role === "assistant" ? "OpenWork" : message.role;
-      const body = message.parts
-        .flatMap((part) => {
-          if (part.type === "text") return [part.text];
-          if (part.type === "reasoning") return [part.text];
-          if (part.type === "dynamic-tool") {
-            if (part.state === "output-error") return [`[tool:${part.toolName}] ${part.errorText}`];
-            if (part.state === "output-available") return [`[tool:${part.toolName}] ${JSON.stringify(part.output)}`];
-            return [`[tool:${part.toolName}] ${JSON.stringify(part.input)}`];
-          }
-          return [];
-        })
-        .join("\n\n");
-      return `${header}\n${body}`.trim();
-    })
+    .map(messageToReadableText)
     .filter(Boolean)
     .join("\n\n---\n\n");
 }
@@ -113,6 +116,17 @@ function statusLabel(snapshot: OpenworkSessionSnapshot | undefined, busy: boolea
   return "Ready";
 }
 
+function controlTextArgument(args: unknown, fallback: string) {
+  if (typeof args === "string") return args;
+  if (args && typeof args === "object" && "text" in args) {
+    const text = (args as { text?: unknown }).text;
+    if (typeof text === "string") return text;
+  }
+  return fallback;
+}
+
+const waitForControl = (ms: number) => new Promise((resolve) => window.setTimeout(resolve, ms));
+
 function useSharedQueryState<T>(queryKey: readonly unknown[], fallback: T) {
   const queryClient = getReactQueryClient();
   // useSyncExternalStore requires getSnapshot to return the same reference
@@ -246,6 +260,7 @@ export function SessionSurface(props: SessionSurfaceProps) {
   const [toolMcpStatus, setToolMcpStatus] = useState<string | null>(null);
   const [toolMcpStatuses, setToolMcpStatuses] = useState<McpStatusMap>({});
   const [toolImportedPlugins, setToolImportedPlugins] = useState<CloudImportedPlugin[]>([]);
+  const composerShellRef = useRef<HTMLDivElement>(null);
   const hydratedKeyRef = useRef<string | null>(null);
   const attachmentsRef = useRef<ComposerAttachment[]>([]);
   attachmentsRef.current = attachments;
@@ -473,7 +488,7 @@ export function SessionSurface(props: SessionSurfaceProps) {
     }
   };
 
-  const handleSend = async () => {
+  const handleSend = useCallback(async () => {
     const text = draft.trim();
     if (!text && attachments.length === 0) return;
     // Intentionally allow sending while the assistant is still streaming.
@@ -499,9 +514,9 @@ export function SessionSurface(props: SessionSurfaceProps) {
       setAwaitingAssistantBaseline(null);
       setSending(false);
     }
-  };
+  }, [attachments, buildDraft, draft, props.onDraftChange, props.onSendDraft, renderedMessages.length]);
 
-  const handleAbort = async () => {
+  const handleAbort = useCallback(async () => {
     if (!chatStreaming) return;
     setError(null);
     try {
@@ -510,7 +525,7 @@ export function SessionSurface(props: SessionSurfaceProps) {
     } catch (nextError) {
       setError({ message: nextError instanceof Error ? nextError.message : "Failed to stop run." });
     }
-  };
+  }, [chatStreaming, opencodeClient, props.sessionId, snapshotQuery.refetch]);
 
   useEffect(() => {
     if (liveStatus.type === "idle") {
@@ -599,6 +614,63 @@ export function SessionSurface(props: SessionSurfaceProps) {
     setDraft((current) => `${current}${current && !current.endsWith("\n") ? "\n" : ""}${links.join("\n")}`);
   };
 
+  const typeComposerText = useCallback(async (text: string) => {
+    window.dispatchEvent(new Event("openwork:focusPrompt"));
+    setDraft("");
+    let next = "";
+    for (const char of text) {
+      next += char;
+      setDraft(next);
+      await waitForControl(char === "\n" ? 80 : 18);
+    }
+  }, []);
+
+  const composerSetTextControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "composer.set_text",
+    label: "Type into the composer",
+    description: "Replace the current session draft and type the supplied text visibly.",
+    sideEffect: "none",
+    requiresArgs: true,
+    previewArgs: { text: "Help me outline the next OpenWork task." },
+    targetRef: composerShellRef,
+    execute: async (args, helpers) => {
+      const text = controlTextArgument(args, "Help me outline the next OpenWork task.");
+      helpers.setNarration(`Typing ${text.length.toLocaleString()} characters into the composer…`);
+      await typeComposerText(text);
+      props.onDraftChange(buildDraft(text, attachments));
+      return { draftLength: text.length };
+    },
+  }), [attachments, buildDraft, props.onDraftChange, typeComposerText]);
+  useControlAction(composerSetTextControlAction);
+
+  const composerSendControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "composer.send",
+    label: "Send the composer prompt",
+    description: "Send the currently visible composer draft to the active session.",
+    sideEffect: "mutation",
+    disabled: (!draft.trim() && attachments.length === 0) || model.transitionState !== "idle",
+    targetRef: composerShellRef,
+    execute: async () => {
+      await handleSend();
+      return true;
+    },
+  }), [attachments.length, draft, handleSend, model.transitionState]);
+  useControlAction(composerSendControlAction);
+
+  const composerStopControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "composer.stop",
+    label: "Stop the current run",
+    description: "Stop the current streaming session run.",
+    sideEffect: "mutation",
+    disabled: !chatStreaming,
+    targetRef: composerShellRef,
+    execute: async () => {
+      await handleAbort();
+      return true;
+    },
+  }), [chatStreaming, handleAbort]);
+  useControlAction(composerStopControlAction);
+
   const listSkills = async (): Promise<SkillCard[]> => {
     const response = await props.client.listSkills(props.workspaceId, { includeGlobal: true });
     const next = (response.items ?? []).map((skill) => ({
@@ -674,6 +746,78 @@ export function SessionSurface(props: SessionSurfaceProps) {
     contentRef,
   });
 
+  const sessionScrollTopControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "session.scroll_top",
+    label: "Go to the top of the session",
+    description: "Scroll the visible session transcript to the first messages.",
+    sideEffect: "none",
+    execute: () => {
+      const container = scrollRef.current;
+      if (!container) return { ok: false, error: "Session transcript is not mounted" };
+      container.scrollTo({ top: 0, behavior: "smooth" });
+      return { ok: true, position: "top" };
+    },
+  }), []);
+  useControlAction(sessionScrollTopControlAction);
+
+  const sessionScrollBottomControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "session.scroll_bottom",
+    label: "Go to the bottom of the session",
+    description: "Scroll the visible session transcript to the newest messages and composer area.",
+    sideEffect: "none",
+    execute: () => {
+      sessionScroll.jumpToLatest("smooth");
+      return { ok: true, position: "bottom" };
+    },
+  }), [sessionScroll.jumpToLatest]);
+  useControlAction(sessionScrollBottomControlAction);
+
+  const sessionLatestMessageControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "session.latest_message",
+    label: "Read the latest session message",
+    description: "Return the latest visible message in the current session transcript.",
+    sideEffect: "none",
+    execute: () => {
+      const message = renderedMessages[renderedMessages.length - 1];
+      if (!message) return { ok: false, error: "No messages are visible in this session" };
+      return {
+        ok: true,
+        sessionId: props.sessionId,
+        index: renderedMessages.length - 1,
+        role: message.role,
+        text: messageToReadableText(message),
+      };
+    },
+  }), [props.sessionId, renderedMessages]);
+  useControlAction(sessionLatestMessageControlAction);
+
+  const sessionReadTranscriptControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "session.read_transcript",
+    label: "Read the current session transcript",
+    description: "Return the last messages from the current session transcript as readable text, including the session ID, title, and message count.",
+    sideEffect: "none",
+    execute: (args) => {
+      const count = typeof args === "object" && args !== null && "count" in args && typeof (args as { count?: unknown }).count === "number"
+        ? Math.min(Math.max(1, (args as { count: number }).count), 30)
+        : 10;
+      const total = renderedMessages.length;
+      const slice = renderedMessages.slice(-count);
+      if (!slice.length) return { ok: false, error: "No messages in this session" };
+      return {
+        ok: true,
+        sessionId: props.sessionId,
+        messageCount: total,
+        returned: slice.length,
+        messages: slice.map((message, index) => ({
+          index: total - slice.length + index,
+          role: message.role,
+          text: messageToReadableText(message),
+        })),
+      };
+    },
+  }), [props.sessionId, renderedMessages]);
+  useControlAction(sessionReadTranscriptControlAction);
+
   return (
     <DevProfiler id="SessionSurface">
     <div className="flex h-full min-h-0 flex-col">
@@ -794,7 +938,7 @@ export function SessionSurface(props: SessionSurfaceProps) {
         ) : null}
       </div>
 
-      <div className="shrink-0 border-t border-dls-border/70 px-0 pb-3 pt-3">
+      <div ref={composerShellRef} className="shrink-0 border-t border-dls-border/70 px-0 pb-3 pt-3">
         <DevProfiler id="SessionComposer">
         <ReactSessionComposer
           draft={draft}
diff --git a/apps/app/src/react-app/shell/app-root.tsx b/apps/app/src/react-app/shell/app-root.tsx
index 50dcfab091..b831de9cb5 100644
--- a/apps/app/src/react-app/shell/app-root.tsx
+++ b/apps/app/src/react-app/shell/app-root.tsx
@@ -11,6 +11,7 @@ import { useDesktopFontZoomBehavior } from "./font-zoom";
 import { LoadingOverlay } from "./loading-overlay";
 import { DevProfiler, DevProfilerOverlay } from "./dev-profiler";
 import { ReactRenderWatchdogOverlay } from "./react-render-watchdog-overlay";
+import { OpenworkControlProvider, OpenworkRouteControlActions } from "./control/control-provider";
 import { SessionRoute } from "./session-route";
 import { SettingsRoute } from "./settings-route";
 import { WelcomeRoute } from "./welcome-route";
@@ -92,54 +93,57 @@ export function AppRoot() {
   return (
     <>
       <DevProfiler id="AppRoot">
-        <DenSigninGate>
-          <Routes>
-            <Route
-              path="/signin"
-              element={
-                <DevProfiler id="SigninRoute">
-                  <ForcedSigninPage developerMode={false} />
-                </DevProfiler>
-              }
-            />
-            <Route
-              path="/welcome"
-              element={
-                <DevProfiler id="WelcomeRoute">
-                  <WelcomeRoute />
-                </DevProfiler>
-              }
-            />
-            <Route
-              path="/session"
-              element={
-                <DevProfiler id="SessionRoute">
-                  <SessionRoute />
-                </DevProfiler>
-              }
-            />
-            <Route
-              path="/session/:sessionId"
-              element={
-                <DevProfiler id="SessionRoute">
-                  <SessionRoute />
-                </DevProfiler>
-              }
-            />
-            <Route
-              path="/settings/*"
-              element={
-                <DevProfiler id="SettingsRoute">
-                  <SettingsRoute />
-                </DevProfiler>
-              }
-            />
-            {/* Default + fallback: land on the session view. Users open
-                settings deliberately via the sidebar or command palette. */}
-            <Route path="/" element={<Navigate to="/session" replace />} />
-            <Route path="*" element={<Navigate to="/session" replace />} />
-          </Routes>
-        </DenSigninGate>
+        <OpenworkControlProvider>
+          <OpenworkRouteControlActions />
+          <DenSigninGate>
+            <Routes>
+              <Route
+                path="/signin"
+                element={
+                  <DevProfiler id="SigninRoute">
+                    <ForcedSigninPage developerMode={false} />
+                  </DevProfiler>
+                }
+              />
+              <Route
+                path="/welcome"
+                element={
+                  <DevProfiler id="WelcomeRoute">
+                    <WelcomeRoute />
+                  </DevProfiler>
+                }
+              />
+              <Route
+                path="/session"
+                element={
+                  <DevProfiler id="SessionRoute">
+                    <SessionRoute />
+                  </DevProfiler>
+                }
+              />
+              <Route
+                path="/session/:sessionId"
+                element={
+                  <DevProfiler id="SessionRoute">
+                    <SessionRoute />
+                  </DevProfiler>
+                }
+              />
+              <Route
+                path="/settings/*"
+                element={
+                  <DevProfiler id="SettingsRoute">
+                    <SettingsRoute />
+                  </DevProfiler>
+                }
+              />
+              {/* Default + fallback: land on the session view. Users open
+                  settings deliberately via the sidebar or command palette. */}
+              <Route path="/" element={<Navigate to="/session" replace />} />
+              <Route path="*" element={<Navigate to="/session" replace />} />
+            </Routes>
+          </DenSigninGate>
+        </OpenworkControlProvider>
         <LoadingOverlay />
       </DevProfiler>
       {/*
diff --git a/apps/app/src/react-app/shell/control/control-provider.tsx b/apps/app/src/react-app/shell/control/control-provider.tsx
new file mode 100644
index 0000000000..a3924cc541
--- /dev/null
+++ b/apps/app/src/react-app/shell/control/control-provider.tsx
@@ -0,0 +1,420 @@
+/** @jsxImportSource react */
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { useLocation, useNavigate } from "react-router-dom";
+
+export type OpenworkControlSideEffect = "none" | "navigation" | "mutation" | "external";
+
+export type OpenworkControlActionMetadata = {
+  id: string;
+  label: string;
+  description?: string;
+  sideEffect: OpenworkControlSideEffect;
+  requiresConfirmation: boolean;
+  requiresArgs: boolean;
+  hasPreviewArgs: boolean;
+  disabled: boolean;
+  busy: boolean;
+};
+
+export type OpenworkControlSnapshot = {
+  version: number;
+  enabled: boolean;
+  route: string;
+  status: "off" | "ready" | "acting";
+  busyActionId: string | null;
+  narration: string;
+  actions: OpenworkControlActionMetadata[];
+};
+
+export type OpenworkControlResult =
+  | { ok: true; actionId: string; result?: unknown }
+  | { ok: false; actionId: string; error: string };
+
+export type OpenworkControlHelpers = {
+  setNarration: (text: string) => void;
+};
+
+export type OpenworkControlTargetRef = {
+  readonly current: HTMLElement | null;
+};
+
+export type OpenworkControlAction = {
+  id: string;
+  label: string;
+  description?: string;
+  sideEffect?: OpenworkControlSideEffect;
+  requiresConfirmation?: boolean;
+  requiresArgs?: boolean;
+  previewArgs?: unknown;
+  disabled?: boolean;
+  targetRef?: OpenworkControlTargetRef;
+  execute: (args: unknown, helpers: OpenworkControlHelpers) => unknown | Promise<unknown>;
+};
+
+type RegisteredAction = OpenworkControlAction & {
+  order: number;
+  token: symbol;
+};
+
+type SpotlightState = {
+  visible: boolean;
+  phase: "target" | "press";
+  rect: { x: number; y: number; width: number; height: number } | null;
+};
+
+type OpenworkControlContextValue = {
+  enabled: boolean;
+  setEnabled: (enabled: boolean) => void;
+  route: string;
+  narration: string;
+  busyActionId: string | null;
+  actions: OpenworkControlActionMetadata[];
+  registerAction: (action: OpenworkControlAction) => () => void;
+  executeAction: (actionId: string, args?: unknown) => Promise<OpenworkControlResult>;
+  snapshot: () => OpenworkControlSnapshot;
+};
+
+type OpenworkControlAPI = {
+  version: number;
+  snapshot: () => OpenworkControlSnapshot;
+  listActions: () => OpenworkControlActionMetadata[];
+  execute: (actionId: string, args?: unknown) => Promise<OpenworkControlResult>;
+  setEnabled: (enabled: boolean) => void;
+  subscribe: (listener: (snapshot: OpenworkControlSnapshot) => void) => () => void;
+};
+
+declare global {
+  interface Window {
+    __openworkControl?: OpenworkControlAPI;
+  }
+}
+
+const CONTROL_API_VERSION = 1;
+const OpenworkControlContext = createContext<OpenworkControlContextValue | null>(null);
+
+const wait = (ms: number) => new Promise((resolve) => window.setTimeout(resolve, ms));
+
+function describeError(error: unknown) {
+  return error instanceof Error ? error.message : String(error || "Unknown error");
+}
+
+function isBrowser() {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
+
+function metadataForAction(action: RegisteredAction, busyActionId: string | null): OpenworkControlActionMetadata {
+  return {
+    id: action.id,
+    label: action.label,
+    description: action.description,
+    sideEffect: action.sideEffect ?? "none",
+    requiresConfirmation: action.requiresConfirmation === true,
+    requiresArgs: action.requiresArgs === true,
+    hasPreviewArgs: action.previewArgs !== undefined,
+    disabled: action.disabled === true,
+    busy: busyActionId === action.id,
+  };
+}
+
+function ControlModeSpotlight({ spotlight }: { spotlight: SpotlightState }) {
+  const rect = spotlight.rect;
+  if (!spotlight.visible || !rect) return null;
+
+  const pad = spotlight.phase === "press" ? 8 : 12;
+  return (
+    <div
+      className="pointer-events-none fixed z-[9998] rounded-[18px] bg-[rgba(var(--dls-accent-rgb),0.1)] shadow-[0_0_0_9999px_rgba(7,10,18,0.08),0_0_36px_rgba(var(--dls-accent-rgb),0.32),inset_0_0_0_1px_rgba(var(--dls-accent-rgb),0.24)] transition-all duration-200 ease-out"
+      style={{
+        left: `${rect.x - pad}px`,
+        top: `${rect.y - pad}px`,
+        width: `${rect.width + pad * 2}px`,
+        height: `${rect.height + pad * 2}px`,
+        transform: spotlight.phase === "press" ? "scale(0.985)" : "scale(1)",
+      }}
+    />
+  );
+}
+
+export function OpenworkControlProvider({ children }: { children: ReactNode }) {
+  const location = useLocation();
+  const actionsRef = useRef(new Map<string, RegisteredAction>());
+  const listenersRef = useRef(new Set<(snapshot: OpenworkControlSnapshot) => void>());
+  const nextOrderRef = useRef(1);
+  const [version, setVersion] = useState(0);
+  const [enabledState, setEnabledState] = useState(false);
+  const [busyActionId, setBusyActionId] = useState<string | null>(null);
+  const [narration, setNarration] = useState("Control mode is off.");
+  const [spotlight, setSpotlight] = useState<SpotlightState>({ visible: false, phase: "target", rect: null });
+
+  const route = `${location.pathname}${location.search}${location.hash}`;
+  const enabled = enabledState;
+  const status: OpenworkControlSnapshot["status"] = !enabled ? "off" : busyActionId ? "acting" : "ready";
+
+  const setEnabled = useCallback((nextEnabled: boolean) => {
+    setEnabledState(nextEnabled);
+  }, []);
+
+  const actions = useMemo(() => {
+    return Array.from(actionsRef.current.values())
+      .sort((left, right) => left.order - right.order)
+      .map((action) => metadataForAction(action, busyActionId));
+  }, [busyActionId, version]);
+
+  const snapshot = useCallback((): OpenworkControlSnapshot => ({
+    version: CONTROL_API_VERSION,
+    enabled,
+    route,
+    status,
+    busyActionId,
+    narration,
+    actions: Array.from(actionsRef.current.values())
+      .sort((left, right) => left.order - right.order)
+      .map((action) => metadataForAction(action, busyActionId)),
+  }), [busyActionId, enabled, narration, route, status]);
+
+  const registerAction = useCallback((action: OpenworkControlAction) => {
+    const token = Symbol(action.id);
+    const previous = actionsRef.current.get(action.id);
+    const registered = action as RegisteredAction;
+    registered.order = previous?.order ?? nextOrderRef.current++;
+    registered.token = token;
+    actionsRef.current.set(action.id, registered);
+    setVersion((current) => current + 1);
+
+    return () => {
+      const current = actionsRef.current.get(action.id);
+      if (current?.token === token) {
+        actionsRef.current.delete(action.id);
+        setVersion((value) => value + 1);
+      }
+    };
+  }, []);
+
+  const playTargetChoreography = useCallback(async (action: RegisteredAction) => {
+    if (!isBrowser()) return;
+    const target = action.targetRef?.current;
+    if (!target) {
+      await wait(80);
+      return;
+    }
+
+    target.scrollIntoView({ block: "center", inline: "nearest", behavior: "smooth" });
+    await wait(180);
+    const rect = target.getBoundingClientRect();
+    setSpotlight({
+      visible: true,
+      phase: "target",
+      rect: {
+        x: rect.left,
+        y: rect.top,
+        width: rect.width,
+        height: rect.height,
+      },
+    });
+    await wait(260);
+    setSpotlight((current) => ({ ...current, phase: "press" }));
+    await wait(130);
+    setSpotlight((current) => ({ ...current, phase: "target" }));
+    await wait(80);
+  }, []);
+
+  const executeAction = useCallback(async (actionId: string, args?: unknown): Promise<OpenworkControlResult> => {
+    const action = actionsRef.current.get(actionId);
+    if (!action) return { ok: false, actionId, error: `Unknown action: ${actionId}` };
+    if (action.disabled) return { ok: false, actionId, error: `Action is disabled: ${action.label}` };
+    if (busyActionId) return { ok: false, actionId, error: `Already acting: ${busyActionId}` };
+
+    if (action.requiresConfirmation && isBrowser()) {
+      const confirmed = window.confirm(`Allow Control Mode to ${action.label}?`);
+      if (!confirmed) return { ok: false, actionId, error: "User cancelled action." };
+    }
+
+    setEnabled(true);
+    setBusyActionId(action.id);
+    setNarration(`Moving to ${action.label}…`);
+
+    try {
+      await playTargetChoreography(action);
+      setNarration(`Running ${action.label}…`);
+      const effectiveArgs = args === undefined ? action.previewArgs : args;
+      const result = await action.execute(effectiveArgs, { setNarration });
+      setNarration(`Done: ${action.label}`);
+      await wait(280);
+      setSpotlight({ visible: false, phase: "target", rect: null });
+      return { ok: true, actionId, result };
+    } catch (error) {
+      const message = describeError(error);
+      setNarration(`Could not ${action.label}: ${message}`);
+      setSpotlight({ visible: false, phase: "target", rect: null });
+      return { ok: false, actionId, error: message };
+    } finally {
+      setBusyActionId(null);
+    }
+  }, [busyActionId, playTargetChoreography, setEnabled]);
+
+  const value = useMemo<OpenworkControlContextValue>(() => ({
+    enabled,
+    setEnabled,
+    route,
+    narration,
+    busyActionId,
+    actions,
+    registerAction,
+    executeAction,
+    snapshot,
+  }), [actions, busyActionId, enabled, executeAction, narration, registerAction, route, setEnabled, snapshot]);
+
+  useEffect(() => {
+    if (!enabled) {
+      setNarration("Control mode is off.");
+    } else if (narration === "Control mode is off.") {
+      setNarration("Ready. A controller can inspect and run visible actions.");
+    }
+  }, [enabled, narration]);
+
+  useEffect(() => {
+    if (!isBrowser()) return;
+
+    const api: OpenworkControlAPI = {
+      version: CONTROL_API_VERSION,
+      snapshot,
+      listActions: () => snapshot().actions,
+      execute: executeAction,
+      setEnabled,
+      subscribe(listener) {
+        listenersRef.current.add(listener);
+        listener(snapshot());
+        return () => {
+          listenersRef.current.delete(listener);
+        };
+      },
+    };
+
+    window.__openworkControl = api;
+    return () => {
+      if (window.__openworkControl === api) {
+        delete window.__openworkControl;
+      }
+    };
+  }, [executeAction, setEnabled, snapshot]);
+
+  useEffect(() => {
+    const next = snapshot();
+    listenersRef.current.forEach((listener) => listener(next));
+  }, [snapshot, version]);
+
+  return (
+    <OpenworkControlContext.Provider value={value}>
+      {children}
+      <ControlModeSpotlight spotlight={spotlight} />
+    </OpenworkControlContext.Provider>
+  );
+}
+
+export function useOpenworkControl() {
+  return useContext(OpenworkControlContext);
+}
+
+export function useControlAction(action: OpenworkControlAction | null | false | undefined) {
+  const control = useOpenworkControl();
+  const registerAction = control?.registerAction;
+  const latestActionRef = useRef<OpenworkControlAction | null>(action || null);
+  latestActionRef.current = action || null;
+  const actionId = action ? action.id : null;
+
+  useEffect(() => {
+    if (!registerAction || !actionId) return undefined;
+    const current = () => latestActionRef.current;
+    const proxy: OpenworkControlAction = {
+      id: actionId,
+      get label() {
+        return current()?.label ?? actionId;
+      },
+      get description() {
+        return current()?.description;
+      },
+      get sideEffect() {
+        return current()?.sideEffect;
+      },
+      get requiresConfirmation() {
+        return current()?.requiresConfirmation;
+      },
+      get requiresArgs() {
+        return current()?.requiresArgs;
+      },
+      get previewArgs() {
+        return current()?.previewArgs;
+      },
+      get disabled() {
+        return current()?.disabled;
+      },
+      get targetRef() {
+        return current()?.targetRef;
+      },
+      execute(args, helpers) {
+        const latest = current();
+        if (!latest) return undefined;
+        return latest.execute(args, helpers);
+      },
+    };
+    return registerAction(proxy);
+  }, [actionId, registerAction]);
+}
+
+export function OpenworkRouteControlActions() {
+  const navigate = useNavigate();
+
+  const actions = useMemo<OpenworkControlAction[]>(() => [
+    {
+      id: "route.session",
+      label: "Open sessions",
+      description: "Navigate to the main session view.",
+      sideEffect: "navigation",
+      execute: () => navigate("/session"),
+    },
+    {
+      id: "route.settings.general",
+      label: "Open general settings",
+      description: "Navigate to general settings.",
+      sideEffect: "navigation",
+      execute: () => navigate("/settings/general"),
+    },
+    {
+      id: "route.settings.extensions",
+      label: "Open MCP and extension settings",
+      description: "Navigate to extension and MCP settings.",
+      sideEffect: "navigation",
+      execute: () => navigate("/settings/extensions"),
+    },
+    {
+      id: "route.settings.skills",
+      label: "Open skills settings",
+      description: "Navigate to skills settings.",
+      sideEffect: "navigation",
+      execute: () => navigate("/settings/skills"),
+    },
+    {
+      id: "route.settings.appearance",
+      label: "Open appearance settings",
+      description: "Navigate to appearance settings.",
+      sideEffect: "navigation",
+      execute: () => navigate("/settings/appearance"),
+    },
+  ], [navigate]);
+
+  useControlAction(actions[0]);
+  useControlAction(actions[1]);
+  useControlAction(actions[2]);
+  useControlAction(actions[3]);
+  useControlAction(actions[4]);
+  return null;
+}
diff --git a/apps/app/src/react-app/shell/session-route.tsx b/apps/app/src/react-app/shell/session-route.tsx
index d04c438f1a..6d0cdb13b8 100644
--- a/apps/app/src/react-app/shell/session-route.tsx
+++ b/apps/app/src/react-app/shell/session-route.tsx
@@ -85,6 +85,7 @@ import {
   publishInspectorSlice,
   recordInspectorEvent,
 } from "./app-inspector";
+import { useControlAction, type OpenworkControlAction } from "./control/control-provider";
 import { useReactRenderWatchdog } from "./react-render-watchdog";
 import { getModelBehaviorSummary } from "../../app/lib/model-behavior";
 import { filterProviderList, mapConfigProvidersToList } from "../../app/utils/providers";
@@ -93,6 +94,7 @@ import { resolveOpenworkConnection } from "./openwork-connection";
 import { useReloadCoordinator } from "./reload-coordinator";
 import { getReactQueryClient } from "../infra/query-client";
 import { useStatusToasts } from "../domains/shell-feedback/status-toasts";
+import { useSessionControlActions } from "../domains/session/control/session-control-actions";
 
 type RouteWorkspace = OpenworkWorkspaceInfo & {
   displayNameResolved: string;
@@ -1545,6 +1547,31 @@ export function SessionRoute() {
     return () => window.removeEventListener("keydown", handler);
   }, [canCreateTask, handleCreateTaskInWorkspace, selectedWorkspaceId]);
 
+  useSessionControlActions({
+    workspaces,
+    sessionsByWorkspaceId,
+    selectedWorkspaceId,
+    selectedWorkspaceRoot,
+    selectedSessionId,
+    canCreateTask,
+    openworkClient: client,
+    opencodeClient,
+    navigateToSession: (sessionId) => navigate(`/session/${sessionId}`),
+    navigateToSessionRoot: () => navigate("/session"),
+    createTaskInWorkspace: handleCreateTaskInWorkspace,
+    openModelPicker: () => setModelPickerOpen(true),
+    refreshRouteState,
+  });
+
+  const commandPaletteControlAction = useMemo<OpenworkControlAction>(() => ({
+    id: "command_palette.open",
+    label: "Open the command palette",
+    description: "Open the in-app command palette so the next choice is visible.",
+    sideEffect: "none",
+    execute: () => setCommandPaletteOpen(true),
+  }), []);
+  useControlAction(commandPaletteControlAction);
+
   const paletteSessionOptions = useMemo<PaletteSessionOption[]>(() => {
     const out: PaletteSessionOption[] = [];
     for (const workspace of workspaces) {
diff --git a/apps/desktop/electron/main.mjs b/apps/desktop/electron/main.mjs
index 18fbd354f6..ccb2c0ad05 100644
--- a/apps/desktop/electron/main.mjs
+++ b/apps/desktop/electron/main.mjs
@@ -1,4 +1,5 @@
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
 import { existsSync } from "node:fs";
 import {
   cp,
@@ -180,6 +181,9 @@ const IDLE_ROUTER_INFO = Object.freeze({
 
 let mainWindow = null;
 const pendingDeepLinks = [];
+let uiControlServer = null;
+let uiControlDiscoveryPath = null;
+const uiControlToken = randomBytes(32).toString("hex");
 
 function normalizePlatform(value) {
   if (value === "darwin" || value === "linux") return value;
@@ -1331,6 +1335,141 @@ async function handleDesktopInvoke(event, command, ...args) {
   }
 }
 
+function sendJsonResponse(response, statusCode, payload) {
+  response.writeHead(statusCode, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Cache-Control": "no-store",
+  });
+  response.end(JSON.stringify(payload));
+}
+
+function readJsonRequestBody(request) {
+  return new Promise((resolve, reject) => {
+    let raw = "";
+    request.setEncoding("utf8");
+    request.on("data", (chunk) => {
+      raw += chunk;
+      if (raw.length > 128_000) {
+        reject(new Error("Request body too large"));
+        request.destroy();
+      }
+    });
+    request.on("end", () => {
+      if (!raw.trim()) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(raw));
+      } catch {
+        reject(new Error("Request body must be JSON"));
+      }
+    });
+    request.on("error", reject);
+  });
+}
+
+function authorizedUiControlRequest(request) {
+  const auth = request.headers.authorization ?? "";
+  return auth === `Bearer ${uiControlToken}`;
+}
+
+async function evaluateOpenworkControl(expression) {
+  const win = await createMainWindow();
+  win.show();
+  if (win.isMinimized()) win.restore();
+  win.focus();
+  return win.webContents.executeJavaScript(expression, true);
+}
+
+async function runOpenworkControlCommand(command, args = {}) {
+  const serializedArgs = JSON.stringify(args ?? {}).replace(/</g, "\\u003c");
+  if (command === "snapshot") {
+    return evaluateOpenworkControl(`(async () => {
+      const control = window.__openworkControl;
+      if (!control) return { ok: false, error: "OpenWork control surface is not available yet." };
+      control.setEnabled?.(true);
+      return { ok: true, snapshot: control.snapshot() };
+    })()`);
+  }
+  if (command === "actions") {
+    return evaluateOpenworkControl(`(async () => {
+      const control = window.__openworkControl;
+      if (!control) return { ok: false, error: "OpenWork control surface is not available yet." };
+      control.setEnabled?.(true);
+      return { ok: true, actions: control.listActions() };
+    })()`);
+  }
+  if (command === "execute") {
+    return evaluateOpenworkControl(`(async () => {
+      const control = window.__openworkControl;
+      const input = ${serializedArgs};
+      if (!control) return { ok: false, error: "OpenWork control surface is not available yet." };
+      if (!input || typeof input.actionId !== "string" || !input.actionId.trim()) {
+        return { ok: false, error: "Missing OpenWork actionId." };
+      }
+      control.setEnabled?.(true);
+      const result = await control.execute(input.actionId, input.args ?? {});
+      return { ok: true, result };
+    })()`);
+  }
+  return { ok: false, error: `Unknown OpenWork control command: ${command}` };
+}
+
+async function startUiControlServer() {
+  if (uiControlServer) return;
+  uiControlServer = createServer(async (request, response) => {
+    try {
+      const url = new URL(request.url ?? "/", "http://127.0.0.1");
+      if (request.method === "GET" && url.pathname === "/health") {
+        sendJsonResponse(response, 200, { ok: true, app: APP_NAME, version: 1 });
+        return;
+      }
+      if (!authorizedUiControlRequest(request)) {
+        sendJsonResponse(response, 401, { ok: false, error: "Unauthorized" });
+        return;
+      }
+      if (request.method === "GET" && url.pathname === "/snapshot") {
+        sendJsonResponse(response, 200, await runOpenworkControlCommand("snapshot"));
+        return;
+      }
+      if (request.method === "GET" && url.pathname === "/actions") {
+        sendJsonResponse(response, 200, await runOpenworkControlCommand("actions"));
+        return;
+      }
+      if (request.method === "POST" && url.pathname === "/execute") {
+        sendJsonResponse(response, 200, await runOpenworkControlCommand("execute", await readJsonRequestBody(request)));
+        return;
+      }
+      sendJsonResponse(response, 404, { ok: false, error: "Not found" });
+    } catch (error) {
+      sendJsonResponse(response, 500, { ok: false, error: error instanceof Error ? error.message : String(error) });
+    }
+  });
+  await new Promise((resolve, reject) => {
+    uiControlServer.once("error", reject);
+    uiControlServer.listen(0, "127.0.0.1", () => resolve(undefined));
+  });
+  const address = uiControlServer.address();
+  const port = typeof address === "object" && address ? address.port : null;
+  if (!port) throw new Error("Could not start OpenWork UI control bridge.");
+  uiControlDiscoveryPath = path.join(app.getPath("userData"), "openwork-ui-control.json");
+  await writeFile(
+    uiControlDiscoveryPath,
+    `${JSON.stringify({ version: 1, app: APP_NAME, baseUrl: `http://127.0.0.1:${port}`, token: uiControlToken }, null, 2)}\n`,
+    "utf8",
+  );
+}
+
+async function stopUiControlServer() {
+  if (uiControlDiscoveryPath) {
+    await rm(uiControlDiscoveryPath, { force: true }).catch(() => undefined);
+  }
+  if (!uiControlServer) return;
+  await new Promise((resolve) => uiControlServer.close(() => resolve(undefined)));
+  uiControlServer = null;
+}
+
 async function createMainWindow() {
   if (mainWindow) return mainWindow;
 
@@ -1413,7 +1552,7 @@ if (!app.requestSingleInstanceLock()) {
   app.on("before-quit", (event) => {
     if (runtimeDisposedForQuit) return;
     event.preventDefault();
-    void disposeRuntimeBeforeQuit().finally(() => app.quit());
+    void Promise.all([disposeRuntimeBeforeQuit(), stopUiControlServer()]).finally(() => app.quit());
   });
 
   app.on("second-instance", async (_event, argv) => {
@@ -1440,6 +1579,9 @@ if (!app.requestSingleInstanceLock()) {
     // Electron see the same workspace list. Import the short-lived
     // Electron-only filename only when the shared file is missing.
     await migrateLegacyElectronWorkspaceStateIfNeeded();
+    await startUiControlServer().catch((error) => {
+      console.warn("[ui-control] failed to start", error);
+    });
     runtimeBootstrapPromise = bootRuntimeForSelectedWorkspace().catch((error) => ({
       ok: false,
       error: error instanceof Error ? error.message : String(error),
diff --git a/docs/mcp-ui-control-profile.md b/docs/mcp-ui-control-profile.md
new file mode 100644
index 0000000000..dc24029a89
--- /dev/null
+++ b/docs/mcp-ui-control-profile.md
@@ -0,0 +1,142 @@
+# MCP UI Control Profile
+
+Status: draft
+
+OpenWork uses MCP as the public integration shape for app and server control. The
+UI Control profile is a convention layered on top of normal MCP tools so any MCP
+client can discover app state and execute semantic UI actions without scraping
+DOM nodes, coordinates, or native accessibility trees.
+
+## Goals
+
+- Make standalone control clients such as HandsFree MCP clients that can control
+  any configured MCP-compatible app or service.
+- Let OpenWork expose product/app actions through MCP instead of a private local
+  bridge.
+- Keep UI automation semantic: actions like `composer.send`, not `click x y`.
+- Preserve escape hatches: CDP, WebDriver BiDi, and native accessibility remain
+  fallback transports when an app has no semantic MCP surface.
+
+## Profile tools
+
+MCP servers that want to expose controllable UI should provide these tools.
+
+### `ui.snapshot`
+
+Returns the app's current semantic state.
+
+Suggested output:
+
+```json
+{
+  "app": { "id": "openwork", "name": "OpenWork", "version": "0.13.3" },
+  "route": "session",
+  "title": "Current session",
+  "selection": { "sessionId": "ses_123" },
+  "summary": "Session page with composer ready",
+  "actions": ["session.read_transcript", "composer.set_text", "composer.send"]
+}
+```
+
+### `ui.list_actions`
+
+Returns currently available semantic actions.
+
+Each action should include:
+
+```json
+{
+  "id": "composer.set_text",
+  "label": "Type into the composer",
+  "description": "Replace the current session draft with supplied text.",
+  "inputSchema": {
+    "type": "object",
+    "properties": { "text": { "type": "string" } },
+    "required": ["text"]
+  },
+  "sideEffect": "draft",
+  "requiresConfirmation": false,
+  "enabled": true
+}
+```
+
+Recommended `sideEffect` values:
+
+- `read`: no visible change
+- `navigation`: route/focus change
+- `draft`: changes unsent input only
+- `mutation`: sends/runs/changes durable state
+- `destructive`: deletes or irreversibly changes state
+- `external`: opens another app, network destination, or OS surface
+
+### `ui.execute_action`
+
+Executes one action returned by `ui.list_actions`.
+
+Input:
+
+```json
+{
+  "actionId": "composer.set_text",
+  "args": { "text": "Hello from HandsFree" },
+  "confirmed": false
+}
+```
+
+Output:
+
+```json
+{
+  "ok": true,
+  "actionId": "composer.set_text",
+  "result": { "draftLength": 16 }
+}
+```
+
+Destructive actions should require `confirmed: true` or return an error that
+explains the required confirmation.
+
+## Generic MCP client behavior in HandsFree
+
+HandsFree treats MCP as the primary app-integration layer.
+
+HandsFree-level MCP tools:
+
+- `mcp_list_servers`: enumerate configured MCP servers.
+- `mcp_list_tools`: inspect tools on a selected MCP server.
+- `mcp_call_tool`: call any MCP tool by server/tool name.
+
+HandsFree reads MCP server definitions from its local settings file under Electron
+`userData`:
+
+```json
+{
+  "mcpServers": {
+    "example-stdio": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    },
+    "example-http": {
+      "type": "http",
+      "url": "http://127.0.0.1:8787/mcp",
+      "headers": { "Authorization": "Bearer local-token" }
+    }
+  }
+}
+```
+
+When a server implements this profile, HandsFree should prefer:
+
+1. `ui.snapshot`
+2. `ui.list_actions`
+3. `ui.execute_action`
+
+over OS typing, keyboard shortcuts, CDP, or accessibility fallbacks.
+
+## OpenWork migration path
+
+1. Keep `window.__openworkControl` as the app-local control registry.
+2. Expose that registry through an OpenWork MCP server using this profile.
+3. Update HandsFree to connect to the OpenWork MCP server like any other MCP server.
+4. Keep the local HTTP bridge private to the OpenWork MCP server implementation.
diff --git a/packages/openwork-ui-mcp/index.mjs b/packages/openwork-ui-mcp/index.mjs
new file mode 100644
index 0000000000..98b920c19c
--- /dev/null
+++ b/packages/openwork-ui-mcp/index.mjs
@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+
+/**
+ * openwork-ui-mcp
+ *
+ * MCP server that exposes OpenWork's UI control surface as MCP tools.
+ * Speaks MCP stdio and proxies to the OpenWork desktop bridge HTTP API.
+ *
+ * Requires OpenWork desktop running with the local UI control bridge active.
+ *
+ * Usage:
+ *   npx openwork-ui-mcp
+ *
+ * MCP config (OpenCode / Claude Desktop / Cursor / etc.):
+ *   {
+ *     "mcpServers": {
+ *       "openwork-ui": {
+ *         "command": "npx",
+ *         "args": ["-y", "openwork-ui-mcp"]
+ *       }
+ *     }
+ *   }
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// ── Bridge discovery ──
+
+const DISCOVERY_PATHS = [
+  join(homedir(), "Library", "Application Support", "com.differentai.openwork", "openwork-ui-control.json"),
+  join(homedir(), "Library", "Application Support", "com.differentai.openwork.dev", "openwork-ui-control.json"),
+];
+
+async function discoverBridge() {
+  for (const candidate of DISCOVERY_PATHS) {
+    try {
+      const raw = await readFile(candidate, "utf8");
+      const parsed = JSON.parse(raw);
+      if (typeof parsed.baseUrl === "string" && typeof parsed.token === "string") {
+        return { baseUrl: parsed.baseUrl, token: parsed.token, path: candidate };
+      }
+    } catch {
+      // Try next
+    }
+  }
+  return null;
+}
+
+async function bridgeRequest(path, options = {}) {
+  const bridge = await discoverBridge();
+  if (!bridge) {
+    return {
+      ok: false,
+      error: "OpenWork is not running. Launch the OpenWork desktop app first.",
+      hint: "The MCP server connects to a running OpenWork instance via its local bridge.",
+    };
+  }
+  const url = `${bridge.baseUrl}${path}`;
+  try {
+    const response = await fetch(url, {
+      method: options.method || "GET",
+      headers: {
+        Authorization: `Bearer ${bridge.token}`,
+        ...(options.body ? { "Content-Type": "application/json" } : {}),
+      },
+      ...(options.body ? { body: JSON.stringify(options.body) } : {}),
+    });
+    const text = await response.text();
+    try {
+      return JSON.parse(text);
+    } catch {
+      return { ok: false, error: text || `HTTP ${response.status}` };
+    }
+  } catch (error) {
+    return { ok: false, error: `Bridge unreachable at ${url}: ${error.message}` };
+  }
+}
+
+// ── MCP Server ──
+
+const server = new McpServer({
+  name: "openwork-ui",
+  version: "0.1.0",
+});
+
+// ── ui.snapshot ──
+server.tool(
+  "ui_snapshot",
+  "Get a snapshot of the current OpenWork UI state: active route, narration, visible actions, and status. Use this before taking action to understand what the user sees.",
+  {},
+  async () => {
+    const result = await bridgeRequest("/snapshot");
+    if (!result.ok && result.error) {
+      return { content: [{ type: "text", text: `Error: ${result.error}${result.hint ? `\n${result.hint}` : ""}` }], isError: true };
+    }
+    const lines = [];
+    if (result.route) lines.push(`Route: ${result.route}`);
+    if (result.status) lines.push(`Status: ${result.status}`);
+    if (result.narration) lines.push(`Narration: ${result.narration}`);
+    if (result.busyActionId) lines.push(`Busy: ${result.busyActionId}`);
+    if (Array.isArray(result.actions)) {
+      lines.push(`\nActions (${result.actions.length}):`);
+      for (const action of result.actions) {
+        const args = action.args?.length ? ` [${action.args.map((a) => a.name).join(", ")}]` : "";
+        lines.push(`  ${action.id} — ${action.label || action.description || ""}${args}`);
+      }
+    }
+    return { content: [{ type: "text", text: lines.join("\n") || JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// ── ui.list_actions ──
+server.tool(
+  "ui_list_actions",
+  "List all UI control actions currently available in OpenWork: session navigation, composer control, transcript access, and more. Each action has an id you can pass to ui_execute_action.",
+  {},
+  async () => {
+    const result = await bridgeRequest("/actions");
+    if (!result.ok && result.error) {
+      return { content: [{ type: "text", text: `Error: ${result.error}` }], isError: true };
+    }
+    if (!Array.isArray(result.actions) || result.actions.length === 0) {
+      return { content: [{ type: "text", text: "No actions available. Is OpenWork on the main screen?" }] };
+    }
+    const text = result.actions.map((a) => {
+      const args = a.args?.length ? `\n    Args: ${a.args.map((p) => `${p.name}${p.required ? " (required)" : ""}: ${p.description || p.type || ""}`).join(", ")}` : "";
+      return `${a.id}\n    ${a.label || ""}${a.description ? ` — ${a.description}` : ""}${args}`;
+    }).join("\n\n");
+    return { content: [{ type: "text", text: `${result.actions.length} actions:\n\n${text}` }] };
+  }
+);
+
+// ── ui.execute_action ──
+server.tool(
+  "ui_execute_action",
+  "Execute an OpenWork UI action by its id. Use ui_list_actions first to see available actions and their required arguments.",
+  {
+    actionId: z.string().describe("The action id from ui_list_actions, e.g. 'session.create_task' or 'composer.set_text'"),
+    args: z.record(z.unknown()).optional().describe("JSON arguments for the action, if required"),
+  },
+  async ({ actionId, args }) => {
+    const result = await bridgeRequest("/execute", {
+      method: "POST",
+      body: { actionId, args: args ?? {} },
+    });
+    if (!result.ok && result.error) {
+      return { content: [{ type: "text", text: `Error executing ${actionId}: ${result.error}` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// ── ui.status ──
+server.tool(
+  "ui_status",
+  "Check if OpenWork is running and the bridge is reachable. Returns connection status and app info.",
+  {},
+  async () => {
+    const bridge = await discoverBridge();
+    if (!bridge) {
+      return { content: [{ type: "text", text: "OpenWork is not running.\nLaunch the OpenWork desktop app to enable UI control." }], isError: true };
+    }
+    try {
+      const response = await fetch(`${bridge.baseUrl}/health`, { signal: AbortSignal.timeout(3000) });
+      const data = await response.json();
+      return { content: [{ type: "text", text: `Connected to ${data.app || "OpenWork"}\nBridge: ${bridge.baseUrl}\nVersion: ${data.version ?? "?"}` }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Bridge file found but not reachable: ${error.message}\nOpenWork may have quit. Relaunch it.` }], isError: true };
+    }
+  }
+);
+
+// ── Start ──
+const transport = new StdioServerTransport();
+await server.connect(transport);
diff --git a/packages/openwork-ui-mcp/package.json b/packages/openwork-ui-mcp/package.json
new file mode 100644
index 0000000000..6dd039c31a
--- /dev/null
+++ b/packages/openwork-ui-mcp/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "openwork-ui-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for OpenWork UI control — exposes snapshot, actions, and execute as MCP tools",
+  "author": "OpenWork <support@openworklabs.com>",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "openwork-ui-mcp": "./index.mjs"
+  },
+  "files": ["index.mjs"],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  }
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 17e7adef12..632ede94a1 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -753,6 +753,15 @@ importers:
         specifier: ^5.6.3
         version: 5.9.3
 
+  packages/openwork-ui-mcp:
+    dependencies:
+      '@modelcontextprotocol/sdk':
+        specifier: ^1.29.0
+        version: 1.29.0(zod@3.25.76)
+      zod:
+        specifier: ^3.25.76
+        version: 3.25.76
+
   packages/types:
     dependencies:
       zod:
@@ -6439,8 +6448,8 @@ packages:
   ms@2.1.3:
     resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
 
-  msw@2.14.2:
-    resolution: {integrity: sha512-D2bTe0tpuf9nw4DA39wFaqUD/hRPKj0DKpo2lAqu+A47Ifg4+h0hbfn6QxVOsiUY2uhgEN6TTpGSHDsc+ysYNg==}
+  msw@2.14.3:
+    resolution: {integrity: sha512-kk8G5cocVlJ4wsKMGZegn2H6XLOEKjbA+nSJE2354e/SRp4mDicCHUYnMXpymzVcVDCs+GUAsmNqSn+yHv4T2A==}
     engines: {node: '>=18'}
     hasBin: true
     peerDependencies:
@@ -8814,7 +8823,7 @@ snapshots:
 
   '@babel/generator@7.28.6':
     dependencies:
-      '@babel/parser': 7.28.6
+      '@babel/parser': 7.29.2
       '@babel/types': 7.28.6
       '@jridgewell/gen-mapping': 0.3.13
       '@jridgewell/trace-mapping': 0.3.31
@@ -9071,7 +9080,7 @@ snapshots:
       '@babel/code-frame': 7.28.6
       '@babel/generator': 7.28.6
       '@babel/helper-globals': 7.28.0
-      '@babel/parser': 7.28.6
+      '@babel/parser': 7.29.2
       '@babel/template': 7.28.6
       '@babel/types': 7.28.6
       debug: 4.4.3
@@ -10981,13 +10990,13 @@ snapshots:
 
   '@slack/logger@4.0.0':
     dependencies:
-      '@types/node': 20.12.12
+      '@types/node': 25.6.0
 
   '@slack/socket-mode@2.0.5':
     dependencies:
       '@slack/logger': 4.0.0
       '@slack/web-api': 7.13.0
-      '@types/node': 20.12.12
+      '@types/node': 25.6.0
       '@types/ws': 8.18.1
       eventemitter3: 5.0.4
       ws: 8.19.0
@@ -11002,7 +11011,7 @@ snapshots:
     dependencies:
       '@slack/logger': 4.0.0
       '@slack/types': 2.19.0
-      '@types/node': 20.12.12
+      '@types/node': 25.6.0
       '@types/retry': 0.12.0
       axios: 1.13.6
       eventemitter3: 5.0.4
@@ -11622,7 +11631,7 @@ snapshots:
     dependencies:
       '@types/http-cache-semantics': 4.2.0
       '@types/keyv': 3.1.4
-      '@types/node': 20.12.12
+      '@types/node': 25.6.0
       '@types/responselike': 1.0.3
 
   '@types/d3-array@3.2.2': {}
@@ -11754,7 +11763,7 @@ snapshots:
 
   '@types/fs-extra@9.0.13':
     dependencies:
-      '@types/node': 20.12.12
+      '@types/node': 25.6.0
 
   '@types/geojson@7946.0.16': {}
 
@@ -11768,7 +11777,7 @@ snapshots:
 
   '@types/keyv@3.1.4':
     dependencies:
-      '@types/node': 20.12.12
+      '@types/node': 25.6.0
 
   '@types/luxon@3.7.1': {}
 
@@ -11800,8 +11809,8 @@ snapshots:
 
   '@types/plist@3.0.5':
     dependencies:
-      '@types/node': 20.12.12
-      xmlbuilder: 11.0.1
+      '@types/node': 25.6.0
+      xmlbuilder: 15.1.1
     optional: true
 
   '@types/prop-types@15.7.15': {}
@@ -11825,7 +11834,7 @@ snapshots:
 
   '@types/responselike@1.0.3':
     dependencies:
-      '@types/node': 20.12.12
+      '@types/node': 25.6.0
 
   '@types/retry@0.12.0': {}
 
@@ -11849,11 +11858,11 @@ snapshots:
 
   '@types/ws@8.18.1':
     dependencies:
-      '@types/node': 20.12.12
+      '@types/node': 25.6.0
 
   '@types/yauzl@2.10.3':
     dependencies:
-      '@types/node': 20.12.12
+      '@types/node': 25.6.0
     optional: true
 
   '@ungap/structured-clone@1.3.0': {}
@@ -12272,7 +12281,7 @@ snapshots:
 
   browserslist@4.28.1:
     dependencies:
-      baseline-browser-mapping: 2.10.11
+      baseline-browser-mapping: 2.9.14
       caniuse-lite: 1.0.30001764
       electron-to-chromium: 1.5.267
       node-releases: 2.0.27
@@ -12333,7 +12342,7 @@ snapshots:
 
   bun-types@1.3.6:
     dependencies:
-      '@types/node': 20.12.12
+      '@types/node': 25.6.0
 
   bun-webgpu-darwin-arm64@0.1.4:
     optional: true
@@ -14838,7 +14847,7 @@ snapshots:
 
   ms@2.1.3: {}
 
-  msw@2.14.2(@types/node@25.6.0)(typescript@5.9.3):
+  msw@2.14.3(@types/node@25.6.0)(typescript@5.9.3):
     dependencies:
       '@inquirer/confirm': 6.0.12(@types/node@25.6.0)
       '@mswjs/interceptors': 0.41.8
@@ -15427,7 +15436,7 @@ snapshots:
       '@protobufjs/path': 1.1.2
       '@protobufjs/pool': 1.1.0
       '@protobufjs/utf8': 1.1.0
-      '@types/node': 20.12.12
+      '@types/node': 25.6.0
       long: 5.3.2
 
   proxy-addr@2.0.7:
@@ -15864,7 +15873,7 @@ snapshots:
       fuzzysort: 3.1.0
       https-proxy-agent: 7.0.6
       kleur: 4.1.5
-      msw: 2.14.2(@types/node@25.6.0)(typescript@5.9.3)
+      msw: 2.14.3(@types/node@25.6.0)(typescript@5.9.3)
       node-fetch: 3.3.2
       open: 11.0.0
       ora: 8.2.0

From 17851494b1c6fba6f54b225a31c342d403d6ffab Mon Sep 17 00:00:00 2001
From: Benjamin Shafii <ben@prologe.io>
Date: Mon, 4 May 2026 12:31:15 -0700
Subject: [PATCH 2/4] docs: rewrite MCP UI control as a tutorial

---
 docs/mcp-ui-control-profile.md | 275 +++++++++++++++++++++------------
 1 file changed, 179 insertions(+), 96 deletions(-)

diff --git a/docs/mcp-ui-control-profile.md b/docs/mcp-ui-control-profile.md
index dc24029a89..9e9016ec05 100644
--- a/docs/mcp-ui-control-profile.md
+++ b/docs/mcp-ui-control-profile.md
@@ -1,142 +1,225 @@
-# MCP UI Control Profile
+# Control OpenWork from any MCP client
 
-Status: draft
+OpenWork exposes its UI as an MCP server so any MCP-capable app can read what's on screen and run actions — no DOM scraping, no coordinates, no accessibility hacks.
 
-OpenWork uses MCP as the public integration shape for app and server control. The
-UI Control profile is a convention layered on top of normal MCP tools so any MCP
-client can discover app state and execute semantic UI actions without scraping
-DOM nodes, coordinates, or native accessibility trees.
+## Why this exists
 
-## Goals
+Apps like HandsFree let people control their computers hands-free using AI. But generic computer-use flows (screenshot → click coordinate) are slow, fragile, and need a vision model for every step.
 
-- Make standalone control clients such as HandsFree MCP clients that can control
-  any configured MCP-compatible app or service.
-- Let OpenWork expose product/app actions through MCP instead of a private local
-  bridge.
-- Keep UI automation semantic: actions like `composer.send`, not `click x y`.
-- Preserve escape hatches: CDP, WebDriver BiDi, and native accessibility remain
-  fallback transports when an app has no semantic MCP surface.
+OpenWork takes a different approach: the app itself tells you what actions are available, what the current state is, and lets you execute actions by name. The MCP server wraps that surface so any MCP client gets a first-class, semantic control experience out of the box.
 
-## Profile tools
+This means:
 
-MCP servers that want to expose controllable UI should provide these tools.
+- **HandsFree** can drive OpenWork sessions, composer, navigation, and transcript without guessing pixels.
+- **OpenCode** can automate OpenWork as part of a larger coding workflow.
+- **Claude Desktop, Codex, Cursor**, or any MCP-compatible tool can add OpenWork control with a single config line.
+- Your own app can do the same.
 
-### `ui.snapshot`
+> Want to control OpenWork Cloud workers and server APIs instead of the desktop UI? Check out the **OpenWork Cloud MCP** (separate package, coming soon).
 
-Returns the app's current semantic state.
+## Quick start with HandsFree
 
-Suggested output:
+HandsFree auto-discovers the OpenWork MCP server when both apps are running on the same machine. No config needed.
+
+1. Launch **OpenWork** (desktop app).
+2. Launch **HandsFree**.
+3. Open the HandsFree connector panel — you should see **OpenWork** with a green "Connected" status and an action count.
+
+That's it. HandsFree can now list your sessions, read transcripts, type into the composer, send prompts, and navigate the app — all through MCP.
+
+### What HandsFree can do once connected
+
+- `ui_snapshot` — see the current route, status, and available actions.
+- `ui_list_actions` — get every action the app currently exposes (session controls, composer, navigation, etc.).
+- `ui_execute_action` — run an action by ID, e.g. `session.create_task`, `composer.set_text`, `composer.send`.
+- `ui_status` — check if OpenWork is running and the bridge is reachable.
+
+## Add to OpenCode
+
+Add the MCP server to your workspace or global `opencode.json`:
 
 ```json
 {
-  "app": { "id": "openwork", "name": "OpenWork", "version": "0.13.3" },
-  "route": "session",
-  "title": "Current session",
-  "selection": { "sessionId": "ses_123" },
-  "summary": "Session page with composer ready",
-  "actions": ["session.read_transcript", "composer.set_text", "composer.send"]
+  "mcp": {
+    "openwork-ui": {
+      "type": "local",
+      "command": ["npx", "-y", "openwork-ui-mcp"],
+      "enabled": true
+    }
+  }
 }
 ```
 
-### `ui.list_actions`
+Then use the tools in any session:
+
+```
+> Use ui_snapshot to see what's on screen in OpenWork, then list the available sessions.
+```
 
-Returns currently available semantic actions.
+## Add to Claude Desktop or Codex
 
-Each action should include:
+Both use the same MCP config shape. Add to your `claude_desktop_config.json` or Codex MCP settings:
 
 ```json
 {
-  "id": "composer.set_text",
-  "label": "Type into the composer",
-  "description": "Replace the current session draft with supplied text.",
-  "inputSchema": {
-    "type": "object",
-    "properties": { "text": { "type": "string" } },
-    "required": ["text"]
-  },
-  "sideEffect": "draft",
-  "requiresConfirmation": false,
-  "enabled": true
+  "mcpServers": {
+    "openwork-ui": {
+      "command": "npx",
+      "args": ["-y", "openwork-ui-mcp"]
+    }
+  }
 }
 ```
 
-Recommended `sideEffect` values:
+Restart the app. The four tools (`ui_status`, `ui_snapshot`, `ui_list_actions`, `ui_execute_action`) will appear in the tool list.
 
-- `read`: no visible change
-- `navigation`: route/focus change
-- `draft`: changes unsent input only
-- `mutation`: sends/runs/changes durable state
-- `destructive`: deletes or irreversibly changes state
-- `external`: opens another app, network destination, or OS surface
+## Add to your own MCP client
 
-### `ui.execute_action`
+If you're building an app that speaks MCP, you can connect to the OpenWork UI server the same way:
 
-Executes one action returned by `ui.list_actions`.
+```js
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 
-Input:
+const transport = new StdioClientTransport({
+  command: "npx",
+  args: ["-y", "openwork-ui-mcp"],
+});
+const client = new Client({ name: "my-app", version: "1.0.0" });
+await client.connect(transport);
 
-```json
-{
-  "actionId": "composer.set_text",
-  "args": { "text": "Hello from HandsFree" },
-  "confirmed": false
-}
+// Check if OpenWork is running
+const status = await client.callTool({ name: "ui_status", arguments: {} });
+console.log(status);
+
+// See what actions are available
+const actions = await client.callTool({ name: "ui_list_actions", arguments: {} });
+console.log(actions);
+
+// Type something into the composer
+await client.callTool({
+  name: "ui_execute_action",
+  arguments: { actionId: "composer.set_text", args: { text: "Hello from my app" } },
+});
 ```
 
-Output:
+## Tool reference
 
-```json
-{
-  "ok": true,
-  "actionId": "composer.set_text",
-  "result": { "draftLength": 16 }
-}
+### `ui_status`
+
+Check if OpenWork is running and reachable. Returns connection status and app info.
+
+**No arguments.**
+
+Example response:
+
+```
+Connected to OpenWork
+Bridge: http://127.0.0.1:52431
+Version: 1
 ```
 
-Destructive actions should require `confirmed: true` or return an error that
-explains the required confirmation.
+### `ui_snapshot`
+
+Get the current OpenWork UI state: active route, narration, visible actions, and status. Call this before acting to understand what the user sees.
+
+**No arguments.**
 
-## Generic MCP client behavior in HandsFree
+Example response:
+
+```
+Route: /session/ses_abc123
+Status: ready
+Narration: Ready. A controller can inspect and run visible actions.
+
+Actions (26):
+  session.create_task — Create a new task
+  session.list_sessions — List available sessions
+  composer.set_text — Type into the composer [text]
+  composer.send — Send the composer prompt
+  ...
+```
 
-HandsFree treats MCP as the primary app-integration layer.
+### `ui_list_actions`
 
-HandsFree-level MCP tools:
+List all UI control actions currently available. Each action has an `id` you can pass to `ui_execute_action`.
 
-- `mcp_list_servers`: enumerate configured MCP servers.
-- `mcp_list_tools`: inspect tools on a selected MCP server.
-- `mcp_call_tool`: call any MCP tool by server/tool name.
+**No arguments.**
 
-HandsFree reads MCP server definitions from its local settings file under Electron
-`userData`:
+Returns the full list with labels, descriptions, and argument info.
+
+### `ui_execute_action`
+
+Execute an OpenWork UI action by its id.
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `actionId` | string | The action id from `ui_list_actions`, e.g. `session.create_task` or `composer.set_text` |
+| `args` | object (optional) | JSON arguments for the action, if required |
+
+Example — list sessions:
 
 ```json
-{
-  "mcpServers": {
-    "example-stdio": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
-    },
-    "example-http": {
-      "type": "http",
-      "url": "http://127.0.0.1:8787/mcp",
-      "headers": { "Authorization": "Bearer local-token" }
-    }
-  }
-}
+{ "actionId": "session.list_sessions" }
 ```
 
-When a server implements this profile, HandsFree should prefer:
+Example — type into the composer:
+
+```json
+{ "actionId": "composer.set_text", "args": { "text": "Summarize this project" } }
+```
 
-1. `ui.snapshot`
-2. `ui.list_actions`
-3. `ui.execute_action`
+Example — send the composer prompt:
 
-over OS typing, keyboard shortcuts, CDP, or accessibility fallbacks.
+```json
+{ "actionId": "composer.send" }
+```
+
+## Available actions
+
+The exact list depends on the current OpenWork route and state. Common actions include:
+
+| Action | Description |
+|--------|-------------|
+| `session.create_task` | Create a new session in the selected workspace |
+| `session.list_sessions` | List sessions across workspaces |
+| `session.open` | Navigate to a session by ID |
+| `session.rename` | Rename a session |
+| `session.delete` | Delete a session (requires confirmation) |
+| `session.latest_message` | Read the latest message in the current session |
+| `session.read_transcript` | Read the last N messages as text |
+| `composer.set_text` | Type text into the composer (visible typing animation) |
+| `composer.send` | Send the current draft |
+| `composer.stop` | Stop a running session |
+| `session.scroll_top` | Scroll to the top of the transcript |
+| `session.scroll_bottom` | Scroll to the bottom |
+| `route.session` | Navigate to the session view |
+| `route.settings.*` | Navigate to various settings pages |
+| `command_palette.open` | Open the command palette |
+| `session.model_picker.open` | Open the model picker |
+| `status.docs.open` | Open documentation |
+| `status.settings.open` | Open settings from the status bar |
+
+## Requirements
+
+- **OpenWork desktop** must be running. The MCP server connects to OpenWork's local bridge which starts automatically when the desktop app launches.
+- **macOS** is the primary supported platform. The bridge uses Electron IPC and writes a discovery file to `~/Library/Application Support/com.differentai.openwork/`.
+- The MCP server runs as a **stdio** process — your MCP client spawns it and communicates over stdin/stdout.
+
+## How it works under the hood
+
+```
+┌─────────────┐     MCP stdio      ┌──────────────────┐     HTTP localhost     ┌──────────────┐
+│  MCP client  │ ←────────────────→ │  openwork-ui-mcp │ ←───────────────────→ │  OpenWork app │
+│  (HandsFree, │                    │  (Node.js)       │                       │  (Electron)   │
+│   OpenCode,  │                    │                  │                       │               │
+│   Codex)     │                    └──────────────────┘                       └──────────────┘
+└─────────────┘
+```
 
-## OpenWork migration path
+1. OpenWork desktop starts a private localhost HTTP bridge on a random port, protected by a bearer token.
+2. It writes a discovery file with the port and token so `openwork-ui-mcp` can find it.
+3. `openwork-ui-mcp` reads the discovery file, proxies MCP tool calls to the bridge, and returns structured results.
+4. The bridge calls `window.__openworkControl` inside the Electron renderer to snapshot state and execute actions.
 
-1. Keep `window.__openworkControl` as the app-local control registry.
-2. Expose that registry through an OpenWork MCP server using this profile.
-3. Update HandsFree to connect to the OpenWork MCP server like any other MCP server.
-4. Keep the local HTTP bridge private to the OpenWork MCP server implementation.
+The bridge and discovery file are implementation details — you never need to touch them directly. Just point your MCP client at `openwork-ui-mcp`.

From a3267d2569e8535ebaf3bee3e0dc4369ba398cd1 Mon Sep 17 00:00:00 2001
From: Benjamin Shafii <ben@prologe.io>
Date: Mon, 4 May 2026 12:38:39 -0700
Subject: [PATCH 3/4] ci: add isolated openwork-ui-mcp check and publish
 workflow

---
 .github/workflows/ci-openwork-ui-mcp.yml | 77 ++++++++++++++++++++++++
 docs/mcp-ui-control-profile.md           | 14 +++++
 packages/openwork-ui-mcp/package.json    |  9 +++
 3 files changed, 100 insertions(+)
 create mode 100644 .github/workflows/ci-openwork-ui-mcp.yml

diff --git a/.github/workflows/ci-openwork-ui-mcp.yml b/.github/workflows/ci-openwork-ui-mcp.yml
new file mode 100644
index 0000000000..739bd8bf1b
--- /dev/null
+++ b/.github/workflows/ci-openwork-ui-mcp.yml
@@ -0,0 +1,77 @@
+name: openwork-ui-mcp
+
+on:
+  push:
+    branches: [dev]
+    paths:
+      - "packages/openwork-ui-mcp/**"
+      - ".github/workflows/ci-openwork-ui-mcp.yml"
+    tags:
+      - "openwork-ui-mcp-v*"
+  pull_request:
+    branches: [dev]
+    paths:
+      - "packages/openwork-ui-mcp/**"
+      - ".github/workflows/ci-openwork-ui-mcp.yml"
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    working-directory: packages/openwork-ui-mcp
+
+jobs:
+  check:
+    name: Syntax & dry-run publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm install --ignore-scripts
+
+      - name: Syntax check
+        run: node --check index.mjs
+
+      - name: Dry-run publish
+        run: npm publish --dry-run --access public
+
+  publish:
+    name: Publish to npm
+    needs: check
+    if: startsWith(github.ref, 'refs/tags/openwork-ui-mcp-v')
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm install --ignore-scripts
+
+      - name: Syntax check
+        run: node --check index.mjs
+
+      - name: Publish
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/docs/mcp-ui-control-profile.md b/docs/mcp-ui-control-profile.md
index 9e9016ec05..77069631ec 100644
--- a/docs/mcp-ui-control-profile.md
+++ b/docs/mcp-ui-control-profile.md
@@ -34,6 +34,20 @@ That's it. HandsFree can now list your sessions, read transcripts, type into the
 - `ui_execute_action` — run an action by ID, e.g. `session.create_task`, `composer.set_text`, `composer.send`.
 - `ui_status` — check if OpenWork is running and the bridge is reachable.
 
+## Install
+
+```bash
+npm install -g openwork-ui-mcp
+```
+
+Or run without installing:
+
+```bash
+npx openwork-ui-mcp
+```
+
+> The package is [`openwork-ui-mcp` on npm](https://www.npmjs.com/package/openwork-ui-mcp).
+
 ## Add to OpenCode
 
 Add the MCP server to your workspace or global `opencode.json`:
diff --git a/packages/openwork-ui-mcp/package.json b/packages/openwork-ui-mcp/package.json
index 6dd039c31a..36b8cd9ed1 100644
--- a/packages/openwork-ui-mcp/package.json
+++ b/packages/openwork-ui-mcp/package.json
@@ -9,6 +9,15 @@
     "openwork-ui-mcp": "./index.mjs"
   },
   "files": ["index.mjs"],
+  "scripts": {
+    "check": "node --check index.mjs",
+    "test": "node --check index.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/different-ai/openwork.git",
+    "directory": "packages/openwork-ui-mcp"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.25.76"

From 84d3df41038067824b338680f08d900338eb347b Mon Sep 17 00:00:00 2001
From: Benjamin Shafii <ben@prologe.io>
Date: Mon, 4 May 2026 13:06:12 -0700
Subject: [PATCH 4/4] fix: harden UI control bridge

---
 .../control/session-control-actions.ts        | 106 ++++++----
 .../session/surface/session-surface.tsx       |  20 +-
 .../shell/control/control-provider.tsx        | 186 +++++++++++-------
 .../app/src/react-app/shell/session-route.tsx |  18 +-
 apps/desktop/electron/main.mjs                |  28 +--
 packages/openwork-ui-mcp/index.mjs            | 114 ++++++++---
 packages/openwork-ui-mcp/package.json         |   9 +-
 7 files changed, 320 insertions(+), 161 deletions(-)

diff --git a/apps/app/src/react-app/domains/session/control/session-control-actions.ts b/apps/app/src/react-app/domains/session/control/session-control-actions.ts
index 1783574350..df30825a8d 100644
--- a/apps/app/src/react-app/domains/session/control/session-control-actions.ts
+++ b/apps/app/src/react-app/domains/session/control/session-control-actions.ts
@@ -49,19 +49,48 @@ function findSessionWorkspace(
   ).some((session) => session.id === sessionId));
 }
 
+function objectArgs(args: unknown) {
+  return args && typeof args === "object" ? args as Record<string, unknown> : {};
+}
+
+function stringArg(args: unknown, name: string) {
+  const value = objectArgs(args)[name];
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function booleanArg(args: unknown, name: string) {
+  return objectArgs(args)[name] === true;
+}
+
 export function useSessionControlActions(input: UseSessionControlActionsInput) {
+  const {
+    canCreateTask,
+    createTaskInWorkspace,
+    navigateToSession,
+    navigateToSessionRoot,
+    openModelPicker,
+    openworkClient,
+    opencodeClient,
+    refreshRouteState,
+    selectedSessionId,
+    selectedWorkspaceId,
+    selectedWorkspaceRoot,
+    sessionsByWorkspaceId,
+    workspaces,
+  } = input;
+
   const createTaskControlAction = useMemo<OpenworkControlAction>(() => ({
     id: "session.create_task",
     label: "Create a new task",
     description: "Create a new session in the selected workspace.",
     sideEffect: "mutation",
-    disabled: !input.canCreateTask || !input.selectedWorkspaceId,
+    disabled: !canCreateTask || !selectedWorkspaceId,
     execute: async () => {
-      if (!input.selectedWorkspaceId) return false;
-      await input.createTaskInWorkspace(input.selectedWorkspaceId);
+      if (!selectedWorkspaceId) return false;
+      await createTaskInWorkspace(selectedWorkspaceId);
       return true;
     },
-  }), [input]);
+  }), [canCreateTask, createTaskInWorkspace, selectedWorkspaceId]);
   useControlAction(createTaskControlAction);
 
   const listSessionsControlAction = useMemo<OpenworkControlAction>(() => ({
@@ -71,8 +100,8 @@ export function useSessionControlActions(input: UseSessionControlActionsInput) {
     sideEffect: "none",
     execute: () => {
       const out: { sessionId: string; title: string; workspace: string; updatedAt: number }[] = [];
-      for (const workspace of input.workspaces) {
-        const list = input.sessionsByWorkspaceId[workspace.id] ?? [];
+      for (const workspace of workspaces) {
+        const list = sessionsByWorkspaceId[workspace.id] ?? [];
         for (const session of list) {
           const sessionId = session.id?.trim() ?? "";
           if (!sessionId) continue;
@@ -84,7 +113,7 @@ export function useSessionControlActions(input: UseSessionControlActionsInput) {
       out.sort((a, b) => b.updatedAt - a.updatedAt);
       return out.slice(0, 30);
     },
-  }), [input]);
+  }), [sessionsByWorkspaceId, workspaces]);
   useControlAction(listSessionsControlAction);
 
   const openSessionControlAction = useMemo<OpenworkControlAction>(() => ({
@@ -93,15 +122,14 @@ export function useSessionControlActions(input: UseSessionControlActionsInput) {
     description: "Navigate to a specific session. Use list_sessions first to get the session ID.",
     sideEffect: "navigation",
     requiresArgs: true,
+    args: [{ name: "sessionId", type: "string", required: true, description: "Session ID from session.list_sessions." }],
     execute: (args) => {
-      const sessionId = typeof args === "object" && args && "sessionId" in args && typeof (args as { sessionId?: unknown }).sessionId === "string"
-        ? (args as { sessionId: string }).sessionId.trim()
-        : "";
+      const sessionId = stringArg(args, "sessionId");
       if (!sessionId) return { ok: false, error: "sessionId is required" };
-      input.navigateToSession(sessionId);
+      navigateToSession(sessionId);
       return { ok: true, navigatedTo: sessionId };
     },
-  }), [input]);
+  }), [navigateToSession]);
   useControlAction(openSessionControlAction);
 
   const renameSessionControlAction = useMemo<OpenworkControlAction>(() => ({
@@ -110,25 +138,28 @@ export function useSessionControlActions(input: UseSessionControlActionsInput) {
     description: "Rename a session by ID. Use list_sessions first to match the title the user said.",
     sideEffect: "mutation",
     requiresArgs: true,
-    disabled: !input.opencodeClient,
+    args: [
+      { name: "sessionId", type: "string", required: true, description: "Session ID from session.list_sessions." },
+      { name: "title", type: "string", required: true, description: "New session title." },
+    ],
+    disabled: !opencodeClient,
     execute: async (args) => {
-      const payload = args && typeof args === "object" ? args as { sessionId?: unknown; title?: unknown } : {};
-      const sessionId = typeof payload.sessionId === "string" ? payload.sessionId.trim() : "";
-      const title = typeof payload.title === "string" ? payload.title.trim() : "";
+      const sessionId = stringArg(args, "sessionId");
+      const title = stringArg(args, "title");
       if (!sessionId) return { ok: false, error: "sessionId is required" };
       if (!title) return { ok: false, error: "title is required" };
-      if (!input.opencodeClient) return { ok: false, error: "OpenCode client is not connected" };
+      if (!opencodeClient) return { ok: false, error: "OpenCode client is not connected" };
 
-      const targetWorkspace = findSessionWorkspace(input.workspaces, input.sessionsByWorkspaceId, sessionId);
-      await input.opencodeClient.session.update({
+      const targetWorkspace = findSessionWorkspace(workspaces, sessionsByWorkspaceId, sessionId);
+      await opencodeClient.session.update({
         sessionID: sessionId,
         title,
-        directory: targetWorkspace?.path || input.selectedWorkspaceRoot || undefined,
+        directory: targetWorkspace?.path || selectedWorkspaceRoot || undefined,
       });
-      await input.refreshRouteState();
+      await refreshRouteState();
       return { ok: true, sessionId, title };
     },
-  }), [input]);
+  }), [opencodeClient, refreshRouteState, selectedWorkspaceRoot, sessionsByWorkspaceId, workspaces]);
   useControlAction(renameSessionControlAction);
 
   const deleteSessionControlAction = useMemo<OpenworkControlAction>(() => ({
@@ -138,25 +169,28 @@ export function useSessionControlActions(input: UseSessionControlActionsInput) {
     sideEffect: "mutation",
     requiresArgs: true,
     requiresConfirmation: true,
-    disabled: !input.openworkClient,
+    args: [
+      { name: "sessionId", type: "string", required: true, description: "Session ID from session.list_sessions." },
+      { name: "confirmed", type: "boolean", required: true, description: "Must be true after explicit user confirmation." },
+    ],
+    disabled: !openworkClient,
     execute: async (args) => {
-      const payload = args && typeof args === "object" ? args as { sessionId?: unknown; confirmed?: unknown } : {};
-      const sessionId = typeof payload.sessionId === "string" ? payload.sessionId.trim() : "";
-      const confirmed = payload.confirmed === true;
+      const sessionId = stringArg(args, "sessionId");
+      const confirmed = booleanArg(args, "confirmed");
       if (!sessionId) return { ok: false, error: "sessionId is required" };
       if (!confirmed) return { ok: false, error: "Deletion requires confirmed: true after explicit user confirmation" };
-      if (!input.openworkClient) return { ok: false, error: "OpenWork server is not connected" };
+      if (!openworkClient) return { ok: false, error: "OpenWork server is not connected" };
 
-      const targetWorkspace = findSessionWorkspace(input.workspaces, input.sessionsByWorkspaceId, sessionId);
+      const targetWorkspace = findSessionWorkspace(workspaces, sessionsByWorkspaceId, sessionId);
       if (!targetWorkspace) return { ok: false, error: "Session was not found in the current session list" };
-      await input.openworkClient.deleteSession(targetWorkspace.id, sessionId);
-      if (input.selectedSessionId === sessionId) {
-        input.navigateToSessionRoot();
+      await openworkClient.deleteSession(targetWorkspace.id, sessionId);
+      if (selectedSessionId === sessionId) {
+        navigateToSessionRoot();
       }
-      await input.refreshRouteState();
+      await refreshRouteState();
       return { ok: true, sessionId, deleted: true };
     },
-  }), [input]);
+  }), [navigateToSessionRoot, openworkClient, refreshRouteState, selectedSessionId, sessionsByWorkspaceId, workspaces]);
   useControlAction(deleteSessionControlAction);
 
   const modelPickerControlAction = useMemo<OpenworkControlAction>(() => ({
@@ -164,8 +198,8 @@ export function useSessionControlActions(input: UseSessionControlActionsInput) {
     label: "Open the model picker",
     description: "Open the current session model picker.",
     sideEffect: "none",
-    disabled: !input.selectedWorkspaceId,
-    execute: input.openModelPicker,
-  }), [input]);
+    disabled: !selectedWorkspaceId,
+    execute: openModelPicker,
+  }), [openModelPicker, selectedWorkspaceId]);
   useControlAction(modelPickerControlAction);
 }
diff --git a/apps/app/src/react-app/domains/session/surface/session-surface.tsx b/apps/app/src/react-app/domains/session/surface/session-surface.tsx
index eeb7e114de..202e6d1d58 100644
--- a/apps/app/src/react-app/domains/session/surface/session-surface.tsx
+++ b/apps/app/src/react-app/domains/session/surface/session-surface.tsx
@@ -43,6 +43,7 @@ import {
 
 const EMPTY_TRANSCRIPT: UIMessage[] = [];
 const IDLE_STATUS: SessionStatus = { type: "idle" };
+const DEFAULT_COMPOSER_CONTROL_TEXT = "Help me outline the next OpenWork task.";
 
 type SessionError = {
   message: string;
@@ -116,13 +117,13 @@ function statusLabel(snapshot: OpenworkSessionSnapshot | undefined, busy: boolea
   return "Ready";
 }
 
-function controlTextArgument(args: unknown, fallback: string) {
+function controlTextArgument(args: unknown) {
   if (typeof args === "string") return args;
   if (args && typeof args === "object" && "text" in args) {
     const text = (args as { text?: unknown }).text;
     if (typeof text === "string") return text;
   }
-  return fallback;
+  return DEFAULT_COMPOSER_CONTROL_TEXT;
 }
 
 const waitForControl = (ms: number) => new Promise((resolve) => window.setTimeout(resolve, ms));
@@ -616,13 +617,8 @@ export function SessionSurface(props: SessionSurfaceProps) {
 
   const typeComposerText = useCallback(async (text: string) => {
     window.dispatchEvent(new Event("openwork:focusPrompt"));
-    setDraft("");
-    let next = "";
-    for (const char of text) {
-      next += char;
-      setDraft(next);
-      await waitForControl(char === "\n" ? 80 : 18);
-    }
+    setDraft(text);
+    await waitForControl(40);
   }, []);
 
   const composerSetTextControlAction = useMemo<OpenworkControlAction>(() => ({
@@ -631,10 +627,11 @@ export function SessionSurface(props: SessionSurfaceProps) {
     description: "Replace the current session draft and type the supplied text visibly.",
     sideEffect: "none",
     requiresArgs: true,
-    previewArgs: { text: "Help me outline the next OpenWork task." },
+    args: [{ name: "text", type: "string", required: true, description: "Prompt text to place in the composer." }],
+    previewArgs: { text: DEFAULT_COMPOSER_CONTROL_TEXT },
     targetRef: composerShellRef,
     execute: async (args, helpers) => {
-      const text = controlTextArgument(args, "Help me outline the next OpenWork task.");
+      const text = controlTextArgument(args);
       helpers.setNarration(`Typing ${text.length.toLocaleString()} characters into the composer…`);
       await typeComposerText(text);
       props.onDraftChange(buildDraft(text, attachments));
@@ -796,6 +793,7 @@ export function SessionSurface(props: SessionSurfaceProps) {
     label: "Read the current session transcript",
     description: "Return the last messages from the current session transcript as readable text, including the session ID, title, and message count.",
     sideEffect: "none",
+    args: [{ name: "count", type: "number", required: false, description: "Number of recent messages to return, from 1 to 30. Defaults to 10." }],
     execute: (args) => {
       const count = typeof args === "object" && args !== null && "count" in args && typeof (args as { count?: unknown }).count === "number"
         ? Math.min(Math.max(1, (args as { count: number }).count), 30)
diff --git a/apps/app/src/react-app/shell/control/control-provider.tsx b/apps/app/src/react-app/shell/control/control-provider.tsx
index a3924cc541..eb89393e1a 100644
--- a/apps/app/src/react-app/shell/control/control-provider.tsx
+++ b/apps/app/src/react-app/shell/control/control-provider.tsx
@@ -13,6 +13,13 @@ import { useLocation, useNavigate } from "react-router-dom";
 
 export type OpenworkControlSideEffect = "none" | "navigation" | "mutation" | "external";
 
+export type OpenworkControlActionArg = {
+  name: string;
+  type?: "string" | "number" | "boolean" | "object" | "array" | "unknown";
+  required?: boolean;
+  description?: string;
+};
+
 export type OpenworkControlActionMetadata = {
   id: string;
   label: string;
@@ -21,6 +28,8 @@ export type OpenworkControlActionMetadata = {
   requiresConfirmation: boolean;
   requiresArgs: boolean;
   hasPreviewArgs: boolean;
+  previewArgs?: unknown;
+  args?: OpenworkControlActionArg[];
   disabled: boolean;
   busy: boolean;
 };
@@ -54,15 +63,22 @@ export type OpenworkControlAction = {
   sideEffect?: OpenworkControlSideEffect;
   requiresConfirmation?: boolean;
   requiresArgs?: boolean;
+  args?: OpenworkControlActionArg[];
   previewArgs?: unknown;
   disabled?: boolean;
   targetRef?: OpenworkControlTargetRef;
   execute: (args: unknown, helpers: OpenworkControlHelpers) => unknown | Promise<unknown>;
 };
 
-type RegisteredAction = OpenworkControlAction & {
+type ControlActionRef = {
+  readonly current: OpenworkControlAction | null;
+};
+
+type RegisteredAction = {
+  id: string;
   order: number;
   token: symbol;
+  ref: ControlActionRef;
 };
 
 type SpotlightState = {
@@ -78,7 +94,7 @@ type OpenworkControlContextValue = {
   narration: string;
   busyActionId: string | null;
   actions: OpenworkControlActionMetadata[];
-  registerAction: (action: OpenworkControlAction) => () => void;
+  registerAction: (actionId: string, actionRef: ControlActionRef) => () => void;
   executeAction: (actionId: string, args?: unknown) => Promise<OpenworkControlResult>;
   snapshot: () => OpenworkControlSnapshot;
 };
@@ -100,6 +116,14 @@ declare global {
 
 const CONTROL_API_VERSION = 1;
 const OpenworkControlContext = createContext<OpenworkControlContextValue | null>(null);
+const SPOTLIGHT_TIMING_MS = Object.freeze({
+  missingTarget: 80,
+  scrollIntoView: 180,
+  target: 260,
+  press: 130,
+  release: 80,
+  done: 280,
+});
 
 const wait = (ms: number) => new Promise((resolve) => window.setTimeout(resolve, ms));
 
@@ -107,21 +131,33 @@ function describeError(error: unknown) {
   return error instanceof Error ? error.message : String(error || "Unknown error");
 }
 
+function returnedActionError(result: unknown) {
+  if (!result || typeof result !== "object") return null;
+  const payload = result as { ok?: unknown; error?: unknown };
+  if (payload.ok !== false) return null;
+  return typeof payload.error === "string" && payload.error.trim()
+    ? payload.error
+    : "Action returned an error.";
+}
+
 function isBrowser() {
   return typeof window !== "undefined" && typeof document !== "undefined";
 }
 
-function metadataForAction(action: RegisteredAction, busyActionId: string | null): OpenworkControlActionMetadata {
+function metadataForAction(registered: RegisteredAction, busyActionId: string | null): OpenworkControlActionMetadata {
+  const action = registered.ref.current;
   return {
-    id: action.id,
-    label: action.label,
-    description: action.description,
-    sideEffect: action.sideEffect ?? "none",
-    requiresConfirmation: action.requiresConfirmation === true,
-    requiresArgs: action.requiresArgs === true,
-    hasPreviewArgs: action.previewArgs !== undefined,
-    disabled: action.disabled === true,
-    busy: busyActionId === action.id,
+    id: registered.id,
+    label: action?.label ?? registered.id,
+    description: action?.description,
+    sideEffect: action?.sideEffect ?? "none",
+    requiresConfirmation: action?.requiresConfirmation === true,
+    requiresArgs: action?.requiresArgs === true,
+    hasPreviewArgs: action?.previewArgs !== undefined,
+    previewArgs: action?.previewArgs,
+    args: action?.args,
+    disabled: action?.disabled === true,
+    busy: busyActionId === registered.id,
   };
 }
 
@@ -154,6 +190,8 @@ export function OpenworkControlProvider({ children }: { children: ReactNode }) {
   const [busyActionId, setBusyActionId] = useState<string | null>(null);
   const [narration, setNarration] = useState("Control mode is off.");
   const [spotlight, setSpotlight] = useState<SpotlightState>({ visible: false, phase: "target", rect: null });
+  const busyActionIdRef = useRef<string | null>(null);
+  const spotlightRunRef = useRef(0);
 
   const route = `${location.pathname}${location.search}${location.hash}`;
   const enabled = enabledState;
@@ -163,12 +201,16 @@ export function OpenworkControlProvider({ children }: { children: ReactNode }) {
     setEnabledState(nextEnabled);
   }, []);
 
-  const actions = useMemo(() => {
+  const listActionMetadata = useCallback((nextBusyActionId = busyActionId) => {
     return Array.from(actionsRef.current.values())
       .sort((left, right) => left.order - right.order)
-      .map((action) => metadataForAction(action, busyActionId));
+      .map((action) => metadataForAction(action, nextBusyActionId));
   }, [busyActionId, version]);
 
+  const actions = useMemo(() => {
+    return listActionMetadata();
+  }, [listActionMetadata]);
+
   const snapshot = useCallback((): OpenworkControlSnapshot => ({
     version: CONTROL_API_VERSION,
     enabled,
@@ -176,39 +218,41 @@ export function OpenworkControlProvider({ children }: { children: ReactNode }) {
     status,
     busyActionId,
     narration,
-    actions: Array.from(actionsRef.current.values())
-      .sort((left, right) => left.order - right.order)
-      .map((action) => metadataForAction(action, busyActionId)),
-  }), [busyActionId, enabled, narration, route, status]);
-
-  const registerAction = useCallback((action: OpenworkControlAction) => {
-    const token = Symbol(action.id);
-    const previous = actionsRef.current.get(action.id);
-    const registered = action as RegisteredAction;
-    registered.order = previous?.order ?? nextOrderRef.current++;
-    registered.token = token;
-    actionsRef.current.set(action.id, registered);
+    actions: listActionMetadata(),
+  }), [busyActionId, enabled, listActionMetadata, narration, route, status]);
+
+  const registerAction = useCallback((actionId: string, actionRef: ControlActionRef) => {
+    const token = Symbol(actionId);
+    const previous = actionsRef.current.get(actionId);
+    actionsRef.current.set(actionId, {
+      id: actionId,
+      order: previous?.order ?? nextOrderRef.current++,
+      token,
+      ref: actionRef,
+    });
     setVersion((current) => current + 1);
 
     return () => {
-      const current = actionsRef.current.get(action.id);
+      const current = actionsRef.current.get(actionId);
       if (current?.token === token) {
-        actionsRef.current.delete(action.id);
+        actionsRef.current.delete(actionId);
         setVersion((value) => value + 1);
       }
     };
   }, []);
 
-  const playTargetChoreography = useCallback(async (action: RegisteredAction) => {
+  const playTargetChoreography = useCallback(async (action: OpenworkControlAction, runId: number) => {
     if (!isBrowser()) return;
+    const stillCurrent = () => spotlightRunRef.current === runId;
     const target = action.targetRef?.current;
     if (!target) {
-      await wait(80);
+      await wait(SPOTLIGHT_TIMING_MS.missingTarget);
       return;
     }
 
     target.scrollIntoView({ block: "center", inline: "nearest", behavior: "smooth" });
-    await wait(180);
+    await wait(SPOTLIGHT_TIMING_MS.scrollIntoView);
+    if (!stillCurrent() || !target.isConnected) return;
     const rect = target.getBoundingClientRect();
     setSpotlight({
       visible: true,
@@ -220,46 +264,65 @@ export function OpenworkControlProvider({ children }: { children: ReactNode }) {
         height: rect.height,
       },
     });
-    await wait(260);
+    await wait(SPOTLIGHT_TIMING_MS.target);
+    if (!stillCurrent()) return;
     setSpotlight((current) => ({ ...current, phase: "press" }));
-    await wait(130);
+    await wait(SPOTLIGHT_TIMING_MS.press);
+    if (!stillCurrent()) return;
     setSpotlight((current) => ({ ...current, phase: "target" }));
-    await wait(80);
+    await wait(SPOTLIGHT_TIMING_MS.release);
   }, []);
 
   const executeAction = useCallback(async (actionId: string, args?: unknown): Promise<OpenworkControlResult> => {
-    const action = actionsRef.current.get(actionId);
-    if (!action) return { ok: false, actionId, error: `Unknown action: ${actionId}` };
+    const registered = actionsRef.current.get(actionId);
+    const action = registered?.ref.current;
+    if (!registered || !action) return { ok: false, actionId, error: `Unknown action: ${actionId}` };
     if (action.disabled) return { ok: false, actionId, error: `Action is disabled: ${action.label}` };
-    if (busyActionId) return { ok: false, actionId, error: `Already acting: ${busyActionId}` };
+    if (busyActionIdRef.current) return { ok: false, actionId, error: `Already acting: ${busyActionIdRef.current}` };
 
     if (action.requiresConfirmation && isBrowser()) {
       const confirmed = window.confirm(`Allow Control Mode to ${action.label}?`);
       if (!confirmed) return { ok: false, actionId, error: "User cancelled action." };
     }
 
+    const runId = spotlightRunRef.current + 1;
+    spotlightRunRef.current = runId;
+    busyActionIdRef.current = action.id;
     setEnabled(true);
     setBusyActionId(action.id);
     setNarration(`Moving to ${action.label}…`);
 
     try {
-      await playTargetChoreography(action);
+      await playTargetChoreography(action, runId);
       setNarration(`Running ${action.label}…`);
       const effectiveArgs = args === undefined ? action.previewArgs : args;
       const result = await action.execute(effectiveArgs, { setNarration });
+      const resultError = returnedActionError(result);
+      if (resultError) {
+        setNarration(`Could not ${action.label}: ${resultError}`);
+        if (spotlightRunRef.current === runId) {
+          setSpotlight({ visible: false, phase: "target", rect: null });
+        }
+        return { ok: false, actionId, error: resultError };
+      }
       setNarration(`Done: ${action.label}`);
-      await wait(280);
-      setSpotlight({ visible: false, phase: "target", rect: null });
+      await wait(SPOTLIGHT_TIMING_MS.done);
+      if (spotlightRunRef.current === runId) {
+        setSpotlight({ visible: false, phase: "target", rect: null });
+      }
       return { ok: true, actionId, result };
     } catch (error) {
       const message = describeError(error);
       setNarration(`Could not ${action.label}: ${message}`);
-      setSpotlight({ visible: false, phase: "target", rect: null });
+      if (spotlightRunRef.current === runId) {
+        setSpotlight({ visible: false, phase: "target", rect: null });
+      }
       return { ok: false, actionId, error: message };
     } finally {
+      if (busyActionIdRef.current === action.id) busyActionIdRef.current = null;
       setBusyActionId(null);
     }
-  }, [busyActionId, playTargetChoreography, setEnabled]);
+  }, [playTargetChoreography, setEnabled]);
 
   const value = useMemo<OpenworkControlContextValue>(() => ({
     enabled,
@@ -307,6 +370,10 @@ export function OpenworkControlProvider({ children }: { children: ReactNode }) {
     };
   }, [executeAction, setEnabled, snapshot]);
 
+  useEffect(() => {
+    busyActionIdRef.current = busyActionId;
+  }, [busyActionId]);
+
   useEffect(() => {
     const next = snapshot();
     listenersRef.current.forEach((listener) => listener(next));
@@ -333,40 +400,7 @@ export function useControlAction(action: OpenworkControlAction | null | false |
 
   useEffect(() => {
     if (!registerAction || !actionId) return undefined;
-    const current = () => latestActionRef.current;
-    const proxy: OpenworkControlAction = {
-      id: actionId,
-      get label() {
-        return current()?.label ?? actionId;
-      },
-      get description() {
-        return current()?.description;
-      },
-      get sideEffect() {
-        return current()?.sideEffect;
-      },
-      get requiresConfirmation() {
-        return current()?.requiresConfirmation;
-      },
-      get requiresArgs() {
-        return current()?.requiresArgs;
-      },
-      get previewArgs() {
-        return current()?.previewArgs;
-      },
-      get disabled() {
-        return current()?.disabled;
-      },
-      get targetRef() {
-        return current()?.targetRef;
-      },
-      execute(args, helpers) {
-        const latest = current();
-        if (!latest) return undefined;
-        return latest.execute(args, helpers);
-      },
-    };
-    return registerAction(proxy);
+    return registerAction(actionId, latestActionRef);
   }, [actionId, registerAction]);
 }
 
diff --git a/apps/app/src/react-app/shell/session-route.tsx b/apps/app/src/react-app/shell/session-route.tsx
index 6d0cdb13b8..0049264c66 100644
--- a/apps/app/src/react-app/shell/session-route.tsx
+++ b/apps/app/src/react-app/shell/session-route.tsx
@@ -1547,6 +1547,18 @@ export function SessionRoute() {
     return () => window.removeEventListener("keydown", handler);
   }, [canCreateTask, handleCreateTaskInWorkspace, selectedWorkspaceId]);
 
+  const navigateToSessionForControl = useCallback((sessionId: string) => {
+    navigate(`/session/${sessionId}`);
+  }, [navigate]);
+
+  const navigateToSessionRootForControl = useCallback(() => {
+    navigate("/session");
+  }, [navigate]);
+
+  const openModelPickerForControl = useCallback(() => {
+    setModelPickerOpen(true);
+  }, []);
+
   useSessionControlActions({
     workspaces,
     sessionsByWorkspaceId,
@@ -1556,10 +1568,10 @@ export function SessionRoute() {
     canCreateTask,
     openworkClient: client,
     opencodeClient,
-    navigateToSession: (sessionId) => navigate(`/session/${sessionId}`),
-    navigateToSessionRoot: () => navigate("/session"),
+    navigateToSession: navigateToSessionForControl,
+    navigateToSessionRoot: navigateToSessionRootForControl,
     createTaskInWorkspace: handleCreateTaskInWorkspace,
-    openModelPicker: () => setModelPickerOpen(true),
+    openModelPicker: openModelPickerForControl,
     refreshRouteState,
   });
 
diff --git a/apps/desktop/electron/main.mjs b/apps/desktop/electron/main.mjs
index ccb2c0ad05..8fb30b8037 100644
--- a/apps/desktop/electron/main.mjs
+++ b/apps/desktop/electron/main.mjs
@@ -1374,22 +1374,28 @@ function authorizedUiControlRequest(request) {
   return auth === `Bearer ${uiControlToken}`;
 }
 
-async function evaluateOpenworkControl(expression) {
+function jsonForJavaScript(value) {
+  return JSON.stringify(JSON.stringify(value ?? {}));
+}
+
+async function evaluateOpenworkControl(expression, options = {}) {
   const win = await createMainWindow();
-  win.show();
-  if (win.isMinimized()) win.restore();
-  win.focus();
+  if (options.focus === true) {
+    win.show();
+    if (win.isMinimized()) win.restore();
+    win.focus();
+  }
   return win.webContents.executeJavaScript(expression, true);
 }
 
 async function runOpenworkControlCommand(command, args = {}) {
-  const serializedArgs = JSON.stringify(args ?? {}).replace(/</g, "\\u003c");
+  const argsJsonLiteral = jsonForJavaScript(args);
   if (command === "snapshot") {
     return evaluateOpenworkControl(`(async () => {
       const control = window.__openworkControl;
       if (!control) return { ok: false, error: "OpenWork control surface is not available yet." };
       control.setEnabled?.(true);
-      return { ok: true, snapshot: control.snapshot() };
+      return { ok: true, ...control.snapshot() };
     })()`);
   }
   if (command === "actions") {
@@ -1403,15 +1409,14 @@ async function runOpenworkControlCommand(command, args = {}) {
   if (command === "execute") {
     return evaluateOpenworkControl(`(async () => {
       const control = window.__openworkControl;
-      const input = ${serializedArgs};
+      const input = JSON.parse(${argsJsonLiteral});
       if (!control) return { ok: false, error: "OpenWork control surface is not available yet." };
       if (!input || typeof input.actionId !== "string" || !input.actionId.trim()) {
         return { ok: false, error: "Missing OpenWork actionId." };
       }
       control.setEnabled?.(true);
-      const result = await control.execute(input.actionId, input.args ?? {});
-      return { ok: true, result };
-    })()`);
+      return control.execute(input.actionId, input.args ?? {});
+    })()`, { focus: true });
   }
   return { ok: false, error: `Unknown OpenWork control command: ${command}` };
 }
@@ -1456,7 +1461,7 @@ async function startUiControlServer() {
   uiControlDiscoveryPath = path.join(app.getPath("userData"), "openwork-ui-control.json");
   await writeFile(
     uiControlDiscoveryPath,
-    `${JSON.stringify({ version: 1, app: APP_NAME, baseUrl: `http://127.0.0.1:${port}`, token: uiControlToken }, null, 2)}\n`,
+    `${JSON.stringify({ version: 1, app: APP_NAME, identifier: APP_IDENTIFIER, platform: process.platform, baseUrl: `http://127.0.0.1:${port}`, token: uiControlToken }, null, 2)}\n`,
     "utf8",
   );
 }
@@ -1464,6 +1469,7 @@ async function startUiControlServer() {
 async function stopUiControlServer() {
   if (uiControlDiscoveryPath) {
     await rm(uiControlDiscoveryPath, { force: true }).catch(() => undefined);
+    uiControlDiscoveryPath = null;
   }
   if (!uiControlServer) return;
   await new Promise((resolve) => uiControlServer.close(() => resolve(undefined)));
diff --git a/packages/openwork-ui-mcp/index.mjs b/packages/openwork-ui-mcp/index.mjs
index 98b920c19c..4ae7d344cc 100644
--- a/packages/openwork-ui-mcp/index.mjs
+++ b/packages/openwork-ui-mcp/index.mjs
@@ -24,25 +24,49 @@
 
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { homedir } from "node:os";
+import { homedir, platform } from "node:os";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 
 // ── Bridge discovery ──
 
-const DISCOVERY_PATHS = [
-  join(homedir(), "Library", "Application Support", "com.differentai.openwork", "openwork-ui-control.json"),
-  join(homedir(), "Library", "Application Support", "com.differentai.openwork.dev", "openwork-ui-control.json"),
-];
+const DISCOVERY_FILE = "openwork-ui-control.json";
+const BRIDGE_CACHE_MS = 2_000;
+const BRIDGE_TIMEOUT_MS = 5_000;
+let cachedBridge = null;
+let cachedBridgeAt = 0;
+
+function userAppDataDir() {
+  if (platform() === "darwin") return join(homedir(), "Library", "Application Support");
+  if (platform() === "win32") return process.env.APPDATA || join(homedir(), "AppData", "Roaming");
+  return process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+}
+
+function discoveryPaths() {
+  return [
+    process.env.OPENWORK_UI_CONTROL_DISCOVERY?.trim(),
+    join(userAppDataDir(), "com.differentai.openwork", DISCOVERY_FILE),
+    join(userAppDataDir(), "com.differentai.openwork.dev", DISCOVERY_FILE),
+  ].filter(Boolean);
+}
+
+function clearBridgeCache() {
+  cachedBridge = null;
+  cachedBridgeAt = 0;
+}
 
 async function discoverBridge() {
-  for (const candidate of DISCOVERY_PATHS) {
+  if (cachedBridge && Date.now() - cachedBridgeAt < BRIDGE_CACHE_MS) return cachedBridge;
+
+  for (const candidate of discoveryPaths()) {
     try {
       const raw = await readFile(candidate, "utf8");
       const parsed = JSON.parse(raw);
       if (typeof parsed.baseUrl === "string" && typeof parsed.token === "string") {
-        return { baseUrl: parsed.baseUrl, token: parsed.token, path: candidate };
+        cachedBridge = { baseUrl: parsed.baseUrl, token: parsed.token, path: candidate };
+        cachedBridgeAt = Date.now();
+        return cachedBridge;
       }
     } catch {
       // Try next
@@ -64,6 +88,7 @@ async function bridgeRequest(path, options = {}) {
   try {
     const response = await fetch(url, {
       method: options.method || "GET",
+      signal: AbortSignal.timeout(options.timeoutMs ?? BRIDGE_TIMEOUT_MS),
       headers: {
         Authorization: `Bearer ${bridge.token}`,
         ...(options.body ? { "Content-Type": "application/json" } : {}),
@@ -72,15 +97,61 @@ async function bridgeRequest(path, options = {}) {
     });
     const text = await response.text();
     try {
-      return JSON.parse(text);
+      const parsed = JSON.parse(text);
+      if (!response.ok) clearBridgeCache();
+      return parsed;
     } catch {
+      if (!response.ok) clearBridgeCache();
       return { ok: false, error: text || `HTTP ${response.status}` };
     }
   } catch (error) {
+    clearBridgeCache();
     return { ok: false, error: `Bridge unreachable at ${url}: ${error.message}` };
   }
 }
 
+function formatArgs(action) {
+  const lines = [];
+  if (Array.isArray(action.args) && action.args.length > 0) {
+    lines.push("    Args:");
+    for (const arg of action.args) {
+      const required = arg.required ? "required" : "optional";
+      const type = arg.type || "unknown";
+      lines.push(`      - ${arg.name} (${type}, ${required})${arg.description ? `: ${arg.description}` : ""}`);
+    }
+  } else if (action.requiresArgs) {
+    lines.push("    Args: required; this action has not published detailed argument metadata yet.");
+  }
+  if (action.previewArgs !== undefined) {
+    lines.push(`    Example: ${JSON.stringify(action.previewArgs)}`);
+  }
+  return lines.join("\n");
+}
+
+function formatActionLine(action) {
+  const disabled = action.disabled ? " [disabled]" : "";
+  const busy = action.busy ? " [busy]" : "";
+  const args = formatArgs(action);
+  return `${action.id}${disabled}${busy}\n    ${action.label || ""}${action.description ? ` — ${action.description}` : ""}${args ? `\n${args}` : ""}`;
+}
+
+function formatExecutionResult(actionId, result) {
+  const payload = result?.result ?? result;
+  if (payload === true || payload === undefined || payload === null) return `Executed ${actionId}.`;
+  if (typeof payload === "string") return payload;
+  if (typeof payload === "number" || typeof payload === "boolean") return `Result: ${payload}`;
+  if (typeof payload === "object") {
+    const lines = [`Executed ${actionId}.`];
+    for (const [key, value] of Object.entries(payload).slice(0, 12)) {
+      if (key === "ok" || key === "actionId") continue;
+      const rendered = typeof value === "object" ? JSON.stringify(value) : String(value);
+      lines.push(`${key}: ${rendered}`);
+    }
+    return lines.join("\n");
+  }
+  return `Executed ${actionId}.`;
+}
+
 // ── MCP Server ──
 
 const server = new McpServer({
@@ -98,19 +169,20 @@ server.tool(
     if (!result.ok && result.error) {
       return { content: [{ type: "text", text: `Error: ${result.error}${result.hint ? `\n${result.hint}` : ""}` }], isError: true };
     }
+    const snapshot = result.snapshot ?? result;
     const lines = [];
-    if (result.route) lines.push(`Route: ${result.route}`);
-    if (result.status) lines.push(`Status: ${result.status}`);
-    if (result.narration) lines.push(`Narration: ${result.narration}`);
-    if (result.busyActionId) lines.push(`Busy: ${result.busyActionId}`);
-    if (Array.isArray(result.actions)) {
-      lines.push(`\nActions (${result.actions.length}):`);
-      for (const action of result.actions) {
-        const args = action.args?.length ? ` [${action.args.map((a) => a.name).join(", ")}]` : "";
+    if (snapshot.route) lines.push(`Route: ${snapshot.route}`);
+    if (snapshot.status) lines.push(`Status: ${snapshot.status}`);
+    if (snapshot.narration) lines.push(`Narration: ${snapshot.narration}`);
+    if (snapshot.busyActionId) lines.push(`Busy: ${snapshot.busyActionId}`);
+    if (Array.isArray(snapshot.actions)) {
+      lines.push(`\nActions (${snapshot.actions.length}):`);
+      for (const action of snapshot.actions) {
+        const args = Array.isArray(action.args) && action.args.length ? ` [${action.args.map((a) => a.name).join(", ")}]` : "";
         lines.push(`  ${action.id} — ${action.label || action.description || ""}${args}`);
       }
     }
-    return { content: [{ type: "text", text: lines.join("\n") || JSON.stringify(result, null, 2) }] };
+    return { content: [{ type: "text", text: lines.join("\n") || "OpenWork is reachable, but it did not return visible UI state." }] };
   }
 );
 
@@ -127,10 +199,7 @@ server.tool(
     if (!Array.isArray(result.actions) || result.actions.length === 0) {
       return { content: [{ type: "text", text: "No actions available. Is OpenWork on the main screen?" }] };
     }
-    const text = result.actions.map((a) => {
-      const args = a.args?.length ? `\n    Args: ${a.args.map((p) => `${p.name}${p.required ? " (required)" : ""}: ${p.description || p.type || ""}`).join(", ")}` : "";
-      return `${a.id}\n    ${a.label || ""}${a.description ? ` — ${a.description}` : ""}${args}`;
-    }).join("\n\n");
+    const text = result.actions.map(formatActionLine).join("\n\n");
     return { content: [{ type: "text", text: `${result.actions.length} actions:\n\n${text}` }] };
   }
 );
@@ -151,7 +220,7 @@ server.tool(
     if (!result.ok && result.error) {
       return { content: [{ type: "text", text: `Error executing ${actionId}: ${result.error}` }], isError: true };
     }
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    return { content: [{ type: "text", text: formatExecutionResult(actionId, result) }] };
   }
 );
 
@@ -170,6 +239,7 @@ server.tool(
       const data = await response.json();
       return { content: [{ type: "text", text: `Connected to ${data.app || "OpenWork"}\nBridge: ${bridge.baseUrl}\nVersion: ${data.version ?? "?"}` }] };
     } catch (error) {
+      clearBridgeCache();
       return { content: [{ type: "text", text: `Bridge file found but not reachable: ${error.message}\nOpenWork may have quit. Relaunch it.` }], isError: true };
     }
   }
diff --git a/packages/openwork-ui-mcp/package.json b/packages/openwork-ui-mcp/package.json
index 36b8cd9ed1..8745b67829 100644
--- a/packages/openwork-ui-mcp/package.json
+++ b/packages/openwork-ui-mcp/package.json
@@ -6,9 +6,11 @@
   "license": "MIT",
   "type": "module",
   "bin": {
-    "openwork-ui-mcp": "./index.mjs"
+    "openwork-ui-mcp": "index.mjs"
   },
-  "files": ["index.mjs"],
+  "files": [
+    "index.mjs"
+  ],
   "scripts": {
     "check": "node --check index.mjs",
     "test": "node --check index.mjs"
@@ -18,6 +20,9 @@
     "url": "git+https://github.com/different-ai/openwork.git",
     "directory": "packages/openwork-ui-mcp"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.25.76"