fix: stop harmony emulator keepalive

Author: linhay

.agents/tritonkit-skills/public/tritonkit-dev-feedback/SKILL.md

@@ -90,6 +90,7 @@ Repository: `NeptuneKit/TritonKit` (`https://github.com/NeptuneKit/TritonKit`)
      - `triton device list --platform harmony --json`
      - `triton device alias set harmony-a --platform harmony --target <hdc-target> --json` for repeated multi-emulator validation;
      - `triton device wait-ready --device harmony-a --json`
+     - `triton device stop --platform harmony --hvd <hvd-name> --path <deployed-path> --confirm --json` when Triton's `triton-harmony-emulator` launchd keepalive job started the HVD;
      - `triton app inspect --platform harmony --bundle <bundle> --target <hdc-target> --json`
      - `triton app install --device harmony-a --hap <debug-signed.hap> --json`
      - `triton app launch --device harmony-a --bundle <bundle> --ability <ability> --json`

.agents/tritonkit-skills/public/tritonkit-emulator-cli-takeover/SKILL.md

@@ -80,10 +80,13 @@ triton device wait-ready --device iphone15 --json
 triton device wait-ready --device harmony-a --json
 triton device screenshot --device iphone15 --output /tmp/<case>-sim.png --json
 triton device screenshot --device harmony-a --output /tmp/<case>.jpeg --json
+triton device stop --platform harmony --hvd "Codex Test Phone" --path ~/.Huawei/Emulator/deployed --confirm --json
 ```
 
 Use `--device <selector>` as the default agent-facing target selector for common host-side commands. Selectors can be aliases, full ids such as `sim:<udid>` / `harmony:<target>`, raw platform ids, `booted`, or `current`. `--platform`, `--name`, `--runtime`, `--state`, and `--ready` are filters; they may auto-select only when the filtered candidate set is unique. Keep `sim` for iOS-only advanced maintenance; `device runtime-url --device <selector>` is the Harmony embedded runtime port-forward setup path, with `--platform harmony --target <target>` retained for compatibility.
 
+When a Harmony HVD was started through Triton's `triton-harmony-emulator` launchd keepalive job, stop it through `triton device stop --platform harmony ... --confirm --json`. The command checks and unloads `gui/<uid>/triton-harmony-emulator` before running DevEco `Emulator -stop`, which prevents launchd from immediately restarting the emulator.
+
 iOS Simulator:
 
 ```bash

.agents/tritonkit-skills/public/tritonkit-real-project-regression/SKILL.md

@@ -90,6 +90,7 @@ Real-project validation is not the same as demo smoke. Treat the business app as
    - list HDC targets: `triton device list --platform harmony --json`;
    - for repeated multi-emulator work, create a stable selector: `triton device alias set harmony-a --platform harmony --target <hdc-target> --json`;
    - wait for boot readiness: `triton device wait-ready --device harmony-a --json`;
+   - close a Triton-supervised HVD with launchd cleanup: `triton device stop --platform harmony --hvd <hvd-name> --path <deployed-path> --confirm --json`;
    - inspect app metadata: `triton app inspect --platform harmony --bundle <bundle> --target <hdc-target> --json`;
    - install a debug HAP when needed: `triton app install --device harmony-a --hap <debug-signed.hap> --json`;
    - launch an Ability: `triton app launch --device harmony-a --bundle <bundle> --ability <ability> --json`;

CLI/Tests/TritonKitCLITests/DeviceCrossPlatformTests.swift

@@ -19,18 +19,60 @@ struct DeviceCrossPlatformTests {
         #expect(optionNames.contains("wait-ready --device <selector>"))
         #expect(optionNames.contains("screenshot --device <selector> --output <path>"))
         #expect(optionNames.contains("runtime-url --device <selector>"))
+        #expect(optionNames.contains("stop --platform harmony --hvd <name> --path <deployed-path> --confirm"))
         #expect(optionNames.contains("--device"))
         #expect(optionNames.contains("--name"))
         #expect(optionNames.contains("--runtime"))
         #expect(optionNames.contains("runtime-url --platform harmony --target <target>"))
         #expect(device.examples.contains("triton device runtime-url --device harmony-a --probe-manifest --json"))
+        #expect(device.examples.contains("triton device stop --platform harmony --hvd 'Codex Test Phone' --path ~/.Huawei/Emulator/deployed --confirm --json"))
         #expect(device.providedCapabilities.contains("host-device"))
         #expect(device.providedCapabilities.contains("device-alias"))
         #expect(device.providedCapabilities.contains("host-device-selector"))
         #expect(device.providedCapabilities.contains("device-list"))
         #expect(device.providedCapabilities.contains("device-use"))
         #expect(device.providedCapabilities.contains("device-wait-ready"))
         #expect(device.providedCapabilities.contains("device-screenshot"))
+        #expect(device.providedCapabilities.contains("harmony-device-stop"))
+    }
+
+    @Test("Harmony emulator stop plans launchd bootout before DevEco stop")
+    func harmonyEmulatorStopPlansLaunchdBootoutBeforeDevEcoStop() throws {
+        let plan = try harmonyEmulatorStopPlan(
+            hvd: "Codex Test Phone",
+            deployedPath: "/Users/linhey/.Huawei/Emulator/deployed",
+            emulator: "/Applications/DevEco-Studio.app/Contents/tools/emulator/Emulator",
+            launchdLabel: "triton-harmony-emulator",
+            launchdDomain: "gui/501",
+            includeLaunchd: true,
+            confirmed: true
+        )
+
+        #expect(plan.action == "device.stop")
+        #expect(plan.platform == "harmony")
+        #expect(plan.hvd == "Codex Test Phone")
+        #expect(plan.launchdLabel == "triton-harmony-emulator")
+        #expect(plan.launchdDomain == "gui/501")
+        #expect(plan.commands.map(hostSourceCommand) == [
+            "launchctl print gui/501/triton-harmony-emulator",
+            "launchctl bootout gui/501/triton-harmony-emulator",
+            "/Applications/DevEco-Studio.app/Contents/tools/emulator/Emulator -stop 'Codex Test Phone' -path /Users/linhey/.Huawei/Emulator/deployed",
+        ])
+    }
+
+    @Test("Harmony emulator stop requires explicit confirmation")
+    func harmonyEmulatorStopRequiresConfirmation() {
+        #expect(throws: HostDeviceSelectionError.self) {
+            _ = try harmonyEmulatorStopPlan(
+                hvd: "Codex Test Phone",
+                deployedPath: "/Users/linhey/.Huawei/Emulator/deployed",
+                emulator: "/Applications/DevEco-Studio.app/Contents/tools/emulator/Emulator",
+                launchdLabel: "triton-harmony-emulator",
+                launchdDomain: "gui/501",
+                includeLaunchd: true,
+                confirmed: false
+            )
+        }
     }
 
     @Test("app and smoke schemas expose unified device selector with compatibility paths")

README.md

@@ -420,6 +420,7 @@ triton device list --platform harmony --json
 triton device use --platform harmony --target 127.0.0.1:10100 --json
 triton device wait-ready --device 127.0.0.1:10100 --json
 triton device screenshot --device 127.0.0.1:10100 --output /tmp/smoke.jpeg --json
+triton device stop --platform harmony --hvd "Codex Test Phone" --path ~/.Huawei/Emulator/deployed --confirm --json
 triton app inspect --platform harmony --bundle com.example.app --target 127.0.0.1:10100 --json
 triton app install --device 127.0.0.1:10100 --hap /tmp/Demo.hap --json
 triton app launch --device 127.0.0.1:10100 --bundle com.example.app --ability EntryAbility --json
@@ -432,6 +433,8 @@ triton screenshot --platform harmony --target 127.0.0.1:10100 --output /tmp/smok
 
 When multiple HDC targets are `Connected`, Triton returns `error.code=ambiguous_target` and requires an explicit `--target`. The adapter records `sourceCommand`; risk/policy metadata is for audit and configuration validation, not an interactive confirmation gate.
 
+When Triton starts a Harmony HVD through its `triton-harmony-emulator` launchd keepalive job, close it with `triton device stop --platform harmony ... --confirm --json` instead of raw `Emulator -stop`. The Triton command unloads `gui/<uid>/triton-harmony-emulator` before calling DevEco `Emulator -stop`, so launchd does not restart the emulator after a successful stop.
+
 Harmony host-side `ax/wait/tap/screenshot` wrap `uitest dumpLayout`, `uitest uiInput click`, and `snapshot_display` with JSON envelopes. Layout and screenshot outputs can contain private UI data; inspect or redact artifacts before attaching them to public issues.
 
 For repeatable regression flows, wait for asynchronous UI state before the next action or assertion:

Sources/TritonKitCLI/CLIHostCommands.swift

@@ -1694,7 +1694,7 @@ struct Device: AsyncParsableCommand {
     static let configuration = CommandConfiguration(
         commandName: "device",
         abstract: "Discover and inspect host-side devices and emulators",
-        subcommands: [DeviceDoctor.self, DeviceList.self, DeviceAlias.self, DeviceUse.self, DeviceCurrent.self, DeviceResolve.self, DeviceWaitReady.self, DeviceScreenshot.self, DeviceRuntimeURL.self]
+        subcommands: [DeviceDoctor.self, DeviceList.self, DeviceAlias.self, DeviceUse.self, DeviceCurrent.self, DeviceResolve.self, DeviceWaitReady.self, DeviceScreenshot.self, DeviceRuntimeURL.self, DeviceStop.self]
     )
 }
 
@@ -2137,3 +2137,61 @@ struct DeviceRuntimeURL: AsyncParsableCommand {
         }
     }
 }
+
+struct DeviceStop: AsyncParsableCommand {
+    static let configuration = CommandConfiguration(commandName: "stop", abstract: "Stop a host-side device or emulator")
+
+    @Option(help: "Platform adapter: harmony") var platform: HostDevicePlatform = .harmony
+    @Option(help: "Harmony HVD name, for example Codex Test Phone") var hvd: String
+    @Option(help: "DevEco deployed emulator path, for example ~/.Huawei/Emulator/deployed") var path: String
+    @Option(help: "Path to DevEco Emulator executable") var emulator: String = "/Applications/DevEco-Studio.app/Contents/tools/emulator/Emulator"
+    @Option(help: "Triton launchd job label to unload before stopping") var launchdLabel: String = "triton-harmony-emulator"
+    @Option(help: "launchd domain, defaults to gui/<uid>") var launchdDomain: String = defaultLaunchdDomain()
+    @Flag(help: "Skip launchd print/bootout and only run Emulator -stop") var skipLaunchd = false
+    @Flag(help: "Confirm stopping the emulator and unloading Triton launchd supervision") var confirm = false
+    @Flag(help: "Alias for --format json") var json = false
+    @Option(help: "Output format: text or json") var format: ClientOutputFormat = .json
+
+    func run() async throws {
+        let outputFormat = effectiveFormat(format, json: json)
+        do {
+            guard platform == .harmony else {
+                throw RuntimeError("device stop currently supports Harmony Emulator only")
+            }
+            let plan = try harmonyEmulatorStopPlan(
+                hvd: hvd,
+                deployedPath: path,
+                emulator: emulator,
+                launchdLabel: launchdLabel,
+                launchdDomain: launchdDomain,
+                includeLaunchd: !skipLaunchd,
+                confirmed: confirm
+            )
+            var sourceCommands: [String] = []
+            for command in plan.commands {
+                let result = try runHostCommand(command)
+                sourceCommands.append(result.sourceCommand)
+            }
+            let output = HostDeviceStopOutput(
+                ok: true,
+                action: plan.action,
+                platform: plan.platform,
+                hvd: plan.hvd,
+                deployedPath: plan.deployedPath,
+                emulator: plan.emulator,
+                launchdLabel: plan.launchdLabel,
+                launchdDomain: plan.launchdDomain,
+                sourceCommands: sourceCommands,
+                note: "Harmony emulator stop completed. Verify with `triton device list --platform harmony --json`; the target should remain disconnected or absent."
+            )
+            switch outputFormat {
+            case .json:
+                print(try encodeJSON(output))
+            case .text:
+                print(output.note)
+            }
+        } catch {
+            try failHostCommand(error, outputFormat: outputFormat)
+        }
+    }
+}

Sources/TritonKitCLI/CLIHostModels.swift

@@ -195,6 +195,30 @@ struct HostDeviceArtifactOutput: Encodable {
     let note: String
 }
 
+struct HarmonyEmulatorStopPlan {
+    let action: String
+    let platform: String
+    let hvd: String
+    let deployedPath: String
+    let emulator: String
+    let launchdLabel: String?
+    let launchdDomain: String?
+    let commands: [TKHostCommand]
+}
+
+struct HostDeviceStopOutput: Encodable {
+    let ok: Bool
+    let action: String
+    let platform: String
+    let hvd: String
+    let deployedPath: String
+    let emulator: String
+    let launchdLabel: String?
+    let launchdDomain: String?
+    let sourceCommands: [String]
+    let note: String
+}
+
 enum HostDeviceSelectionError: Error, CustomStringConvertible {
     case ambiguousTargets([HostDeviceTarget])
     case targetNotFound(String)

Sources/TritonKitCLI/CLIHostRuntime.swift

@@ -547,6 +547,89 @@ func harmonyTarget(from target: HostDeviceTarget) -> TKHarmonyTarget {
     )
 }
 
+func defaultLaunchdDomain() -> String {
+    "gui/\(getuid())"
+}
+
+func harmonyLaunchctlPrintCommand(domain: String, label: String) -> TKHostCommand {
+    TKHostCommand(
+        executable: "launchctl",
+        arguments: ["print", "\(domain)/\(label)"],
+        riskLevel: .readonly,
+        requiredConfig: [.timeout]
+    )
+}
+
+func harmonyLaunchctlBootoutCommand(domain: String, label: String) -> TKHostCommand {
+    TKHostCommand(
+        executable: "launchctl",
+        arguments: ["bootout", "\(domain)/\(label)"],
+        riskLevel: .automation,
+        requiredConfig: [.timeout, .auditRecord]
+    )
+}
+
+func harmonyEmulatorStopCommand(hvd: String, deployedPath: String, emulator: String) -> TKHostCommand {
+    TKHostCommand(
+        executable: emulator,
+        arguments: ["-stop", hvd, "-path", deployedPath],
+        riskLevel: .automation,
+        requiredConfig: [.target, .timeout, .auditRecord]
+    )
+}
+
+func harmonyEmulatorStopPlan(
+    hvd: String,
+    deployedPath: String,
+    emulator: String,
+    launchdLabel: String,
+    launchdDomain: String,
+    includeLaunchd: Bool,
+    confirmed: Bool
+) throws -> HarmonyEmulatorStopPlan {
+    guard confirmed else {
+        throw HostDeviceSelectionError.parameterConflict("device stop requires --confirm.")
+    }
+    let trimmedHVD = hvd.trimmingCharacters(in: .whitespacesAndNewlines)
+    let trimmedPath = deployedPath.trimmingCharacters(in: .whitespacesAndNewlines)
+    let trimmedEmulator = emulator.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !trimmedHVD.isEmpty else {
+        throw HostDeviceSelectionError.parameterConflict("Harmony device stop requires --hvd.")
+    }
+    guard !trimmedPath.isEmpty else {
+        throw HostDeviceSelectionError.parameterConflict("Harmony device stop requires --path.")
+    }
+    guard !trimmedEmulator.isEmpty else {
+        throw HostDeviceSelectionError.parameterConflict("Harmony device stop requires --emulator.")
+    }
+
+    var commands: [TKHostCommand] = []
+    let label = launchdLabel.trimmingCharacters(in: .whitespacesAndNewlines)
+    let domain = launchdDomain.trimmingCharacters(in: .whitespacesAndNewlines)
+    if includeLaunchd {
+        guard !label.isEmpty else {
+            throw HostDeviceSelectionError.parameterConflict("Harmony device stop requires --launchd-label unless --skip-launchd is set.")
+        }
+        guard !domain.isEmpty else {
+            throw HostDeviceSelectionError.parameterConflict("Harmony device stop requires --launchd-domain unless --skip-launchd is set.")
+        }
+        commands.append(harmonyLaunchctlPrintCommand(domain: domain, label: label))
+        commands.append(harmonyLaunchctlBootoutCommand(domain: domain, label: label))
+    }
+    commands.append(harmonyEmulatorStopCommand(hvd: trimmedHVD, deployedPath: trimmedPath, emulator: trimmedEmulator))
+
+    return HarmonyEmulatorStopPlan(
+        action: "device.stop",
+        platform: "harmony",
+        hvd: trimmedHVD,
+        deployedPath: trimmedPath,
+        emulator: trimmedEmulator,
+        launchdLabel: includeLaunchd ? label : nil,
+        launchdDomain: includeLaunchd ? domain : nil,
+        commands: commands
+    )
+}
+
 func ensureParentDirectory(for path: String) throws {
     let directory = URL(fileURLWithPath: path).deletingLastPathComponent()
     try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)

Sources/TritonKitCLI/CLIRuntimeTransport.swift

@@ -270,6 +270,7 @@ func runtimeCapabilities(connected: Bool) -> [TKRuntimeCapability] {
         TKRuntimeCapability(name: "harmony-device-use", supported: true),
         TKRuntimeCapability(name: "harmony-device-wait-ready", supported: true),
         TKRuntimeCapability(name: "harmony-device-screenshot", supported: true),
+        TKRuntimeCapability(name: "harmony-device-stop", supported: true),
         TKRuntimeCapability(name: "harmony-runtime-url", supported: true),
         TKRuntimeCapability(name: "harmony-app-install", supported: true),
         TKRuntimeCapability(name: "harmony-app-open-url", supported: true),