agentic-mobile-control/openspec/changes/archive/2026-07-15-task-execution-progress-visibility/specs/host-agent-dependency-supervisor/spec.md

MODIFIED Requirements

Requirement: Supervisor is opt-in and disabled by default

The Host Agent SHALL NOT start, adopt-check, or supervise Appium unless HOST_AGENT_DEPENDENCY_SUPERVISOR_ENABLED is explicitly set to true. Appium supervision SHALL additionally require HOST_AGENT_APPIUM_SUPERVISED=true and SHALL default to false.

Scenario: Default configuration behaves exactly as before

• WHEN a Host Agent starts with no HOST_AGENT_DEPENDENCY_SUPERVISOR_ENABLED or related Appium environment variable set
• THEN the Host Agent does not attempt to connect to, probe, or spawn Appium, and its heartbeat/claim behavior is unchanged

Scenario: Top-level flag on and Appium flag off

• WHEN HOST_AGENT_DEPENDENCY_SUPERVISOR_ENABLED=true and HOST_AGENT_APPIUM_SUPERVISED=false
• THEN the Host Agent does not probe, adopt, or spawn Appium

Requirement: Spawn supervised dependencies that are not already running

The Host Agent SHALL spawn Appium as a child process when Appium supervision is enabled and no healthy Appium instance is adopted, via appium --address <host> --port <port> and SHALL forward the child process's stdout/stderr into the Host Agent's own logging, tagged by dependency name.

Scenario: Appium is not running at Host Agent startup

• WHEN Appium supervision is enabled and no healthy Appium instance is already listening
• THEN the Host Agent spawns Appium before proceeding to its first device-connect attempt, and its output is visible in Host Agent logs

Scenario: Spawn fails because the executable is missing

• WHEN the Host Agent attempts to spawn Appium but appium is not found on PATH
• THEN the Host Agent logs a dependency-supervisor-specific startup error naming the missing dependency, distinct from a runtime crash of an already-started process

ADDED Requirements

Requirement: Runtime supervision settings are retired

The Host Agent SHALL reject HOST_AGENT_RUNTIME_SUPERVISED, HOST_AGENT_RUNTIME_HOST, and HOST_AGENT_RUNTIME_PORT because the standalone Runtime service no longer exists.

Scenario: A legacy Runtime supervision variable is set

• WHEN startup configuration includes any removed Runtime supervision variable
• THEN configuration fails with an actionable migration error