@openvcs/sdk 0.2.18-nightly.20260421.22 → 0.3.0-beta.34

package/lib/runtime/index.d.ts

@@ -9,7 +9,7 @@ export { ModalBuilder } from './modal';
 export { bootstrapPluginModule, createRegisteredPluginRuntime, } from './registration';
 export { VcsDelegateBase } from './vcs-delegate-base';
 export type { VcsDelegateAssignments } from './vcs-delegate-metadata';
-export { getMenu, getOrCreateMenu, createMenu, addMenuItem, addMenuSeparator, removeMenu, hideMenu, showMenu, registerAction, invoke, notify, } from './menu';
+export { getMenu, getOrCreateMenu, createMenu, addMenuItem, addMenuSeparator, removeMenu, hideMenu, showMenu, registerAction, resetMenuRegistry, invoke, notify, } from './menu';
 export type { MenuHandle } from './menu';
 /** Starts a previously created plugin runtime on process stdio. */
 export declare function startPluginRuntime(runtime: PluginRuntime, transport?: PluginRuntimeTransport): void;

package/lib/runtime/index.js

@@ -2,7 +2,7 @@
 // Copyright © 2025-2026 OpenVCS Contributors
 // SPDX-License-Identifier: GPL-3.0-or-later
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.notify = exports.invoke = exports.registerAction = exports.showMenu = exports.hideMenu = exports.removeMenu = exports.addMenuSeparator = exports.addMenuItem = exports.createMenu = exports.getOrCreateMenu = exports.getMenu = exports.VcsDelegateBase = exports.createRegisteredPluginRuntime = exports.bootstrapPluginModule = exports.ModalBuilder = exports.createHost = exports.createPluginRuntime = exports.pluginError = exports.isPluginFailure = exports.createRuntimeDispatcher = exports.createDefaultPluginDelegates = void 0;
+exports.notify = exports.invoke = exports.resetMenuRegistry = exports.registerAction = exports.showMenu = exports.hideMenu = exports.removeMenu = exports.addMenuSeparator = exports.addMenuItem = exports.createMenu = exports.getOrCreateMenu = exports.getMenu = exports.VcsDelegateBase = exports.createRegisteredPluginRuntime = exports.bootstrapPluginModule = exports.ModalBuilder = exports.createHost = exports.createPluginRuntime = exports.pluginError = exports.isPluginFailure = exports.createRuntimeDispatcher = exports.createDefaultPluginDelegates = void 0;
 exports.startPluginRuntime = startPluginRuntime;
 var dispatcher_1 = require("./dispatcher");
 Object.defineProperty(exports, "createDefaultPluginDelegates", { enumerable: true, get: function () { return dispatcher_1.createDefaultPluginDelegates; } });
@@ -31,6 +31,7 @@ Object.defineProperty(exports, "removeMenu", { enumerable: true, get: function (
 Object.defineProperty(exports, "hideMenu", { enumerable: true, get: function () { return menu_1.hideMenu; } });
 Object.defineProperty(exports, "showMenu", { enumerable: true, get: function () { return menu_1.showMenu; } });
 Object.defineProperty(exports, "registerAction", { enumerable: true, get: function () { return menu_1.registerAction; } });
+Object.defineProperty(exports, "resetMenuRegistry", { enumerable: true, get: function () { return menu_1.resetMenuRegistry; } });
 Object.defineProperty(exports, "invoke", { enumerable: true, get: function () { return menu_1.invoke; } });
 Object.defineProperty(exports, "notify", { enumerable: true, get: function () { return menu_1.notify; } });
 /** Starts a previously created plugin runtime on process stdio. */

package/lib/runtime/menu.d.ts

@@ -1,30 +1,47 @@
 import type { MenubarItem } from '../types/menubar.js';
-import type { PluginDelegates } from '../types/plugin.js';
+import type { PluginDelegates, PluginHandleActionParams } from '../types/plugin.js';
 import type { PluginRuntimeContext } from './contracts.js';
 type MenubarMenuOptions = {
     before?: string;
     after?: string;
 };
+/** UI surface targeted by a menu: 'menubar' (top-level bar) or 'settings' (preferences panel). */
+type MenuSurface = 'menubar' | 'settings';
+/** Validates and returns the incoming plugin action id. */
+export declare function requireActionId(params: PluginHandleActionParams): string;
+/** Clears all registered menus and action handlers.
+ * @internal
+ * Called by bootstrap to prevent state leaking between in-process plugin setup runs.
+ */
+export declare function resetMenuRegistry(): void;
+/** Returns whether one registered action handler exists. */
+export declare function hasRegisteredAction(actionId: string): boolean;
 /** Runs a registered action handler by id. */
 export declare function runRegisteredAction(actionId: string, ...args: unknown[]): Promise<unknown>;
 export interface MenuHandle {
     id: string;
     addItem(item: MenubarItem): void;
-    addSeparator(beforeAction?: string): void;
+    addSeparator(beforeAction?: string, afterAction?: string): void;
     removeItem(actionId: string): void;
     hideItem(actionId: string): void;
     showItem(actionId: string): void;
 }
 /** Returns a menu by id, or null when it does not exist. */
 export declare function getMenu(menuId: string): MenuHandle | null;
-/** Returns a menu by id, creating it if needed. */
-export declare function getOrCreateMenu(menuId: string, label: string): MenuHandle | null;
-/** Creates a menu at a specific position. */
-export declare function createMenu(menuId: string, label: string, options?: MenubarMenuOptions): MenuHandle | null;
-/** Adds one item to a menu. */
+/** Returns a menu by id, creating it if needed.
+ * @param menuId - Menu identifier.
+ * @param label - User-visible label.
+ * @param options - Placement options, including the required `surface` so the runtime can serialize the menu for the correct host UI surface.
+ */
+export declare function getOrCreateMenu(menuId: string, label: string, options: MenubarMenuOptions & {
+    surface: MenuSurface;
+}): MenuHandle | null;
+/** Creates a menu at a specific position (alias for getOrCreateMenu). */
+export declare const createMenu: typeof getOrCreateMenu;
+/** Adds one item to a menu, silently no-op if the menu does not exist. */
 export declare function addMenuItem(menuId: string, item: MenubarItem): void;
-/** Adds one separator to a menu. */
-export declare function addMenuSeparator(menuId: string, beforeAction?: string): void;
+/** Adds one separator to a menu, silently no-op if the menu does not exist. */
+export declare function addMenuSeparator(menuId: string, beforeAction?: string, afterAction?: string): void;
 /** Removes one menu from the registry. */
 export declare function removeMenu(menuId: string): void;
 /** Hides one menu from the registry. */

package/lib/runtime/menu.js

@@ -2,10 +2,13 @@
 // Copyright © 2025-2026 OpenVCS Contributors
 // SPDX-License-Identifier: GPL-3.0-or-later
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMenu = void 0;
+exports.requireActionId = requireActionId;
+exports.resetMenuRegistry = resetMenuRegistry;
+exports.hasRegisteredAction = hasRegisteredAction;
 exports.runRegisteredAction = runRegisteredAction;
 exports.getMenu = getMenu;
 exports.getOrCreateMenu = getOrCreateMenu;
-exports.createMenu = createMenu;
 exports.addMenuItem = addMenuItem;
 exports.addMenuSeparator = addMenuSeparator;
 exports.removeMenu = removeMenu;
@@ -15,10 +18,29 @@ exports.registerAction = registerAction;
 exports.invoke = invoke;
 exports.notify = notify;
 exports.createMenuPluginDelegates = createMenuPluginDelegates;
+const errors_js_1 = require("./errors.js");
 const menus = new Map();
 const menuOrder = [];
 const actionHandlers = new Map();
 let syntheticId = 0;
+/** Validates and returns the incoming plugin action id. */
+function requireActionId(params) {
+    const actionId = typeof params?.action_id === 'string' ? params.action_id.trim() : '';
+    if (!actionId) {
+        throw (0, errors_js_1.pluginError)('plugin-invalid-action-id', 'plugin.handle_action requires params.action_id to be a non-empty string');
+    }
+    return actionId;
+}
+/** Clears all registered menus and action handlers.
+ * @internal
+ * Called by bootstrap to prevent state leaking between in-process plugin setup runs.
+ */
+function resetMenuRegistry() {
+    menus.clear();
+    menuOrder.splice(0, menuOrder.length);
+    actionHandlers.clear();
+    syntheticId = 0;
+}
 /** Returns the host-side OpenVCS helper, when the environment provides one. */
 function getOpenVCS() {
     return globalThis.OpenVCS;
@@ -66,16 +88,17 @@ function placeMenuId(menuId, options) {
     menuOrder.push(id);
 }
 /** Ensures a menu record exists for one id. */
-function ensureStoredMenu(menuId, label, options) {
+function ensureStoredMenu(menuId, label, options, surface) {
     const id = normalizeMenuId(menuId);
     const safeLabel = String(label || '').trim() || id;
     let menu = menus.get(id);
     if (!menu) {
-        menu = { id, label: safeLabel, items: [] };
+        menu = { id, label: safeLabel, surface, items: [] };
         menus.set(id, menu);
     }
     else {
         menu.label = safeLabel;
+        menu.surface = surface;
     }
     placeMenuId(id, options);
     return menu;
@@ -148,6 +171,7 @@ function serializeMenus() {
             id: menu.id,
             label: menu.label,
             order: index + 1,
+            surface: menu.surface,
             elements: menu.items
                 .map((item) => serializeMenuItem(item))
                 .filter((item) => Boolean(item)),
@@ -155,6 +179,13 @@ function serializeMenus() {
     })
         .filter((menu) => Boolean(menu));
 }
+/** Returns whether one registered action handler exists. */
+function hasRegisteredAction(actionId) {
+    const id = String(actionId || '').trim();
+    if (!id)
+        return false;
+    return actionHandlers.has(id);
+}
 /** Runs a registered action handler by id. */
 async function runRegisteredAction(actionId, ...args) {
     const id = String(actionId || '').trim();
@@ -175,7 +206,11 @@ function createMenuHandle(menuId) {
             const action = String(item?.action || '').trim();
             if (!label || !action)
                 return;
-            const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
+            let menu = getStoredMenu(this.id);
+            if (!menu) {
+                // Default to menubar for internal menu handle operations.
+                menu = ensureStoredMenu(this.id, this.id, {}, 'menubar');
+            }
             insertMenuItem(menu, {
                 kind: 'button',
                 id: action,
@@ -184,14 +219,18 @@ function createMenuHandle(menuId) {
                 action,
             }, item.before, item.after);
         },
-        addSeparator(beforeAction) {
-            const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
+        addSeparator(beforeAction, afterAction) {
+            let menu = getStoredMenu(this.id);
+            if (!menu) {
+                // Default to menubar for internal menu handle operations.
+                menu = ensureStoredMenu(this.id, this.id, {}, 'menubar');
+            }
             insertMenuItem(menu, {
                 kind: 'separator',
                 id: allocateSyntheticId(`${menu.id}-separator`),
                 label: 'Separator',
                 content: '—',
-            }, beforeAction);
+            }, beforeAction, afterAction);
         },
         removeItem(actionId) {
             const menu = getStoredMenu(this.id);
@@ -225,23 +264,30 @@ function getMenu(menuId) {
         return null;
     return createMenuHandle(stored.id);
 }
-/** Returns a menu by id, creating it if needed. */
-function getOrCreateMenu(menuId, label) {
-    const stored = ensureStoredMenu(menuId, label);
+/** Returns a menu by id, creating it if needed.
+ * @param menuId - Menu identifier.
+ * @param label - User-visible label.
+ * @param options - Placement options, including the required `surface` so the runtime can serialize the menu for the correct host UI surface.
+ */
+function getOrCreateMenu(menuId, label, options) {
+    const { surface, ...restOptions } = options;
+    const stored = ensureStoredMenu(menuId, label, restOptions, surface);
     return createMenuHandle(stored.id);
 }
-/** Creates a menu at a specific position. */
-function createMenu(menuId, label, options) {
-    const stored = ensureStoredMenu(menuId, label, options);
-    return createMenuHandle(stored.id);
-}
-/** Adds one item to a menu. */
+/** Creates a menu at a specific position (alias for getOrCreateMenu). */
+exports.createMenu = getOrCreateMenu;
+/** Adds one item to a menu, silently no-op if the menu does not exist. */
 function addMenuItem(menuId, item) {
-    createMenuHandle(menuId).addItem(item);
+    const handle = createMenuHandle(menuId);
+    if (!getStoredMenu(menuId))
+        return;
+    handle.addItem(item);
 }
-/** Adds one separator to a menu. */
-function addMenuSeparator(menuId, beforeAction) {
-    createMenuHandle(menuId).addSeparator(beforeAction);
+/** Adds one separator to a menu, silently no-op if the menu does not exist. */
+function addMenuSeparator(menuId, beforeAction, afterAction) {
+    if (!getStoredMenu(menuId))
+        return;
+    createMenuHandle(menuId).addSeparator(beforeAction, afterAction);
 }
 /** Removes one menu from the registry. */
 function removeMenu(menuId) {
@@ -279,7 +325,10 @@ function invoke(cmd, args) {
 /** Emits a notification when the host helper is available. */
 function notify(msg) {
     const openvcs = getOpenVCS();
-    openvcs?.notify(msg);
+    if (!openvcs) {
+        throw new Error('OpenVCS host is not available in this runtime');
+    }
+    openvcs.notify(msg);
 }
 /** Builds SDK delegates from the local menu/action registries. */
 function createMenuPluginDelegates() {
@@ -288,11 +337,7 @@ function createMenuPluginDelegates() {
             return serializeMenus();
         },
         async 'plugin.handle_action'(params) {
-            const actionId = String(params?.action_id || params?.id || '').trim();
-            if (actionId) {
-                return await runRegisteredAction(actionId, params?.payload);
-            }
-            return null;
+            return await runRegisteredAction(requireActionId(params), params?.payload);
         },
     };
 }

package/lib/runtime/registration.js

@@ -26,8 +26,8 @@ function createRegisteredPluginRuntime(definition = {}) {
                 ];
             },
             'plugin.handle_action': async (params, ctx) => {
-                const actionId = String(params?.action_id || '').trim();
-                if (actionId) {
+                const actionId = (0, menu_1.requireActionId)(params);
+                if ((0, menu_1.hasRegisteredAction)(actionId)) {
                     const result = await (0, menu_1.runRegisteredAction)(actionId, params?.payload);
                     if (result !== null && result !== undefined) {
                         return result;
@@ -36,6 +36,7 @@ function createRegisteredPluginRuntime(definition = {}) {
                 if (explicitHandleAction) {
                     return explicitHandleAction(params, ctx);
                 }
+                ctx.host.info(`plugin.handle_action ignored unhandled action_id '${actionId}'`);
                 return null;
             },
         },
@@ -54,6 +55,8 @@ async function bootstrapPluginModule(options) {
     if (typeof onPluginStart !== 'function') {
         throw new Error(`plugin module '${options.modulePath}' must export OnPluginStart()`);
     }
+    // Reset internal state so repeated in-process setups do not leak menu or action state.
+    (0, menu_1.resetMenuRegistry)();
     try {
         await onPluginStart();
     }

package/lib/runtime/vcs-delegate-base.d.ts

@@ -77,6 +77,8 @@ export declare abstract class VcsDelegateBase<TDeps, TContext = PluginRuntimeCon
     writeMergeResult(_params: VcsTypes.VcsWriteMergeResultParams, _context: TContext): VcsHandlerResult<null>;
     /** Handles `vcs.stage_patch`. */
     stagePatch(_params: VcsTypes.VcsStagePatchParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.stage_paths`. */
+    stagePaths(_params: VcsTypes.VcsStagePathsParams, _context: TContext): VcsHandlerResult<null>;
     /** Handles `vcs.discard_paths`. */
     discardPaths(_params: VcsTypes.VcsDiscardPathsParams, _context: TContext): VcsHandlerResult<null>;
     /** Handles `vcs.apply_reverse_patch`. */

package/lib/runtime/vcs-delegate-base.js

@@ -157,6 +157,10 @@ class VcsDelegateBase {
     stagePatch(_params, _context) {
         return this.unimplemented('stagePatch');
     }
+    /** Handles `vcs.stage_paths`. */
+    stagePaths(_params, _context) {
+        return this.unimplemented('stagePaths');
+    }
     /** Handles `vcs.discard_paths`. */
     discardPaths(_params, _context) {
         return this.unimplemented('discardPaths');

package/lib/runtime/vcs-delegate-metadata.d.ts

@@ -30,6 +30,7 @@ export type VcsDelegateBindings<TContext> = {
     checkoutConflictSide: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.checkout_conflict_side']>;
     writeMergeResult: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.write_merge_result']>;
     stagePatch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stage_patch']>;
+    stagePaths: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stage_paths']>;
     discardPaths: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.discard_paths']>;
     applyReversePatch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.apply_reverse_patch']>;
     deleteBranch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.delete_branch']>;
@@ -85,6 +86,7 @@ export declare const VCS_DELEGATE_METHOD_MAPPINGS: {
     readonly checkoutConflictSide: "vcs.checkout_conflict_side";
     readonly writeMergeResult: "vcs.write_merge_result";
     readonly stagePatch: "vcs.stage_patch";
+    readonly stagePaths: "vcs.stage_paths";
     readonly discardPaths: "vcs.discard_paths";
     readonly applyReversePatch: "vcs.apply_reverse_patch";
     readonly deleteBranch: "vcs.delete_branch";

package/lib/runtime/vcs-delegate-metadata.js

@@ -33,6 +33,7 @@ exports.VCS_DELEGATE_METHOD_MAPPINGS = {
     checkoutConflictSide: 'vcs.checkout_conflict_side',
     writeMergeResult: 'vcs.write_merge_result',
     stagePatch: 'vcs.stage_patch',
+    stagePaths: 'vcs.stage_paths',
     discardPaths: 'vcs.discard_paths',
     applyReversePatch: 'vcs.apply_reverse_patch',
     deleteBranch: 'vcs.delete_branch',

package/lib/types/menubar.d.ts

@@ -22,8 +22,8 @@ export interface MenubarMenu {
     id: string;
     /** Adds an item to this menu. */
     addItem(item: MenubarItem): void;
-    /** Adds a separator to this menu. */
-    addSeparator(beforeAction?: string): void;
+    /** Adds a separator to this menu before or after an existing action. */
+    addSeparator(beforeAction?: string, afterAction?: string): void;
     /** Removes an item by action ID. */
     removeItem(actionId: string): void;
     /** Hides an item by action ID. */

package/lib/types/plugin.d.ts

@@ -15,15 +15,46 @@ export interface PluginInitializeResult {
 }
 /** Describes one optional override returned by a custom initialize handler. */
 export type PluginInitializeOverride = Partial<PluginInitializeResult>;
+/** Describes the UI surface targeted by one plugin menu definition. */
+export type PluginMenuSurface = 'menubar' | 'settings';
+/** Describes one static text element contributed to a plugin menu. */
+export interface PluginMenuTextElement {
+    /** Stores the serialized element kind. */
+    type: 'text';
+    /** Stores the stable plugin-local element id. */
+    id: string;
+    /** Stores the rendered text content. */
+    content: string;
+}
+/** Describes one button element contributed to a plugin menu. */
+export interface PluginMenuButtonElement {
+    /** Stores the serialized element kind. */
+    type: 'button';
+    /** Stores the stable action id dispatched back to the plugin. */
+    id: string;
+    /** Stores the user-visible button label. */
+    label: string;
+}
+/** Describes one renderable plugin menu element. */
+export type PluginMenuElement = PluginMenuTextElement | PluginMenuButtonElement;
 /** Describes one plugin-contributed menu definition. */
-export type PluginMenuDefinition = Record<string, unknown>;
+export interface PluginMenuDefinition {
+    /** Stores the stable plugin-local menu id. */
+    id: string;
+    /** Stores the user-visible menu label. */
+    label: string;
+    /** Stores the display ordering hint assigned by the runtime. */
+    order: number;
+    /** Stores the target UI surface for the menu. */
+    surface: PluginMenuSurface;
+    /** Stores the renderable elements contributed under the menu. */
+    elements: PluginMenuElement[];
+}
 /** Describes one plugin settings value payload. */
 export type PluginSettingsValue = Record<string, unknown>;
 /** Describes the params shape for plugin action handling. */
 export interface PluginHandleActionParams extends RequestParams {
-    /** Stores the action id selected by the user when provided by the transport. */
-    id?: string;
-    /** Stores the action id selected by the user. */
+    /** Stores the action id selected by the user. Runtime handlers require a non-empty string. */
     action_id?: string;
     /** Stores an optional payload supplied by the triggering UI. */
     payload?: Record<string, unknown>;

package/lib/types/vcs.d.ts

@@ -261,6 +261,11 @@ export interface VcsStagePatchParams extends VcsSessionParams {
     /** Stores the textual patch content. */
     patch: string;
 }
+/** Describes params for staging repository-relative paths into the index. */
+export interface VcsStagePathsParams extends VcsSessionParams {
+    /** Stores the paths to stage. */
+    paths?: string[];
+}
 /** Describes params for discarding path changes. */
 export interface VcsDiscardPathsParams extends VcsSessionParams {
     /** Stores the paths to discard. */
@@ -424,6 +429,8 @@ export interface VcsDelegates<TContext = unknown> {
     'vcs.write_merge_result'?: RpcMethodHandler<VcsWriteMergeResultParams, null, TContext>;
     /** Handles `vcs.stage_patch`. */
     'vcs.stage_patch'?: RpcMethodHandler<VcsStagePatchParams, null, TContext>;
+    /** Handles `vcs.stage_paths`. */
+    'vcs.stage_paths'?: RpcMethodHandler<VcsStagePathsParams, null, TContext>;
     /** Handles `vcs.discard_paths`. */
     'vcs.discard_paths'?: RpcMethodHandler<VcsDiscardPathsParams, null, TContext>;
     /** Handles `vcs.apply_reverse_patch`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.2.18-nightly.20260421.22",
+  "version": "0.3.0-beta.34",
   "description": "OpenVCS SDK CLI for plugin scaffolding and runtime asset builds",
   "license": "GPL-3.0-or-later",
   "homepage": "https://openvcs.app/",
@@ -40,7 +40,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.3.3",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   },
   "files": [
     "src/",

package/src/lib/runtime/index.ts

@@ -39,6 +39,7 @@ export {
   hideMenu,
   showMenu,
   registerAction,
+  resetMenuRegistry,
   invoke,
   notify,
 } from './menu';

package/src/lib/runtime/menu.ts

@@ -5,13 +5,17 @@ import type { MenubarItem } from '../types/menubar.js';
 import type {
   PluginDelegates,
   PluginHandleActionParams,
+  PluginMenuElement,
   PluginMenuDefinition,
 } from '../types/plugin.js';
 
 import type { PluginRuntimeContext } from './contracts.js';
+import { pluginError } from './errors.js';
 
 type MenubarMenuOptions = { before?: string; after?: string };
 type MenuEntryKind = 'button' | 'text' | 'separator';
+/** UI surface targeted by a menu: 'menubar' (top-level bar) or 'settings' (preferences panel). */
+type MenuSurface = 'menubar' | 'settings';
 
 type OpenVCSGlobal = typeof globalThis & {
   OpenVCS?: {
@@ -26,6 +30,7 @@ interface StoredMenuItem {
   label: string;
   title?: string;
   content?: string;
+  /** Action id dispatched back to the plugin when the user activates this item. */
   action?: string;
   hidden?: boolean;
 }
@@ -34,28 +39,39 @@ interface StoredMenuState {
   id: string;
   label: string;
   hidden?: boolean;
+  /** Surface target for rendering ('menubar' or 'settings'), must be explicitly provided. */
+  surface: MenuSurface;
   items: StoredMenuItem[];
 }
 
-interface SerializedMenuItem {
-  type: 'button' | 'text';
-  id: string;
-  label?: string;
-  content?: string;
-}
-
-interface SerializedMenuDefinition {
-  id: string;
-  label: string;
-  order: number;
-  elements: SerializedMenuItem[];
-}
-
 const menus = new Map<string, StoredMenuState>();
 const menuOrder: string[] = [];
 const actionHandlers = new Map<string, (...args: unknown[]) => unknown>();
 let syntheticId = 0;
 
+/** Validates and returns the incoming plugin action id. */
+export function requireActionId(params: PluginHandleActionParams): string {
+  const actionId = typeof params?.action_id === 'string' ? params.action_id.trim() : '';
+  if (!actionId) {
+    throw pluginError(
+      'plugin-invalid-action-id',
+      'plugin.handle_action requires params.action_id to be a non-empty string',
+    );
+  }
+  return actionId;
+}
+
+/** Clears all registered menus and action handlers.
+ * @internal
+ * Called by bootstrap to prevent state leaking between in-process plugin setup runs.
+ */
+export function resetMenuRegistry(): void {
+  menus.clear();
+  menuOrder.splice(0, menuOrder.length);
+  actionHandlers.clear();
+  syntheticId = 0;
+}
+
 /** Returns the host-side OpenVCS helper, when the environment provides one. */
 function getOpenVCS() {
   return (globalThis as OpenVCSGlobal).OpenVCS;
@@ -115,17 +131,19 @@ function placeMenuId(menuId: string, options?: MenubarMenuOptions): void {
 function ensureStoredMenu(
   menuId: string,
   label: string,
-  options?: MenubarMenuOptions,
+  options: MenubarMenuOptions,
+  surface: MenuSurface,
 ): StoredMenuState {
   const id = normalizeMenuId(menuId);
   const safeLabel = String(label || '').trim() || id;
   let menu = menus.get(id);
 
   if (!menu) {
-    menu = { id, label: safeLabel, items: [] };
+    menu = { id, label: safeLabel, surface, items: [] };
     menus.set(id, menu);
   } else {
     menu.label = safeLabel;
+    menu.surface = surface;
   }
 
   placeMenuId(id, options);
@@ -171,7 +189,7 @@ function insertMenuItem(menu: StoredMenuState, item: StoredMenuItem, before?: st
 }
 
 /** Converts one stored item into a serializable menu payload element. */
-function serializeMenuItem(item: StoredMenuItem): SerializedMenuItem | null {
+function serializeMenuItem(item: StoredMenuItem): PluginMenuElement | null {
   if (item.hidden) return null;
 
   if (item.kind === 'separator') {
@@ -198,7 +216,7 @@ function serializeMenuItem(item: StoredMenuItem): SerializedMenuItem | null {
 }
 
 /** Serializes the local registry into plugin menu payloads. */
-function serializeMenus(): SerializedMenuDefinition[] {
+function serializeMenus(): PluginMenuDefinition[] {
   return menuOrder
     .map((menuId, index) => {
       const menu = menus.get(menuId);
@@ -207,12 +225,20 @@ function serializeMenus(): SerializedMenuDefinition[] {
         id: menu.id,
         label: menu.label,
         order: index + 1,
+        surface: menu.surface,
         elements: menu.items
           .map((item) => serializeMenuItem(item))
-          .filter((item): item is SerializedMenuItem => Boolean(item)),
+          .filter((item): item is PluginMenuElement => Boolean(item)),
       };
     })
-    .filter((menu): menu is SerializedMenuDefinition => Boolean(menu));
+    .filter((menu): menu is PluginMenuDefinition => Boolean(menu));
+}
+
+/** Returns whether one registered action handler exists. */
+export function hasRegisteredAction(actionId: string): boolean {
+  const id = String(actionId || '').trim();
+  if (!id) return false;
+  return actionHandlers.has(id);
 }
 
 /** Runs a registered action handler by id. */
@@ -229,7 +255,7 @@ export async function runRegisteredAction(actionId: string, ...args: unknown[]):
 export interface MenuHandle {
   id: string;
   addItem(item: MenubarItem): void;
-  addSeparator(beforeAction?: string): void;
+  addSeparator(beforeAction?: string, afterAction?: string): void;
   removeItem(actionId: string): void;
   hideItem(actionId: string): void;
   showItem(actionId: string): void;
@@ -246,7 +272,11 @@ function createMenuHandle(menuId: string): MenuHandle {
       const action = String(item?.action || '').trim();
       if (!label || !action) return;
 
-      const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
+      let menu = getStoredMenu(this.id);
+      if (!menu) {
+        // Default to menubar for internal menu handle operations.
+        menu = ensureStoredMenu(this.id, this.id, {}, 'menubar');
+      }
       insertMenuItem(menu, {
         kind: 'button',
         id: action,
@@ -255,14 +285,18 @@ function createMenuHandle(menuId: string): MenuHandle {
         action,
       }, item.before, item.after);
     },
-    addSeparator(beforeAction?: string) {
-      const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
+    addSeparator(beforeAction?: string, afterAction?: string) {
+      let menu = getStoredMenu(this.id);
+      if (!menu) {
+        // Default to menubar for internal menu handle operations.
+        menu = ensureStoredMenu(this.id, this.id, {}, 'menubar');
+      }
       insertMenuItem(menu, {
         kind: 'separator',
         id: allocateSyntheticId(`${menu.id}-separator`),
         label: 'Separator',
         content: '—',
-      }, beforeAction);
+      }, beforeAction, afterAction);
     },
     removeItem(actionId: string) {
       const menu = getStoredMenu(this.id);
@@ -292,26 +326,35 @@ export function getMenu(menuId: string): MenuHandle | null {
   return createMenuHandle(stored.id);
 }
 
-/** Returns a menu by id, creating it if needed. */
-export function getOrCreateMenu(menuId: string, label: string): MenuHandle | null {
-  const stored = ensureStoredMenu(menuId, label);
+/** Returns a menu by id, creating it if needed.
+ * @param menuId - Menu identifier.
+ * @param label - User-visible label.
+ * @param options - Placement options, including the required `surface` so the runtime can serialize the menu for the correct host UI surface.
+ */
+export function getOrCreateMenu(
+  menuId: string,
+  label: string,
+  options: MenubarMenuOptions & { surface: MenuSurface },
+): MenuHandle | null {
+  const { surface, ...restOptions } = options;
+  const stored = ensureStoredMenu(menuId, label, restOptions, surface);
   return createMenuHandle(stored.id);
 }
 
-/** Creates a menu at a specific position. */
-export function createMenu(menuId: string, label: string, options?: MenubarMenuOptions): MenuHandle | null {
-  const stored = ensureStoredMenu(menuId, label, options);
-  return createMenuHandle(stored.id);
-}
+/** Creates a menu at a specific position (alias for getOrCreateMenu). */
+export const createMenu = getOrCreateMenu;
 
-/** Adds one item to a menu. */
+/** Adds one item to a menu, silently no-op if the menu does not exist. */
 export function addMenuItem(menuId: string, item: MenubarItem): void {
-  createMenuHandle(menuId).addItem(item);
+  const handle = createMenuHandle(menuId);
+  if (!getStoredMenu(menuId)) return;
+  handle.addItem(item);
 }
 
-/** Adds one separator to a menu. */
-export function addMenuSeparator(menuId: string, beforeAction?: string): void {
-  createMenuHandle(menuId).addSeparator(beforeAction);
+/** Adds one separator to a menu, silently no-op if the menu does not exist. */
+export function addMenuSeparator(menuId: string, beforeAction?: string, afterAction?: string): void {
+  if (!getStoredMenu(menuId)) return;
+  createMenuHandle(menuId).addSeparator(beforeAction, afterAction);
 }
 
 /** Removes one menu from the registry. */
@@ -352,21 +395,20 @@ export function invoke<T = unknown>(cmd: string, args?: unknown): Promise<T> {
 /** Emits a notification when the host helper is available. */
 export function notify(msg: string): void {
   const openvcs = getOpenVCS();
-  openvcs?.notify(msg);
+  if (!openvcs) {
+    throw new Error('OpenVCS host is not available in this runtime');
+  }
+  openvcs.notify(msg);
 }
 
 /** Builds SDK delegates from the local menu/action registries. */
 export function createMenuPluginDelegates(): PluginDelegates<PluginRuntimeContext> {
   return {
     async 'plugin.get_menus'(): Promise<PluginMenuDefinition[]> {
-      return serializeMenus() as unknown as PluginMenuDefinition[];
+      return serializeMenus();
     },
     async 'plugin.handle_action'(params: PluginHandleActionParams): Promise<unknown> {
-      const actionId = String(params?.action_id || params?.id || '').trim();
-      if (actionId) {
-        return await runRegisteredAction(actionId, params?.payload);
-      }
-      return null;
+      return await runRegisteredAction(requireActionId(params), params?.payload);
     },
   };
 }

package/src/lib/runtime/registration.ts

@@ -16,6 +16,9 @@ import type {
 import { createPluginRuntime } from './factory';
 import {
   createMenuPluginDelegates,
+  hasRegisteredAction,
+  requireActionId,
+  resetMenuRegistry,
   runRegisteredAction,
 } from './menu';
 
@@ -79,8 +82,8 @@ export function createRegisteredPluginRuntime(
         ];
       },
       'plugin.handle_action': async (params, ctx) => {
-        const actionId = String(params?.action_id || '').trim();
-        if (actionId) {
+        const actionId = requireActionId(params);
+        if (hasRegisteredAction(actionId)) {
           const result = await runRegisteredAction(actionId, params?.payload);
           if (result !== null && result !== undefined) {
             return result;
@@ -89,6 +92,7 @@ export function createRegisteredPluginRuntime(
         if (explicitHandleAction) {
           return explicitHandleAction(params, ctx);
         }
+        ctx.host.info(`plugin.handle_action ignored unhandled action_id '${actionId}'`);
         return null;
       },
     },
@@ -114,6 +118,9 @@ export async function bootstrapPluginModule(
     );
   }
 
+  // Reset internal state so repeated in-process setups do not leak menu or action state.
+  resetMenuRegistry();
+
   try {
     await onPluginStart();
   } catch (error) {

package/src/lib/runtime/vcs-delegate-base.ts

@@ -303,6 +303,14 @@ export abstract class VcsDelegateBase<
     return this.unimplemented('stagePatch');
   }
 
+  /** Handles `vcs.stage_paths`. */
+  stagePaths(
+    _params: VcsTypes.VcsStagePathsParams,
+    _context: TContext,
+  ): VcsHandlerResult<null> {
+    return this.unimplemented('stagePaths');
+  }
+
   /** Handles `vcs.discard_paths`. */
   discardPaths(
     _params: VcsTypes.VcsDiscardPathsParams,

package/src/lib/runtime/vcs-delegate-metadata.ts

@@ -53,6 +53,7 @@ export type VcsDelegateBindings<TContext> = {
     VcsTypes.VcsDelegates<TContext>['vcs.write_merge_result']
   >;
   stagePatch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stage_patch']>;
+  stagePaths: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stage_paths']>;
   discardPaths: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.discard_paths']>;
   applyReversePatch: NonNullable<
     VcsTypes.VcsDelegates<TContext>['vcs.apply_reverse_patch']
@@ -122,6 +123,7 @@ export const VCS_DELEGATE_METHOD_MAPPINGS = {
   checkoutConflictSide: 'vcs.checkout_conflict_side',
   writeMergeResult: 'vcs.write_merge_result',
   stagePatch: 'vcs.stage_patch',
+  stagePaths: 'vcs.stage_paths',
   discardPaths: 'vcs.discard_paths',
   applyReversePatch: 'vcs.apply_reverse_patch',
   deleteBranch: 'vcs.delete_branch',

package/src/lib/types/menubar.ts

@@ -23,8 +23,8 @@ export interface MenubarMenu {
   id: string;
   /** Adds an item to this menu. */
   addItem(item: MenubarItem): void;
-  /** Adds a separator to this menu. */
-  addSeparator(beforeAction?: string): void;
+  /** Adds a separator to this menu before or after an existing action. */
+  addSeparator(beforeAction?: string, afterAction?: string): void;
   /** Removes an item by action ID. */
   removeItem(actionId: string): void;
   /** Hides an item by action ID. */

package/src/lib/types/plugin.ts

@@ -22,17 +22,52 @@ export interface PluginInitializeResult {
 /** Describes one optional override returned by a custom initialize handler. */
 export type PluginInitializeOverride = Partial<PluginInitializeResult>;
 
+/** Describes the UI surface targeted by one plugin menu definition. */
+export type PluginMenuSurface = 'menubar' | 'settings';
+
+/** Describes one static text element contributed to a plugin menu. */
+export interface PluginMenuTextElement {
+  /** Stores the serialized element kind. */
+  type: 'text';
+  /** Stores the stable plugin-local element id. */
+  id: string;
+  /** Stores the rendered text content. */
+  content: string;
+}
+
+/** Describes one button element contributed to a plugin menu. */
+export interface PluginMenuButtonElement {
+  /** Stores the serialized element kind. */
+  type: 'button';
+  /** Stores the stable action id dispatched back to the plugin. */
+  id: string;
+  /** Stores the user-visible button label. */
+  label: string;
+}
+
+/** Describes one renderable plugin menu element. */
+export type PluginMenuElement = PluginMenuTextElement | PluginMenuButtonElement;
+
 /** Describes one plugin-contributed menu definition. */
-export type PluginMenuDefinition = Record<string, unknown>;
+export interface PluginMenuDefinition {
+  /** Stores the stable plugin-local menu id. */
+  id: string;
+  /** Stores the user-visible menu label. */
+  label: string;
+  /** Stores the display ordering hint assigned by the runtime. */
+  order: number;
+  /** Stores the target UI surface for the menu. */
+  surface: PluginMenuSurface;
+  /** Stores the renderable elements contributed under the menu. */
+  elements: PluginMenuElement[];
+}
 
 /** Describes one plugin settings value payload. */
 export type PluginSettingsValue = Record<string, unknown>;
 
 /** Describes the params shape for plugin action handling. */
 export interface PluginHandleActionParams extends RequestParams {
-  /** Stores the action id selected by the user when provided by the transport. */
-  id?: string;
-  /** Stores the action id selected by the user. */
+  /** Stores the action id selected by the user. Runtime handlers require a non-empty string. */
   action_id?: string;
   /** Stores an optional payload supplied by the triggering UI. */
   payload?: Record<string, unknown>;

package/src/lib/types/vcs.ts

@@ -298,6 +298,12 @@ export interface VcsStagePatchParams extends VcsSessionParams {
   patch: string;
 }
 
+/** Describes params for staging repository-relative paths into the index. */
+export interface VcsStagePathsParams extends VcsSessionParams {
+  /** Stores the paths to stage. */
+  paths?: string[];
+}
+
 /** Describes params for discarding path changes. */
 export interface VcsDiscardPathsParams extends VcsSessionParams {
   /** Stores the paths to discard. */
@@ -518,6 +524,8 @@ export interface VcsDelegates<TContext = unknown> {
   >;
   /** Handles `vcs.stage_patch`. */
   'vcs.stage_patch'?: RpcMethodHandler<VcsStagePatchParams, null, TContext>;
+  /** Handles `vcs.stage_paths`. */
+  'vcs.stage_paths'?: RpcMethodHandler<VcsStagePathsParams, null, TContext>;
   /** Handles `vcs.discard_paths`. */
   'vcs.discard_paths'?: RpcMethodHandler<VcsDiscardPathsParams, null, TContext>;
   /** Handles `vcs.apply_reverse_patch`. */

package/test/runtime.test.js

@@ -4,7 +4,21 @@ const test = require("node:test");
 
 const {
   bootstrapPluginModule,
-  createPluginRuntime,
+  createRegisteredPluginRuntime,
+  resetMenuRegistry,
+} = require("../lib/runtime");
+const {
+  addMenuItem,
+  addMenuSeparator,
+  createMenu,
+  getMenu,
+  registerAction,
+  removeMenu,
+  hideMenu,
+  showMenu,
+} = require("../lib/runtime/menu");
+const {
+  createMenu: createMenuFromRoot,
 } = require("../lib/runtime");
 const {
   parseFramedMessages,
@@ -20,7 +34,7 @@ function createRuntimeHarness(options) {
       return true;
     },
   };
-  const runtime = createPluginRuntime(options);
+  const runtime = createRegisteredPluginRuntime(options);
   runtime.start({ stdin, stdout });
 
   return {
@@ -233,3 +247,308 @@ test("bootstrapPluginModule rejects when OnPluginStart throws", async () => {
     /plugin startup failed/
   );
 });
+
+test("resetMenuRegistry clears all menus and action handlers", () => {
+  createMenu("reset-test", "Reset Test", { surface: "menubar" });
+  registerAction("reset-test-action", () => "ok");
+  assert.notEqual(getMenu("reset-test"), null);
+
+  resetMenuRegistry();
+
+  assert.equal(getMenu("reset-test"), null);
+  // After reset, addMenuItem/addMenuSeparator must silently no-op for unknown menus.
+});
+
+test("addMenuItem silently ignores when menu does not exist", () => {
+  resetMenuRegistry();
+  // Must not throw.
+  addMenuItem("nonexistent-menu", {
+    label: "Irrelevant",
+    action: "test-action",
+  });
+  assert.equal(getMenu("nonexistent-menu"), null);
+});
+
+test("addMenuSeparator silently ignores when menu does not exist", () => {
+  resetMenuRegistry();
+  // Must not throw.
+  addMenuSeparator("nonexistent-menu");
+  assert.equal(getMenu("nonexistent-menu"), null);
+});
+
+test("addMenuItem and addMenuSeparator do not implicitly create menus", () => {
+  resetMenuRegistry();
+  createMenu("existing-menu", "Existing Menu", { surface: "menubar" });
+  addMenuItem("existing-menu", {
+    label: "Test Item",
+    action: "test-action",
+  });
+  addMenuSeparator("existing-menu");
+  assert.notEqual(getMenu("existing-menu"), null);
+  // Verify state was not leaked from prior tests.
+  assert.equal(getMenu("reset-test"), null);
+  removeMenu("existing-menu");
+});
+
+test("hideMenu and showMenu toggle menu visibility", () => {
+  resetMenuRegistry();
+  createMenu("visible-menu", "Visible Menu", { surface: "menubar" });
+  addMenuItem("visible-menu", {
+    label: "Test Item",
+    action: "visibility-action",
+  });
+
+  const menu = getMenu("visible-menu");
+  assert.notEqual(menu, null);
+  hideMenu("visible-menu");
+  assert.notEqual(getMenu("visible-menu"), null);
+
+  showMenu("visible-menu");
+  assert.notEqual(getMenu("visible-menu"), null);
+
+  removeMenu("visible-menu");
+});
+
+test("hideMenu and showMenu affect serialized menus", async () => {
+  resetMenuRegistry();
+  createMenu("serial-menu", "Serial Menu", { surface: "menubar" });
+  addMenuItem("serial-menu", {
+    label: "Serial Item",
+    action: "serial-action",
+  });
+
+  const harness = createRuntimeHarness({ plugin: {} });
+
+  hideMenu("serial-menu");
+  let hidden = await harness.request({
+    jsonrpc: "2.0",
+    id: 30,
+    method: "plugin.get_menus",
+    params: {},
+  });
+  assert.deepEqual(hidden, [{ jsonrpc: "2.0", id: 30, result: [] }]);
+
+  showMenu("serial-menu");
+  const visible = await harness.request({
+    jsonrpc: "2.0",
+    id: 31,
+    method: "plugin.get_menus",
+    params: {},
+  });
+  assert.deepEqual(visible, [{
+    jsonrpc: "2.0",
+    id: 31,
+    result: [{
+      id: "serial-menu",
+      label: "Serial Menu",
+      order: 1,
+      surface: "menubar",
+      elements: [{ type: "button", id: "serial-action", label: "Serial Item" }],
+    }],
+  }]);
+});
+
+test("addMenuSeparator supports afterAction positioning", async () => {
+  resetMenuRegistry();
+  createMenu("separator-menu", "Separator Menu", { surface: "menubar" });
+  addMenuItem("separator-menu", {
+    label: "First Item",
+    action: "first-action",
+  });
+  addMenuItem("separator-menu", {
+    label: "Second Item",
+    action: "second-action",
+  });
+
+  addMenuSeparator("separator-menu", undefined, "first-action");
+
+  const harness = createRuntimeHarness({ plugin: {} });
+  const messages = await harness.request({
+    jsonrpc: "2.0",
+    id: 32,
+    method: "plugin.get_menus",
+    params: {},
+  });
+
+  assert.deepEqual(messages, [{
+    jsonrpc: "2.0",
+    id: 32,
+    result: [{
+      id: "separator-menu",
+      label: "Separator Menu",
+      order: 1,
+      surface: "menubar",
+      elements: [
+        { type: "button", id: "first-action", label: "First Item" },
+        { type: "text", id: "separator-menu-separator-1", content: "—" },
+        { type: "button", id: "second-action", label: "Second Item" },
+      ],
+    }],
+  }]);
+
+  removeMenu("separator-menu");
+});
+
+test("plugin.handle_action rejects missing action_id", async () => {
+  resetMenuRegistry();
+  const harness = createRuntimeHarness({ plugin: {} });
+
+  const missing = await harness.request({
+    jsonrpc: "2.0",
+    id: 20,
+    method: "plugin.handle_action",
+    params: {},
+  });
+  assert.deepEqual(missing, [
+    {
+      jsonrpc: "2.0",
+      id: 20,
+      error: {
+        code: -32001,
+        message: "plugin.handle_action requires params.action_id to be a non-empty string",
+        data: {
+          code: "plugin-invalid-action-id",
+          message: "plugin.handle_action requires params.action_id to be a non-empty string",
+        },
+      },
+    },
+  ]);
+});
+
+test("plugin.handle_action rejects empty action_id", async () => {
+  resetMenuRegistry();
+  const harness = createRuntimeHarness({ plugin: {} });
+
+  const empty = await harness.request({
+    jsonrpc: "2.0",
+    id: 21,
+    method: "plugin.handle_action",
+    params: { action_id: "" },
+  });
+  assert.deepEqual(empty, [
+    {
+      jsonrpc: "2.0",
+      id: 21,
+      error: {
+        code: -32001,
+        message: "plugin.handle_action requires params.action_id to be a non-empty string",
+        data: {
+          code: "plugin-invalid-action-id",
+          message: "plugin.handle_action requires params.action_id to be a non-empty string",
+        },
+      },
+    },
+  ]);
+});
+
+test("createMenu is available from runtime root export", () => {
+  resetMenuRegistry();
+  const menu = createMenuFromRoot("root-export-menu", "Root Export Menu", { surface: "menubar" });
+  assert.notEqual(menu, null);
+  assert.equal(menu.id, "root-export-menu");
+
+  resetMenuRegistry();
+});
+
+test("plugin.handle_action dispatches only on action_id (not id)", async () => {
+  resetMenuRegistry();
+  // Register after reset so the handler is present.
+  registerAction("test-action-id", (payload) => {
+    if (typeof payload === "object" && payload != null) {
+      return (payload).message;
+    }
+    return null;
+  });
+
+  const harness = createRuntimeHarness({
+    plugin: {},
+  });
+
+  // Valid dispatch via action_id.
+  const valid = await harness.request({
+    jsonrpc: "2.0",
+    id: 10,
+    method: "plugin.handle_action",
+    params: { action_id: "test-action-id", payload: { message: "hello" } },
+  });
+  assert.deepEqual(valid, [
+    { jsonrpc: "2.0", id: 10, result: "hello" },
+  ]);
+
+  // `id` is ignored; only `action_id` is valid.
+  const wrongField = await harness.request({
+    jsonrpc: "2.0",
+    id: 12,
+    method: "plugin.handle_action",
+    params: { id: "test-action-id" },
+  });
+  assert.deepEqual(wrongField, [
+    {
+      jsonrpc: "2.0",
+      id: 12,
+      error: {
+        code: -32001,
+        message: "plugin.handle_action requires params.action_id to be a non-empty string",
+        data: {
+          code: "plugin-invalid-action-id",
+          message: "plugin.handle_action requires params.action_id to be a non-empty string",
+        },
+      },
+    },
+  ]);
+});
+
+test("plugin.handle_action logs unhandled actions without explicit handler", async () => {
+  resetMenuRegistry();
+  const harness = createRuntimeHarness({ plugin: {} });
+
+  const messages = await harness.request({
+    jsonrpc: "2.0",
+    id: 13,
+    method: "plugin.handle_action",
+    params: { action_id: "missing-action" },
+  });
+
+  assert.deepEqual(messages, [
+    {
+      jsonrpc: "2.0",
+      method: "host.log",
+      params: {
+        level: "info",
+        target: "openvcs.plugin",
+        message: "plugin.handle_action ignored unhandled action_id 'missing-action'",
+      },
+    },
+    { jsonrpc: "2.0", id: 13, result: null },
+  ]);
+});
+
+test("bootstrapPluginModule resets menu registry before OnPluginStart", async () => {
+  resetMenuRegistry();
+  // Pre-populate state that should be cleared.
+  createMenu("leak-test", "Leak Test", { surface: "menubar" });
+  registerAction("leak-action", () => "leaked");
+
+  const stdin = new EventEmitter();
+  const chunks = [];
+  const stdout = {
+    write(chunk) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      return true;
+    },
+  };
+
+  await bootstrapPluginModule({
+    modulePath: "./plugin.js",
+    transport: { stdin, stdout },
+    async importPluginModule() {
+      return {
+        PluginDefinition: { plugin: {} },
+        OnPluginStart() {},
+      };
+    },
+  });
+
+  // Menu from before bootstrap must not be present.
+  assert.equal(getMenu("leak-test"), null);
+});