@robota-sdk/agent-command 3.0.0-beta.79 → 3.0.0-beta.82

package/src/preset/preset-command.ts

@@ -1,21 +1,60 @@
 import { selectAction } from '@robota-sdk/agent-core';
 import { applyPresetToSession } from '@robota-sdk/agent-framework';
-import { getPreset, listPresets, resolvePreset } from '@robota-sdk/agent-preset';
+import { createPresetRegistry } from '@robota-sdk/agent-preset';
 
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type {
+  ICommandHostAdapterAccess,
+  ICommandHostPresetApplication,
+  IPresetApplicationOptions,
+  ICommandHostSessionAccess,
+  ICommandHostUserInteraction,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { IPresetSummary } from '@robota-sdk/agent-preset';
 
-/** Default active preset id reported when the runtime has no recorded active preset. */
-const DEFAULT_ACTIVE_PRESET_ID = 'default';
+/**
+ * ARCH-009 — the registry `/preset` discovers through.
+ *
+ * The host supplies the instance it resolved with through the ADAPTER bag — the same path
+ * `/permission-mode` and `/plugin` already take to their host capabilities. A host that supplies none
+ * gets a fresh built-ins registry. That order is the point: while discovery read a module-global
+ * registry directly, two products in one process shared one mutable list, so ARCH-008's per-instance
+ * resolution was only half-true for an embedded host. A command runs with an `ICommandHostContext`
+ * and nothing else, so the context is the only path from here to the instance the shell built.
+ *
+ * The fallback is deliberate rather than transitional, and it is no longer process state: a host that
+ * never loads external presets has nothing to hand over, and `/preset` should still list the
+ * built-ins. `createPresetRegistry()` with no argument is exactly that, constructed per call.
+ */
+/**
+ * What `/preset` actually needs from a registry — three members, no assertion.
+ *
+ * Narrower than `agent-preset`'s `IPresetRegistry` on purpose. Review of ARCH-009 reported the first
+ * version reaching that contract with three casts, one of which (`listPresets()`) widened optional
+ * `title`/`description` into required ones and would have printed `id — undefined: undefined` for a
+ * host that typechecked. The fix is not a better cast: it is asking for the shape the command uses,
+ * so both the built-in registry and a host adapter satisfy it STRUCTURALLY and nothing is asserted.
+ *
+ * `getPreset` returns `unknown` because presence is the whole question here.
+ */
+interface IPresetDiscovery {
+  listPresets(): readonly IPresetSummary[];
+  getPreset(id: string): unknown;
+  resolvePreset(id: string, context?: unknown): IPresetApplicationOptions;
+}
+
+function presetRegistry(context: ICommandHostAdapterAccess): IPresetDiscovery {
+  return context.getCommandHostAdapters?.().presetRegistry ?? createPresetRegistry();
+}
 
 /** Read the active preset id from the session, defaulting when the optional seam is absent. */
-function readActivePresetId(context: ICommandHostContext): string {
-  return context.getSession().getActivePresetId?.() ?? DEFAULT_ACTIVE_PRESET_ID;
+function readActivePresetId(context: ICommandHostSessionAccess): string {
+  return context.getSession().getActivePresetId();
 }
 
 /** Build the `/preset` listing: one line per preset, marking the active one with a `*` prefix. */
-function formatPresetList(active: string): string {
-  const lines = listPresets().map((preset) => {
+function formatPresetList(active: string, registry: IPresetDiscovery): string {
+  const lines = registry.listPresets().map((preset) => {
     const marker = preset.id === active ? '* ' : '  ';
     return `${marker}${preset.id} — ${preset.title}: ${preset.description}`;
   });
@@ -23,20 +62,24 @@ function formatPresetList(active: string): string {
 }
 
 /** Build the rejection message for an unknown preset id, listing the valid ids. */
-function formatUnknownPresetMessage(id: string): string {
-  const ids = listPresets()
+function formatUnknownPresetMessage(id: string, registry: IPresetDiscovery): string {
+  const ids = registry
+    .listPresets()
     .map((preset) => preset.id)
     .join(', ');
   return `Unknown preset: ${id}. Available: ${ids}`;
 }
 
 /** The `/preset` (or `/preset list`) listing result. */
-function presetListResult(context: ICommandHostContext): ICommandResult {
+function presetListResult(
+  context: ICommandHostSessionAccess,
+  registry: IPresetDiscovery,
+): ICommandResult {
   const active = readActivePresetId(context);
   return {
-    message: formatPresetList(active),
+    message: formatPresetList(active, registry),
     success: true,
-    data: { presets: listPresets(), active },
+    data: { presets: registry.listPresets(), active },
   };
 }
 
@@ -44,10 +87,13 @@ function presetListResult(context: ICommandHostContext): ICommandResult {
  * Ask the user to pick a preset (CMD-004 inline ask). Returns the chosen id, or `undefined` when no
  * interactive renderer is attached or the user cancelled — the caller then shows the preset list.
  */
-async function resolvePresetViaAsk(context: ICommandHostContext): Promise<string | undefined> {
-  const ui = context.getUserInteraction?.();
+async function resolvePresetViaAsk(
+  context: ICommandHostUserInteraction,
+  registry: IPresetDiscovery,
+): Promise<string | undefined> {
+  const ui = context.getUserInteraction();
   if (!ui) return undefined;
-  const options = listPresets().map((preset) => ({
+  const options = registry.listPresets().map((preset) => ({
     value: preset.id,
     label: preset.id,
     description: preset.description,
@@ -57,34 +103,46 @@ async function resolvePresetViaAsk(context: ICommandHostContext): Promise<string
 }
 
 export async function executePresetCommand(
-  context: ICommandHostContext,
+  context: ICommandHostPresetApplication &
+    ICommandHostSessionAccess &
+    ICommandHostUserInteraction &
+    ICommandHostAdapterAccess,
   args: string,
 ): Promise<ICommandResult> {
+  // ARCH-009: resolved ONCE per invocation, so listing, lookup and resolution cannot disagree — a
+  // host that swapped registries mid-command would otherwise report one set and apply another.
+  const registry = presetRegistry(context);
   let id: string | undefined = args.trim().split(/\s+/)[0];
 
   if (id === 'list') {
-    return presetListResult(context);
+    return presetListResult(context, registry);
   }
 
   if (id === undefined || id.length === 0) {
-    id = await resolvePresetViaAsk(context);
+    id = await resolvePresetViaAsk(context, registry);
     if (id === undefined) {
-      return presetListResult(context);
+      return presetListResult(context, registry);
     }
   }
 
-  if (getPreset(id) === undefined) {
+  if (registry.getPreset(id) === undefined) {
     return {
-      message: formatUnknownPresetMessage(id),
+      message: formatUnknownPresetMessage(id, registry),
       success: false,
     };
   }
 
-  const resolved = resolvePreset(id);
-  await applyPresetToSession(context, id, resolved);
+  const resolved = registry.resolvePreset(id);
+  const result = await applyPresetToSession(context, id, resolved);
+  // INFRA-032: surface any preset command-module name that matched no live module as a non-fatal
+  // notice — an in-session `/preset` switch is no longer silent about a short form / typo.
+  const noticeLines = result.unknownCommandModules.map(
+    ({ name, kind }) =>
+      `Preset command-module "${name}" (${kind}) matched no module — expected the agent-command-* form; ignored.`,
+  );
   return {
-    message: `Switched to preset: ${id}`,
+    message: [`Switched to preset: ${id}`, ...noticeLines].join('\n'),
     success: true,
-    data: { preset: id },
+    data: { preset: id, unknownCommandModules: result.unknownCommandModules },
   };
 }

package/src/provider/__tests__/org-policy.test.ts

@@ -9,6 +9,7 @@ import type {
 } from '@robota-sdk/agent-framework';
 import { createProviderCommandModule } from '../provider-command-module.js';
 import { scriptedContext } from './scripted-interaction.js';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
 
 const providerDefinitions: readonly IProviderDefinition[] = [
   {
@@ -64,7 +65,7 @@ function createExecutor(
 }
 
 /** Context with no interactive renderer attached (headless/automation). */
-const headlessContext = {} as ICommandHostContext;
+const headlessContext = createTestCommandHost();
 
 describe('org policy enforcement in provider commands', () => {
   afterEach(() => {
@@ -92,7 +93,7 @@ describe('org policy enforcement in provider commands', () => {
     expect(result?.success).toBe(false);
     expect(result?.message).toContain('"openai" is not allowed');
     expect(result?.message).toContain('admin@example.com');
-    expect(result?.effects).toBeUndefined();
+    expect(result?.hostActions).toBeUndefined();
   });
 
   it('allows /provider switch when target is in allowedProviders', async () => {
@@ -112,9 +113,7 @@ describe('org policy enforcement in provider commands', () => {
     );
 
     expect(result?.success).toBe(true);
-    expect(result?.effects).toEqual([
-      { type: 'provider-hot-swap-requested', profileName: 'openai' },
-    ]);
+    expect(result?.hostActions).toEqual([{ type: 'provider-hot-swap', profileName: 'openai' }]);
   });
 
   it('rejects plaintext API key during edit when requireApiKeyFromEnv is true', async () => {

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

@@ -8,6 +8,7 @@ import type {
 } from '@robota-sdk/agent-framework';
 import { createProviderCommandModule } from '../provider-command-module.js';
 import { scriptedContext } from './scripted-interaction.js';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
 
 const providerDefinitions: readonly IProviderDefinition[] = [
   {
@@ -95,7 +96,7 @@ function createExecutor(adapter: IProviderCommandSettingsAdapter): SystemCommand
 }
 
 /** Context with no interactive renderer attached (headless/automation). */
-const headlessContext = {} as ICommandHostContext;
+const headlessContext = createTestCommandHost();
 
 describe('createProviderCommandModule', () => {
   it('contributes /provider metadata and executable command from the provider package', () => {
@@ -190,9 +191,7 @@ describe('createProviderCommandModule', () => {
       'Switched to openai (supergemma4-26b-uncensored-v2). History preserved.',
     );
     expect(readTarget().currentProvider).toBe('openai');
-    expect(result?.effects).toEqual([
-      { type: 'provider-hot-swap-requested', profileName: 'openai' },
-    ]);
+    expect(result?.hostActions).toEqual([{ type: 'provider-hot-swap', profileName: 'openai' }]);
   });
 
   it('switches from the provider profile action menu immediately without confirmation', async () => {
@@ -217,9 +216,7 @@ describe('createProviderCommandModule', () => {
       'Switched to openai (supergemma4-26b-uncensored-v2). History preserved.',
     );
     expect(readTarget().currentProvider).toBe('openai');
-    expect(result?.effects).toEqual([
-      { type: 'provider-hot-swap-requested', profileName: 'openai' },
-    ]);
+    expect(result?.hostActions).toEqual([{ type: 'provider-hot-swap', profileName: 'openai' }]);
   });
 
   it('edits a provider profile through provider-owned setup metadata without exposing secrets', async () => {
@@ -261,8 +258,8 @@ describe('createProviderCommandModule', () => {
       },
     });
     expect(completed?.message).toBe('Provider anthropic updated. Switching...');
-    expect(completed?.effects).toEqual([
-      { type: 'provider-hot-swap-requested', profileName: 'anthropic' },
+    expect(completed?.hostActions).toEqual([
+      { type: 'provider-hot-swap', profileName: 'anthropic' },
     ]);
   });
 
@@ -296,7 +293,7 @@ describe('createProviderCommandModule', () => {
         },
       },
     });
-    expect(completed?.effects).toBeUndefined();
+    expect(completed?.hostActions).toBeUndefined();
   });
 
   it('deletes inactive provider profiles after confirmation', async () => {
@@ -371,9 +368,9 @@ describe('createProviderCommandModule', () => {
         openai: { type: 'openai', model: 'supergemma4-26b-uncensored-v2' },
       },
     });
-    expect(completed?.effects).toEqual([
+    expect(completed?.hostActions).toEqual([
       {
-        type: 'session-restart-requested',
+        type: 'session-restart',
         reason: 'other',
         message: 'Provider delete restart',
       },
@@ -437,9 +434,9 @@ describe('createProviderCommandModule', () => {
         },
       },
     });
-    expect(completed?.effects).toEqual([
+    expect(completed?.hostActions).toEqual([
       {
-        type: 'session-restart-requested',
+        type: 'session-restart',
         reason: 'other',
         message: 'Provider setup restart',
       },

package/src/provider/__tests__/provider-startup-host-settings.test.ts

@@ -0,0 +1,16 @@
+import { expect, it } from 'vitest';
+
+import { ensureProviderConfig } from '../provider-startup.js';
+
+it('requires host settings access before provider startup', async () => {
+  await expect(
+    ensureProviderConfig(
+      process.cwd(),
+      {} as never,
+      async () => '',
+      { writeLine: () => undefined, writeError: () => undefined } as never,
+      [],
+      { formatError: () => 'Provider is not configured.' },
+    ),
+  ).rejects.toThrow('Provider startup requires host settings sources and stores.');
+});

package/src/provider/__tests__/scripted-interaction.ts

@@ -1,5 +1,6 @@
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
 import type { IActionRequest, IUserInteraction, TActionResponse } from '@robota-sdk/agent-core';
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
 
 /**
  * Build a command host context whose `getUserInteraction().ask` replays a scripted sequence of
@@ -8,7 +9,7 @@ import type { ICommandHostContext } from '@robota-sdk/agent-framework';
  * returns `{ type: 'cancelled' }`, mirroring a user dismissing the prompt.
  */
 export function scriptedContext(answers: readonly TActionResponse[]): {
-  context: ICommandHostContext;
+  context: ReturnType<typeof createTestCommandHost>;
   requests: IActionRequest[];
 } {
   const requests: IActionRequest[] = [];
@@ -21,8 +22,9 @@ export function scriptedContext(answers: readonly TActionResponse[]): {
       return Promise.resolve(answer ?? { type: 'cancelled' });
     },
   };
-  const context = {
-    getUserInteraction: () => ui,
-  } as Partial<ICommandHostContext> as ICommandHostContext;
+  // ARCH-029: the double answers "no capability of that kind" for everything else, so this fixture
+  // states exactly the one capability it scripts. The double cast it replaced —
+  // `as Partial<…> as ICommandHostContext` — asserted conformance twice over one member.
+  const context = createTestCommandHost({ overrides: { getUserInteraction: () => ui } });
   return { context, requests };
 }

package/src/provider/provider-command-execution.ts

@@ -12,18 +12,18 @@ import { formatProviderSetupChoiceLabel } from './provider-setup-flow.js';
 
 import type { IUserInteraction } from '@robota-sdk/agent-core';
 import type {
-  ICommandHostContext,
+  ICommandHostUserInteraction,
   IProviderCommandModuleOptions,
   IProviderProfileSettings,
 } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 
 export async function executeProviderCommand(
-  context: ICommandHostContext,
+  context: ICommandHostUserInteraction,
   args: string,
   options: IProviderCommandModuleOptions,
 ): Promise<ICommandResult> {
-  const ui = context.getUserInteraction?.();
+  const ui = context.getUserInteraction();
   const settings = options.settings.readMergedSettings();
   const trimmedArgs = args.trim();
   if (trimmedArgs.length === 0) {

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

@@ -6,7 +6,7 @@ import type {
   IProviderCommandSettingsAdapter,
   ISystemCommand as TSystemCommand,
 } from '@robota-sdk/agent-framework';
-import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
 export type { IProviderCommandModuleOptions, IProviderCommandSettingsAdapter };
 
 function buildProviderSubcommands(): ICommand[] {
@@ -25,6 +25,7 @@ export function createProviderCommandEntry(): ICommand {
     displayName: 'Provider Setup',
     description: 'Manage provider profiles',
     source: 'provider',
+    // User-only: provider profiles hold account credentials; a credential action.
     modelInvocable: false,
     argumentHint: 'current | list | switch <profile> | add [type] | test [profile]',
     subcommands: buildProviderSubcommands(),

package/src/provider/provider-command-profile-lifecycle.ts

@@ -9,11 +9,11 @@ import { formatProviderChoiceLabel } from './provider-command-profile-operations
 
 import type { IUserInteraction } from '@robota-sdk/agent-core';
 import type { IProviderCommandModuleOptions } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 
 const MAX_DUPLICATE_PROFILE_SUFFIX = 1000;
-const PROVIDER_RESTART_EFFECT = {
-  type: 'session-restart-requested',
+const PROVIDER_RESTART_ACTION = {
+  type: 'session-restart',
   reason: 'other',
 } as const;
 
@@ -166,7 +166,7 @@ function completeActiveProviderDelete(
   return {
     message: `Provider profile deleted: ${profileName}. Restarting with ${replacementName}...`,
     success: true,
-    effects: [{ ...PROVIDER_RESTART_EFFECT, message: 'Provider delete restart' }],
+    hostActions: [{ ...PROVIDER_RESTART_ACTION, message: 'Provider delete restart' }],
   };
 }
 

package/src/provider/provider-command-profile-operations.ts

@@ -15,7 +15,7 @@ import type {
   IProviderProfileSettings,
   IProviderSetupInput,
 } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 
 export function formatProviderChoiceLabel(
   name: string,
@@ -62,7 +62,7 @@ export function buildProviderSwitch(
   return {
     message: `Switched to ${profileName} (${modelLabel}). History preserved.`,
     success: true,
-    effects: [{ type: 'provider-hot-swap-requested', profileName }],
+    hostActions: [{ type: 'provider-hot-swap', profileName }],
   };
 }
 
@@ -146,6 +146,6 @@ function completeProviderEdit(
       ? `Provider ${profileName} updated. Switching...`
       : `Provider ${profileName} updated.`,
     success: true,
-    ...(isCurrent ? { effects: [{ type: 'provider-hot-swap-requested', profileName }] } : {}),
+    ...(isCurrent ? { hostActions: [{ type: 'provider-hot-swap' as const, profileName }] } : {}),
   };
 }

package/src/provider/provider-command-profile.ts

@@ -16,7 +16,7 @@ import type {
   IProviderCommandModuleOptions,
   IProviderProfileSettings,
 } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 
 const ACTION_SWITCH = 'switch';
 const ACTION_EDIT = 'edit';

package/src/provider/provider-command-setup.ts

@@ -14,10 +14,10 @@ import type {
   IProviderCommandModuleOptions,
   IProviderSetupInput,
 } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 
-const PROVIDER_RESTART_EFFECT = {
-  type: 'session-restart-requested',
+const PROVIDER_RESTART_ACTION = {
+  type: 'session-restart',
   reason: 'other',
 } as const;
 
@@ -108,6 +108,6 @@ function completeProviderSetup(
   return {
     message: `Provider ${input.profile} configured. Restarting...`,
     success: true,
-    effects: [{ ...PROVIDER_RESTART_EFFECT, message: 'Provider setup restart' }],
+    hostActions: [{ ...PROVIDER_RESTART_ACTION, message: 'Provider setup restart' }],
   };
 }

package/src/provider/provider-startup.ts

@@ -1,15 +1,11 @@
-import { join } from 'node:path';
-
 import {
   checkSettingsDocument,
   ProviderConfigError,
   readMergedProviderSettings,
-  readSettings,
-  writeSettings,
   resolveEnvDefaultProvider,
-  resolveSettingsPathForScope,
-  getProviderSettingsPaths,
   applyProviderConfiguration,
+  resolveProviderSettingsWriteTarget,
+  WorkspaceAuthorityRequiredError,
 } from '@robota-sdk/agent-framework';
 
 import { runOnboardingBranch } from './provider-onboarding.js';
@@ -22,11 +18,17 @@ import {
 
 import type { IProviderDefinition } from '@robota-sdk/agent-core';
 import type { ITerminalOutput } from '@robota-sdk/agent-core';
-import type { TSettingsScope } from '@robota-sdk/agent-framework';
+import type {
+  ISettingsDocumentStore,
+  TSettingsScope,
+  TSettingsSource,
+} from '@robota-sdk/agent-framework';
 
 export interface IProviderStartupContext {
   provider?: string;
   settingsScope?: TSettingsScope;
+  settingsSources: readonly TSettingsSource[];
+  settingsStores: readonly ISettingsDocumentStore[];
 }
 
 export interface IEnsureProviderConfigOptions {
@@ -44,8 +46,11 @@ export async function runProviderStartupSetup(
   providerDefinitions: readonly IProviderDefinition[],
 ): Promise<void> {
   const onboarding = await runOnboardingBranch(promptInput, terminal);
-  const existingProfileNames = Object.keys(readMergedProviderSettings(cwd).providers ?? {});
-  const settingsPath = resolveSettingsPathForScope(cwd, ctx.settingsScope);
+  const access = resolveSettingsAccess(ctx);
+  const existingProfileNames = Object.keys(
+    readMergedProviderSettings(access.sources).providers ?? {},
+  );
+  const settingsStore = selectSettingsStore(access.stores, ctx.settingsScope);
 
   let type: string;
   if (onboarding.preselectedType !== undefined) {
@@ -60,14 +65,14 @@ export async function runProviderStartupSetup(
   const input = await runProviderSetupPromptFlow(type, promptInput, providerDefinitions, {
     existingProfileNames,
   });
-  applyProviderConfiguration(settingsPath, input, { providerDefinitions });
+  applyProviderConfiguration(settingsStore, input, { providerDefinitions });
   const language = await promptInput('  Response language (ko/en/ja/zh, default: en): ');
   if (language) {
-    const settings = readSettings(settingsPath);
+    const settings = settingsStore.read();
     settings.language = language;
-    writeSettings(settingsPath, settings);
+    settingsStore.write(settings);
   }
-  terminal.writeLine(`\n  Config saved to ${settingsPath}\n`);
+  terminal.writeLine(`\n  Config saved to ${settingsStore.displayName}\n`);
 }
 
 export async function ensureProviderConfig(
@@ -78,7 +83,8 @@ export async function ensureProviderConfig(
   providerDefinitions: readonly IProviderDefinition[],
   options: IEnsureProviderConfigOptions,
 ): Promise<void> {
-  const merged = readMergedProviderSettings(cwd);
+  const access = resolveSettingsAccess(ctx);
+  const merged = readMergedProviderSettings(access.sources);
   const selectedSettings =
     ctx.provider !== undefined ? { ...merged, currentProvider: ctx.provider } : merged;
   if (checkSettingsDocument(selectedSettings, providerDefinitions) === 'valid') {
@@ -98,12 +104,12 @@ export async function ensureProviderConfig(
   }
   await runProviderStartupSetup(
     cwd,
-    selectStartupContext(cwd, ctx),
+    selectStartupContext(ctx, access.stores),
     promptInput,
     terminal,
     providerDefinitions,
   );
-  const updated = readMergedProviderSettings(cwd);
+  const updated = readMergedProviderSettings(access.sources);
   const updatedSettings =
     ctx.provider !== undefined ? { ...updated, currentProvider: ctx.provider } : updated;
   if (checkSettingsDocument(updatedSettings, providerDefinitions) !== 'valid') {
@@ -111,30 +117,51 @@ export async function ensureProviderConfig(
   }
 }
 
-function selectStartupContext(cwd: string, ctx: IProviderStartupContext): IProviderStartupContext {
-  if (ctx.settingsScope !== undefined || ctx.provider !== undefined) return ctx;
-  const currentProviderPath = findHighestPriorityCurrentProviderPath(getProviderSettingsPaths(cwd));
-  if (currentProviderPath === undefined) return ctx;
-  const projectSettingsPath = join(cwd, '.robota', 'settings.json');
-  const projectLocalSettingsPath = join(cwd, '.robota', 'settings.local.json');
-  if (
-    currentProviderPath === projectSettingsPath ||
-    currentProviderPath === projectLocalSettingsPath
-  ) {
-    return { ...ctx, settingsScope: 'project-local' };
+function resolveSettingsAccess(ctx: IProviderStartupContext): {
+  sources: readonly TSettingsSource[];
+  stores: readonly ISettingsDocumentStore[];
+} {
+  if (ctx.settingsSources === undefined || ctx.settingsStores === undefined) {
+    throw new Error('Provider startup requires host settings sources and stores.');
   }
+  return {
+    sources: ctx.settingsSources,
+    stores: ctx.settingsStores,
+  };
+}
+
+function selectSettingsStore(
+  stores: readonly ISettingsDocumentStore[],
+  scope: TSettingsScope | undefined,
+): ISettingsDocumentStore {
+  if (scope === undefined) return resolveProviderSettingsWriteTarget(stores);
+  const targetScope = scope === 'user' ? 'user' : 'project-local';
+  const store = stores.findLast((candidate) => candidate.scope === targetScope);
+  if (store !== undefined) return store;
+  throw new WorkspaceAuthorityRequiredError(
+    `No authorized ${targetScope} settings store is available.`,
+  );
+}
+
+function selectStartupContext(
+  ctx: IProviderStartupContext,
+  stores: readonly ISettingsDocumentStore[],
+): IProviderStartupContext {
+  if (ctx.settingsScope !== undefined || ctx.provider !== undefined) return ctx;
+  const currentProviderStore = findHighestPriorityCurrentProviderStore(stores);
+  if (currentProviderStore?.kind === 'project') return { ...ctx, settingsScope: 'project-local' };
   return ctx;
 }
 
-function findHighestPriorityCurrentProviderPath(
-  settingsPaths: readonly string[],
-): string | undefined {
-  for (let index = settingsPaths.length - 1; index >= 0; index -= 1) {
-    const settingsPath = settingsPaths[index];
-    if (settingsPath === undefined) continue;
-    const settings = readSettings(settingsPath);
+function findHighestPriorityCurrentProviderStore(
+  stores: readonly ISettingsDocumentStore[],
+): ISettingsDocumentStore | undefined {
+  for (let index = stores.length - 1; index >= 0; index -= 1) {
+    const store = stores[index];
+    if (store === undefined) continue;
+    const settings = store.read();
     if (typeof settings.currentProvider === 'string') {
-      return settingsPath;
+      return store;
     }
   }
   return undefined;

package/src/remote-control/__tests__/remote-control-command-module.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import { createRemoteControlCommandModule } from '../remote-control-command-module.js';
+
+describe('createRemoteControlCommandModule metadata', () => {
+  it('keeps palette metadata aligned with the executable command and status as the safe default', async () => {
+    const module = createRemoteControlCommandModule();
+    const palette = module.commandSources?.[0]?.getCommands()[0];
+    const executable = module.systemCommands?.[0];
+
+    expect(palette).toBeDefined();
+    expect(executable).toBeDefined();
+    expect(palette?.argumentHint).toBe('[enable|stop|status|devices|revoke <device-id>]');
+    expect(palette?.description).toBe(executable?.description);
+    expect(palette?.modelInvocable).toBe(executable?.modelInvocable);
+    expect(palette?.argumentHint).toBe(executable?.argumentHint);
+    expect(palette?.userInvocable).toBe(executable?.userInvocable);
+    expect(palette?.subcommands?.map(({ name }) => name)).toEqual([
+      'status',
+      'devices',
+      'enable',
+      'stop',
+      'revoke',
+    ]);
+    expect(palette?.subcommands).toEqual(executable?.subcommands);
+    expect(executable?.requiresPermission).toBe(false);
+    expect(executable?.modelInvocable).toBe(false);
+    expect(executable?.userInvocable).toBe(true);
+
+    const result = await executable!.execute(createTestCommandHost(), 'status');
+    expect(result.message).toContain('not available');
+    expect(result.hostActions).toBeUndefined();
+  });
+});