@robota-sdk/agent-command 3.0.0-beta.100

package/src/plan/__tests__/plan-command.test.ts

@@ -0,0 +1,129 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { describe, it, expect, vi } from 'vitest';
+
+import { executePlanCommand } from '../plan-command.js';
+
+import type { IPlanArtifact } from '@robota-sdk/agent-interface-session';
+import {
+  createTestCommandHost,
+  type ICreateTestCommandHostOptions,
+} from '@robota-sdk/agent-framework/testing';
+
+function plan(overrides: Partial<IPlanArtifact> = {}): IPlanArtifact {
+  return {
+    id: 'p1',
+    objective: 'ship the feature',
+    steps: [{ id: 'p1_0', description: 'draft the change', status: 'pending' }],
+    phase: 'planning',
+    createdAt: '2026-07-17T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+function host(overrides: ICreateTestCommandHostOptions['overrides'] = {}) {
+  // ARCH-029: the partial is now an OVERRIDE over a conformant host, not a cast that turns the
+  // check off. A fixture that names three members no longer claims to satisfy 46.
+  return createTestCommandHost({ overrides });
+}
+
+describe('executePlanCommand (SELFHOST-002 /plan)', () => {
+  it('drafts a plan from the objective text', async () => {
+    const setPlan = vi.fn().mockResolvedValue(plan());
+    const result = await executePlanCommand(host({ setPlan }), 'ship the feature');
+    expect(setPlan).toHaveBeenCalledWith('ship the feature');
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('/plan approve');
+    expect(result.data).toMatchObject({ planId: 'p1' });
+  });
+
+  it('renders the current plan on "status"', async () => {
+    const result = await executePlanCommand(
+      host({ getPlanState: () => plan({ phase: 'awaiting-approval' }) }),
+      'status',
+    );
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('ship the feature');
+    expect(result.message).toContain('Phase: awaiting-approval');
+    expect(result.message).toContain('1. [pending] draft the change');
+  });
+
+  it('reports when no plan is active', async () => {
+    const result = await executePlanCommand(host({ getPlanState: () => null }), 'status');
+    expect(result.message).toBe('No plan is active.');
+  });
+
+  it('approves via approvePlan and reports the executing phase', async () => {
+    const approvePlan = vi.fn().mockReturnValue(plan({ phase: 'executing' }));
+    const result = await executePlanCommand(
+      host({ getPlanState: () => plan({ phase: 'awaiting-approval' }), approvePlan }),
+      'approve',
+    );
+    expect(approvePlan).toHaveBeenCalled();
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('edits will auto-apply');
+    expect(result.data).toMatchObject({ phase: 'executing' });
+  });
+
+  it('rejects approve when no plan exists', async () => {
+    const approvePlan = vi.fn();
+    const result = await executePlanCommand(
+      host({ getPlanState: () => null, approvePlan }),
+      'approve',
+    );
+    expect(approvePlan).not.toHaveBeenCalled();
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('No plan to approve');
+  });
+
+  it('surfaces an out-of-phase approval error as a failed result', async () => {
+    const approvePlan = vi.fn(() => {
+      throw new Error('approve requires phase "awaiting-approval", got "executing".');
+    });
+    const result = await executePlanCommand(
+      host({ getPlanState: () => plan({ phase: 'executing' }), approvePlan }),
+      'approve',
+    );
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('awaiting-approval');
+  });
+
+  it('reverts via revertPlan', async () => {
+    const revertPlan = vi.fn().mockReturnValue(plan({ phase: 'planning' }));
+    const result = await executePlanCommand(
+      host({ getPlanState: () => plan({ phase: 'executing' }), revertPlan }),
+      'revert',
+    );
+    expect(revertPlan).toHaveBeenCalled();
+    expect(result.message).toContain('edits are blocked again');
+  });
+
+  it('shows usage on empty args or help', async () => {
+    const result = await executePlanCommand(host({}), '');
+    expect(result.message).toContain('Usage:');
+    expect(result.message).toContain('/plan approve');
+  });
+
+  it('ARCH-029 TC-09: the availability guards are gone from the source', () => {
+    // Review caught the first attempt at this case: it re-asserted "No plan is active." for a
+    // null-returning host, which `reports when no plan is active` above already pins with a
+    // STRONGER matcher, over an override that is the double's own default. It would have passed
+    // unchanged on the pre-fix code — a check that cannot fail on the thing it names.
+    //
+    // Stated plainly instead: there is NO behavioural test for this deletion, because there was no
+    // behaviour. `if (!context.setPlan) return 'Plan mode is not available in this session.'` was
+    // already unreachable — the members are unconditionally implemented on `InteractiveSession`
+    // over always-constructed controllers, and it is the only host (`implements` is compiler-
+    // checked, casts are ratcheted at 0, and heritage-clause aliases are counted since this
+    // review). Required-ness makes the branch unreachable for the type checker too. So what can be
+    // pinned is that the branch is not in the file, and that is what this asserts.
+    const source = readFileSync(
+      fileURLToPath(new URL('../plan-command.js', import.meta.url)).replace(/\.js$/, '.ts'),
+      'utf8',
+    );
+
+    expect(source).not.toContain('is not available in this session');
+    expect(source).not.toMatch(/if \(!context\.[a-zA-Z]+\)/);
+  });
+});

package/src/plan/index.ts

@@ -0,0 +1,9 @@
+/**
+ * SELFHOST-002: `/plan` explicit plan-mode command.
+ *
+ * Only the module factory is a package-entry export (matching the other command modules — sources,
+ * command handlers, and descriptions stay internal, imported by direct path). This keeps the
+ * package's public surface minimal and its SPEC Public API table in sync.
+ */
+
+export { createPlanCommandModule } from './plan-command-module.js';

package/src/plan/plan-command-module.ts

@@ -0,0 +1,49 @@
+/**
+ * SELFHOST-002: `/plan` command module registration.
+ */
+
+import { executePlanCommand, PLAN_COMMAND_DESCRIPTION } from './plan-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createPlanCommandEntry(): ICommand {
+  return {
+    name: 'plan',
+    displayName: 'Plan Mode',
+    description: PLAN_COMMAND_DESCRIPTION,
+    source: 'plan',
+    // User-only: approving a plan unblocks edits; that permission change is the user's.
+    modelInvocable: false,
+  };
+}
+
+function createPlanSystemCommand(): ISystemCommand {
+  const entry = createPlanCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: executePlanCommand,
+  };
+}
+
+export class PlanCommandSource implements ICommandSource {
+  readonly name = 'plan';
+
+  getCommands(): ICommand[] {
+    return [createPlanCommandEntry()];
+  }
+}
+
+export function createPlanCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-plan',
+    commandSources: [new PlanCommandSource()],
+    systemCommands: [createPlanSystemCommand()],
+  };
+}

package/src/plan/plan-command.ts

@@ -0,0 +1,92 @@
+/**
+ * SELFHOST-002: the `/plan` slash command — explicit plan-mode (plan → review → approve → act).
+ * Delegates to the framework-owned plan controller via the command host context; the phase machine
+ * and the `setPermissionMode` application both live in agent-framework. The mutation block stays the
+ * existing `plan` permission mode; approving flips to `acceptEdits` (edits auto-apply, shell stays
+ * per-call confirmed).
+ */
+
+import type { ICommandHostPlan } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { IPlanArtifact } from '@robota-sdk/agent-interface-session';
+
+export const PLAN_COMMAND_DESCRIPTION =
+  'Draft a reviewable plan, then approve it to unblock edits (plan → review → approve → act).';
+
+const PLAN_COMMAND_USAGE =
+  'Usage:\n  /plan <objective>   draft a plan for review (stays read-only until approved)\n' +
+  '  /plan status         show the current plan and phase\n' +
+  '  /plan approve        approve the plan (edits auto-apply; shell stays confirmed)\n' +
+  '  /plan revert         return to drafting (re-blocks edits)';
+
+function formatPlan(plan: IPlanArtifact): string {
+  const lines = [
+    `Plan: ${plan.objective}`,
+    `Phase: ${plan.phase}${plan.approvedAt ? ` (approved ${plan.approvedAt})` : ''}`,
+  ];
+  plan.steps.forEach((step, index) => {
+    lines.push(`  ${index + 1}. [${step.status}] ${step.description}`);
+  });
+  return lines.join('\n');
+}
+
+export async function executePlanCommand(
+  context: ICommandHostPlan,
+  args: string,
+): Promise<ICommandResult> {
+  const trimmed = args.trim();
+  const verb = trimmed.split(/\s+/)[0]?.toLowerCase() ?? '';
+
+  if (trimmed.length === 0 || verb === 'help') {
+    return { message: PLAN_COMMAND_USAGE, success: true };
+  }
+
+  if (verb === 'status') {
+    const plan = context.getPlanState();
+    return plan
+      ? { message: formatPlan(plan), success: true, data: { phase: plan.phase } }
+      : { message: 'No plan is active.', success: true };
+  }
+
+  if (verb === 'approve') {
+    if (!context.getPlanState()) {
+      return { message: 'No plan to approve. Start one with /plan <objective>.', success: false };
+    }
+    try {
+      const plan = context.approvePlan();
+      return {
+        message: `Plan approved — edits will auto-apply; shell steps stay confirmed.\nPhase: ${plan.phase}`,
+        success: true,
+        data: { phase: plan.phase },
+      };
+    } catch (error) {
+      // allow-fallback: an out-of-phase approval surfaces as a failed command, not a crash
+      return { message: error instanceof Error ? error.message : String(error), success: false };
+    }
+  }
+
+  if (verb === 'revert') {
+    if (!context.getPlanState()) {
+      return { message: 'No plan to revert.', success: false };
+    }
+    const plan = context.revertPlan();
+    return {
+      message: `Reverted to drafting — edits are blocked again (plan mode).\nPhase: ${plan.phase}`,
+      success: true,
+      data: { phase: plan.phase },
+    };
+  }
+
+  let plan: IPlanArtifact;
+  try {
+    plan = await context.setPlan(trimmed);
+  } catch (error) {
+    // allow-fallback: surface an invalid-objective error as a failed command result, not a crash
+    return { message: error instanceof Error ? error.message : String(error), success: false };
+  }
+  return {
+    message: `Plan drafted (read-only until approved). Review it, then run /plan approve:\n${plan.objective}`,
+    success: true,
+    data: { planId: plan.id },
+  };
+}

package/src/plugin/__tests__/plugin-active-turn.test.ts

@@ -0,0 +1,100 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it, vi } from 'vitest';
+import { InteractiveSession } from '@robota-sdk/agent-framework';
+import type { IAIProvider, TUniversalMessage } from '@robota-sdk/agent-core';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+import { createPluginCommandModule } from '../plugin-command-module.js';
+
+async function heldTurn(denyRemote = false, commandModules = [createPluginCommandModule()]) {
+  const root = mkdtempSync(join(tmpdir(), 'plugin-active-turn-'));
+  let release!: (value: TUniversalMessage) => void;
+  const pending = new Promise<TUniversalMessage>((resolve) => { release = resolve; });
+  const run = vi.fn(() => pending);
+  const adapter: ICommandPluginAdapter = {
+    listInstalled: async () => [], listAvailablePlugins: async () => [],
+    install: vi.fn(async () => {}), uninstall: vi.fn(async () => {}),
+    enable: vi.fn(async () => {}), disable: vi.fn(async () => {}),
+    marketplaceAdd: async () => 'fixture', marketplaceRemove: async () => {},
+    marketplaceUpdate: async () => {}, marketplaceList: async () => [],
+    reloadPlugins: async () => ({ loadedPluginCount: 0 }),
+  };
+  const session = new InteractiveSession({
+    cwd: root, bare: true, environment: { HOME: root },
+    provider: { name: 'held-provider', version: '1', chat: run } as unknown as IAIProvider,
+    config: {
+      provider: { name: 'held-provider', model: 'fixture-model', apiKey: undefined },
+      defaultTrustLevel: 'safe', permissions: { allow: [], deny: [] }, env: {},
+    },
+    commandModules,
+    commandHostAdapters: { plugin: adapter },
+    ...(denyRemote ? { remoteCommandPolicy: { isAllowed: () => false } } : {}),
+  });
+  const submission = session.submit('Hold this fixture turn until its owner releases it.');
+  await vi.waitFor(() => expect(run).toHaveBeenCalledOnce());
+  return {
+    session, adapter,
+    close: async () => {
+      release({ id: 'held-response', role: 'assistant', state: 'complete', content: 'Finished', timestamp: new Date() });
+      try { await (await submission).completed; } finally {
+        await session.shutdown();
+        rmSync(root, { recursive: true, force: true });
+      }
+    },
+  };
+}
+
+describe.each(['user', 'remote'] as const)('plugin withdrawal during a %s command', (source) => {
+  it.each(['disable', 'uninstall'] as const)('allows %s while an admitted turn remains active', async (operation) => {
+    const owned = await heldTurn();
+    try {
+      const result = await owned.session.executeCommand('plugin', `${operation} fixture@market`, source);
+      expect(result?.success).toBe(true);
+      expect(owned.adapter[operation]).toHaveBeenCalledExactlyOnceWith('fixture@market');
+      expect(owned.session.isExecuting()).toBe(true);
+    } finally { await owned.close(); }
+  });
+
+  it.each(['enable', 'install'] as const)('keeps %s behind the active-turn gate', async (operation) => {
+    const owned = await heldTurn();
+    try {
+      const result = await owned.session.executeCommand('plugin', `${operation} fixture@market`, source);
+      expect(result?.success).toBe(false);
+      expect(result?.message).toContain('already running');
+      expect(owned.adapter[operation]).not.toHaveBeenCalled();
+    } finally { await owned.close(); }
+  });
+});
+
+it('preserves remote policy and model refusal for active-turn withdrawal', async () => {
+  const owned = await heldTurn(true);
+  try {
+    const result = await owned.session.executeCommand('plugin', 'disable fixture@market', 'remote');
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('configured remote-command policy');
+    for (const operation of ['disable', 'uninstall'] as const) {
+      expect(await owned.session.executeModelCommand('plugin', `${operation} fixture@market`)).toBeNull();
+      expect(owned.adapter[operation]).not.toHaveBeenCalled();
+    }
+  } finally { await owned.close(); }
+});
+
+it.each(['inline', 'blocking'] as const)('honors generic host control metadata only for %s lifecycle', async (lifecycle) => {
+  const execute = vi.fn(() => ({ success: true, message: 'Control applied' }));
+  const owned = await heldTurn(false, [{
+    name: 'fixture-control', systemCommands: [{
+      name: 'withdraw-fixture', description: 'Owner fixture control', lifecycle,
+      canRunDuringTurn: (args) => args === 'stop', modelInvocable: false, execute,
+    }],
+  }]);
+  try {
+    const refused = await owned.session.executeCommand('withdraw-fixture', 'start');
+    expect(refused?.success).toBe(false);
+    expect(execute).not.toHaveBeenCalled();
+    const result = await owned.session.executeCommand('withdraw-fixture', 'stop');
+    expect(result?.success).toBe(lifecycle === 'inline');
+    expect(execute).toHaveBeenCalledTimes(lifecycle === 'inline' ? 1 : 0);
+    expect(owned.session.isExecuting()).toBe(true);
+  } finally { await owned.close(); }
+});

package/src/plugin/__tests__/plugin-command-module.test.ts

@@ -0,0 +1,300 @@
+import type { ICommandHostContext, ICommandSessionRuntime } from '@robota-sdk/agent-framework';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+import { describe, expect, it, vi } from 'vitest';
+import { createPluginCommandModule } from '../plugin-command-module.js';
+import { executePluginCommand, executeReloadPluginsCommand } from '../plugin-command.js';
+import {
+  createTestCommandHost,
+  createTestSessionRuntime,
+} from '@robota-sdk/agent-framework/testing';
+
+function createPluginAdapter(overrides?: Partial<ICommandPluginAdapter>): ICommandPluginAdapter {
+  return {
+    listInstalled: vi.fn().mockResolvedValue([]),
+    listAvailablePlugins: vi.fn().mockResolvedValue([]),
+    install: vi.fn().mockResolvedValue(undefined),
+    uninstall: vi.fn().mockResolvedValue(undefined),
+    enable: vi.fn().mockResolvedValue(undefined),
+    disable: vi.fn().mockResolvedValue(undefined),
+    marketplaceAdd: vi.fn().mockResolvedValue('community'),
+    marketplaceRemove: vi.fn().mockResolvedValue(undefined),
+    marketplaceUpdate: vi.fn().mockResolvedValue(undefined),
+    marketplaceList: vi.fn().mockResolvedValue([]),
+    reloadPlugins: vi.fn().mockResolvedValue({ loadedPluginCount: 2 }),
+    ...overrides,
+  };
+}
+
+function createCommandSessionRuntime() {
+  return createTestSessionRuntime({
+    clearHistory: () => undefined,
+    compact: async () => undefined,
+    getContextState: () => ({
+      maxTokens: 100,
+      usedTokens: 10,
+      usedPercentage: 10,
+      remainingPercentage: 90,
+    }),
+    getPermissionMode: () => 'default',
+    setPermissionMode: () => undefined,
+    getSessionId: () => 'session_1',
+    getMessageCount: () => 0,
+    getSessionAllowedTools: () => [],
+    getAutoCompactThreshold: () => false,
+    getFullHistory: () => [],
+    getHistory: () => [],
+  });
+}
+
+function createCommandHostContext(adapter?: ICommandPluginAdapter, locality?: 'local' | 'remote') {
+  const checkpoint = {
+    id: 'checkpoint_1',
+    sessionId: 'session_1',
+    sequence: 1,
+    prompt: 'prompt',
+    createdAt: '2026-05-03T00:00:00.000Z',
+    fileCount: 0,
+  };
+  return createTestCommandHost({
+    overrides: {
+      getSession: () => createCommandSessionRuntime(),
+      getContextState: () => ({
+        maxTokens: 100,
+        usedTokens: 10,
+        usedPercentage: 10,
+        remainingPercentage: 90,
+      }),
+      getAutoCompactThreshold: () => 0.8,
+      getCommandHostAdapters: () => (adapter === undefined ? {} : { plugin: adapter }),
+      ...(locality ? { getCommandSurfaceLocality: () => locality } : {}),
+      compactContext: async () => undefined,
+      getCwd: () => '/workspace',
+      listCommands: () => [],
+      listEditCheckpoints: () => [],
+      restoreEditCheckpoint: async () => ({
+        target: checkpoint,
+        restoredCheckpointCount: 0,
+        restoredFileCount: 0,
+        removedCheckpointCount: 0,
+      }),
+      rollbackEditCheckpoint: async () => ({
+        target: checkpoint,
+        restoredCheckpointCount: 0,
+        restoredFileCount: 0,
+        removedCheckpointCount: 0,
+      }),
+      getUsedMemoryReferences: () => [],
+      recordMemoryEvent: () => undefined,
+      listBackgroundTasks: () => [],
+      readBackgroundTaskLog: async (taskId) => ({ taskId, lines: [] }),
+      cancelBackgroundTask: async () => undefined,
+      closeBackgroundTask: async () => undefined,
+    },
+  });
+}
+
+describe('createPluginCommandModule', () => {
+  it('contributes plugin command metadata and executable commands', () => {
+    const module = createPluginCommandModule();
+
+    expect(module.name).toBe('agent-command-plugin');
+    expect(module.commandSources?.[0]?.getCommands()).toEqual([
+      expect.objectContaining({
+        name: 'plugin',
+        description: expect.stringContaining('returns operation status'),
+        source: 'plugin-manager',
+        modelInvocable: false,
+        argumentHint: expect.stringContaining('install'),
+      }),
+      expect.objectContaining({
+        name: 'reload-plugins',
+        description: expect.stringContaining(
+          'refresh the command list, skill routing and model skill catalogue',
+        ),
+        source: 'plugin-manager',
+        modelInvocable: false,
+      }),
+    ]);
+    expect(module.systemCommands?.map((command) => command.name)).toEqual([
+      'plugin',
+      'reload-plugins',
+    ]);
+    expect(module.systemCommands?.[0]?.lifecycle).toBe('inline');
+  });
+});
+
+describe('executePluginCommand', () => {
+  it('opens the host plugin manager for empty args', async () => {
+    await expect(executePluginCommand(createCommandHostContext(), '')).resolves.toEqual({
+      success: true,
+      message: 'Opening plugin manager...',
+      uiIntents: [{ type: 'show-plugin-manager' }],
+    });
+  });
+
+  it('returns unavailable when an operation needs a missing adapter', async () => {
+    await expect(
+      executePluginCommand(createCommandHostContext(), 'install demo@community'),
+    ).resolves.toEqual({
+      success: false,
+      message: 'Plugin management is not available.',
+    });
+  });
+
+  it('installs plugins through the adapter', async () => {
+    const adapter = createPluginAdapter();
+
+    await expect(
+      executePluginCommand(createCommandHostContext(adapter), 'install demo@community'),
+    ).resolves.toEqual({
+      success: true,
+      message: 'Installed plugin: demo@community',
+    });
+    expect(adapter.install).toHaveBeenCalledWith('demo@community');
+  });
+
+  it('lists marketplaces through the adapter', async () => {
+    const adapter = createPluginAdapter({
+      marketplaceList: vi.fn().mockResolvedValue([{ name: 'community', type: 'git' }]),
+    });
+
+    const result = await executePluginCommand(
+      createCommandHostContext(adapter),
+      'marketplace list',
+    );
+
+    expect(result).toEqual({
+      success: true,
+      message: 'Marketplace sources:\n  community (git)',
+    });
+    expect(adapter.marketplaceList).toHaveBeenCalled();
+  });
+
+  it('reports adapter errors as command failures', async () => {
+    const adapter = createPluginAdapter({
+      enable: vi.fn().mockRejectedValue(new Error('not installed')),
+    });
+
+    await expect(
+      executePluginCommand(createCommandHostContext(adapter), 'enable missing@community'),
+    ).resolves.toEqual({
+      success: false,
+      message: 'Plugin error: not installed',
+    });
+  });
+
+  it('returns usage for incomplete subcommands', async () => {
+    await expect(executePluginCommand(createCommandHostContext(), 'disable')).resolves.toEqual({
+      success: false,
+      message: 'Usage: /plugin disable <name>@<marketplace>',
+    });
+  });
+
+  it('lists installed plugins through the adapter, for the Settings screen (#3282 §4 part b-2)', async () => {
+    const adapter = createPluginAdapter({
+      listInstalled: vi.fn().mockResolvedValue([
+        { name: 'formatter@fixture-agent', description: 'Formats code.', enabled: true },
+        { name: 'linter@fixture-agent', description: 'Lints code.', enabled: false },
+      ]),
+    });
+
+    const result = await executePluginCommand(createCommandHostContext(adapter), 'list');
+
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual({
+      plugins: [
+        { name: 'formatter@fixture-agent', description: 'Formats code.', enabled: true },
+        { name: 'linter@fixture-agent', description: 'Lints code.', enabled: false },
+      ],
+    });
+    expect(result.message).toContain('formatter@fixture-agent');
+    expect(result.message).toContain('linter@fixture-agent (disabled)');
+  });
+
+  it('no plugins installed reports a plain empty list', async () => {
+    const adapter = createPluginAdapter();
+    const result = await executePluginCommand(createCommandHostContext(adapter), 'list');
+    expect(result).toEqual({
+      success: true,
+      message: 'No plugins are installed.',
+      data: { plugins: [] },
+    });
+  });
+
+  describe('install/uninstall stay local-surface-only (#3282 §4 part b-2)', () => {
+    it('runs install from a local surface', async () => {
+      const adapter = createPluginAdapter();
+      const result = await executePluginCommand(
+        createCommandHostContext(adapter, 'local'),
+        'install demo@community',
+      );
+      expect(result.success).toBe(true);
+      expect(adapter.install).toHaveBeenCalledWith('demo@community');
+    });
+
+    it('refuses install from a remote surface with a plain message, writing nothing', async () => {
+      const adapter = createPluginAdapter();
+      const result = await executePluginCommand(
+        createCommandHostContext(adapter, 'remote'),
+        'install demo@community',
+      );
+      expect(result.success).toBe(false);
+      expect(result.message).toMatch(/only works from the desktop app or the page opened here/);
+      expect(result.message).toMatch(/not from a remote device/);
+      expect(adapter.install).not.toHaveBeenCalled();
+    });
+
+    it('refuses uninstall from a remote surface with a plain message, writing nothing', async () => {
+      const adapter = createPluginAdapter();
+      const result = await executePluginCommand(
+        createCommandHostContext(adapter, 'remote'),
+        'uninstall demo@community',
+      );
+      expect(result.success).toBe(false);
+      expect(result.message).toMatch(/not from a remote device/);
+      expect(adapter.uninstall).not.toHaveBeenCalled();
+    });
+
+    it('never refuses enable/disable/reload from a remote surface — only install/uninstall run new code', async () => {
+      const adapter = createPluginAdapter();
+      const enableResult = await executePluginCommand(
+        createCommandHostContext(adapter, 'remote'),
+        'enable demo@community',
+      );
+      expect(enableResult.success).toBe(true);
+      expect(adapter.enable).toHaveBeenCalledWith('demo@community');
+    });
+  });
+});
+
+describe('executeReloadPluginsCommand', () => {
+  it('reloads plugins through the adapter and requests registry refresh', async () => {
+    const adapter = createPluginAdapter({
+      reloadPlugins: vi.fn().mockResolvedValue({ loadedPluginCount: 3 }),
+    });
+
+    await expect(
+      executeReloadPluginsCommand(createCommandHostContext(adapter), ''),
+    ).resolves.toEqual({
+      success: true,
+      message:
+        'Reloaded 3 plugin resources. Plugin commands and skills are active now; hook changes apply to new sessions.',
+      data: { pluginRegistryReloaded: true },
+    });
+    expect(adapter.reloadPlugins).toHaveBeenCalled();
+  });
+
+  it('reports reload failures instead of returning placeholder success', async () => {
+    const adapter = createPluginAdapter({
+      reloadPlugins: vi.fn().mockRejectedValue(new Error('manifest failed')),
+    });
+
+    await expect(
+      executeReloadPluginsCommand(createCommandHostContext(adapter), ''),
+    ).resolves.toEqual({
+      success: false,
+      message: 'Plugin error: manifest failed',
+      data: { pluginRegistryReloaded: true },
+    });
+  });
+});