fix: preserve orientation rename compatibility

Author: thymikee

src/__tests__/batch-command-alias.test.ts

@@ -33,3 +33,15 @@ test('daemon batch policy leaves canonical and unknown names intact', () => {
   assert.equal(normalizeBatchCommandName('press'), 'press');
   assert.throws(() => readStructuredBatchCommandName('not-a-command', 1), /not available/);
 });
+
+test('non-CLI batch normalization does not drop relaunch implied flags', () => {
+  assert.equal(normalizeBatchCommandName('relaunch'), 'relaunch');
+  assert.throws(() => readStructuredBatchCommandName('relaunch', 1), /not available/);
+  assert.throws(
+    () =>
+      readCliBatchStepsJson(
+        JSON.stringify([{ command: 'relaunch', positionals: ['com.example.app'] }]),
+      ),
+    /not available/,
+  );
+});

src/batch-policy.ts

@@ -1,6 +1,6 @@
 import { deriveStructuredBatchCommandNames } from './core/command-descriptor/derive.ts';
 import { commandDescriptors } from './core/command-descriptor/registry.ts';
-import { normalizeCommandAlias } from './command-aliases.ts';
+import { normalizeCrossSurfaceCommandAlias } from './command-aliases.ts';
 import { AppError } from './kernel/errors.ts';
 
 /**
@@ -62,7 +62,7 @@ export function normalizeBatchCommandName(command: unknown): string {
   // map so structured batch data carrying a renamed command validates and runs
   // against the canonical descriptor instead of failing as unavailable.
   const raw = typeof command === 'string' ? command.trim().toLowerCase() : '';
-  return raw ? normalizeCommandAlias(raw) : '';
+  return raw ? normalizeCrossSurfaceCommandAlias(raw) : '';
 }
 
 export function readStructuredBatchCommandName(

src/cli/batch-steps.ts

@@ -3,7 +3,7 @@ import { type SessionRuntimeHints } from '../kernel/contracts.ts';
 import { parseBatchStepRuntime } from '../batch-contract.ts';
 import { readInputFromCli } from '../commands/cli-grammar.ts';
 import { isCommandName, type CommandName } from '../commands/command-metadata.ts';
-import { normalizeCommandAlias } from '../command-aliases.ts';
+import { normalizeCrossSurfaceCommandAlias } from '../command-aliases.ts';
 import type { CliFlags } from '../commands/cli-grammar/flag-types.ts';
 import { AppError } from '../kernel/errors.ts';
 import { isRecord } from '../utils/parsing.ts';
@@ -70,7 +70,7 @@ function readStructuredBatchStep(
   return {
     ...rest,
     // Resolve command-name aliases (e.g. `rotate` -> `orientation`) from the shared map.
-    command: normalizeCommandAlias(rest.command),
+    command: normalizeCrossSurfaceCommandAlias(rest.command),
     ...(runtime === undefined ? {} : { runtime }),
   };
 }
@@ -96,7 +96,7 @@ function readLegacyCommand(value: unknown, stepNumber: number): CommandName {
   const raw = typeof value === 'string' ? value.trim().toLowerCase() : '';
   if (!raw) throw new AppError('INVALID_ARGS', `Batch step ${stepNumber} requires command.`);
   // Resolve command-name aliases (e.g. `rotate` -> `orientation`) from the shared map.
-  const command = normalizeCommandAlias(raw);
+  const command = normalizeCrossSurfaceCommandAlias(raw);
   if (isCommandName(command)) return command;
   throw new AppError(
     'INVALID_ARGS',

src/command-aliases.ts

@@ -8,22 +8,29 @@ export type CommandAlias = {
   alias: string;
   command: string;
   impliedFlags?: readonly BooleanCliFlagKey[];
+  /** A previously canonical command name that must work outside CLI parsing. */
+  crossSurfaceRename?: true;
+  /** Legacy response discriminant retained for hidden compatibility execution. */
+  legacyResultAction?: string;
 };
 
-// The single source of truth for command-name aliases. It is applied at two
-// ingress boundaries so an alias resolves the same way regardless of how a
-// command arrives: CLI token parsing (`src/cli/parser/args.ts`) and the daemon
-// request boundary (`src/daemon/request-router.ts`), which covers structured
-// batch steps, recorded replay data, and older remote clients that send the
-// wire command directly. `impliedFlags` is a CLI-parse-only concern.
+// The single source of truth for command-name aliases. CLI parsing accepts all
+// entries and applies implied flags. Non-CLI command-data boundaries accept only
+// cross-surface renames: ordinary CLI aliases such as `relaunch` cannot be
+// rewritten safely without also applying their parser-only implied flags.
 const COMMAND_ALIASES: readonly CommandAlias[] = [
   { alias: 'long-press', command: 'longpress' },
   { alias: 'metrics', command: 'perf' },
   { alias: 'tap', command: 'press' },
   { alias: 'launch', command: 'open' },
   { alias: 'relaunch', command: 'open', impliedFlags: ['relaunch'] },
   // Deprecated: `rotate` collided with the `gesture rotate` two-finger gesture.
-  { alias: 'rotate', command: 'orientation' },
+  {
+    alias: 'rotate',
+    command: 'orientation',
+    crossSurfaceRename: true,
+    legacyResultAction: 'rotate',
+  },
 ];
 
 const aliasByToken: ReadonlyMap<string, CommandAlias> = new Map(
@@ -34,6 +41,11 @@ export function normalizeCommandAlias(command: string): string {
   return aliasByToken.get(command.toLowerCase())?.command ?? command;
 }
 
+export function normalizeCrossSurfaceCommandAlias(command: string): string {
+  const entry = aliasByToken.get(command.toLowerCase());
+  return entry?.crossSurfaceRename === true ? entry.command : command;
+}
+
 export function commandAlias(rawCommand: string): CommandAlias | undefined {
   return aliasByToken.get(rawCommand.toLowerCase());
 }

src/daemon/__tests__/request-router-command-alias.test.ts

@@ -91,3 +91,22 @@ test('daemon boundary leaves canonical commands untouched', async () => {
 
   expect(mockDispatch.mock.calls[0]?.[1]).toBe('orientation');
 });
+
+test('daemon boundary does not rewrite relaunch to plain open without its implied flag', async () => {
+  const sessionStore = makeSessionStore('agent-device-router-alias-');
+  sessionStore.set('qa-ios', makeIosSession('qa-ios'));
+
+  const handler = createHandler(sessionStore);
+  await handler({
+    token: 'test-token',
+    session: 'qa-ios',
+    command: 'relaunch',
+    positionals: ['com.example.app'],
+    flags: {},
+    meta: { requestId: 'req-relaunch-alias' },
+  });
+
+  expect(mockDispatch).toHaveBeenCalledTimes(1);
+  expect(mockDispatch.mock.calls[0]?.[1]).toBe('relaunch');
+  expect(mockDispatch.mock.calls[0]?.[1]).not.toBe('open');
+});

src/daemon/request-router.ts

@@ -3,7 +3,7 @@ import {
   withTargetDeviceResolutionScope,
 } from '../core/dispatch-resolve.ts';
 import { AppError, normalizeError, retriableForErrorCode } from '../kernel/errors.ts';
-import { normalizeCommandAlias } from '../command-aliases.ts';
+import { normalizeCrossSurfaceCommandAlias } from '../command-aliases.ts';
 import { supportedPlatformsForCommand } from '../core/capabilities.ts';
 import { timingSafeStringEqual } from '../utils/timing-safe-equal.ts';
 import type { DaemonArtifactType, DaemonError, ResponseCost } from '../kernel/contracts.ts';
@@ -369,7 +369,7 @@ function enrichDaemonError(command: string, error: DaemonError): DaemonError {
 // command reaches its canonical descriptor no matter the ingress path. Returns
 // the original request object unchanged when the command is already canonical.
 function canonicalizeRequestCommand(req: DaemonRequest): DaemonRequest {
-  const canonical = normalizeCommandAlias(req.command);
+  const canonical = normalizeCrossSurfaceCommandAlias(req.command);
   return canonical === req.command ? req : { ...req, command: canonical };
 }
 

src/mcp/__tests__/command-tools.test.ts

@@ -39,6 +39,33 @@ test('MCP command tool executor hides client creation behind an execution adapte
   assert.equal(result.content[0]?.text, 'Ran wait');
 });
 
+test('MCP executes deprecated rotate calls without advertising a second tool', async () => {
+  const calls: unknown[] = [];
+  const executor = createCommandToolExecutor({
+    createClient: () => ({}) as AgentDeviceClient,
+    runCommand: async (_client, name, input) => {
+      calls.push({ name, input });
+      return {
+        action: 'orientation',
+        orientation: 'landscape-left',
+        message: 'Rotated to landscape-left',
+      };
+    },
+  });
+
+  const result = await executor.execute('rotate', { orientation: 'landscape-left' });
+
+  assert.deepEqual(calls, [
+    { name: 'orientation', input: { orientation: 'landscape-left' } },
+  ]);
+  assert.deepEqual(result.structuredContent, {
+    action: 'rotate',
+    orientation: 'landscape-left',
+    message: 'Rotated to landscape-left',
+  });
+  assert.equal(listCommandTools().some((tool) => tool.name === 'rotate'), false);
+});
+
 test('MCP command tool executor renders optimized snapshot text by default', async () => {
   const executor = createCommandToolExecutor({
     createClient: () => ({}) as AgentDeviceClient,

src/mcp/command-tools.ts

@@ -10,6 +10,11 @@ import {
 import { COMMAND_OUTPUT_SCHEMAS } from './command-output-schemas.ts';
 import { AppError } from '../kernel/errors.ts';
 import { formatToolErrorText, normalizeToolError } from './tool-error.ts';
+import {
+  commandAlias,
+  normalizeCrossSurfaceCommandAlias,
+  type CommandAlias,
+} from '../command-aliases.ts';
 
 export type ToolResult = {
   isError: boolean;
@@ -65,17 +70,28 @@ export function createCommandToolExecutor(deps: CommandToolExecutorDeps = {}): C
   const refPinsByScope = new Map<string, Map<string, number>>();
   return {
     execute: async (name, input) => {
-      if (!isCommandName(name)) {
+      const canonicalName = normalizeCrossSurfaceCommandAlias(name);
+      if (!isCommandName(canonicalName)) {
         throw new AppError('INVALID_ARGS', `Unknown command tool: ${name}`);
       }
+      const alias = canonicalName === name ? undefined : commandAlias(name);
       const config = readMcpToolConfig(input);
       const commandInput = stripMcpConfigFields(input);
       const scopeKey = readPinScopeKey(config, commandInput);
-      const pinnedInput = pinPlainRefArguments(name, commandInput, refPinsByScope.get(scopeKey));
+      const pinnedInput = pinPlainRefArguments(
+        canonicalName,
+        commandInput,
+        refPinsByScope.get(scopeKey),
+      );
       const client = await createClient(deps, config.client);
       try {
-        const result = await (deps.runCommand ?? runCommand)(client, name, pinnedInput);
-        mergeIssuedRefPins(refPinsByScope, scopeKey, name, result);
+        const canonicalResult = await (deps.runCommand ?? runCommand)(
+          client,
+          canonicalName,
+          pinnedInput,
+        );
+        const result = restoreLegacyAliasResult(alias, canonicalResult);
+        mergeIssuedRefPins(refPinsByScope, scopeKey, canonicalName, result);
         return {
           isError: false,
           structuredContent: result,
@@ -85,7 +101,7 @@ export function createCommandToolExecutor(deps: CommandToolExecutorDeps = {}): C
               // Render from the UNPINNED input: the model typed plain refs and
               // must never see generation suffixes (zero token cost).
               text: renderToolText({
-                name,
+                name: canonicalName,
                 input: commandInput,
                 result,
                 outputFormat: config.outputFormat,
@@ -101,6 +117,12 @@ export function createCommandToolExecutor(deps: CommandToolExecutorDeps = {}): C
   };
 }
 
+function restoreLegacyAliasResult(alias: CommandAlias | undefined, result: unknown): unknown {
+  if (!alias?.legacyResultAction) return result;
+  const record = asOptionalRecord(result);
+  return record ? { ...record, action: alias.legacyResultAction } : result;
+}
+
 /**
  * ADR 0012: a command error is a ref-issuing result — `isError: true`, the
  * normalized error as `structuredContent`, and an `available`