feat(host-agent): make execution history authoritative

2026-07-15 11:46:27 +08:00
parent ccde30e378
commit 77d4813bb2
46 changed files with 890 additions and 3132 deletions
@@ -0,0 +1,51 @@
+## 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