From 28d22579f17df6d8c94d4edc0854924ea811ffee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 21 Oct 2026 00:05:10 +0200
Subject: [PATCH 1/2] feat(hardware-button): press phone volume and power keys
 once (#3848)

---
 .../RunnerTests+CommandExecution.swift        |  12 ++
 .../RunnerTests+Interaction.swift             |  25 +++++
 .../RunnerTests+Models.swift                  |   4 +-
 .../UnitTests/RunnerTests+ModelsTests.swift   |  12 +-
 contracts/fixtures/runner-requests.json       |   2 +
 .../src/__tests__/command-result.test.ts      |   1 +
 .../command-registry/src/command-result.ts    |   2 +
 packages/command-registry/src/registry.ts     |  13 +++
 packages/contracts/src/client-system.ts       |  10 +-
 packages/contracts/src/device-rotation.ts     |  92 +++++++++++++++
 packages/contracts/src/facades/client.ts      |   1 +
 packages/contracts/src/facades/device.ts      |   5 +
 ...ctor-operation-catalog-conformance.test.ts |   3 +
 .../src/interactor-operation-catalog.ts       |  15 +++
 packages/contracts/src/interactor-types.ts    |  17 +++
 packages/contracts/src/navigation.ts          |  15 ++-
 .../src/platform-runtime-operations.ts        |  10 ++
 .../contracts/src/runtime-operation-names.ts  |   3 +
 .../src/system-button-runtime.test.ts         |  75 +++++++++++++
 .../contracts/src/system-button-runtime.ts    |  78 ++++++++++++-
 .../support/runtime-binding-conformance.ts    |  35 ++++++
 .../src/core/runtime-operation-effects.ts     |   3 +
 .../__tests__/system-button-runtime.test.ts   |  72 ++++++++++++
 .../execution/generic-runtime-execution.ts    |   9 +-
 .../src/execution/system-button-runtime.ts    | 105 +++++++++++++++++-
 .../src/__tests__/input-actions.test.ts       |  17 +++
 .../platform-android/src/input-actions.ts     |  25 +++++
 packages/platform-android/src/mechanics.ts    |   1 +
 packages/platform-android/src/runtime.test.ts |  48 ++++++++
 packages/platform-android/src/runtime.ts      |  19 +++-
 .../__tests__/index-runner-requests.test.ts   |   2 +
 .../interactor-runner-provider.test.ts        |   2 +
 packages/platform-apple/src/interactor.ts     |  16 +++
 .../platform-apple/src/navigation/runtime.ts  |  26 +++++
 packages/platform-apple/src/runner-demand.ts  |   7 +-
 .../__tests__/runner-command-traits.test.ts   |   2 +
 .../src/runner/runner-command-traits.ts       |   2 +
 .../src/runner/runner-contract.ts             |   2 +
 packages/platform-apple/src/runtime.test.ts   |  51 +++++++++
 packages/platform-linux/src/runtime.test.ts   |   6 +-
 packages/platform-web/src/runtime.test.ts     |   6 +-
 .../src/interaction-operations.test.ts        |  30 +++++
 .../src/interaction-operations.ts             |  17 ++-
 .../provider-webdriver/src/capabilities.ts    |  41 ++++++-
 .../src/platform-runtime.test.ts              |  28 +++++
 .../src/platform-runtime.ts                   |  25 ++++-
 ...bdriver-interactor-hardware-button.test.ts |  76 +++++++++++++
 .../src/webdriver-interactor.ts               |  41 +++++++
 .../src/session-event-action-presentation.ts  |  10 ++
 .../runner-read-only-registry-parity.test.ts  |   2 +
 src/agent-device-client.ts                    |   2 +
 src/client/client-types.ts                    |  15 +--
 src/commands/replay/replay-script.fixtures.ts |   1 +
 src/commands/system/index.test.ts             |  20 ++++
 src/commands/system/index.ts                  |  68 ++++++++++++
 src/commands/system/output.ts                 |   1 +
 src/core/interactors/android.ts               |   4 +
 .../command-coverage/declarations.ts          |  33 ++++++
 test/integration/command-coverage/evidence.ts |  10 ++
 .../apple-platform-output-guard.test.ts       |   1 +
 .../provider-device-runtime.fixtures.ts       |  12 ++
 .../provider-ios-runner-transport.test.ts     |  92 +++++++++++++--
 website/docs/docs/client-api.md               |   6 +
 website/docs/docs/commands.md                 |   6 +
 64 files changed, 1339 insertions(+), 53 deletions(-)
 create mode 100644 packages/provider-webdriver/src/webdriver-interactor-hardware-button.test.ts

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index d8fd33a985..f8205b0305 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -539,6 +539,18 @@ extension RunnerTests {
         )
       }
       return Response(ok: true, data: DataPayload(message: "actionButton"))
+    case .volumeUp, .volumeDown:
+      guard pressVolumeButton(command.command) else {
+        return Response(
+          ok: false,
+          error: ErrorPayload(
+            code: "UNSUPPORTED_OPERATION",
+            message: "\(command.command) requires a physical iPhone or iPad; XCUIDevice exposes no volume press on a simulator",
+            hint: "hardware-button volume-up/volume-down is supported on physical iOS devices through the runner or Appium; iOS Simulators have no pressable volume key."
+          )
+        )
+      }
+      return Response(ok: true, data: DataPayload(message: command.command.rawValue))
     case .keyboardDismiss:
       let result = dismissKeyboard(app: activeApp)
       if result.wasVisible && !result.dismissed {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
index c9e410f220..1998fcd036 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
@@ -141,6 +141,31 @@ extension RunnerTests {
 #endif
   }
 
+  /// Presses a physical volume key once, returning false when this target cannot express the press.
+  ///
+  /// `XCUIDevice.press(_:)` declares `.volumeUp` and `.volumeDown` unavailable to simulator
+  /// builds (`XCUI_SIMULATOR_UNAVAILABLE` in the XCUITest header), so the press compiles only for
+  /// a physical-device build; a simulator target refuses rather than pressing a control that
+  /// does not exist there. Every iPhone and iPad carries a volume key, so no per-model probe is
+  /// needed the way the Action Button needs `hasHardwareButton(.action)`.
+  @discardableResult
+  func pressVolumeButton(_ button: CommandType) -> Bool {
+#if os(iOS) && !targetEnvironment(simulator)
+    switch button {
+    case .volumeUp:
+      XCUIDevice.shared.press(.volumeUp)
+      return true
+    case .volumeDown:
+      XCUIDevice.shared.press(.volumeDown)
+      return true
+    default:
+      return false
+    }
+#else
+    return false
+#endif
+  }
+
   func findElement(app: XCUIApplication, text: String) -> XCUIElement? {
     let predicate = NSPredicate(format: "label CONTAINS[c] %@ OR identifier CONTAINS[c] %@ OR value CONTAINS[c] %@", text, text, text)
     let element = app.descendants(matching: .any).matching(predicate).firstMatch
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
index b2b4252d4f..bb3c41658d 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
@@ -23,6 +23,8 @@ enum CommandType: String, Codable, CaseIterable {
   case rotate
   case appSwitcher
   case actionButton
+  case volumeUp
+  case volumeDown
   case keyboardDismiss
   case keyboardReturn
   case alert
@@ -292,7 +294,7 @@ extension Command {
     case .pasteboardWrite:
       return .deviceState
 
-    case .actionButton:
+    case .actionButton, .volumeUp, .volumeDown:
       return .presentedSurfaceMutation
 
     case .querySelector:
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift
index 5104e61801..59cf06ba41 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift
@@ -208,7 +208,9 @@ extension RunnerTests {
   /// Commands that did not exist at the merge-base, so no classification of its is compared with
   /// theirs. `appState` arrived with #2929, `pasteboardWrite` with the runner-written simulator
   /// clipboard.
-  private static let commandsNewerThanTheMergeBase: Set<CommandType> = [.appState, .pasteboardWrite]
+  private static let commandsNewerThanTheMergeBase: Set<CommandType> = [
+    .appState, .pasteboardWrite, .volumeUp, .volumeDown,
+  ]
 
   /// The commands production never runs through the prepared path's body: `executeOnMain` answers
   /// these before `executeOnMainPrepared` runs, and `executeDispatched` answers `snapshot` earlier
@@ -278,6 +280,14 @@ extension RunnerTests {
         .actionButton,
         expectation(interaction: false, retry: false, launch: .presentedSurface, converts: true, retains: true)
       ),
+      (
+        .volumeUp,
+        expectation(interaction: false, retry: false, launch: .presentedSurface, converts: true, retains: true)
+      ),
+      (
+        .volumeDown,
+        expectation(interaction: false, retry: false, launch: .presentedSurface, converts: true, retains: true)
+      ),
       (.keyboardDismiss, expectation(interaction: true, retry: false, launch: .mayLaunch, converts: true, retains: true)),
       (.keyboardReturn, expectation(interaction: true, retry: false, launch: .mayLaunch, converts: true, retains: true)),
       (
diff --git a/contracts/fixtures/runner-requests.json b/contracts/fixtures/runner-requests.json
index 1beed4fbd0..f8c44628d5 100644
--- a/contracts/fixtures/runner-requests.json
+++ b/contracts/fixtures/runner-requests.json
@@ -45,6 +45,8 @@
   {"name": "ios-simulator.interactor-set-orientation.rotate", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "rotate", "orientation": "landscape-left", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
   {"name": "ios-simulator.interactor-snapshot.every-option", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "snapshot", "appBundleId": "com.example.app", "interactiveOnly": true, "preferredBackend": "tree", "customActions": true, "depth": 3, "scope": "Go", "raw": true, "commandId": "<commandId>"}},
   {"name": "ios-simulator.interactor-snapshot.observe-only", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "snapshot", "appBundleId": "com.example.app", "observeOnly": true, "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactor-volume-down.press", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "volumeDown", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactor-volume-up.press", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "volumeUp", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
   {"name": "ios-simulator.interactor-write-clipboard.text", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "pasteboardWrite", "text": "one-time code 246810", "commandId": "<commandId>"}},
   {"name": "ios-simulator.recording-clock-anchor.snapshot", "producer": "src/__tests__/screen-recording-runner-requests.test.ts", "request": {"command": "snapshot", "appBundleId": "com.example.app", "interactiveOnly": true, "depth": 1}},
   {"name": "ios-simulator.recording-start.default", "producer": "src/__tests__/screen-recording-runner-requests.test.ts", "request": {"command": "recordStart", "outPath": "capture.mp4", "appBundleId": "com.example.app"}},
diff --git a/packages/command-registry/src/__tests__/command-result.test.ts b/packages/command-registry/src/__tests__/command-result.test.ts
index 2884e64567..6d97d6887f 100644
--- a/packages/command-registry/src/__tests__/command-result.test.ts
+++ b/packages/command-registry/src/__tests__/command-result.test.ts
@@ -130,6 +130,7 @@ test('CommandResultMap is seeded only from already-existing contract result type
     | 'orientation'
     | 'app-switcher'
     | 'action-button'
+    | 'hardware-button'
     | 'fold'
     | 'clipboard'
     | 'appstate'
diff --git a/packages/command-registry/src/command-result.ts b/packages/command-registry/src/command-result.ts
index 56e2805d3c..6e0a9aeb1b 100644
--- a/packages/command-registry/src/command-result.ts
+++ b/packages/command-registry/src/command-result.ts
@@ -15,6 +15,7 @@ import type {
   AppSwitcherCommandResult,
   BackCommandResult,
   FoldCommandResult,
+  HardwareButtonCommandResult,
   HomeCommandResult,
   OrientationCommandResult,
   TvRemoteCommandResult,
@@ -72,6 +73,7 @@ export interface CommandResultMap {
   fill: FillCommandResponseData;
   find: FindCommandResponseData;
   fold: FoldCommandResult;
+  'hardware-button': HardwareButtonCommandResult;
   home: HomeCommandResult;
   hover: HoverCommandResponseData;
   keyboard: KeyboardCommandResult;
diff --git a/packages/command-registry/src/registry.ts b/packages/command-registry/src/registry.ts
index 79eecf1335..f8a8e4eda5 100644
--- a/packages/command-registry/src/registry.ts
+++ b/packages/command-registry/src/registry.ts
@@ -58,6 +58,7 @@ import {
   focusRuntimeUse,
   gestureRuntimePlanUses,
   gestureViewportRuntimeUse,
+  hardwareButtonRuntimePlanUses,
   homeRuntimeUse,
   hoverRuntimeUses,
   keyboardRuntimePlanUses,
@@ -1640,6 +1641,18 @@ export const RAW_COMMAND_DESCRIPTORS = [
     ...GENERIC_MUTATING_COMMAND_TRAITS,
     platformExecution: { kind: 'device-runtime', uses: [actionButtonRuntimeUse] },
   },
+  {
+    name: 'hardware-button',
+    ...(ownerFilesEnabled ? { ownerFiles: ['src/commands/system/index.ts'] as const } : {}),
+    catalog: { group: 'public', key: 'hardwareButton' },
+    frameworkTier: 'extended',
+    // The first positional selects the cell (volume-up, volume-down, power), the way `orientation`
+    // selects between setOrientation and unlockOrientation; admission binds exactly that one fact.
+    // Like action-button, no post-action observation is declared: the press goes to the system,
+    // not the session app, and settling would re-capture the app the press leaves alone (#3848).
+    ...GENERIC_MUTATING_COMMAND_TRAITS,
+    platformExecution: { kind: 'device-runtime', uses: hardwareButtonRuntimePlanUses },
+  },
   {
     name: 'install-from-source',
     deviceClaimPolicy: 'none',
diff --git a/packages/contracts/src/client-system.ts b/packages/contracts/src/client-system.ts
index 6b2e209c06..0de68503d9 100644
--- a/packages/contracts/src/client-system.ts
+++ b/packages/contracts/src/client-system.ts
@@ -5,7 +5,11 @@ import type { BackMode } from './back-mode.ts';
 import type { SelectorSnapshotCommandOptions } from './client-capture.ts';
 import type { DeviceCommandBaseOptions } from './client-connection.ts';
 import type { SettleCommandOptions } from './client-gesture.ts';
-import type { OrientationRequest, SetFoldPoseInput } from './device-rotation.ts';
+import type {
+  HardwareButtonName,
+  OrientationRequest,
+  SetFoldPoseInput,
+} from './device-rotation.ts';
 import type { TelephonyEventInput } from './telephony-input.ts';
 import type { TvRemoteButton } from './tv-remote.ts';
 
@@ -103,6 +107,10 @@ export type TvRemoteCommandOptions = DeviceCommandBaseOptions & {
   durationMs?: number;
 };
 
+export type HardwareButtonCommandOptions = DeviceCommandBaseOptions & {
+  button: HardwareButtonName;
+};
+
 export type TelephonyCommandOptions = DeviceCommandBaseOptions & TelephonyEventInput;
 
 export type KeyboardCommandOptions = DeviceCommandBaseOptions & {
diff --git a/packages/contracts/src/device-rotation.ts b/packages/contracts/src/device-rotation.ts
index 6107699568..629e21e13c 100644
--- a/packages/contracts/src/device-rotation.ts
+++ b/packages/contracts/src/device-rotation.ts
@@ -82,6 +82,98 @@ export function parseOrientationRequest(input: string | undefined): OrientationR
   return input?.trim().toLowerCase() === 'auto' ? 'auto' : parseDeviceRotation(input);
 }
 
+// ---- Hardware button ---------------------------------------------------------------------------
+// The `hardware-button` command's positional vocabulary lives beside the rotation vocabulary
+// because every entry that parses one command positional already evaluates this module; a module
+// of its own would join the eager closure of the daemon, replay-port, session-journal and CLI
+// entries that name a volume key (the eager-closure budgets in
+// scripts/__tests__/eager-closure-budgets.ts). The runtime-press vocabulary — the button family,
+// labels and binding — stays in system-button-runtime.ts. This module must not import from it,
+// type-only included: system-button-runtime.ts reaches this module through the snapshot and
+// interactor type graphs, so an edge back would close a contracts type cycle (layering R9/R10).
+// The label owner pins the drift with a type-level check instead — see system-button-runtime.ts.
+
+/**
+ * The phone hardware keys the `hardware-button` command selects between by positional, the way
+ * `keyboard <status|dismiss|enter>` selects a keyboard-family cell. `home`, `appSwitcher` and
+ * `actionButton` keep their own public commands, so each button has exactly one public route.
+ * Each name is a cell of {@link SYSTEM_BUTTONS}; system-button-runtime.ts checks that at
+ * compile time. The cells stay module-internal: consumers select a button by its public name.
+ */
+const HARDWARE_BUTTONS = ['volumeUp', 'volumeDown', 'power'] as const;
+
+export type HardwareButton = (typeof HARDWARE_BUTTONS)[number];
+
+/**
+ * The public positional names of the hardware keys: `volume-up`, `volume-down`, `power`.
+ * The literals are the same ones SYSTEM_BUTTON_LABELS carries for these buttons; the label
+ * owner's type-level check and the contracts tests refuse drift between the two lists.
+ */
+export type HardwareButtonName = 'volume-up' | 'volume-down' | 'power';
+
+/**
+ * The accepted positional values, in command order. `satisfies` turns an out-of-vocabulary
+ * typo into a build failure; the contracts test pins the list is exhaustive.
+ */
+export const HARDWARE_BUTTON_NAMES = [
+  'volume-up',
+  'volume-down',
+  'power',
+] as const satisfies readonly HardwareButtonName[];
+
+/** The CLI synopsis tail naming the accepted positional names. */
+export const HARDWARE_BUTTON_USAGE = `<${HARDWARE_BUTTON_NAMES.join('|')}>`;
+
+/**
+ * The public positional name each parsed button answers with, and the same literals
+ * SYSTEM_BUTTON_LABELS carries. Readers in eager-closure entries take the label from here
+ * rather than value-importing system-button-runtime.ts (#3848). The parse direction is
+ * derived by inverting this table rather than restating it.
+ */
+export const HARDWARE_BUTTON_NAME_LABELS = {
+  volumeUp: 'volume-up',
+  volumeDown: 'volume-down',
+  power: 'power',
+} as const satisfies Record<HardwareButton, HardwareButtonName>;
+
+const HARDWARE_BUTTON_NAME_MAP: ReadonlyMap<HardwareButtonName, HardwareButton> = new Map(
+  (Object.entries(HARDWARE_BUTTON_NAME_LABELS) as [HardwareButton, HardwareButtonName][]).map(
+    ([button, name]) => [name, button],
+  ),
+);
+
+/**
+ * Parses the `hardware-button` positional. Exact names only — no aliases — and an unknown name
+ * refuses with `INVALID_ARGS` before any device dispatch.
+ */
+/** Public entry for parsing one positional is {@link parseHardwareButtonPositionals}. */
+function parseHardwareButton(value: string | undefined): HardwareButton {
+  const normalized = value?.toLowerCase();
+  const button =
+    normalized === undefined
+      ? undefined
+      : HARDWARE_BUTTON_NAME_MAP.get(normalized as HardwareButtonName);
+  if (button) return button;
+  throw new AppError(
+    'INVALID_ARGS',
+    `hardware-button button must be one of: ${HARDWARE_BUTTON_NAMES.join(', ')}.`,
+  );
+}
+
+/**
+ * Owns the whole `hardware-button` positional contract: exactly one name, then the parse. The CLI
+ * reader and the daemon resolver both call this, so one typed answer serves both seams.
+ */
+export function parseHardwareButtonPositionals(positionals: readonly string[]): HardwareButton {
+  if (positionals.length !== 1) {
+    throw new AppError(
+      'INVALID_ARGS',
+      `hardware-button requires exactly one button: ${HARDWARE_BUTTON_NAMES.join(', ')}.`,
+    );
+  }
+  return parseHardwareButton(positionals[0]);
+}
+
 // ---- Hinge pose ------------------------------------------------------------------------------
 // Lives beside the rotation vocabulary because every entry that reads one device pose already
 // evaluates this module; a module of its own would join the eager closure of entries that can
diff --git a/packages/contracts/src/facades/client.ts b/packages/contracts/src/facades/client.ts
index f10e131d96..9325a37ae9 100644
--- a/packages/contracts/src/facades/client.ts
+++ b/packages/contracts/src/facades/client.ts
@@ -123,6 +123,7 @@ export type {
   ClipboardCommandOptions,
   FoldCommandOptions,
   DoctorCommandOptions,
+  HardwareButtonCommandOptions,
   HomeCommandOptions,
   KeyboardCommandOptions,
   OrientationCommandOptions,
diff --git a/packages/contracts/src/facades/device.ts b/packages/contracts/src/facades/device.ts
index 051aee5e1e..5373fde7fd 100644
--- a/packages/contracts/src/facades/device.ts
+++ b/packages/contracts/src/facades/device.ts
@@ -46,7 +46,12 @@ export {
   ORIENTATION_REQUESTS,
   parseOrientationRequest,
   parseFoldPose,
+  HARDWARE_BUTTON_NAMES,
+  HARDWARE_BUTTON_NAME_LABELS,
+  HARDWARE_BUTTON_USAGE,
+  parseHardwareButtonPositionals,
 } from '../device-rotation.ts';
+export type { HardwareButton, HardwareButtonName } from '../device-rotation.ts';
 export {
   TELEPHONY_ACTIONS,
   TELEPHONY_CALL_ACTIONS,
diff --git a/packages/contracts/src/interactor-operation-catalog-conformance.test.ts b/packages/contracts/src/interactor-operation-catalog-conformance.test.ts
index af902a059e..14d38343af 100644
--- a/packages/contracts/src/interactor-operation-catalog-conformance.test.ts
+++ b/packages/contracts/src/interactor-operation-catalog-conformance.test.ts
@@ -36,6 +36,9 @@ const EXPECTATIONS: {
   writeClipboard: { method: 'writeClipboard', input: { text: '' } },
   appSwitcher: { method: 'appSwitcher', input: {} },
   actionButton: { method: 'actionButton', input: {} },
+  volumeUp: { method: 'volumeUp', input: {} },
+  volumeDown: { method: 'volumeDown', input: {} },
+  power: { method: 'power', input: {} },
   triggerAppEvent: { method: 'open', input: { eventUrl: 'myapp://x' } },
   setSetting: {
     method: 'setSetting',
diff --git a/packages/contracts/src/interactor-operation-catalog.ts b/packages/contracts/src/interactor-operation-catalog.ts
index c07319310b..f77a73f229 100644
--- a/packages/contracts/src/interactor-operation-catalog.ts
+++ b/packages/contracts/src/interactor-operation-catalog.ts
@@ -99,6 +99,21 @@ export const INTERACTOR_OPERATIONS = [
     label: SYSTEM_BUTTON_LABELS.actionButton,
     bind: (signal, resolve) => bindSystemButton('actionButton', signal, resolve),
   },
+  {
+    operation: 'volumeUp',
+    label: SYSTEM_BUTTON_LABELS.volumeUp,
+    bind: (signal, resolve) => bindSystemButton('volumeUp', signal, resolve),
+  },
+  {
+    operation: 'volumeDown',
+    label: SYSTEM_BUTTON_LABELS.volumeDown,
+    bind: (signal, resolve) => bindSystemButton('volumeDown', signal, resolve),
+  },
+  {
+    operation: 'power',
+    label: SYSTEM_BUTTON_LABELS.power,
+    bind: (signal, resolve) => bindSystemButton('power', signal, resolve),
+  },
   { operation: 'triggerAppEvent', label: 'trigger-app-event', bind: bindAppEvent },
   { operation: 'setSetting', label: 'settings', bind: bindSetSetting },
   { operation: 'readSetting', label: 'settings read', bind: bindReadSetting },
diff --git a/packages/contracts/src/interactor-types.ts b/packages/contracts/src/interactor-types.ts
index c0a30db5b3..4167053f7e 100644
--- a/packages/contracts/src/interactor-types.ts
+++ b/packages/contracts/src/interactor-types.ts
@@ -432,6 +432,23 @@ export type Interactor = {
    * absent member as a successful no-op.
    */
   actionButton?(): Promise<void>;
+  /**
+   * Optional (parity with `home`): presses the physical volume-up key once, a control phone
+   * owners with a volume button carry. An owner without it leaves it undefined; its fact refuses
+   * the press before binding, and the system-button binder fails closed rather than resolving an
+   * absent member as a silent no-op.
+   */
+  volumeUp?(): Promise<void>;
+  /**
+   * Optional (parity with `volumeUp`): presses the physical volume-down key once.
+   */
+  volumeDown?(): Promise<void>;
+  /**
+   * Optional (parity with `volumeUp`): presses the physical power key once, which toggles the
+   * screen on Android. Apple exposes no public power/lock button press, so no Apple leaf carries
+   * it; an owner without it leaves it undefined and its fact refuses before binding.
+   */
+  power?(): Promise<void>;
   /** Optional: only Android implements a live status read (see {@link KeyboardStatusResult}). */
   keyboardStatus?(): Promise<KeyboardStatusResult>;
   /** Optional: platforms with no keyboard-dismiss concept leave it undefined. */
diff --git a/packages/contracts/src/navigation.ts b/packages/contracts/src/navigation.ts
index fca6600b99..8c2e998c51 100644
--- a/packages/contracts/src/navigation.ts
+++ b/packages/contracts/src/navigation.ts
@@ -1,5 +1,5 @@
 import type { BackMode } from './back-mode.ts';
-import type { DeviceRotation, FoldPose } from './device-rotation.ts';
+import type { DeviceRotation, FoldPose, HardwareButtonName } from './device-rotation.ts';
 import type { FoldScreenReport } from './fold-runtime.ts';
 import type { SettleObservation } from './interaction.ts';
 import type { TvRemoteButton } from './tv-remote.ts';
@@ -89,3 +89,16 @@ export type TvRemoteCommandResult = {
   durationMs?: number;
   message: string;
 };
+
+/**
+ * `hardware-button` — `{ action: 'hardware-button', button, message: 'Pressed hardware button <button>' }`.
+ *
+ * The button is the public name (`volume-up`, `volume-down`, `power`). The result reports that the
+ * press was dispatched; it carries no volume level or screen state, because the command observes
+ * neither (#3848).
+ */
+export type HardwareButtonCommandResult = {
+  action: 'hardware-button';
+  button: HardwareButtonName;
+  message: string;
+};
diff --git a/packages/contracts/src/platform-runtime-operations.ts b/packages/contracts/src/platform-runtime-operations.ts
index 749abd734e..b5c6f0b06a 100644
--- a/packages/contracts/src/platform-runtime-operations.ts
+++ b/packages/contracts/src/platform-runtime-operations.ts
@@ -127,6 +127,16 @@ export const keyboardDismissUse = defineUse({ required: ['keyboardDismiss'] });
 export const keyboardEnterUse = defineUse({ required: ['keyboardEnter'] });
 export const appSwitcherRuntimeUse = defineUse({ required: ['appSwitcher'] });
 export const actionButtonRuntimeUse = defineUse({ required: ['actionButton'] });
+// `hardware-button`'s cells (ADR 0019 §9): the daemon admits and binds exactly the one the parsed
+// positional names, never all three (#3848).
+export const volumeUpRuntimeUse = defineUse({ required: ['volumeUp'] });
+export const volumeDownRuntimeUse = defineUse({ required: ['volumeDown'] });
+export const powerRuntimeUse = defineUse({ required: ['power'] });
+export const hardwareButtonRuntimePlanUses = Object.freeze([
+  volumeUpRuntimeUse,
+  volumeDownRuntimeUse,
+  powerRuntimeUse,
+] as const);
 export const appEventRuntimeUse = defineUse({ required: ['triggerAppEvent'] });
 export const settingsRuntimeUse = defineUse({ required: ['setSetting'] });
 export const settingReadUse = defineUse({ required: ['readSetting'] });
diff --git a/packages/contracts/src/runtime-operation-names.ts b/packages/contracts/src/runtime-operation-names.ts
index 0dd86633d3..56c04b52c8 100644
--- a/packages/contracts/src/runtime-operation-names.ts
+++ b/packages/contracts/src/runtime-operation-names.ts
@@ -63,6 +63,7 @@ export const RUNTIME_OPERATION_NAMES = [
   'performGesturePlan',
   'performMultiTouchGesturePlan',
   'performTargetAuthoredDrag',
+  'power',
   'prepareAppleRunner',
   'prepareApplicationOpen',
   'querySelector',
@@ -90,6 +91,8 @@ export const RUNTIME_OPERATION_NAMES = [
   'typeText',
   'uninstallApp',
   'unlockOrientation',
+  'volumeDown',
+  'volumeUp',
   'writeClipboard',
 ] as const;
 
diff --git a/packages/contracts/src/system-button-runtime.test.ts b/packages/contracts/src/system-button-runtime.test.ts
index 13468254d1..21e1cdac55 100644
--- a/packages/contracts/src/system-button-runtime.test.ts
+++ b/packages/contracts/src/system-button-runtime.test.ts
@@ -1,8 +1,11 @@
 import { expect, test, vi } from 'vitest';
 import type { Interactor } from './interactor-types.ts';
 import { localInteractorSource } from './interactor-operation-binding.ts';
+import { HARDWARE_BUTTON_NAMES, parseHardwareButtonPositionals } from './device-rotation.ts';
 import {
   SYSTEM_BUTTONS,
+  SYSTEM_BUTTON_LABELS,
+  androidHardwareButtonAvailability,
   bindSystemButton,
   systemButtonRuntimeOperationFacts,
 } from './system-button-runtime.ts';
@@ -22,11 +25,17 @@ test('an omitted button reports the family denial, a named one its own cell', ()
     home: available,
     appSwitcher: unsupported,
     actionButton: unsupported,
+    volumeUp: unsupported,
+    volumeDown: unsupported,
+    power: unsupported,
   });
   expect(systemButtonRuntimeOperationFacts({ unsupported })).toEqual({
     home: unsupported,
     appSwitcher: unsupported,
     actionButton: unsupported,
+    volumeUp: unsupported,
+    volumeDown: unsupported,
+    power: unsupported,
   });
 });
 
@@ -71,3 +80,69 @@ test('an admitted button whose interactor lacks the member fails closed instead
     details: { reason: 'interactor-method-missing' },
   });
 });
+
+// The hardware-button vocabulary the `hardware-button` command routes through: each public name
+// maps to exactly one family cell whose family label is the name itself, and an unknown name
+// refuses before any device dispatch (#3848).
+test('the hardware-button vocabulary is exhaustive over the family cells and parses exactly', () => {
+  expect(
+    HARDWARE_BUTTON_NAMES.map(
+      (name) => SYSTEM_BUTTON_LABELS[parseHardwareButtonPositionals([name])],
+    ),
+  ).toEqual([...HARDWARE_BUTTON_NAMES]);
+  expect(
+    [...HARDWARE_BUTTON_NAMES].map((name) => parseHardwareButtonPositionals([name])).sort(),
+  ).toEqual(['power', 'volumeDown', 'volumeUp']);
+  expect(parseHardwareButtonPositionals(['volume-up'])).toBe('volumeUp');
+  expect(parseHardwareButtonPositionals(['Volume-Down'])).toBe('volumeDown');
+  expect(parseHardwareButtonPositionals(['power'])).toBe('power');
+  for (const name of ['', 'vol', 'mute', 'home', undefined] as const) {
+    expect(() => parseHardwareButtonPositionals([name as string])).toThrowError(
+      expect.objectContaining({
+        code: 'INVALID_ARGS',
+        message: 'hardware-button button must be one of: volume-up, volume-down, power.',
+      }),
+    );
+  }
+});
+
+// The whole positional contract one shared helper owns for both the CLI reader and the daemon
+// resolver: exactly one name, then the exact-name parse (#3848).
+test('the hardware-button positional helper enforces arity and the exact-name parse', () => {
+  expect(parseHardwareButtonPositionals(['volume-up'])).toBe('volumeUp');
+  for (const positionals of [[], ['volume-up', 'power'], ['power', 'extra']] as const) {
+    expect(() => parseHardwareButtonPositionals(positionals)).toThrowError(
+      expect.objectContaining({
+        code: 'INVALID_ARGS',
+        message: 'hardware-button requires exactly one button: volume-up, volume-down, power.',
+      }),
+    );
+  }
+  expect(() => parseHardwareButtonPositionals(['mute'])).toThrowError(
+    expect.objectContaining({ code: 'INVALID_ARGS' }),
+  );
+});
+
+// The Android hardware-button admission rule both Android owners share: a phone or tablet
+// answers available, a TV target refuses toward tv-remote, and the synthetic simulator row has
+// no device behind it (#3848).
+test('the shared Android hardware-button rule admits phones and refuses TV and simulator', () => {
+  expect(androidHardwareButtonAvailability({ kind: 'emulator' })).toEqual({ available: true });
+  expect(androidHardwareButtonAvailability({ kind: 'mobile', target: 'phone' })).toEqual({
+    available: true,
+  });
+  expect(androidHardwareButtonAvailability({ kind: 'mobile', target: 'tv' })).toEqual(
+    expect.objectContaining({
+      available: false,
+      reason: 'unsupported-device-kind',
+      hint: 'hardware-button is not supported on Android TV targets; use tv-remote.',
+    }),
+  );
+  expect(androidHardwareButtonAvailability({ kind: 'simulator' })).toEqual(
+    expect.objectContaining({
+      available: false,
+      reason: 'unsupported-device-kind',
+      hint: 'hardware-button is supported on Android emulators and physical devices.',
+    }),
+  );
+});
diff --git a/packages/contracts/src/system-button-runtime.ts b/packages/contracts/src/system-button-runtime.ts
index 9b17bd4dfd..4752300e08 100644
--- a/packages/contracts/src/system-button-runtime.ts
+++ b/packages/contracts/src/system-button-runtime.ts
@@ -1,3 +1,4 @@
+import type { HARDWARE_BUTTON_NAME_LABELS, HardwareButton } from './device-rotation.ts';
 import { requireInteractorMethod } from './interactor-operation-binding.ts';
 import type { Interactor, RunnerContext } from './interactor-types.ts';
 import type { RuntimeOperationFact, RuntimeOperationUnavailability } from './platform-runtime.ts';
@@ -5,11 +6,19 @@ import type { SnapshotRuntimeExecution } from './snapshot-runtime.ts';
 
 /**
  * The system buttons: one press each, no arguments, nothing returned. `home` and `appSwitcher`
- * reach a springboard or recents surface; `actionButton` presses iPhone/iPad hardware. What
- * varies between them is which owners carry the control, and that is the fact table's job, not
- * a per-button module's: a button joins this list and its owners state a cell.
+ * reach a springboard or recents surface; `actionButton` presses iPhone/iPad hardware;
+ * `volumeUp`, `volumeDown` and `power` press the phone hardware keys the `hardware-button`
+ * command names. What varies between them is which owners carry the control, and that is the
+ * fact table's job, not a per-button module's: a button joins this list and its owners state a cell.
  */
-export const SYSTEM_BUTTONS = ['home', 'appSwitcher', 'actionButton'] as const;
+export const SYSTEM_BUTTONS = [
+  'home',
+  'appSwitcher',
+  'actionButton',
+  'volumeUp',
+  'volumeDown',
+  'power',
+] as const;
 
 export type SystemButton = (typeof SYSTEM_BUTTONS)[number];
 
@@ -18,8 +27,35 @@ export const SYSTEM_BUTTON_LABELS = {
   home: 'home',
   appSwitcher: 'app-switcher',
   actionButton: 'action-button',
+  volumeUp: 'volume-up',
+  volumeDown: 'volume-down',
+  power: 'power',
 } as const satisfies Record<SystemButton, string>;
 
+// The hardware-button command vocabulary in device-rotation.ts must stay a family sub-cell with
+// these labels. device-rotation.ts cannot import this module — the type-only edge would close a
+// contracts type cycle through the snapshot and interactor graphs (layering R9/R10) — so the pin
+// runs here, on the label owner's side: a hardware button that is not a family cell, or a label
+// rename that drifts from the command's positional names, fails to build. The contracts tests
+// pin the lists are exhaustive in both directions at runtime.
+// (A value-import of these literals from device-rotation.ts instead was measured and rejected:
+// it made system-button-runtime.ts value-eager and joined 5 entry closures in
+// scripts/__tests__/eager-closure-budgets.ts with no shared home to absorb it.)
+type HardwareButtonsAreFamilyCells = HardwareButton extends SystemButton
+  ? true
+  : { drift: HardwareButton };
+const hardwareButtonsAreFamilyCells: HardwareButtonsAreFamilyCells = true;
+void hardwareButtonsAreFamilyCells;
+
+type HardwareButtonLabelsMatchCommandNames = [
+  typeof HARDWARE_BUTTON_NAME_LABELS,
+  Pick<typeof SYSTEM_BUTTON_LABELS, HardwareButton>,
+] extends [Pick<typeof SYSTEM_BUTTON_LABELS, HardwareButton>, typeof HARDWARE_BUTTON_NAME_LABELS]
+  ? true
+  : { drift: Pick<typeof SYSTEM_BUTTON_LABELS, HardwareButton> };
+const hardwareButtonLabelsMatchCommandNames: HardwareButtonLabelsMatchCommandNames = true;
+void hardwareButtonLabelsMatchCommandNames;
+
 /** Neutral intent for one press: no arguments, so only runner metadata travels. */
 export type SystemButtonInput = Readonly<{
   options?: Readonly<{ appBundleId?: string }>;
@@ -61,6 +97,40 @@ export function systemButtonRuntimeOperationFacts(
   return Object.freeze(facts);
 }
 
+/**
+ * The Android `hardware-button` admission rule, shared by every owner that presses the phone
+ * keys through `input keyevent` (the local adb runtime and the Limrun provider alike). A TV
+ * target has no phone volume/power semantics and its own command family, so it refuses and
+ * points at `tv-remote`; the synthetic `simulator` row has no device behind it.
+ */
+export interface AndroidHardwareButtonSubject {
+  readonly kind: string;
+  readonly target?: string;
+}
+
+// Frozen literals rather than unavailableFact(): that helper lives in platform-runtime.ts and a
+// value import would add it to this module's eager closure, which the eager-closure budgets gate
+// refuses for a contract with four eager modules at the merge-base.
+const androidHardwareButtonTvUnavailable: RuntimeOperationUnavailability = Object.freeze({
+  available: false,
+  reason: 'unsupported-device-kind',
+  hint: 'hardware-button is not supported on Android TV targets; use tv-remote.',
+});
+const androidHardwareButtonKindUnavailable: RuntimeOperationUnavailability = Object.freeze({
+  available: false,
+  reason: 'unsupported-device-kind',
+  hint: 'hardware-button is supported on Android emulators and physical devices.',
+});
+
+const ANDROID_AVAILABLE = Object.freeze({ available: true } as const);
+
+export function androidHardwareButtonAvailability(
+  device: AndroidHardwareButtonSubject,
+): RuntimeOperationFact {
+  if (device.kind === 'simulator') return androidHardwareButtonKindUnavailable;
+  return device.target === 'tv' ? androidHardwareButtonTvUnavailable : ANDROID_AVAILABLE;
+}
+
 /**
  * Captures one selected owner's interactor authority for the lifetime of a request binding and
  * presses one button through it. `Interactor` members for hardware only some owners carry are
diff --git a/packages/daemon/src/__tests__/support/runtime-binding-conformance.ts b/packages/daemon/src/__tests__/support/runtime-binding-conformance.ts
index 3bbdd5f1a3..57c4b2fd99 100644
--- a/packages/daemon/src/__tests__/support/runtime-binding-conformance.ts
+++ b/packages/daemon/src/__tests__/support/runtime-binding-conformance.ts
@@ -157,6 +157,41 @@ export const conformedRuntimeBindings = {
         }),
       ),
   },
+  // Each `hardware-button` name is its own admission cell on the one `hardware-button`
+  // descriptor (#3848), so each owes its own refusal row, the way `orientation auto` does.
+  'hardware-button': {
+    plan: { refused: 'volumeUp', admitted: [] },
+    resolve: async (device, bindings) =>
+      refusable(
+        await resolveBoundSystemButtonRuntime('hardware-button', {
+          device,
+          positionals: ['volume-up'],
+          ...bindings,
+        }),
+      ),
+  },
+  'hardware-button volume-down': {
+    plan: { refused: 'volumeDown', admitted: [], command: 'hardware-button' },
+    resolve: async (device, bindings) =>
+      refusable(
+        await resolveBoundSystemButtonRuntime('hardware-button', {
+          device,
+          positionals: ['volume-down'],
+          ...bindings,
+        }),
+      ),
+  },
+  'hardware-button power': {
+    plan: { refused: 'power', admitted: [], command: 'hardware-button' },
+    resolve: async (device, bindings) =>
+      refusable(
+        await resolveBoundSystemButtonRuntime('hardware-button', {
+          device,
+          positionals: ['power'],
+          ...bindings,
+        }),
+      ),
+  },
   'tv-remote': {
     resolve: async (device, bindings) =>
       refusable(await resolveBoundTvRemoteRuntime({ device, positionals: ['down'], ...bindings })),
diff --git a/packages/daemon/src/core/runtime-operation-effects.ts b/packages/daemon/src/core/runtime-operation-effects.ts
index 396be3cc6b..a11ded7f1d 100644
--- a/packages/daemon/src/core/runtime-operation-effects.ts
+++ b/packages/daemon/src/core/runtime-operation-effects.ts
@@ -70,6 +70,7 @@ export const RUNTIME_OPERATION_EFFECTS: Readonly<
   performGesturePlan: 'mutates',
   performMultiTouchGesturePlan: 'mutates',
   performTargetAuthoredDrag: 'mutates',
+  power: 'mutates',
   prepareAppleRunner: 'repeatable',
   prepareApplicationOpen: 'repeatable',
   querySelector: 'repeatable',
@@ -97,5 +98,7 @@ export const RUNTIME_OPERATION_EFFECTS: Readonly<
   typeText: 'mutates',
   uninstallApp: 'mutates',
   unlockOrientation: 'mutates',
+  volumeDown: 'mutates',
+  volumeUp: 'mutates',
   writeClipboard: 'mutates',
 });
diff --git a/packages/daemon/src/execution/__tests__/system-button-runtime.test.ts b/packages/daemon/src/execution/__tests__/system-button-runtime.test.ts
index 09aaeb8835..b6bd25e876 100644
--- a/packages/daemon/src/execution/__tests__/system-button-runtime.test.ts
+++ b/packages/daemon/src/execution/__tests__/system-button-runtime.test.ts
@@ -14,6 +14,7 @@ import {
   actionButtonRuntimeUse,
   appSwitcherRuntimeUse,
   homeRuntimeUse,
+  volumeUpRuntimeUse,
   type PlatformRuntimeOperations,
 } from '@agent-device/contracts/platform-runtime-operations';
 import type { SystemButton } from '@agent-device/contracts/system-button-runtime';
@@ -29,9 +30,12 @@ import type {
 } from '../../core/request-runtime-binding.ts';
 import type { GenericPlatformExecutionParams } from '../../core/generic-leaf-execution.ts';
 import {
+  isSystemButtonRouteCommand,
+  resolveBoundHardwareButtonRuntime,
   resolveBoundSystemButtonRuntime,
   type SystemButtonCommand,
 } from '../system-button-runtime.ts';
+import { commandDescriptors } from '@agent-device/command-registry/registry';
 import {
   expectRefusesUnavailableExactOwnerFact,
   systemButtonCommands,
@@ -87,6 +91,15 @@ const EXPECTED: Record<
 };
 
 test('the registry names exactly the commands the press route serves', () => {
+  // The denominator is the route's own predicate over the registry: the three argumentless
+  // presses plus the positional-selected `hardware-button`, so a press command joining (or
+  // leaving) the route without a row here or in the route set fails.
+  const routeCommands = commandDescriptors
+    .map((descriptor) => descriptor.name)
+    .filter(isSystemButtonRouteCommand);
+  expect([...routeCommands].sort()).toEqual([...Object.keys(EXPECTED), 'hardware-button'].sort());
+  // The conformance family stays the argumentless presses; hardware-button carries its own
+  // plan rows in the conformance table.
   expect([...systemButtonCommands].sort()).toEqual(Object.keys(EXPECTED).sort());
 });
 
@@ -205,3 +218,62 @@ test('request router joins home admission to execution, recording, and ref inval
   expect(harness.bind).toHaveBeenCalledTimes(1);
   expect(harness.press).toHaveBeenCalledTimes(1);
 });
+
+// The hardware-button route selects exactly the named cell from the positional: one inspect, one
+// bind of that cell's use, one press, and a response that echoes the public button name (#3848).
+test('hardware-button binds the named cell and reports the public button name', async () => {
+  const harness = runtimeHarness('volumeUp');
+
+  const resolved = await resolveBoundHardwareButtonRuntime({
+    platformServices: daemonPlatformServicesFixture(),
+    device: iosSimulator,
+    positionals: ['volume-up'],
+    inspectFacts: harness.inspectFacts,
+    bindDevice: harness.bindDevice,
+  });
+
+  expect(resolved.ok).toBe(true);
+  if (!resolved.ok) return;
+  expect(harness.inspectFacts).toHaveBeenCalledTimes(1);
+  expect(harness.bindDevice).toHaveBeenCalledWith(iosSimulator, volumeUpRuntimeUse);
+  const session = makeSession('system-button-runtime', { device: iosSimulator });
+  expect(
+    await resolved.execute({
+      session,
+      sessionName: session.name,
+      logPath: '/tmp/daemon.log',
+      command: 'hardware-button',
+      request: {
+        command: 'hardware-button',
+        positionals: ['volume-up'],
+        token: 't',
+        session: session.name,
+      },
+      positionals: ['volume-up'],
+      out: undefined,
+      dispatchContext: {},
+    }),
+  ).toEqual({
+    action: 'hardware-button',
+    button: 'volume-up',
+    message: 'Pressed hardware button volume-up',
+  });
+  expect(harness.press).toHaveBeenCalledTimes(1);
+});
+
+test('hardware-button refuses an unknown or missing button before inspecting any device', async () => {
+  const harness = runtimeHarness('volumeUp');
+  for (const positionals of [[], ['mute'], ['volume-up', 'extra']] as const) {
+    await expect(
+      resolveBoundHardwareButtonRuntime({
+        platformServices: daemonPlatformServicesFixture(),
+        device: iosSimulator,
+        positionals,
+        inspectFacts: harness.inspectFacts,
+        bindDevice: harness.bindDevice,
+      }),
+    ).rejects.toMatchObject({ code: 'INVALID_ARGS' });
+  }
+  expect(harness.inspectFacts).not.toHaveBeenCalled();
+  expect(harness.press).not.toHaveBeenCalled();
+});
diff --git a/packages/daemon/src/execution/generic-runtime-execution.ts b/packages/daemon/src/execution/generic-runtime-execution.ts
index 28ca400a6d..3af1dc5781 100644
--- a/packages/daemon/src/execution/generic-runtime-execution.ts
+++ b/packages/daemon/src/execution/generic-runtime-execution.ts
@@ -8,7 +8,10 @@ import type { DaemonRequest } from '../core/daemon-request.ts';
 import type { SessionState } from '../core/session-state.ts';
 import { resolveBoundViewportRuntime } from './viewport-runtime.ts';
 import { resolveBoundBackRuntime } from './back-runtime.ts';
-import { isSystemButtonCommand, resolveBoundSystemButtonRuntime } from './system-button-runtime.ts';
+import {
+  isSystemButtonRouteCommand,
+  resolveBoundSystemButtonRuntime,
+} from './system-button-runtime.ts';
 import { resolveBoundOrientationRuntime } from './orientation-runtime.ts';
 import { resolveBoundFoldRuntime } from './fold-runtime.ts';
 import { resolveBoundTvRemoteRuntime } from './tv-remote-runtime.ts';
@@ -36,9 +39,11 @@ export async function resolveGenericRuntimeExecution(
   }> &
     ScreenshotRuntimeBindings,
 ): Promise<ResolvedGenericExecution> {
-  if (isSystemButtonCommand(params.req.command)) {
+  if (isSystemButtonRouteCommand(params.req.command)) {
     return await resolveBoundSystemButtonRuntime(params.req.command, {
       device: params.session.device,
+      // Only `hardware-button` reads these; the resolver owns the arity refusal for a miss.
+      positionals: params.req.positionals,
       inspectFacts: params.inspectFacts,
       platformServices: params.platformServices,
       bindDevice: params.bindDevice,
diff --git a/packages/daemon/src/execution/system-button-runtime.ts b/packages/daemon/src/execution/system-button-runtime.ts
index c5be8300c0..b045b3ee58 100644
--- a/packages/daemon/src/execution/system-button-runtime.ts
+++ b/packages/daemon/src/execution/system-button-runtime.ts
@@ -2,9 +2,20 @@ import {
   actionButtonRuntimeUse,
   appSwitcherRuntimeUse,
   homeRuntimeUse,
+  powerRuntimeUse,
+  volumeDownRuntimeUse,
+  volumeUpRuntimeUse,
   type PlatformRuntimeOperations,
 } from '@agent-device/contracts/platform-runtime-operations';
 import type { BoundDeviceRuntime, RuntimeUse } from '@agent-device/contracts/platform-runtime';
+// The hardware-button vocabulary reads arrive through the contracts/device façade, whose
+// device-rotation.ts section is the eager home for command positional vocabulary (#3848,
+// eager-closure budgets); only the press-route types come from system-button-runtime.ts.
+import {
+  HARDWARE_BUTTON_NAME_LABELS,
+  parseHardwareButtonPositionals,
+  type HardwareButton,
+} from '@agent-device/contracts/device';
 import type {
   SystemButton,
   SystemButtonInput,
@@ -47,10 +58,37 @@ const SYSTEM_BUTTON_COMMANDS = {
 
 export type SystemButtonCommand = keyof typeof SYSTEM_BUTTON_COMMANDS;
 
+/**
+ * Every generic-route command the shared press route below serves: the three argumentless presses
+ * plus the positional-selected `hardware-button`, whose first positional names the cell (#3848).
+ * The dispatcher's one guard covers the whole family, so a fourth button row grows this module's
+ * table only — never the dispatcher's switch.
+ */
+export type SystemButtonRouteCommand = SystemButtonCommand | 'hardware-button';
+
 export function isSystemButtonCommand(command: string): command is SystemButtonCommand {
   return Object.hasOwn(SYSTEM_BUTTON_COMMANDS, command);
 }
 
+export function isSystemButtonRouteCommand(command: string): command is SystemButtonRouteCommand {
+  return command === 'hardware-button' || isSystemButtonCommand(command);
+}
+
+/**
+ * The `hardware-button` command's positional-selected rows (ADR 0019 §9): the button names the
+ * one family cell it presses, the way `keyboard <status|dismiss|enter>` names a keyboard cell.
+ * One press, no settle and no observation payload — the same trait set `action-button` carries,
+ * because the press goes to the system, not to the session app (#3848).
+ */
+const HARDWARE_BUTTON_COMMAND_ROWS = {
+  // The row labels are derived from HARDWARE_BUTTON_NAME_LABELS, the same literals
+  // SYSTEM_BUTTON_LABELS answers for; device-rotation.ts is already in this entry's eager
+  // closure through the facade import above, so deriving them costs nothing (#3848).
+  volumeUp: { use: volumeUpRuntimeUse, label: HARDWARE_BUTTON_NAME_LABELS.volumeUp },
+  volumeDown: { use: volumeDownRuntimeUse, label: HARDWARE_BUTTON_NAME_LABELS.volumeDown },
+  power: { use: powerRuntimeUse, label: HARDWARE_BUTTON_NAME_LABELS.power },
+} as const satisfies Record<HardwareButton, Readonly<{ use: SystemButtonUse; label: string }>>;
+
 /** The neutral intent one press carries, projected from a resolved command context. */
 function systemButtonInput(context: DaemonCommandContext): SystemButtonInput {
   return {
@@ -60,14 +98,30 @@ function systemButtonInput(context: DaemonCommandContext): SystemButtonInput {
 }
 
 /**
- * The one place a system-button command reaches a device. Admission inspects the exact owner's
- * cell for the button and binds once, before the dispatcher runs, so an owner without the control
- * is refused rather than discovered mid-execution.
+ * The one place a system-button family command reaches a device. Admission inspects the exact
+ * owner's cell for the button and binds once, before the dispatcher runs, so an owner without the
+ * control is refused rather than discovered mid-execution. The `hardware-button` row delegates to
+ * the positional-selected resolver below, which owns the button's arity and parse (#3848).
  */
 export async function resolveBoundSystemButtonRuntime(
-  command: SystemButtonCommand,
-  params: { device: DeviceInfo } & RuntimeAdmissionBindings,
+  command: SystemButtonRouteCommand,
+  params: {
+    device: DeviceInfo;
+    /** Only `hardware-button` reads positionals; the argumentless presses ignore them. */
+    positionals?: readonly string[];
+  } & RuntimeAdmissionBindings,
 ): Promise<ResolvedGenericExecution> {
+  if (command === 'hardware-button') {
+    return await resolveBoundHardwareButtonRuntime({
+      device: params.device,
+      // The hardware resolver owns the positional default and the arity refusal; the delegate
+      // forwards the request's optional positionals untouched.
+      positionals: params.positionals,
+      inspectFacts: params.inspectFacts,
+      platformServices: params.platformServices,
+      bindDevice: params.bindDevice,
+    });
+  }
   const row: SystemButtonCommandRow = SYSTEM_BUTTON_COMMANDS[command];
   return await resolveBoundGenericRuntime(
     {
@@ -85,3 +139,44 @@ export async function resolveBoundSystemButtonRuntime(
     },
   );
 }
+
+/**
+ * The one place `hardware-button` reaches a device (ADR 0019 §9). The positional picks the family
+ * cell — one bind per request, never all three — and admission inspects the exact owner's cell for
+ * that button before the dispatcher runs, so an owner without the key is refused rather than
+ * discovered mid-execution. The result reports the dispatched press and nothing observed after it.
+ */
+export async function resolveBoundHardwareButtonRuntime(
+  params: {
+    device: DeviceInfo;
+    /** Absent means no positional; the arity refusal below is what answers for it. */
+    positionals?: readonly string[];
+  } & RuntimeAdmissionBindings,
+): Promise<ResolvedGenericExecution> {
+  // Shared with the CLI reader: exactly one name, then the exact-name parse; an unknown name
+  // refuses with INVALID_ARGS before any device dispatch.
+  const button = parseHardwareButtonPositionals(params.positionals ?? []);
+  const row = HARDWARE_BUTTON_COMMAND_ROWS[button];
+  // Widen to the family use so one call site serves all three rows.
+  const use: SystemButtonUse = row.use;
+  return await resolveBoundGenericRuntime(
+    {
+      command: 'hardware-button',
+      device: params.device,
+      use,
+      inspectFacts: params.inspectFacts,
+      platformServices: params.platformServices,
+      bindDevice: params.bindDevice,
+    },
+    async (runtime: BoundDeviceRuntime<SystemButtonUse>, context) => {
+      const [operation] = row.use.required;
+      await runtime.operations[operation](systemButtonInput(context));
+      const name = row.label;
+      return {
+        action: 'hardware-button',
+        button: name,
+        ...successText(`Pressed hardware button ${name}`),
+      };
+    },
+  );
+}
diff --git a/packages/platform-android/src/__tests__/input-actions.test.ts b/packages/platform-android/src/__tests__/input-actions.test.ts
index 95c0fc2e6e..6ba42019a0 100644
--- a/packages/platform-android/src/__tests__/input-actions.test.ts
+++ b/packages/platform-android/src/__tests__/input-actions.test.ts
@@ -6,6 +6,7 @@ import {
   longPressAndroid,
   pressAndroid,
   pressAndroidEnter,
+  pressAndroidHardwareButton,
   pressAndroidTvRemote,
   probeAndroidDisplayRotation,
   scrollAndroid,
@@ -425,6 +426,22 @@ test('homeAndroid presses keyevent 3', async () => {
   );
 });
 
+test('pressAndroidHardwareButton presses the volume and power keyevents', async () => {
+  await withFakeAdb(
+    () => undefined,
+    async ({ calls, device }) => {
+      await pressAndroidHardwareButton(device, 'volumeUp');
+      await pressAndroidHardwareButton(device, 'volumeDown');
+      await pressAndroidHardwareButton(device, 'power');
+      assert.deepEqual(calls, [
+        ['shell', 'input', 'keyevent', '24'],
+        ['shell', 'input', 'keyevent', '25'],
+        ['shell', 'input', 'keyevent', '26'],
+      ]);
+    },
+  );
+});
+
 test('pressAndroidEnter presses the ENTER keyevent', async () => {
   await withFakeAdb(
     () => undefined,
diff --git a/packages/platform-android/src/input-actions.ts b/packages/platform-android/src/input-actions.ts
index 710b4dd447..fc15c8727c 100644
--- a/packages/platform-android/src/input-actions.ts
+++ b/packages/platform-android/src/input-actions.ts
@@ -258,6 +258,31 @@ export async function appSwitcherAndroid(device: DeviceInfo): Promise<void> {
   await runAndroidShell(device, ['input', 'keyevent', '187']);
 }
 
+/**
+ * The `input keyevent` codes for the phone hardware keys the `hardware-button` command names:
+ * KEYCODE_VOLUME_UP/DOWN/POWER. The helper's `kind:'key'` path takes any code, so both Android
+ * legs press all three the way `homeAndroid` presses 3.
+ */
+const ANDROID_HARDWARE_BUTTON_KEYCODES = {
+  volumeUp: 24,
+  volumeDown: 25,
+  power: 26,
+} as const;
+
+/** Presses one phone hardware key once. TV targets are gated by the runtime facts, not here. */
+export async function pressAndroidHardwareButton(
+  device: DeviceInfo,
+  button: keyof typeof ANDROID_HARDWARE_BUTTON_KEYCODES,
+): Promise<void> {
+  const keyCode = ANDROID_HARDWARE_BUTTON_KEYCODES[button];
+  const { runAndroidAutomationHelper } = await import('./automation-helper.ts');
+  if (
+    await runAndroidAutomationHelper(device, { action: 'input', input: { kind: 'key', keyCode } })
+  )
+    return;
+  await runAndroidShell(device, ['input', 'keyevent', String(keyCode)]);
+}
+
 export async function longPressAndroid(
   device: DeviceInfo,
   x: number,
diff --git a/packages/platform-android/src/mechanics.ts b/packages/platform-android/src/mechanics.ts
index d03872ab5f..6f5fed8096 100644
--- a/packages/platform-android/src/mechanics.ts
+++ b/packages/platform-android/src/mechanics.ts
@@ -183,6 +183,7 @@ export {
   longPressAndroid,
   pressAndroid,
   pressAndroidEnter,
+  pressAndroidHardwareButton,
   pressAndroidTvRemote,
   scrollAndroid,
   setAndroidOrientation,
diff --git a/packages/platform-android/src/runtime.test.ts b/packages/platform-android/src/runtime.test.ts
index d08f6344a4..95b34722c9 100644
--- a/packages/platform-android/src/runtime.test.ts
+++ b/packages/platform-android/src/runtime.test.ts
@@ -189,6 +189,51 @@ test.each([
   },
 );
 
+test('Android admits the hardware-button facts on phones and tablets and refuses a TV target', async () => {
+  for (const runtimeDevice of [
+    ANDROID_EMULATOR,
+    { ...ANDROID_EMULATOR, kind: 'device' as const },
+    UNKNOWN_KIND_DEVICE,
+  ]) {
+    const binding = await bindOrdinary(
+      createAndroidPlatformRuntime(androidNavigationHost()),
+      runtimeDevice,
+    );
+    // One `input keyevent` each on the same adb path `home` rides, on every kind with a device.
+    for (const operation of ['volumeUp', 'volumeDown', 'power'] as const) {
+      expect(binding.facts.operations[operation]).toEqual({ available: true });
+      expect(binding.operations[operation]).toBeTypeOf('function');
+    }
+  }
+
+  // A TV target has no phone volume/power semantics; the refusal points at `tv-remote`.
+  const tvDevice = { ...ANDROID_EMULATOR, kind: 'emulator' as const, target: 'tv' as const };
+  const tv = await bindOrdinary(createAndroidPlatformRuntime(androidNavigationHost()), tvDevice);
+  for (const operation of ['volumeUp', 'volumeDown', 'power'] as const) {
+    expect(tv.facts.operations[operation]).toEqual({
+      available: false,
+      reason: 'unsupported-device-kind',
+      hint: 'hardware-button is not supported on Android TV targets; use tv-remote.',
+    });
+    expect(tv.operations[operation]).toBeUndefined();
+  }
+
+  // The synthetic `simulator` row has no device behind it, and its refusal names the hardware
+  // keys rather than borrowing another command's sentence.
+  const synthetic = await bindOrdinary(createAndroidPlatformRuntime(androidNavigationHost()), {
+    ...ANDROID_EMULATOR,
+    kind: 'simulator' as const,
+  });
+  for (const operation of ['volumeUp', 'volumeDown', 'power'] as const) {
+    expect(synthetic.facts.operations[operation]).toEqual({
+      available: false,
+      reason: 'unsupported-device-kind',
+      hint: 'hardware-button is supported on Android emulators and physical devices.',
+    });
+    expect(synthetic.operations[operation]).toBeUndefined();
+  }
+});
+
 test('admits Android tv-remote only for a real TV target', async () => {
   const tvDevice = { ...ANDROID_EMULATOR, kind: 'emulator' as const, target: 'tv' as const };
   const binding = await bindOrdinary(
@@ -338,6 +383,9 @@ test('the synthetic Android simulator cell refuses back/home/orientation/keyboar
     'readClipboard',
     'writeClipboard',
     'appSwitcher',
+    'volumeUp',
+    'volumeDown',
+    'power',
     'triggerAppEvent',
     'setSetting',
     'readAlert',
diff --git a/packages/platform-android/src/runtime.ts b/packages/platform-android/src/runtime.ts
index 799ebf0225..bebe742bc4 100644
--- a/packages/platform-android/src/runtime.ts
+++ b/packages/platform-android/src/runtime.ts
@@ -42,7 +42,10 @@ import { backRuntimeOperationFacts } from '@agent-device/contracts/back-runtime'
 import { alertRuntimeOperationFacts } from '@agent-device/contracts/alert-runtime';
 import { appEventRuntimeOperationFacts } from '@agent-device/contracts/app-event-runtime';
 import { settingsRuntimeOperationFacts } from '@agent-device/contracts/settings-runtime';
-import { systemButtonRuntimeOperationFacts } from '@agent-device/contracts/system-button-runtime';
+import {
+  androidHardwareButtonAvailability,
+  systemButtonRuntimeOperationFacts,
+} from '@agent-device/contracts/system-button-runtime';
 import { clipboardRuntimeOperationFacts } from '@agent-device/contracts/clipboard-runtime';
 import { bindLocalInteractorOperationSet } from '@agent-device/contracts/local-interactor-operation-set';
 import { keyboardRuntimeOperationFacts } from '@agent-device/contracts/keyboard-runtime';
@@ -90,9 +93,10 @@ const keyboardKindUnavailable = unavailableFact(
 );
 const hoverUnavailable = unavailableFact('unsupported-platform-leaf');
 /**
- * `home` and `app-switcher` are the system buttons `input keyevent` can press. Any other (the
- * iPhone Action Button today) is hardware with no Android key event behind it, so there is no adb
- * path to admit even on the kinds every other Android cell admits.
+ * `home`, `app-switcher`, and the three `hardware-button` keys are the system buttons
+ * `input keyevent` can press. Any other (the iPhone Action Button today) is hardware with no
+ * Android key event behind it, so there is no adb path to admit even on the kinds every other
+ * Android cell admits.
  */
 const systemButtonUnavailable = unavailableFact(
   'unsupported-platform-leaf',
@@ -342,11 +346,16 @@ export function createAndroidPlatformRuntime(host: PlatformRuntimeHost): Platfor
         }),
         ...backRuntimeOperationFacts({ back: androidTouchFact(device) }),
         // `home` and `app-switcher` are one `input keyevent` each, admitted wherever the retired
-        // `ANDROID_ALL` bucket admitted them.
+        // `ANDROID_ALL` bucket admitted them. The hardware-button keys use the same keyevent path
+        // but the shared Android rule gates the target: a TV device refuses and points at
+        // `tv-remote`.
         ...systemButtonRuntimeOperationFacts({
           unsupported: systemButtonUnavailable,
           home: androidTouchFact(device),
           appSwitcher: androidTouchFact(device),
+          volumeUp: androidHardwareButtonAvailability(device),
+          volumeDown: androidHardwareButtonAvailability(device),
+          power: androidHardwareButtonAvailability(device),
         }),
         ...androidFoldableFacts(device),
         ...androidTelephonyFacts(device),
diff --git a/packages/platform-apple/src/__tests__/index-runner-requests.test.ts b/packages/platform-apple/src/__tests__/index-runner-requests.test.ts
index 0df1030327..133bf3aa1c 100644
--- a/packages/platform-apple/src/__tests__/index-runner-requests.test.ts
+++ b/packages/platform-apple/src/__tests__/index-runner-requests.test.ts
@@ -158,6 +158,8 @@ const INTERACTOR_SITES: Record<string, InteractorDrive> = {
   'ios-simulator.interactor-app-state.read': [IOS_SIMULATOR, (i) => i.appState!()],
   'ios-simulator.interactor-app-switcher.open': [IOS_SIMULATOR, (i) => i.appSwitcher!()],
   'ios-simulator.interactor-action-button.press': [IOS_SIMULATOR, (i) => i.actionButton!()],
+  'ios-simulator.interactor-volume-up.press': [IOS_SIMULATOR, (i) => i.volumeUp!()],
+  'ios-simulator.interactor-volume-down.press': [IOS_SIMULATOR, (i) => i.volumeDown!()],
   'tvos.interactor-tv-remote.hold': [TVOS_SIMULATOR, (i) => i.tvRemote!('select', 500)],
   'ios-simulator.interactor-keyboard-dismiss.dismiss': [IOS_SIMULATOR, (i) => i.keyboardDismiss!()],
   'ios-simulator.interactor-keyboard-enter.return': [IOS_SIMULATOR, (i) => i.keyboardEnter!()],
diff --git a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
index 6ac5c5bde8..d21b66480e 100644
--- a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
+++ b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
@@ -78,6 +78,8 @@ const RUNNER_TRANSPORT_METHODS: Record<
   setOrientation: { invoke: (i) => i.setOrientation('portrait'), runnerCommand: 'rotate' },
   appSwitcher: { invoke: (i) => i.appSwitcher!(), runnerCommand: 'appSwitcher' },
   actionButton: { invoke: (i) => i.actionButton!(), runnerCommand: 'actionButton' },
+  volumeUp: { invoke: (i) => i.volumeUp!(), runnerCommand: 'volumeUp' },
+  volumeDown: { invoke: (i) => i.volumeDown!(), runnerCommand: 'volumeDown' },
   tvRemote: { invoke: (i) => i.tvRemote!('select'), runnerCommand: 'remotePress' },
   keyboardDismiss: { invoke: (i) => i.keyboardDismiss!(), runnerCommand: 'keyboardDismiss' },
   keyboardEnter: { invoke: (i) => i.keyboardEnter!(), runnerCommand: 'keyboardReturn' },
diff --git a/packages/platform-apple/src/interactor.ts b/packages/platform-apple/src/interactor.ts
index 20b030fb27..07f01ca7a2 100644
--- a/packages/platform-apple/src/interactor.ts
+++ b/packages/platform-apple/src/interactor.ts
@@ -184,6 +184,22 @@ export function createAppleInteractor(
         runnerOpts,
       );
     },
+    // Volume presses reach the runner only on physical iPhone/iPad; the facts refuse every other
+    // kind, and Apple exposes no power press at all, so no `power` member exists here.
+    volumeUp: async () => {
+      await runAppleRunnerCommand(
+        device,
+        { command: 'volumeUp', appBundleId: runnerContext.appBundleId },
+        runnerOpts,
+      );
+    },
+    volumeDown: async () => {
+      await runAppleRunnerCommand(
+        device,
+        { command: 'volumeDown', appBundleId: runnerContext.appBundleId },
+        runnerOpts,
+      );
+    },
     tvRemote: async (button, durationMs) => {
       await runAppleRunnerCommand(
         device,
diff --git a/packages/platform-apple/src/navigation/runtime.ts b/packages/platform-apple/src/navigation/runtime.ts
index 787b45835d..8cd1b9937d 100644
--- a/packages/platform-apple/src/navigation/runtime.ts
+++ b/packages/platform-apple/src/navigation/runtime.ts
@@ -160,6 +160,28 @@ function appleActionButtonFact(device: DeviceInfo): RuntimeOperationFact {
   return hasAppleActionButton(device) ? available : actionButtonOsUnavailable;
 }
 
+const volumeButtonOsUnavailable = Object.freeze({
+  available: false,
+  reason: 'unsupported-platform-leaf',
+  hint: 'hardware-button volume presses the iPhone/iPad volume key; this Apple leaf has none.',
+} as const);
+const volumeButtonSimulatorUnavailable = Object.freeze({
+  available: false,
+  reason: 'unsupported-device-kind',
+  hint: 'hardware-button volume is supported on physical iPhone and iPad; iOS Simulators refuse because XCUIDevice exposes no volume press there.',
+} as const);
+/**
+ * `XCUIDevice.press(.volumeUp/.volumeDown)` is simulator-unavailable in the XCUITest header, so
+ * the local runner presses volume on a physical iPhone or iPad only. The iPhone/iPad leaf read is
+ * {@link hasAppleActionButton}; tvOS, macOS, watchOS and visionOS have no volume key to press and
+ * hear that refusal, not the simulator one (#3848 review).
+ */
+function appleVolumeButtonFact(device: DeviceInfo): RuntimeOperationFact {
+  if (!hasAppleActionButton(device)) return volumeButtonOsUnavailable;
+  if (device.kind !== 'device') return volumeButtonSimulatorUnavailable;
+  return available;
+}
+
 /**
  * The navigation cells: back, home, app-switcher, action-button, orientation, tv-remote, and
  * keyboard status/dismiss/enter.
@@ -172,6 +194,10 @@ export function appleNavigationFacts(device: DeviceInfo) {
       home: appleSpringboardFact(device, homeKindUnavailable),
       appSwitcher: appleSpringboardFact(device, appSwitcherKindUnavailable),
       actionButton: appleActionButtonFact(device),
+      // Power is the family denial: Apple exposes no public power/lock button press to XCUITest,
+      // on any kind or OS, so no cell overrides it.
+      volumeUp: appleVolumeButtonFact(device),
+      volumeDown: appleVolumeButtonFact(device),
     }),
     ...orientationRuntimeOperationFacts({ orientation: appleOrientationFact(device) }),
     ...tvRemoteRuntimeOperationFacts({
diff --git a/packages/platform-apple/src/runner-demand.ts b/packages/platform-apple/src/runner-demand.ts
index 013bc9071c..20ec4f35e6 100644
--- a/packages/platform-apple/src/runner-demand.ts
+++ b/packages/platform-apple/src/runner-demand.ts
@@ -53,9 +53,14 @@ const APPLE_SIMULATOR_OPERATION_HOSTS: Readonly<
   setSetting: 'simulator',
   readSetting: 'simulator',
   setFoldPose: 'simulator',
-  // Refused on every Apple leaf at admission, so nothing waits on the runner.
+  // Refused on every Apple leaf at admission, so nothing waits on the runner. The volume keys are
+  // refused on the simulator leaf too (XCUIDevice exposes no volume press there), and power is
+  // refused on every kind and OS.
   sendTelephonyEvent: 'simulator',
   unlockOrientation: 'simulator',
+  power: 'simulator',
+  volumeDown: 'simulator',
+  volumeUp: 'simulator',
   // Observation: the AX bridge presents regular and raw trees; custom actions need XCTest.
   captureSnapshot: 'simulator',
   captureSnapshotWithoutActiveApp: 'simulator',
diff --git a/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts b/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts
index 60974e424b..21951b5f0b 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts
@@ -60,6 +60,8 @@ test('runner command trait table pins lifecycle-sensitive command groups', () =>
       'rotate',
       'shutdown',
       'type',
+      'volumeDown',
+      'volumeUp',
     ],
   });
   assert.deepEqual(Object.values(groups).flat().sort(), [...RUNNER_COMMANDS].sort());
diff --git a/packages/platform-apple/src/runner/runner-command-traits.ts b/packages/platform-apple/src/runner/runner-command-traits.ts
index 17d5582cb7..b419962847 100644
--- a/packages/platform-apple/src/runner/runner-command-traits.ts
+++ b/packages/platform-apple/src/runner/runner-command-traits.ts
@@ -74,6 +74,8 @@ export const RUNNER_COMMAND_TRAITS = {
   gestureViewport: READ_ONLY_TRAITS,
   appSwitcher: DEFAULT_TRAITS,
   actionButton: DEFAULT_TRAITS,
+  volumeUp: DEFAULT_TRAITS,
+  volumeDown: DEFAULT_TRAITS,
   keyboardDismiss: DEFAULT_TRAITS,
   keyboardReturn: DEFAULT_TRAITS,
   alert: readAlertActionTraits,
diff --git a/packages/platform-apple/src/runner/runner-contract.ts b/packages/platform-apple/src/runner/runner-contract.ts
index 98769aed7c..a775fe78ae 100644
--- a/packages/platform-apple/src/runner/runner-contract.ts
+++ b/packages/platform-apple/src/runner/runner-contract.ts
@@ -82,6 +82,8 @@ export type RunnerCommand = {
     | 'gestureViewport'
     | 'appSwitcher'
     | 'actionButton'
+    | 'volumeUp'
+    | 'volumeDown'
     | 'keyboardDismiss'
     | 'keyboardReturn'
     | 'alert'
diff --git a/packages/platform-apple/src/runtime.test.ts b/packages/platform-apple/src/runtime.test.ts
index 6bd4071edf..9afee6c09d 100644
--- a/packages/platform-apple/src/runtime.test.ts
+++ b/packages/platform-apple/src/runtime.test.ts
@@ -350,6 +350,57 @@ test.each(Object.entries(leaves))(
   },
 );
 
+// The volume keys are the hardware-button cells Apple can press: `XCUIDevice.press(.volumeUp/
+// .volumeDown)` is simulator-unavailable in the XCUITest header, so only a physical iPhone or
+// iPad admits them. Each refusal names its own axis: the iOS-family simulator hears the kind
+// refusal, tvOS/macOS/watchOS/visionOS hear the leaf refusal for having no volume key at all.
+// Power is the family denial on every leaf: XCUITest exposes no power press.
+test.each([
+  ...Object.entries(leaves).map(([name, device]) => [name, device, false] as const),
+  ['ios physical device', appleDevice({ kind: 'device' }), true] as const,
+  ['ipados physical device', appleDevice({ kind: 'device', appleOs: 'ipados' }), true] as const,
+  [
+    'tvos physical device',
+    appleDevice({ kind: 'device', appleOs: 'tvos', target: 'tv' }),
+    false,
+  ] as const,
+])(
+  'classifies the hardware-button volume facts for the %s leaf',
+  async (_name, device, available) => {
+    const binding = await createApplePlatformRuntime(platformRuntimeHostFixture()).bind({
+      device,
+      intent: { kind: 'ordinary' },
+      scope: {
+        signal: new AbortController().signal,
+        diagnostics: { emit: () => {} },
+        progress: { report: () => {} },
+      },
+    });
+    for (const operation of ['volumeUp', 'volumeDown'] as const) {
+      expectOperationAvailability(binding, operation, available);
+      if (available) continue;
+      // The iPhone/iPad simulator refuses on the kind (XCUIDevice hides the press); every leaf
+      // whose OS has no volume key refuses on the leaf, whichever kind it runs as.
+      expect(binding.facts.operations[operation]).toMatchObject(
+        device.appleOs === 'ios' || device.appleOs === 'ipados'
+          ? {
+              reason: 'unsupported-device-kind',
+              hint: expect.stringContaining('physical iPhone and iPad'),
+            }
+          : {
+              reason: 'unsupported-platform-leaf',
+              hint: expect.stringContaining('this Apple leaf has none'),
+            },
+      );
+    }
+    expectOperationAvailability(binding, 'power', false);
+    expect(binding.facts.operations.power).toMatchObject({
+      reason: 'unsupported-platform-leaf',
+      hint: expect.stringContaining('No Apple leaf carries this system button'),
+    });
+  },
+);
+
 test.each(Object.entries(leaves))(
   'classifies the fold fact for the %s leaf',
   async (_name, device) => {
diff --git a/packages/platform-linux/src/runtime.test.ts b/packages/platform-linux/src/runtime.test.ts
index 67f8b8c9fe..90caf783c3 100644
--- a/packages/platform-linux/src/runtime.test.ts
+++ b/packages/platform-linux/src/runtime.test.ts
@@ -218,8 +218,12 @@ function expectLinuxNavigationAndKeyboardFacts(
     // R56: the Linux interactor's own `appSwitcher` throws, and the retired descriptor declared
     // `linux: {}`, so no Linux cell was ever admitted.
     'appSwitcher',
-    // The Action Button is iPhone/iPad hardware; the Linux desktop has no equivalent control.
+    // The Action Button is iPhone/iPad hardware; the Linux desktop has no equivalent control,
+    // and neither does it have the phone volume and power keys hardware-button presses (#3848).
     'actionButton',
+    'volumeUp',
+    'volumeDown',
+    'power',
     // Nor does it have a foldable hinge to pose.
     'setFoldPose',
     // Nor a modem to simulate a call or text message on.
diff --git a/packages/platform-web/src/runtime.test.ts b/packages/platform-web/src/runtime.test.ts
index 3eae17d812..c2f485e9e9 100644
--- a/packages/platform-web/src/runtime.test.ts
+++ b/packages/platform-web/src/runtime.test.ts
@@ -212,8 +212,12 @@ test('clipboard, the app switcher, app events, settings and alerts carry no web
     'readClipboard',
     'writeClipboard',
     'appSwitcher',
-    // The Action Button is iPhone/iPad hardware with no web analogue at all.
+    // The Action Button is iPhone/iPad hardware with no web analogue at all, and so are the
+    // phone volume and power keys the hardware-button command presses (#3848).
     'actionButton',
+    'volumeUp',
+    'volumeDown',
+    'power',
     // A foldable hinge is posed through the host's iOS simulator HID helper; the web target has
     // none.
     'setFoldPose',
diff --git a/packages/provider-limrun/src/interaction-operations.test.ts b/packages/provider-limrun/src/interaction-operations.test.ts
index 9a0e440310..233fb2db2d 100644
--- a/packages/provider-limrun/src/interaction-operations.test.ts
+++ b/packages/provider-limrun/src/interaction-operations.test.ts
@@ -91,6 +91,36 @@ test('home is admitted on both legs, app-switcher only on Android, the action bu
   expect(stale.actionButton).toEqual(liveSessionUnavailable);
 });
 
+// The Android leg's interactor comes from createAndroidInteractor, which carries the three
+// hardware-button presses, so a leased phone/tablet admits them with the local owner's phone
+// and TV rule; the iOS leg has no such member and falls to the family denial (#3848).
+test('the Android leg admits the hardware-button presses and gates them on the local rule', () => {
+  const android = limrunSystemButtonOperationFacts(androidMobileDevice);
+  expect(android.volumeUp).toEqual({ available: true });
+  expect(android.volumeDown).toEqual({ available: true });
+  expect(android.power).toEqual({ available: true });
+
+  const tv = limrunSystemButtonOperationFacts(androidTvDevice);
+  expect(tv.volumeUp).toEqual({
+    available: false,
+    reason: 'unsupported-device-kind',
+    hint: 'hardware-button is not supported on Android TV targets; use tv-remote.',
+  });
+  expect(tv.power).toEqual(tv.volumeUp);
+
+  const ios = limrunSystemButtonOperationFacts(iosDevice);
+  expect(ios.volumeUp).toMatchObject({
+    available: false,
+    reason: 'unsupported-provider-mode',
+    hint: 'No Limrun session exposes this system button.',
+  });
+
+  const stale = limrunSystemButtonOperationFacts(androidMobileDevice, liveSessionUnavailable);
+  expect(stale.volumeUp).toEqual(liveSessionUnavailable);
+  expect(stale.volumeDown).toEqual(liveSessionUnavailable);
+  expect(stale.power).toEqual(liveSessionUnavailable);
+});
+
 // R57: app-event delivery is the one system leaf BOTH direct-session legs serve, because each
 // implements `open` and a deep link is exactly what that method routes.
 test('app-event delivery is admitted on both direct-session legs', () => {
diff --git a/packages/provider-limrun/src/interaction-operations.ts b/packages/provider-limrun/src/interaction-operations.ts
index bf9326cd58..a2c5cef6cd 100644
--- a/packages/provider-limrun/src/interaction-operations.ts
+++ b/packages/provider-limrun/src/interaction-operations.ts
@@ -21,7 +21,10 @@ import { settingsRuntimeOperationFacts } from '@agent-device/contracts/settings-
 import type { AndroidSetting } from '@agent-device/platform-android/mechanics';
 import type { LimrunIosSetting } from './ios-settings.ts';
 import { alertRuntimeOperationFacts } from '@agent-device/contracts/alert-runtime';
-import { systemButtonRuntimeOperationFacts } from '@agent-device/contracts/system-button-runtime';
+import {
+  androidHardwareButtonAvailability,
+  systemButtonRuntimeOperationFacts,
+} from '@agent-device/contracts/system-button-runtime';
 import { clipboardRuntimeOperationFacts } from '@agent-device/contracts/clipboard-runtime';
 import { keyboardRuntimeOperationFacts } from '@agent-device/contracts/keyboard-runtime';
 import { orientationRuntimeOperationFacts } from '@agent-device/contracts/orientation-runtime';
@@ -136,6 +139,9 @@ const systemButtonUnavailable = unavailableFact(
   'unsupported-provider-mode',
   'No Limrun session exposes this system button.',
 );
+// The hardware-button cells use the shared Android admission rule, so a Limrun-managed phone
+// and a local adb phone state the same verdict. On a leased phone or tablet the Android leg's
+// `createAndroidInteractor` carries all three presses.
 
 /**
  * The interactor-backed interaction cells a live Limrun session serves: everything here rides
@@ -289,9 +295,9 @@ export function limrunAlertOperationFacts(
 }
 
 /**
- * The Android leg rides the local family's own interactor factory for `home` and `appSwitcher`.
- * The iOS direct session presses `home` through Limrun's button actions and refuses
- * `appSwitcher`. No Limrun session exposes the action button.
+ * The Android leg rides the local family's own interactor factory for `home`, `appSwitcher` and
+ * the three hardware-button presses. The iOS direct session presses `home` through Limrun's button
+ * actions and refuses `appSwitcher`. No Limrun session exposes the action button.
  */
 export function limrunSystemButtonOperationFacts(
   device: DeviceInfo,
@@ -305,6 +311,9 @@ export function limrunSystemButtonOperationFacts(
       unsupported: systemButtonUnavailable,
       home: available,
       appSwitcher: available,
+      volumeUp: androidHardwareButtonAvailability(device),
+      volumeDown: androidHardwareButtonAvailability(device),
+      power: androidHardwareButtonAvailability(device),
     });
   }
   return systemButtonRuntimeOperationFacts({
diff --git a/packages/provider-webdriver/src/capabilities.ts b/packages/provider-webdriver/src/capabilities.ts
index 4417106cad..511ec30628 100644
--- a/packages/provider-webdriver/src/capabilities.ts
+++ b/packages/provider-webdriver/src/capabilities.ts
@@ -20,6 +20,9 @@ export type CloudWebDriverOperation =
   | 'orientation'
   | 'appSwitcher'
   | 'tvRemote'
+  | 'volumeUp'
+  | 'volumeDown'
+  | 'power'
   | 'clipboard.read'
   | 'clipboard.write'
   | 'settings'
@@ -103,6 +106,22 @@ const BASE_WEBDRIVER_CAPABILITIES: CloudWebDriverCapabilityMap = {
     support: 'partial',
     note: 'Uses provider/Appium mobile pressButton support where available.',
   },
+  // hardware-button legs. The base rows state the iOS route (XCUITest `mobile: pressButton`
+  // carries the volume names and exposes no power press at all); the Android platform entry below
+  // replaces all three with the `mobile: pressKey` keycodes UiAutomator2 presses, and lifts
+  // `power` from unsupported to partial.
+  volumeUp: {
+    support: 'partial',
+    note: 'Uses provider/Appium mobile pressButton volumeup support where available; real devices only.',
+  },
+  volumeDown: {
+    support: 'partial',
+    note: 'Uses provider/Appium mobile pressButton volumedown support where available; real devices only.',
+  },
+  power: {
+    support: 'unsupported',
+    note: 'XCUITest exposes no power press to Appium on any iOS session.',
+  },
   tvRemote: unsupported,
   'clipboard.read': {
     support: 'partial',
@@ -133,12 +152,32 @@ export function createCloudWebDriverCapabilities(options: {
   platform: CloudWebDriverPlatform;
   overrides?: CloudWebDriverCapabilityOverrides;
 }): CloudWebDriverProviderCapabilities {
+  const base: CloudWebDriverCapabilityMap =
+    options.platform === 'android'
+      ? {
+          ...BASE_WEBDRIVER_CAPABILITIES,
+          // UiAutomator2's execute map (checked against 8.x) registers no pressButton route; it
+          // presses any keycode through mobile pressKey — the same keyevents the local Android owner sends through `input keyevent`.
+          volumeUp: {
+            support: 'partial',
+            note: 'Uses provider/Appium mobile pressKey keycode 24 where available.',
+          },
+          volumeDown: {
+            support: 'partial',
+            note: 'Uses provider/Appium mobile pressKey keycode 25 where available.',
+          },
+          power: {
+            support: 'partial',
+            note: "Uses provider/Appium mobile pressKey keycode 26 where available; the screen state after the press is the device's own.",
+          },
+        }
+      : BASE_WEBDRIVER_CAPABILITIES;
   return {
     provider: options.provider,
     platform: options.platform,
     snapshotBackend: options.platform === 'ios' ? 'xctest' : 'android',
     snapshotSource: 'appium-page-source',
-    operations: applyCapabilityOverrides(BASE_WEBDRIVER_CAPABILITIES, options.overrides),
+    operations: applyCapabilityOverrides(base, options.overrides),
   };
 }
 
diff --git a/packages/provider-webdriver/src/platform-runtime.test.ts b/packages/provider-webdriver/src/platform-runtime.test.ts
index 14b5053b58..906b94376c 100644
--- a/packages/provider-webdriver/src/platform-runtime.test.ts
+++ b/packages/provider-webdriver/src/platform-runtime.test.ts
@@ -620,6 +620,34 @@ test('a reachable provider with no overrides still admits its declared operation
   }
 });
 
+// The hardware-button split lives in the platform's declared map, not in a device-kind rule:
+// the Android map carries `power` (mobile pressKey 26) and volume on the pressKey keycodes, the
+// iOS map refuses power and carries volume on mobile pressButton (#3848).
+test('hardware-button facts follow the platform capability map', async () => {
+  const owner = (platform: CloudWebDriverPlatform) =>
+    createWebDriverPlatformRuntimeOwner({
+      host: host(async () => ({ stdout: '', stderr: '', exitCode: 0 })),
+      owner: providerRuntimeOwner('browserstack', platform),
+      ownsDevice: () => true,
+      capabilities: capabilities(platform),
+      getInteractor: () => ({}) as unknown as Interactor,
+    });
+
+  const android = await owner('android').inspectFacts(device);
+  for (const key of ['volumeUp', 'volumeDown', 'power'] as const) {
+    expect(android.operations[key].available).toBe(true);
+  }
+
+  const iosDevice: DeviceInfo = { ...device, platform: 'apple', appleOs: 'ios' };
+  const ios = await owner('ios').inspectFacts(iosDevice);
+  expect(ios.operations.volumeUp.available).toBe(true);
+  expect(ios.operations.volumeDown.available).toBe(true);
+  expect(ios.operations.power).toMatchObject({
+    available: false,
+    reason: 'owner-capability-missing',
+  });
+});
+
 test('an Apple WebDriver dump bounded to one entry reports unnamed traffic without its identities', async () => {
   // Five keep-alive requests CFNetwork logged no URL for, and no connection
   // line to resolve them against: many more unnamed tasks than maxEntries.
diff --git a/packages/provider-webdriver/src/platform-runtime.ts b/packages/provider-webdriver/src/platform-runtime.ts
index 26cdea38a9..4b9125a616 100644
--- a/packages/provider-webdriver/src/platform-runtime.ts
+++ b/packages/provider-webdriver/src/platform-runtime.ts
@@ -205,16 +205,27 @@ const appSwitcherUnavailable = unavailableFact(
 );
 
 /**
- * Unlike `home` and `appSwitcher` this is never a per-session capability question: no WebDriver
- * `mobile:` script presses hardware such as the iPhone Action Button, so the fact refuses
- * unconditionally. There is deliberately no capability key for it, which would advertise a button
- * this provider can never press.
+ * The Action Button is the one system button this family still denies outright: no WebDriver
+ * `mobile:` script presses hardware such as the iPhone Action Button, so there is deliberately no
+ * capability key for it, which would advertise a button this provider can never press. The
+ * hardware-button keys below are the family's declared-capability cells instead.
  */
 const systemButtonUnavailable = unavailableFact(
   'unsupported-provider-mode',
   'No WebDriver backend presses this system button.',
 );
 
+/**
+ * The hardware-button legs ride `mobile: pressButton` / `mobile: pressKey`, so the cell reads the
+ * seam the same way `home` does: a reachable interactor plus the provider's declaration. The
+ * declaration carries the platform split — the iOS capability map marks `power` unsupported, the
+ * Android map does not — so nothing here restates it as a device-kind rule.
+ */
+const hardwareButtonUnavailable = unavailableFact(
+  'unsupported-provider-mode',
+  'This WebDriver provider runtime does not expose hardware-button for this device.',
+);
+
 /** No WebDriver `mobile:` script poses a foldable hinge; the refusal is unconditional like the Action Button's. */
 const foldUnavailable = unavailableFact(
   'unsupported-provider-mode',
@@ -623,6 +634,12 @@ function webDriverFacts(
         unsupported: systemButtonUnavailable,
         home: declared('home', homeUnavailable),
         appSwitcher: declared('appSwitcher', appSwitcherUnavailable),
+        // Volume and power ride the backend's own hardware-key route and read the same
+        // declared-capability seam `home` uses; the iOS platform map declares power unsupported, so
+        // the declaration — not a device-kind guess — is what refuses it there.
+        volumeUp: declared('volumeUp', hardwareButtonUnavailable),
+        volumeDown: declared('volumeDown', hardwareButtonUnavailable),
+        power: declared('power', hardwareButtonUnavailable),
       }),
       setFoldPose: foldUnavailable,
       sendTelephonyEvent: telephonyUnavailable,
diff --git a/packages/provider-webdriver/src/webdriver-interactor-hardware-button.test.ts b/packages/provider-webdriver/src/webdriver-interactor-hardware-button.test.ts
new file mode 100644
index 0000000000..5bc5966792
--- /dev/null
+++ b/packages/provider-webdriver/src/webdriver-interactor-hardware-button.test.ts
@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { AppError } from '@agent-device/kernel/errors';
+import { createCloudWebDriverCapabilities } from './capabilities.ts';
+import type { WebDriverClient } from './webdriver-client.ts';
+import { createWebDriverInteractor } from './webdriver-interactor.ts';
+
+/**
+ * The hardware-button legs (#3848): UiAutomator2 registers no pressButton and presses the volume
+ * and power keycodes through `mobile: pressKey`; XCUITest carries volume through
+ * `mobile: pressButton` and exposes no power press, so an iOS session refuses power from its
+ * declared capability map before the driver is asked.
+ */
+
+function recordingClient(transcript: string[]): WebDriverClient {
+  return {
+    executeScript: async (script: string, args: unknown[]) => {
+      transcript.push(`${script} ${JSON.stringify(args)}`);
+    },
+  } as unknown as WebDriverClient;
+}
+
+test('Android volume presses ride the mobile pressKey volume keycodes', async () => {
+  const transcript: string[] = [];
+  const interactor = createWebDriverInteractor({
+    client: recordingClient(transcript),
+    backend: 'android',
+    capabilities: createCloudWebDriverCapabilities({ provider: 'test', platform: 'android' }),
+  });
+  await interactor.volumeUp!();
+  await interactor.volumeDown!();
+  assert.deepEqual(transcript, [
+    'mobile: pressKey [{"keycode":24}]',
+    'mobile: pressKey [{"keycode":25}]',
+  ]);
+});
+
+test('iOS volume presses ride mobile pressButton and power refuses before the driver', async () => {
+  const transcript: string[] = [];
+  const ios = createWebDriverInteractor({
+    client: recordingClient(transcript),
+    backend: 'xctest',
+    capabilities: createCloudWebDriverCapabilities({ provider: 'test', platform: 'ios' }),
+  });
+  await ios.volumeUp!();
+  await ios.volumeDown!();
+  assert.deepEqual(transcript, [
+    'mobile: pressButton [{"name":"volumeup"}]',
+    'mobile: pressButton [{"name":"volumedown"}]',
+  ]);
+
+  const powerClient = {
+    executeScript: async () => {
+      throw new Error('the iOS power refusal must reach the driver');
+    },
+  } as unknown as WebDriverClient;
+  const powerIos = createWebDriverInteractor({
+    client: powerClient,
+    backend: 'xctest',
+    capabilities: createCloudWebDriverCapabilities({ provider: 'test', platform: 'ios' }),
+  });
+  await assert.rejects(powerIos.power!(), (error: unknown) => {
+    return error instanceof AppError && error.code === 'UNSUPPORTED_OPERATION';
+  });
+});
+
+test('Android power presses KEYCODE_POWER through mobile pressKey', async () => {
+  const transcript: string[] = [];
+  const android = createWebDriverInteractor({
+    client: recordingClient(transcript),
+    backend: 'android',
+    capabilities: createCloudWebDriverCapabilities({ provider: 'test', platform: 'android' }),
+  });
+  await android.power!();
+  assert.deepEqual(transcript, ['mobile: pressKey [{"keycode":26}]']);
+});
diff --git a/packages/provider-webdriver/src/webdriver-interactor.ts b/packages/provider-webdriver/src/webdriver-interactor.ts
index 2a75fec1b3..afecb62811 100644
--- a/packages/provider-webdriver/src/webdriver-interactor.ts
+++ b/packages/provider-webdriver/src/webdriver-interactor.ts
@@ -53,6 +53,12 @@ const SNAPSHOT_VIEWPORT_PROBE_TIMEOUT_MS = 500;
 
 /** The Android `KEYCODE_ENTER` the IME's return key sends. */
 const ANDROID_KEYCODE_ENTER = 66;
+/** The Android `KEYCODE_VOLUME_UP` the `hardware-button volume-up` press sends. */
+const ANDROID_KEYCODE_VOLUME_UP = 24;
+/** The Android `KEYCODE_VOLUME_DOWN` the `hardware-button volume-down` press sends. */
+const ANDROID_KEYCODE_VOLUME_DOWN = 25;
+/** The Android `KEYCODE_POWER` the `hardware-button power` press sends. */
+const ANDROID_KEYCODE_POWER = 26;
 /** How a WebDriver dismiss lowers the iOS keyboard: Appium's hide-keyboard route. */
 const WEBDRIVER_DISMISS_MECHANISM = 'appium-hide-keyboard';
 
@@ -420,6 +426,41 @@ class WebDriverInteractor implements Interactor {
     await this.client.executeScript('mobile: pressButton', [{ name: 'appSwitch' }]);
   }
 
+  /**
+   * The volume legs split by backend because the two drivers expose different routes: XCUITest
+   * answers `mobile: pressButton` with the `volumeup`/`volumedown` names (the only hardware-key
+   * route it exposes), while UiAutomator2 registers no pressButton at all and presses the
+   * KEYCODE_VOLUME_UP/DOWN keycodes through `mobile: pressKey` — the same keyevents the local
+   * Android owner sends. The press lands on the system, which is what the command claims.
+   */
+  async volumeUp(): Promise<void> {
+    this.requireSupport('volumeUp');
+    await this.pressVolumeKey(ANDROID_KEYCODE_VOLUME_UP, 'volumeup');
+  }
+
+  async volumeDown(): Promise<void> {
+    this.requireSupport('volumeDown');
+    await this.pressVolumeKey(ANDROID_KEYCODE_VOLUME_DOWN, 'volumedown');
+  }
+
+  private async pressVolumeKey(androidKeycode: number, xcuiButtonName: string): Promise<void> {
+    if (this.backend === 'android') {
+      await this.client.executeScript('mobile: pressKey', [{ keycode: androidKeycode }]);
+      return;
+    }
+    await this.client.executeScript('mobile: pressButton', [{ name: xcuiButtonName }]);
+  }
+
+  /**
+   * Android presses KEYCODE_POWER through `mobile: pressKey`, the same keycode the local owner
+   * sends through `input keyevent`. iOS has no power press in any Appium route, and its
+   * capability map declares `power` unsupported, so the declaration refuses before this leg.
+   */
+  async power(): Promise<void> {
+    this.requireSupport('power');
+    await this.client.executeScript('mobile: pressKey', [{ keycode: ANDROID_KEYCODE_POWER }]);
+  }
+
   async tvRemote(_button: TvRemoteButton, _durationMs?: number): Promise<void> {
     this.unsupported('tvRemote');
   }
diff --git a/packages/session-journal/src/session-event-action-presentation.ts b/packages/session-journal/src/session-event-action-presentation.ts
index 933681cb6e..20824d555f 100644
--- a/packages/session-journal/src/session-event-action-presentation.ts
+++ b/packages/session-journal/src/session-event-action-presentation.ts
@@ -1,6 +1,7 @@
 import type { SessionAction } from '@agent-device/contracts/session';
 import {
   FOLD_POSES,
+  HARDWARE_BUTTON_NAMES,
   ORIENTATION_REQUESTS,
   TELEPHONY_ACTIONS,
 } from '@agent-device/contracts/device';
@@ -43,6 +44,8 @@ export function buildStructuredActionSummary(action: SessionAction): string | un
       return 'Opened app switcher';
     case PUBLIC_COMMANDS.actionButton:
       return 'Pressed Action Button';
+    case PUBLIC_COMMANDS.hardwareButton:
+      return buildHardwareButtonActionSummary(result);
     case PUBLIC_COMMANDS.orientation:
       return buildOrientationActionSummary(result);
     case PUBLIC_COMMANDS.fold:
@@ -112,6 +115,8 @@ export function buildStructuredActionDetails(action: SessionAction): Record<stri
         button: isTvRemoteButton(result.button) ? result.button : undefined,
         durationMs: readSessionEventNumber(result.durationMs),
       });
+    case PUBLIC_COMMANDS.hardwareButton:
+      return compactDetails({ button: readEnum(result.button, HARDWARE_BUTTON_NAMES) });
     case PUBLIC_COMMANDS.gesture:
     case PUBLIC_COMMANDS.swipe:
       return buildGestureActionDetails(result);
@@ -261,6 +266,11 @@ function buildKeyboardActionDetails(result: Record<string, unknown>): Record<str
   });
 }
 
+function buildHardwareButtonActionSummary(result: Record<string, unknown>): string {
+  const button = readEnum(result.button, HARDWARE_BUTTON_NAMES);
+  return button === undefined ? 'Pressed hardware button' : `Pressed hardware button ${button}`;
+}
+
 function buildTvRemoteActionSummary(result: Record<string, unknown>): string {
   const button = isTvRemoteButton(result.button) ? result.button : undefined;
   return button ? `Pressed TV remote ${button}` : 'Used TV remote';
diff --git a/src/__tests__/runner-read-only-registry-parity.test.ts b/src/__tests__/runner-read-only-registry-parity.test.ts
index 587c1756bf..8c732c823c 100644
--- a/src/__tests__/runner-read-only-registry-parity.test.ts
+++ b/src/__tests__/runner-read-only-registry-parity.test.ts
@@ -47,6 +47,8 @@ const REGISTRY_COUNTERPART: Record<RunnerName, RegistryRequest> = {
   gesture: { command: 'gesture' },
   appSwitcher: { command: 'app-switcher' },
   actionButton: { command: 'action-button' },
+  volumeUp: { command: 'hardware-button', positionals: ['volume-up'] },
+  volumeDown: { command: 'hardware-button', positionals: ['volume-down'] },
   keyboardDismiss: { command: 'keyboard', positionals: ['dismiss'] },
   keyboardReturn: { command: 'keyboard', positionals: ['enter'] },
   pasteboardWrite: { command: 'clipboard', positionals: ['write', 'x'] },
diff --git a/src/agent-device-client.ts b/src/agent-device-client.ts
index a7e0ce9613..abcf90e43d 100644
--- a/src/agent-device-client.ts
+++ b/src/agent-device-client.ts
@@ -199,6 +199,8 @@ export function createAgentDeviceClient(
         await executeCommand<CommandResult<'clipboard'>>('clipboard', options),
       tvRemote: async (options) =>
         await executeCommand<CommandResult<'tv-remote'>>('tv-remote', options),
+      hardwareButton: async (options) =>
+        await executeCommand<CommandResult<'hardware-button'>>('hardware-button', options),
       telephony: async (options) =>
         await executeCommand<CommandResult<'telephony'>>('telephony', options),
       reactNative: async (options) => await executeCommand('react-native', options),
diff --git a/src/client/client-types.ts b/src/client/client-types.ts
index 4c7b5809f8..ab48d7b2df 100644
--- a/src/client/client-types.ts
+++ b/src/client/client-types.ts
@@ -31,20 +31,13 @@ export type {
 
 // Contracts/kernel types re-exported into the PUBLISHED surface: `agent-device-client.ts` picks
 // these up via `export type *`, and that is their only job — every internal consumer imports
-// them from the declaring module instead. Fallow therefore sees no consumer, which is exactly
-// right and exactly not actionable: deleting them would remove names from the package's public
-// types. Suppressed per name rather than baselined so the reason travels with the code.
-// fallow-ignore-next-line unused-type
+// them from the declaring module instead. Deleting one would remove a name from the package's
+// public types.
 export type { TargetShutdownResult } from '@agent-device/contracts/device';
-// fallow-ignore-next-line unused-type
 export type { MetroBridgeScope } from '@agent-device/contracts/remote';
-// fallow-ignore-next-line unused-type
 export type { AppsFilter } from '@agent-device/contracts/device';
-// fallow-ignore-next-line unused-type
 export type { AlertAction } from '@agent-device/contracts/alert-contract';
-// fallow-ignore-next-line unused-type
 export type { AppleOS } from '@agent-device/kernel/device';
-// fallow-ignore-next-line unused-type
 export type { JsonObject } from '@agent-device/contracts/client';
 export type { BatchRunResult } from '@agent-device/command-registry/batch';
 
@@ -133,6 +126,7 @@ import type {
   TapGestureOptions,
   TransformGestureOptions,
   TvRemoteCommandOptions,
+  HardwareButtonCommandOptions,
   TypeTextOptions,
   ViewportCommandOptions,
   WaitCommandOptions,
@@ -174,6 +168,9 @@ export type AgentDeviceCommandClient = {
   appSwitcher: (options?: AppSwitcherCommandOptions) => Promise<CommandResult<'app-switcher'>>;
   actionButton: (options?: ActionButtonCommandOptions) => Promise<CommandResult<'action-button'>>;
   tvRemote: (options: TvRemoteCommandOptions) => Promise<CommandResult<'tv-remote'>>;
+  hardwareButton: (
+    options: HardwareButtonCommandOptions,
+  ) => Promise<CommandResult<'hardware-button'>>;
   telephony: (options: TelephonyCommandOptions) => Promise<CommandResult<'telephony'>>;
   wait: (options: WaitCommandOptions) => Promise<CommandResult<'wait'>>;
   alert: (options?: AlertCommandOptions) => Promise<CommandRequestResult>;
diff --git a/src/commands/replay/replay-script.fixtures.ts b/src/commands/replay/replay-script.fixtures.ts
index e670560a12..a89a4c254e 100644
--- a/src/commands/replay/replay-script.fixtures.ts
+++ b/src/commands/replay/replay-script.fixtures.ts
@@ -180,6 +180,7 @@ const REPLAY_SCRIPT_LINE_PLANS = {
   trace: GENERIC_REPLAY_LINE,
   'trigger-app-event': GENERIC_REPLAY_LINE,
   'tv-remote': GENERIC_REPLAY_LINE,
+  'hardware-button': GENERIC_REPLAY_LINE,
   uninstall: GENERIC_REPLAY_LINE,
   viewport: GENERIC_REPLAY_LINE,
   human_control: { waived: 'host-local control commands are never recorded in replay scripts' },
diff --git a/src/commands/system/index.test.ts b/src/commands/system/index.test.ts
index b74b931254..adba37a001 100644
--- a/src/commands/system/index.test.ts
+++ b/src/commands/system/index.test.ts
@@ -21,6 +21,8 @@ import {
   clipboardDaemonWriter,
   foldCliReader,
   foldDaemonWriter,
+  hardwareButtonCliReader,
+  hardwareButtonDaemonWriter,
   keyboardCliReader,
   keyboardDaemonWriter,
   orientationCliReader,
@@ -385,6 +387,24 @@ describe('system command interface', () => {
     );
     expectInvalidArgs(() => tvRemoteCliReader(['blue'], flags()), 'button must be one of');
   });
+
+  test('hardware-button reader and writer validate the button positional', () => {
+    expect(hardwareButtonCliReader(['volume-up'], flags())).toMatchObject({ button: 'volume-up' });
+    expect(hardwareButtonCliReader(['Volume-Down'], flags())).toMatchObject({
+      button: 'volume-down',
+    });
+    expect(
+      hardwareButtonDaemonWriter({ button: 'power' } as Record<string, unknown>).positionals,
+    ).toEqual(['power']);
+    expectInvalidArgs(() => hardwareButtonCliReader([], flags()), 'requires exactly one button');
+    expectInvalidArgs(
+      () => hardwareButtonCliReader(['volume-up', 'power'], flags()),
+      'requires exactly one button',
+    );
+    // Exact names only: no aliases, and nothing reaches the daemon for an unknown name.
+    expectInvalidArgs(() => hardwareButtonCliReader(['vol'], flags()), 'button must be one of');
+    expectInvalidArgs(() => hardwareButtonCliReader(['mute'], flags()), 'button must be one of');
+  });
 });
 
 test('fold keyframes survive CLI and daemon projection without a preset', () => {
diff --git a/src/commands/system/index.ts b/src/commands/system/index.ts
index 32beb3d052..8734a2256e 100644
--- a/src/commands/system/index.ts
+++ b/src/commands/system/index.ts
@@ -18,6 +18,12 @@ import {
   parseTelephonyEventInput,
   parseTelephonyPositionals,
   telephonyPositionals,
+  // The hardware-button vocabulary arrives through the same eager device-vocabulary façade the
+  // orientation and fold readers use (#3848, eager-closure budgets).
+  HARDWARE_BUTTON_NAMES,
+  HARDWARE_BUTTON_NAME_LABELS,
+  HARDWARE_BUTTON_USAGE,
+  parseHardwareButtonPositionals,
 } from '@agent-device/contracts/device';
 import { type BackMode, BACK_MODES } from '@agent-device/contracts/back-mode';
 import {
@@ -76,6 +82,7 @@ const ORIENTATION_COMMAND_NAME = 'orientation';
 const FOLD_COMMAND_NAME = 'fold';
 const APP_SWITCHER_COMMAND_NAME = 'app-switcher';
 const ACTION_BUTTON_COMMAND_NAME = 'action-button';
+const HARDWARE_BUTTON_COMMAND_NAME = 'hardware-button';
 const KEYBOARD_COMMAND_NAME = 'keyboard';
 const CLIPBOARD_COMMAND_NAME = 'clipboard';
 const TV_REMOTE_COMMAND_NAME = 'tv-remote';
@@ -164,6 +171,14 @@ export const SYSTEM_COMMAND_OUTPUT_SCHEMAS = {
     },
     ['action', 'button', 'message'],
   ),
+  'hardware-button': objectSchema(
+    {
+      action: constSchema('hardware-button'),
+      button: enumSchema(HARDWARE_BUTTON_NAMES),
+      message: stringSchema(),
+    },
+    ['action', 'button', 'message'],
+  ),
   // packages/contracts/src/telephony-input.ts — discriminated union on `action`.
   telephony: {
     type: 'object',
@@ -262,6 +277,7 @@ export const SYSTEM_COMMAND_OUTPUT_SCHEMAS = {
   | 'fold'
   | 'action-button'
   | 'tv-remote'
+  | 'hardware-button'
   | 'telephony'
   | 'clipboard'
   | 'appstate'
@@ -317,6 +333,9 @@ const actionButtonCommandDescription =
 const tvRemoteCommandDescription =
   'Press or long-press a TV remote button on Android TV, tvOS, or Vega OS. Android TV also supports volume, power, media, channel, guide, captions, input, color keys, and android-keycode:N. tvOS and Vega OS support up, down, left, right, select, menu, home, and back. Phones and WebDriver sessions are unsupported. The aliases ok, center, and enter map to select.';
 
+const hardwareButtonCommandDescription =
+  'Press a phone hardware button once: volume-up, volume-down, or power. The press is dispatched without activating the session app and nothing is re-observed afterwards, so the OS decides what the key does — which audio stream a volume press moves, and whether the HUD shows, is device behavior this command does not claim. Power toggles the Android screen; after a press that turns it off, later commands may hit a locked screen. Android (ADB-backed and Appium) presses all three on phones and tablets; a physical iPhone or iPad presses volume only through the local runner or Appium, never power. iOS Simulators, Android TV and tvOS targets refuse: on TV targets use tv-remote.';
+
 const telephonyCommandDescription =
   'Simulate an incoming phone call or SMS on an Android emulator through its console over adb: call rings from the number, accept answers, cancel ends the call, and sms delivers a text message. The call screen or notification can cover the app, so re-snapshot afterwards.';
 
@@ -413,6 +432,19 @@ const tvRemoteCommandMetadata = defineFieldCommandMetadata(
   },
 );
 
+const hardwareButtonCommandMetadata = defineFieldCommandMetadata(
+  HARDWARE_BUTTON_COMMAND_NAME,
+  hardwareButtonCommandDescription,
+  {
+    button: requiredField(
+      enumField(
+        HARDWARE_BUTTON_NAMES,
+        'One press each. volume-up and volume-down move the system volume stream the OS selects; power toggles the screen on Android and is refused on every Apple leaf.',
+      ),
+    ),
+  },
+);
+
 const telephonyFields = {
   action: requiredField(
     enumField(
@@ -487,6 +519,11 @@ const tvRemoteCliSchema = {
   allowedFlags: ['durationMs'],
 } as const satisfies CommandSchemaOverride;
 
+const hardwareButtonCliSchema = {
+  usageOverride: `hardware-button ${HARDWARE_BUTTON_USAGE}`,
+  positionalArgs: ['button'],
+} as const satisfies CommandSchemaOverride;
+
 const telephonyCliSchema = {
   usageOverride: TELEPHONY_USAGE,
   listUsageOverride: 'telephony call|accept|cancel|sms <number> [text]',
@@ -527,6 +564,11 @@ export const tvRemoteCliReader: CliReader = (positionals, flags) => ({
   ...readTvRemoteInput(positionals, flags.durationMs),
 });
 
+export const hardwareButtonCliReader: CliReader = (positionals, flags) => ({
+  ...commonInputFromFlags(flags),
+  ...readHardwareButtonInput(positionals),
+});
+
 export const telephonyCliReader: CliReader = (positionals, flags) => ({
   ...commonInputFromFlags(flags),
   ...parseTelephonyPositionals(positionals),
@@ -562,6 +604,11 @@ export const tvRemoteDaemonWriter: DaemonWriter = direct(TV_REMOTE_COMMAND_NAME,
   requiredDaemonString(input.button, 'tv-remote requires button'),
 ]);
 
+export const hardwareButtonDaemonWriter: DaemonWriter = direct(
+  HARDWARE_BUTTON_COMMAND_NAME,
+  (input) => [requiredDaemonString(input.button, 'hardware-button requires button')],
+);
+
 export const telephonyDaemonWriter: DaemonWriter = direct(TELEPHONY_COMMAND_NAME, (input) =>
   telephonyPositionals(parseTelephonyEventInput(input)),
 );
@@ -689,6 +736,21 @@ const tvRemoteCommandFacet = defineCommandFacet({
   cliOutputFormatter: systemCliOutputFormatters['tv-remote'],
 });
 
+const hardwareButtonCommandFacet = defineCommandFacet({
+  name: HARDWARE_BUTTON_COMMAND_NAME,
+  text: {
+    summary: 'Press a phone hardware button once',
+    cliDetail:
+      'Single press; no hold. Android presses volume-up, volume-down, and power on phones and tablets. A physical iPhone or iPad presses volume only; power is never supported on Apple targets. iOS Simulators, Android TV, and tvOS refuse — use tv-remote on TV targets.',
+  },
+  metadata: hardwareButtonCommandMetadata,
+  run: (client, input) => client.command.hardwareButton(input),
+  cliSchema: hardwareButtonCliSchema,
+  cliReader: hardwareButtonCliReader,
+  daemonWriter: hardwareButtonDaemonWriter,
+  cliOutputFormatter: systemCliOutputFormatters['hardware-button'],
+});
+
 const telephonyCommandFacet = defineCommandFacet({
   name: TELEPHONY_COMMAND_NAME,
   text: {
@@ -717,6 +779,7 @@ export const systemCommandFamily = defineCommandFamilyFromFacets({
     keyboardCommandFacet,
     clipboardCommandFacet,
     tvRemoteCommandFacet,
+    hardwareButtonCommandFacet,
     telephonyCommandFacet,
   ],
 });
@@ -774,6 +837,11 @@ function readTvRemoteInput(
   });
 }
 
+function readHardwareButtonInput(positionals: string[]): Record<string, unknown> {
+  // One shared helper answers arity and parse for the CLI reader and the daemon resolver alike.
+  return { button: HARDWARE_BUTTON_NAME_LABELS[parseHardwareButtonPositionals(positionals)] };
+}
+
 function readKeyboardAction(
   value: string | undefined,
 ): 'status' | 'dismiss' | 'enter' | 'return' | undefined {
diff --git a/src/commands/system/output.ts b/src/commands/system/output.ts
index e0ce129983..ad1357283e 100644
--- a/src/commands/system/output.ts
+++ b/src/commands/system/output.ts
@@ -52,6 +52,7 @@ export const systemCliOutputFormatters = withSettleCapableNotes({
   keyboard: resultOutput(keyboardCliOutput),
   clipboard: resultOutput(clipboardCliOutput),
   'tv-remote': messageOutput,
+  'hardware-button': messageOutput,
   telephony: messageOutput,
 } satisfies Record<string, CliOutputFormatter>);
 
diff --git a/src/core/interactors/android.ts b/src/core/interactors/android.ts
index 636056db3d..1fcbc8c729 100644
--- a/src/core/interactors/android.ts
+++ b/src/core/interactors/android.ts
@@ -17,6 +17,7 @@ import {
   doubleTapAndroid,
   pressAndroid,
   pressAndroidEnter,
+  pressAndroidHardwareButton,
   pressAndroidTvRemote,
   readAndroidClipboardText,
   readAndroidGestureViewport,
@@ -124,6 +125,9 @@ export function createAndroidInteractor(
     setOrientation: (orientation) => setAndroidOrientation(device, orientation),
     unlockOrientation: () => unlockAndroidOrientation(device),
     appSwitcher: () => appSwitcherAndroid(device),
+    volumeUp: () => pressAndroidHardwareButton(device, 'volumeUp'),
+    volumeDown: () => pressAndroidHardwareButton(device, 'volumeDown'),
+    power: () => pressAndroidHardwareButton(device, 'power'),
     tvRemote: (button, durationMs) => pressAndroidTvRemote(device, button, durationMs),
     keyboardStatus: async () => ({ kind: 'ime-probe', ...(await getAndroidKeyboardState(device)) }),
     keyboardDismiss: async () => ({ kind: 'ime-probe', ...(await dismissAndroidKeyboard(device)) }),
diff --git a/test/integration/command-coverage/declarations.ts b/test/integration/command-coverage/declarations.ts
index 1a534b7e4c..2ba59e8afa 100644
--- a/test/integration/command-coverage/declarations.ts
+++ b/test/integration/command-coverage/declarations.ts
@@ -17,12 +17,14 @@ import {
   ANDROID_AUDIO_CONTRACT_EVIDENCE,
   ANDROID_APPLICATION_LIFECYCLE_CONTRACT_EVIDENCE,
   ANDROID_FOLD_RUNTIME_CONTRACT_EVIDENCE,
+  ANDROID_HARDWARE_BUTTON_RUNTIME_CONTRACT_EVIDENCE,
   ANDROID_HOVER_RUNTIME_CONTRACT_EVIDENCE,
   ANDROID_TELEPHONY_RUNTIME_CONTRACT_EVIDENCE,
   ANDROID_TV_REMOTE_RUNTIME_CONTRACT_EVIDENCE,
   ANDROID_UNINSTALL_CONTRACT_EVIDENCE,
   ANDROID_VIEWPORT_RUNTIME_CONTRACT_EVIDENCE,
   APPLE_ACTION_BUTTON_FACT_EVIDENCE,
+  APPLE_HARDWARE_BUTTON_FACT_EVIDENCE,
   APPLE_HOVER_DENIAL_EVIDENCE,
   APPLE_NAVIGATION_FACTS_EVIDENCE,
   LINUX_HOVER_DENIAL_EVIDENCE,
@@ -1404,6 +1406,37 @@ const COMMAND_COVERAGE_DECLARATIONS = {
       'the exact-owner runtime fact refuses an Action Button press on the Linux desktop',
     ),
   },
+  [C.hardwareButton]: {
+    androidEmulator: androidEmulator.contract(
+      ANDROID_HARDWARE_BUTTON_RUNTIME_CONTRACT_EVIDENCE,
+      'Android admits the hardware-button facts on phones and tablets through the keyevent path and refuses a TV target with a pointer to tv-remote',
+    ),
+    iosSimulator: iosSimulator.contract(
+      APPLE_HARDWARE_BUTTON_FACT_EVIDENCE.path,
+      APPLE_HARDWARE_BUTTON_FACT_EVIDENCE.test,
+      'the exact-owner runtime fact refuses hardware-button volume on the simulator leaf (XCUIDevice exposes no volume press there) and power on every leaf',
+    ),
+    macos: macos.contract(
+      APPLE_HARDWARE_BUTTON_FACT_EVIDENCE.path,
+      APPLE_HARDWARE_BUTTON_FACT_EVIDENCE.test,
+      'the exact-owner runtime fact refuses hardware-button on the macOS host leaf',
+    ),
+    tvos: tvos.contract(
+      APPLE_HARDWARE_BUTTON_FACT_EVIDENCE.path,
+      APPLE_HARDWARE_BUTTON_FACT_EVIDENCE.test,
+      'the exact-owner runtime fact refuses hardware-button on the tvOS leaf, whose remote has its own command family',
+    ),
+    web: web.contract(
+      WEB_SYSTEM_SURFACE_DENIAL_EVIDENCE.path,
+      WEB_SYSTEM_SURFACE_DENIAL_EVIDENCE.test,
+      'the exact-owner runtime fact refuses a hardware-button press on the web target',
+    ),
+    linux: linux.contract(
+      LINUX_RUNTIME_EVIDENCE.path,
+      LINUX_RUNTIME_EVIDENCE.test,
+      'the exact-owner runtime fact refuses a hardware-button press on every Linux leaf',
+    ),
+  },
   [C.fold]: {
     androidEmulator: androidEmulator.contract(
       ANDROID_FOLD_RUNTIME_CONTRACT_EVIDENCE,
diff --git a/test/integration/command-coverage/evidence.ts b/test/integration/command-coverage/evidence.ts
index 1d8d661b62..1460f8013b 100644
--- a/test/integration/command-coverage/evidence.ts
+++ b/test/integration/command-coverage/evidence.ts
@@ -49,6 +49,12 @@ export const ANDROID_FOLD_RUNTIME_CONTRACT_EVIDENCE: AndroidContractEvidence =
     [C.fold],
     'Android admits the fold fact on emulators and refuses every other kind',
   );
+export const ANDROID_HARDWARE_BUTTON_RUNTIME_CONTRACT_EVIDENCE: AndroidContractEvidence =
+  defineAndroidContractEvidence(
+    'packages/platform-android/src/runtime.test.ts',
+    [C.hardwareButton],
+    'Android admits the hardware-button facts on phones and tablets and refuses a TV target',
+  );
 export const ANDROID_UNINSTALL_CONTRACT_EVIDENCE: AndroidContractEvidence =
   defineAndroidContractEvidence(
     'test/integration/provider-scenarios/android-uninstall.test.ts',
@@ -93,6 +99,10 @@ export const APPLE_ACTION_BUTTON_FACT_EVIDENCE: RepositoryEvidence = {
   path: 'packages/platform-apple/src/runtime.test.ts',
   test: 'classifies the action-button fact for the %s leaf',
 };
+export const APPLE_HARDWARE_BUTTON_FACT_EVIDENCE: RepositoryEvidence = {
+  path: 'packages/platform-apple/src/runtime.test.ts',
+  test: 'classifies the hardware-button volume facts for the %s leaf',
+};
 export const APPLE_HOVER_DENIAL_EVIDENCE: RepositoryEvidence = {
   path: 'packages/platform-apple/src/runtime.test.ts',
   test: 'hover has no Apple interactor route on macOS, iOS, or tvOS; the touch family reports its typed denial',
diff --git a/test/integration/provider-scenarios/apple-platform-output-guard.test.ts b/test/integration/provider-scenarios/apple-platform-output-guard.test.ts
index e8d4b5230f..61af0c4221 100644
--- a/test/integration/provider-scenarios/apple-platform-output-guard.test.ts
+++ b/test/integration/provider-scenarios/apple-platform-output-guard.test.ts
@@ -129,6 +129,7 @@ const DRIVEN_COMMANDS: Record<string, DriveSpec> = {
   [PUBLIC_COMMANDS.tvRemote]: () => one(['select']),
   [PUBLIC_COMMANDS.appSwitcher]: () => one(),
   [PUBLIC_COMMANDS.actionButton]: () => one(),
+  [PUBLIC_COMMANDS.hardwareButton]: () => one(['volume-up']),
   [PUBLIC_COMMANDS.fold]: () => one(['open']),
   [PUBLIC_COMMANDS.telephony]: () => one(['call', '5551234']),
 
diff --git a/test/integration/provider-scenarios/provider-device-runtime.fixtures.ts b/test/integration/provider-scenarios/provider-device-runtime.fixtures.ts
index 5d496b981b..e8d9f9acdd 100644
--- a/test/integration/provider-scenarios/provider-device-runtime.fixtures.ts
+++ b/test/integration/provider-scenarios/provider-device-runtime.fixtures.ts
@@ -270,6 +270,18 @@ function providerScenarioRuntimeFacts(
       // hardware exists on the iPhone/iPad leaf only, so the fixture reads the same kernel rule the
       // Apple owner's fact reads instead of restating it (#2699).
       actionButton: hasAppleActionButton(device) ? fakeProviderAvailable : fakeProviderUnavailable,
+      // The hardware-button volume press rides the same runner transport, and the XCUITest
+      // volume key exists on a physical iPhone/iPad only, so the fixture reads the same kind and
+      // leaf rule the Apple owner's fact reads (#3848). No Apple leaf presses power.
+      volumeUp:
+        device.kind === 'device' && hasAppleActionButton(device)
+          ? fakeProviderAvailable
+          : fakeProviderUnavailable,
+      volumeDown:
+        device.kind === 'device' && hasAppleActionButton(device)
+          ? fakeProviderAvailable
+          : fakeProviderUnavailable,
+      power: fakeProviderUnavailable,
       // A provider session has no host simulator for the fold HID helper, so no fixture leg poses
       // a hinge.
       setFoldPose: fakeProviderUnavailable,
diff --git a/test/integration/provider-scenarios/provider-ios-runner-transport.test.ts b/test/integration/provider-scenarios/provider-ios-runner-transport.test.ts
index 81fd9d4fc4..f874cfe2c0 100644
--- a/test/integration/provider-scenarios/provider-ios-runner-transport.test.ts
+++ b/test/integration/provider-scenarios/provider-ios-runner-transport.test.ts
@@ -132,6 +132,63 @@ test('provider transport carries the Action Button press without an app activati
   });
 });
 
+// The volume press rides the same interactor seam and owes the session app the same nothing:
+// `hardware-button volume-up` must reach the provider transport as the `volumeUp` runner command
+// without activating the app (#3848).
+test('provider transport carries the hardware-button volume press without an app activation', async () => {
+  await withProviderScenarioResource(
+    createPhysicalInteractorSeamWorld,
+    async ({ daemon, calls }) => {
+      const lease = await allocateLease(daemon);
+      const request = { flags: leaseFlags(lease.leaseId), meta: leaseMeta(lease.leaseId) };
+      assertRpcOk(await daemon.callCommand('open', ['com.example.app'], request.flags, request));
+
+      calls.runner.length = 0;
+      assert.deepEqual(
+        assertRpcOk(
+          await daemon.callCommand('hardware-button', ['volume-up'], request.flags, request),
+        ),
+        {
+          action: 'hardware-button',
+          button: 'volume-up',
+          message: 'Pressed hardware button volume-up',
+        },
+      );
+      assert.ok(
+        calls.runner.some((call) => call.command.command === 'volumeUp'),
+        'expected volumeUp on the provider transport, not local XCTest',
+      );
+      assert.deepEqual(
+        calls.runner.filter((call) => call.command.command === 'activate'),
+        [],
+        'a hardware-button press must not activate the session app',
+      );
+    },
+  );
+});
+
+// Apple exposes no power press to XCUITest on any kind, so even the physical-device world refuses
+// `hardware-button power` at admission, before anything reaches the transport (#3848).
+test('provider transport refuses hardware-button power before any runner traffic', async () => {
+  await withProviderScenarioResource(
+    createPhysicalInteractorSeamWorld,
+    async ({ daemon, calls }) => {
+      const lease = await allocateLease(daemon);
+      const request = { flags: leaseFlags(lease.leaseId), meta: leaseMeta(lease.leaseId) };
+      assertRpcOk(await daemon.callCommand('open', ['com.example.app'], request.flags, request));
+
+      calls.runner.length = 0;
+      assertRpcError(
+        await daemon.callCommand('hardware-button', ['power'], request.flags, request),
+        500,
+        'UNSUPPORTED_OPERATION',
+        /hardware-button/,
+      );
+      assert.deepEqual(calls.runner, [], 'a refused power press must not reach the transport');
+    },
+  );
+});
+
 // A hinge pose is sent by a HID helper the host spawns inside a local iOS simulator, which a
 // provider-owned device is not, so the provider fixture states the refusal cell and admission
 // refuses before anything reaches the transport.
@@ -222,13 +279,22 @@ async function createInteractorSeamWorld() {
   return await createRunnerTransportWorld({ requestScope: false });
 }
 
+// The same seam with a physical iPhone leaf: the hardware-button volume fact admits a physical
+// device, so the press must reach the transport on this world (#3848).
+async function createPhysicalInteractorSeamWorld() {
+  return await createRunnerTransportWorld({
+    requestScope: false,
+    device: { ...DEVICE, kind: 'device' },
+  });
+}
+
 // The request-boundary seam: getAppleRunnerProvider scopes the whole request,
 // covering runner commands issued outside interactor methods.
 async function createRequestScopeWorld() {
   return await createRunnerTransportWorld({ requestScope: true });
 }
 
-async function createRunnerTransportWorld(options: { requestScope: boolean }) {
+async function createRunnerTransportWorld(options: { requestScope: boolean; device?: DeviceInfo }) {
   const calls: RunnerTransportCalls = { runner: [], opens: 0 };
   const runtime = createProviderRuntime(calls, options);
   const providers = createProviderDeviceRuntimeRequestProviders([runtime]);
@@ -256,8 +322,9 @@ async function createRunnerTransportWorld(options: { requestScope: boolean }) {
 
 function createProviderRuntime(
   calls: RunnerTransportCalls,
-  options: { requestScope: boolean },
+  options: { requestScope: boolean; device?: DeviceInfo },
 ): ProviderDeviceRuntime {
+  const device = options.device ?? DEVICE;
   const transport: AppleRunnerProvider = {
     hasLiveSession: () => true,
     runCommand: async (_device, command, options) => {
@@ -267,23 +334,23 @@ function createProviderRuntime(
   };
   const leaseLifecycle: LeaseLifecycleProvider = {
     allocate: async (lease) =>
-      lease.leaseProvider === PROVIDER ? { provider: PROVIDER, deviceId: DEVICE.id } : undefined,
+      lease.leaseProvider === PROVIDER ? { provider: PROVIDER, deviceId: device.id } : undefined,
   };
   const deviceInventoryProvider: DeviceInventoryProvider = async (request) =>
-    request.leaseProvider === PROVIDER && request.leaseId ? [DEVICE] : null;
+    request.leaseProvider === PROVIDER && request.leaseId ? [device] : null;
   return {
     provider: PROVIDER,
     leaseLifecycle,
     deviceInventoryProvider,
-    ownsDevice: (device) => device.id === DEVICE.id,
-    getInteractor: (device, runnerContext) =>
-      device.id === DEVICE.id
-        ? createRunnerTransportInteractor(calls, transport, runnerContext)
+    ownsDevice: (candidate) => candidate.id === device.id,
+    getInteractor: (candidate, runnerContext) =>
+      candidate.id === device.id
+        ? createRunnerTransportInteractor(calls, transport, runnerContext, device)
         : undefined,
     ...(options.requestScope
       ? {
-          getAppleRunnerProvider: (device: DeviceInfo) =>
-            device.id === DEVICE.id ? transport : undefined,
+          getAppleRunnerProvider: (candidate: DeviceInfo) =>
+            candidate.id === device.id ? transport : undefined,
         }
       : {}),
     shutdown: async () => undefined,
@@ -294,9 +361,10 @@ function createRunnerTransportInteractor(
   calls: RunnerTransportCalls,
   transport: AppleRunnerProvider,
   runnerContext: RunnerContext | undefined,
+  device: DeviceInfo,
 ): Interactor {
   const runner = runnerContext ?? {};
-  const implementation = applePlugin.createInteractor(DEVICE, runner, {
+  const implementation = applePlugin.createInteractor(device, runner, {
     env: process.env,
     cwd: process.cwd(),
   });
@@ -311,7 +379,7 @@ function createRunnerTransportInteractor(
       return (...args: unknown[]) =>
         withAppleRunnerProvider(
           transport,
-          { deviceId: DEVICE.id, requestId: runner.requestId },
+          { deviceId: device.id, requestId: runner.requestId },
           async () => {
             const interactor = await implementation;
             const operation = interactor[property as keyof Interactor];
diff --git a/website/docs/docs/client-api.md b/website/docs/docs/client-api.md
index 75b55d385b..21379c32c9 100644
--- a/website/docs/docs/client-api.md
+++ b/website/docs/docs/client-api.md
@@ -276,6 +276,9 @@ await client.command.tvRemote({
 
 await client.command.appSwitcher();
 await client.command.actionButton();
+await client.command.hardwareButton({ button: 'volume-up' });
+await client.command.hardwareButton({ button: 'volume-down' });
+await client.command.hardwareButton({ button: 'power', platform: 'android' });
 await client.command.fold({ pose: 'open' });
 await client.command.telephony({ action: 'call', number: '5551234' });
 await client.command.telephony({ action: 'sms', number: '5551234', text: 'Your code is 1234' });
@@ -291,6 +294,8 @@ await client.command.fold({
 
 `fold` accepts either `pose` or `keyframes`. Keyframes use linear interpolation at roughly 60 updates per second; repeat an angle to hold it. Timestamps must start at zero and increase strictly, with 2–64 frames and a final timestamp no greater than 60,000ms. Angles must be finite and between 0° and 180°. The final timestamp bounds motion, excluding helper preparation and final hinge verification. A custom final angle is verified within 0.5°; interior angles must also settle. Cancellation stops the motion at its current angle. Re-snapshot afterwards, including after interrupted motion. Android emulators accept `pose` only.
 
+`hardwareButton` presses one phone hardware key once: `button` is `'volume-up'`, `'volume-down'`, or `'power'`. It takes no hold duration and activates no app; the result reports the dispatched press, not the OS reaction. Android presses all three on phones and tablets; a physical iPhone or iPad presses volume only; iOS Simulators, Android TV, and tvOS refuse (use `tvRemote` on TV targets).
+
 `press`, `click`, and `longpress` do not wait for a missing target to appear. When a screen is still loading, wait for its landmark before interacting:
 
 ```ts
@@ -314,6 +319,7 @@ Supported command methods:
 - `orientation`
 - `appSwitcher`
 - `actionButton`
+- `hardwareButton`
 - `fold`
 - `telephony`
 - `keyboard`
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index de62aa7871..07bdaebcd5 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -56,6 +56,9 @@ agent-device orientation landscape-left
 agent-device orientation auto
 agent-device app-switcher
 agent-device action-button
+agent-device hardware-button volume-up
+agent-device hardware-button volume-down
+agent-device hardware-button power
 agent-device fold closed
 agent-device fold half-open
 agent-device fold open
@@ -120,6 +123,9 @@ Back, orientation, and hardware buttons:
 - `orientation auto` hands rotation back to the sensor on ADB-backed Android, local or Limrun (`accelerometer_rotation=1`, `user_rotation` untouched), and reports `orientation: "auto"`. It does not wait for the display to rotate, because there is no target rotation: the sensor decides, and an emulator usually settles on portrait. Every other backend refuses `auto` with `UNSUPPORTED_OPERATION`.
 - `action-button` presses the iPhone or iPad Action Button once. It takes no arguments, no hold duration, and no `--settle`, and it doesn't activate the session app or drive Camera Control. Other platforms refuse it, and a model without the button (an iPhone SE, most iPad simulators) fails with `UNSUPPORTED_OPERATION`.
 - `action-button` reports that the press was dispatched, not what it triggered. Simulators run no Shortcuts or App Intents, so verify the outcome on a physical iPhone. Expect a press to take about five seconds on a Simulator.
+- `hardware-button volume-up|volume-down|power` presses one phone hardware key once, with no hold and no `--settle`, and it doesn't activate the session app. The response reports the dispatched press, not what the OS did with it: which audio stream a volume press moves and whether the HUD shows is device behavior the command does not claim.
+- Android presses all three keys on phones and tablets: the ADB-backed and helper paths send `input keyevent` 24/25/26, and an Appium-backed device presses the same keycodes through its `mobile: pressKey` route. A physical iPhone or iPad presses volume only, through the local runner or Appium's volume button press; no Apple leaf presses power. iOS Simulators refuse volume (`XCUIDevice` exposes no volume press there), and Android TV and tvOS targets refuse with a pointer to `tv-remote`.
+- A `power` press toggles the Android screen. After a press that turns it off, later commands may hit a locked screen; nothing in agent-device presses the key again to wake it.
 
 Fold a foldable device:
 

From 066cb0d7427aecb50ac066256427a597a9d7fb4a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 21 Oct 2026 00:05:34 +0200
Subject: [PATCH 2/2] chore(gates): raise registry.ts line cap for the
 hardware-button descriptor

---
 oxlint.config.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/oxlint.config.ts b/oxlint.config.ts
index e6dcf7be2c..f4d8b84457 100644
--- a/oxlint.config.ts
+++ b/oxlint.config.ts
@@ -53,7 +53,7 @@ const LEGACY_FILE_LINE_CAPS = {
   'src/daemon-client/__tests__/daemon-client.test.ts': 1340,
   'src/mcp/__tests__/command-tools.test.ts': 1029,
   'test/integration/provider-scenarios/android-lifecycle.test.ts': 1227,
-  'packages/command-registry/src/registry.ts': 2179,
+  'packages/command-registry/src/registry.ts': 2192,
   'packages/host-kit/src/internal/exec.ts': 1032,
   'packages/react-native/src/metro/client-metro.ts': 1123,
   'src/cli/commands/connection-runtime.ts': 1019,