feat(maestro): support killApp via close mode

[Rohit3523]

Summary

Supports Maestro killApp (system-initiated process death) end to end, mirroring stopApp plumbing. On Android it dispatches adb shell am kill; every other platform aliases stopApp through the shared close dispatcher (Interactor.kill fallback). No new public CLI surface — killApp stays inside the Maestro compatibility layer.

• contracts: optional Interactor.kill, CloseApplicationInput.mode, kill-with-fallback in invokeApplicationClose
• android: killAndroidApp (am kill) wired onto the interactor
• maestro: killApp IR kind, parser, runtime port, daemon projection to an app-only close carrying killApp dispatch
• daemon: replay dispatch folds killApp; session close passes mode: kill into closeApplication
• upstream/116_kill_app now classifies identical; declared divergence removed. Touched 30 files.

Validation

Tested commit 369a51b35. Focused suites pass: contracts interaction, maestro parser/runtime-port/daemon-port/conformance-verify (node --test, 14 pass), android app-lifecycle, session-close, replay-maestro-request, fuzz arbitraries, maestro help/docs sync. pnpm check:quick (lint + typecheck) passes. pnpm check:affected --run: fallow audit clean on changed files; complexity gate shows only the 2 inherited findings after table-driving the lifecycle dispatch. Unresolved: check:production-exports reports 68 unused exports — reproduced identical on origin/main, pre-existing and unrelated. No live-device run; risk is Android am kill semantics on a real emulator (unit asserts the exact argv).

[thymikee]

Reviewed 78727e3. I found no code defect, but the kill route has only run against adb fakes, and I have one smaller-design question.

The route (Maestro replay → close with closeAppOnly + killApp → Android closeApplication with mode kill → killAndroidApp: focus check, am kill, pidof check) is exercised only through adb exec fakes, and the PR body names real-emulator am kill behaviour as the open risk (app-lifecycle.ts#L510). Two things are unproven: that am kill reaps an app sent to the background with Home, and that the post-kill pidof check does not misread a cached process that is still alive. Can you run a live Android emulator replay through agent-device replay: launchApp → pressKey Home → killApp → launchApp with stopApp false? It passes when killApp succeeds, adb shell pidof <pkg> prints nothing after it, and the relaunch is a cold start. In the same session, launchApp → killApp with the app in the foreground should fail with android-kill-requires-background-app. Please paste both outputs.

Could this be smaller? Only the Android lifecycle owner reads mode. Could packages/platform-android/src/lifecycle.ts call killAndroidApp directly when mode === 'kill', instead of adding Interactor.kill and a fallback branch to the shared contracts type? That would also make it explicit that owners that ignore mode keep force-stop, which matches what Maestro does on iOS. What would have to change first?

Not blocking: the support matrix and replay-e2e.md do not say that a foreground killApp is refused rather than a silent no-op; a process that survives am kill while in the background (for example a foreground service) gets the same android-kill-requires-background-app reason, which is misleading; and mode?: 'stop' | 'kill' is declared twice although nothing writes 'stop'.

All checks are green and there are no conflicts. I could not check whether upstream Maestro's killApp also refuses a foreground app.

[Rohit3523]

Hey! Yeah, I’m going to check the review and push the changes. I’m just waiting for the weekend 😄 It would be great to collaborate and get this thing done together ^_^

[cubic-dev-ai]

7 issues found across 27 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/platform-android/src/__tests__/app-lifecycle-open.test.ts">

<violation number="1" location="packages/platform-android/src/__tests__/app-lifecycle-open.test.ts:239">
P3: These two tests invoke `killAndroidApp` twice because `assertRejectsAppError` (test-utils/app-error.ts) only matches `code`/`message`/`hint`, so a second raw call is needed just to read `details.reason`. In the survivor test the second invocation re-runs the whole failure path, adding another ~2 s of real time (ANDROID_CLOSE_PROCESS_TIMEOUT_MS poll loop) to CI and duplicating identical adb mock traffic. Either extend `ExpectedAppError` with a `details` partial matcher and assert `code`+`hint`+`reason` in one `assertRejectsAppError`, or replace the double call with a single try/catch that asserts code, hint, and `details.reason` together.</violation>
</file>

<file name="src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts">

<violation number="1" location="src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts:338">
P3: `mockBindDeviceRuntime.mockImplementation(...)` permanently replaces the shared harness mock for the rest of this file: the file's `beforeEach` only calls `mockClear`, which keeps implementations, so the wrapper (and its `seenModes` closure) stays installed for every subsequent test here. Such tests still pass only because the wrapper delegates to `baseBind`, but the shared mock is left hijacked, which silently couples this test to all later tests in the file. Restore the base implementation at the end of the test, or use two `mockImplementationOnce` registrations.</violation>
</file>

<file name="src/daemon/session-lifecycle/internal/session-close.ts">

<violation number="1" location="src/daemon/session-lifecycle/internal/session-close.ts:152">
P1: This only propagates `kill` through the session-backed dispatcher. A Maestro flow that starts before a daemon session exists enters `closeWithoutSession`, where the omitted mode makes Android perform `stop` instead of `killApp`; pass the same mode through that branch too.</violation>
</file>

<file name="packages/platform-android/src/app-lifecycle.ts">

<violation number="1" location="packages/platform-android/src/app-lifecycle.ts:512">
P2: `killAndroidPackage` proceeds with `am kill` when the foreground probe cannot produce a state. `getAndroidAppState` converts failed or empty dumps into `{}`, so this guard cannot enforce the documented foreground precondition; fail closed or surface the probe failure before dispatching.</violation>

<violation number="2" location="packages/platform-android/src/app-lifecycle.ts:521">
P1: This final liveness check cannot prove the process is gone because `isAndroidPackageProcessRunning` treats every empty `pidof` result as false, including probe failures. Distinguish the normal no-process exit from command errors and fail when the liveness probe itself is unavailable.</violation>
</file>

<file name="packages/maestro/src/internal/__tests__/runtime-port.test.ts">

<violation number="1" location="packages/maestro/src/internal/__tests__/runtime-port.test.ts:187">
P3: The explicit and config app ids are the same value, so this test cannot distinguish the two paths it claims to cover: the dispatcher computes `{ appId: command.appId ?? request.appId }`, and both commands resolve to `com.example.checkout` regardless of which branch is exercised. A regression that, for example, always used the config app id and dropped the explicit `killApp:` app id would still pass. Use a distinct explicit app id (e.g. `com.example.other`) and assert calls[0] receives it while calls[1] falls back to the config id.</violation>
</file>

<file name="packages/platform-android/src/lifecycle.ts">

<violation number="1" location="packages/platform-android/src/lifecycle.ts:69">
P2: `mode: 'kill'` with an empty `positionals` returns success without killing anything. Fall back to `input.appBundleId` (the session-app identity this binding uses everywhere else) and throw `INVALID_ARGS` when neither exists, so a kill that has no target fails loudly instead of reading as success.</violation>
</file>

<sub>Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: This only propagates kill through the session-backed dispatcher. A Maestro flow that starts before a daemon session exists enters closeWithoutSession, where the omitted mode makes Android perform stop instead of killApp; pass the same mode through that branch too.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/daemon/session-lifecycle/internal/session-close.ts, line 152:

<comment>This only propagates `kill` through the session-backed dispatcher. A Maestro flow that starts before a daemon session exists enters `closeWithoutSession`, where the omitted mode makes Android perform `stop` instead of `killApp`; pass the same mode through that branch too.</comment>

<file context>
@@ -149,6 +149,7 @@ async function dispatchTargetedPlatformClose(params: {
       outPath: req.flags?.out,
       appBundleId: session.appBundleId,
       surface: session.surface ?? 'app',
+      ...(req.internal?.killApp === true ? { mode: 'kill' as const } : {}),
       execution: applicationLifecycleExecutionFromRequest(req, logPath, session.trace?.outPath),
     });
</file context>

[cubic-dev-ai]

P1: This final liveness check cannot prove the process is gone because isAndroidPackageProcessRunning treats every empty pidof result as false, including probe failures. Distinguish the normal no-process exit from command errors and fail when the liveness probe itself is unavailable.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/platform-android/src/app-lifecycle.ts, line 521:

<comment>This final liveness check cannot prove the process is gone because `isAndroidPackageProcessRunning` treats every empty `pidof` result as false, including probe failures. Distinguish the normal no-process exit from command errors and fail when the liveness probe itself is unavailable.</comment>

<file context>
@@ -488,6 +488,44 @@ export async function closeAndroidApp(device: DeviceInfo, app: string): Promise<
+  }
+  await runAndroidShell(device, ['am', 'kill', packageName]);
+  await waitForAndroidPackageStopped(device, packageName);
+  if (await isAndroidPackageProcessRunning(device, packageName)) {
+    throw new AppError('COMMAND_FAILED', `am kill did not stop ${packageName}`, {
+      reason: 'android-kill-process-survived',
</file context>

[cubic-dev-ai]

P2: killAndroidPackage proceeds with am kill when the foreground probe cannot produce a state. getAndroidAppState converts failed or empty dumps into {}, so this guard cannot enforce the documented foreground precondition; fail closed or surface the probe failure before dispatching.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/platform-android/src/app-lifecycle.ts, line 512:

<comment>`killAndroidPackage` proceeds with `am kill` when the foreground probe cannot produce a state. `getAndroidAppState` converts failed or empty dumps into `{}`, so this guard cannot enforce the documented foreground precondition; fail closed or surface the probe failure before dispatching.</comment>

<file context>
@@ -488,6 +488,44 @@ export async function closeAndroidApp(device: DeviceInfo, app: string): Promise<
+}
+
+async function killAndroidPackage(device: DeviceInfo, packageName: string): Promise<void> {
+  const foreground = await readAndroidForegroundApp(device);
+  if (foreground?.package === packageName) {
+    throw new AppError('COMMAND_FAILED', `Cannot kill foreground app ${packageName}`, {
</file context>

[cubic-dev-ai]

P2: mode: 'kill' with an empty positionals returns success without killing anything. Fall back to input.appBundleId (the session-app identity this binding uses everywhere else) and throw INVALID_ARGS when neither exists, so a kill that has no target fails loudly instead of reading as success.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/platform-android/src/lifecycle.ts, line 69:

<comment>`mode: 'kill'` with an empty `positionals` returns success without killing anything. Fall back to `input.appBundleId` (the session-app identity this binding uses everywhere else) and throw `INVALID_ARGS` when neither exists, so a kill that has no target fails loudly instead of reading as success.</comment>

<file context>
@@ -63,6 +64,11 @@ export function bindAndroidApplicationLifecycle(
       }
+      if (input.mode === 'kill') {
+        const target = input.positionals[0];
+        if (target) await killAndroidApp(device, target);
+        return;
+      }
</file context>

[cubic-dev-ai]

P3: These two tests invoke killAndroidApp twice because assertRejectsAppError (test-utils/app-error.ts) only matches code/message/hint, so a second raw call is needed just to read details.reason. In the survivor test the second invocation re-runs the whole failure path, adding another ~2 s of real time (ANDROID_CLOSE_PROCESS_TIMEOUT_MS poll loop) to CI and duplicating identical adb mock traffic. Either extend ExpectedAppError with a details partial matcher and assert code+hint+reason in one assertRejectsAppError, or replace the double call with a single try/catch that asserts code, hint, and details.reason together.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/platform-android/src/__tests__/app-lifecycle-open.test.ts, line 239:

<comment>These two tests invoke `killAndroidApp` twice because `assertRejectsAppError` (test-utils/app-error.ts) only matches `code`/`message`/`hint`, so a second raw call is needed just to read `details.reason`. In the survivor test the second invocation re-runs the whole failure path, adding another ~2 s of real time (ANDROID_CLOSE_PROCESS_TIMEOUT_MS poll loop) to CI and duplicating identical adb mock traffic. Either extend `ExpectedAppError` with a `details` partial matcher and assert `code`+`hint`+`reason` in one `assertRejectsAppError`, or replace the double call with a single try/catch that asserts code, hint, and `details.reason` together.</comment>

<file context>
@@ -162,6 +162,151 @@ test('closeAndroidApp waits until package process exits after force-stop', async
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /Background the app before killApp/,
</file context>

[cubic-dev-ai]

P3: mockBindDeviceRuntime.mockImplementation(...) permanently replaces the shared harness mock for the rest of this file: the file's beforeEach only calls mockClear, which keeps implementations, so the wrapper (and its seenModes closure) stays installed for every subsequent test here. Such tests still pass only because the wrapper delegates to baseBind, but the shared mock is left hijacked, which silently couples this test to all later tests in the file. Restore the base implementation at the end of the test, or use two mockImplementationOnce registrations.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts, line 338:

<comment>`mockBindDeviceRuntime.mockImplementation(...)` permanently replaces the shared harness mock for the rest of this file: the file's `beforeEach` only calls `mockClear`, which keeps implementations, so the wrapper (and its `seenModes` closure) stays installed for every subsequent test here. Such tests still pass only because the wrapper delegates to `baseBind`, but the shared mock is left hijacked, which silently couples this test to all later tests in the file. Restore the base implementation at the end of the test, or use two `mockImplementationOnce` registrations.</comment>

<file context>
@@ -319,6 +319,56 @@ test('a supported Android close clears admitted runtime hints exactly once', asy
+  sessionStore.set(sessionName, session);
+  const seenModes: Array<unknown> = [];
+  const baseBind = mockBindDeviceRuntime.getMockImplementation();
+  mockBindDeviceRuntime.mockImplementation(async (boundDevice, use) => {
+    const binding = await baseBind!(boundDevice, use);
+    const innerClose = binding.operations.closeApplication;
</file context>

[cubic-dev-ai]

P3: The explicit and config app ids are the same value, so this test cannot distinguish the two paths it claims to cover: the dispatcher computes { appId: command.appId ?? request.appId }, and both commands resolve to com.example.checkout regardless of which branch is exercised. A regression that, for example, always used the config app id and dropped the explicit killApp: app id would still pass. Use a distinct explicit app id (e.g. com.example.other) and assert calls[0] receives it while calls[1] falls back to the config id.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/maestro/src/internal/__tests__/runtime-port.test.ts, line 187:

<comment>The explicit and config app ids are the same value, so this test cannot distinguish the two paths it claims to cover: the dispatcher computes `{ appId: command.appId ?? request.appId }`, and both commands resolve to `com.example.checkout` regardless of which branch is exercised. A regression that, for example, always used the config app id and dropped the explicit `killApp:` app id would still pass. Use a distinct explicit app id (e.g. `com.example.other`) and assert calls[0] receives it while calls[1] falls back to the config id.</comment>

<file context>
@@ -178,6 +178,25 @@ describe('MaestroRuntimePort', () => {
+      killApp: vi.fn(async (input, context) => record(calls, 'killApp', input, context)),
+    });
+    const program = parseMaestroProgram(
+      ['appId: com.example.checkout', '---', '- killApp: com.example.checkout', '- killApp'].join(
+        '\n',
+      ),
</file context>

[Rohit3523]

The Compatibility & Provenance → Run Fallow audit failure is pre-existing mainline drift, not introduced by this PR.

I reproduced the audit locally at this PR's head (5058165f1, base a79879) and on a clean worktree of plain main (6428c54, zero PR commits). Both fail with the identical gate-new findings, all in files this PR never touches:

• packages/platform-apple/src/runner/runner-contract.ts:40 — unused export APP_NOT_RUNNING_RUNNER_CODE (introduced by mainline fix(ios): never launch a not-running session app from an observation #2852/chore(ios-runner): remove unset env knobs, the dead back wire command, and unreachable paths #2828)
• clone dup:8d32f339 — packages/maestro/src/daemon-port/run-script-http.ts:115-130 × packages/provision-kit/src/install-source-network-transport.ts:74-89
• clone dup:be14bf95 — packages/platform-apple/src/recording/recovery.ts:115-142 × packages/platform-harmonyos/src/recording/recovery.ts:46-72

The 4 complexity hits (conformance-normalize.ts, cli/parser/args.ts) are all marked inherited — this PR only adds 2 trivial case returns to already-critical functions. This PR's own scope (pnpm check:affected) is clean.

Suggested path: the owning mainline changes address those three findings (or get path-keyed baseline updates), then a rebase turns this job green. Per repo rules I'm keeping this PR within its command-family scope and not touching those files or regenerating baselines.

[thymikee]

Following up on f894395 after the earlier evidence-pending review at 78727e3.

The kill route (packages/platform-android/src/app-lifecycle.ts#L510) is still only exercised through adb exec fakes: Maestro replay calls close with closeAppOnly+killApp, lifecycle.ts:70 calls killAndroidPackage, which does a foreground probe, am kill, waitForAndroidPackageStopped, then a pidof check. Neither this delta nor any author comment adds the emulator replay the earlier review asked for. Nobody has shown that am kill actually reaps an app that was sent to background with Home on a real emulator, or that the pidof check correctly reads a backgrounded-but-alive process. Either gap could make killApp fail with android-kill-process-survived, or report success without the process being killed. Can you run agent-device replay on an Android emulator with launchApp, pressKey Home, killApp, launchApp (stopApp: false), and paste output showing killApp succeeded, adb shell pidof <pkg> prints nothing afterward, and the relaunch was a cold start? In the same session, please also run launchApp then killApp with the app still in the foreground and paste the failure carrying reason android-kill-requires-background-app.

Not blocking, can be taken or left: the stricter isAndroidPackageProcessRunning (app-lifecycle.ts#L585) now throws android-process-probe-unavailable on any pidof hiccup, which would abort close/stopApp/relaunch paths on a single flaky probe even after force-stop already succeeded, so should a probe failure only fail the operation whose contract needs proof of death, and should closeWithoutSession's mode spread in session-close.ts#L439 get a direct test (closing with {closeAppOnly, killApp} and no stored session, asserting mode 'kill' reaches platform closeApplication) since nothing exercises it today; also the killAndroidApp re-export in mechanics.ts#L86 looks like dead leftover code with no consumer at head, and the PR body still references the old Interactor.kill design and a different tested commit, so worth cleaning up before merge.

Compatibility & Provenance ran fallow against the pre-rebase base and its findings sit in files this PR does not touch (session-test-harness.ts, runner-contract.ts, runner/index.ts, the apple/harmonyos recovery.ts pair, run-script-http.ts, install-source-network-transport.ts, args.ts); the one file this PR does touch, conformance-normalize.ts, only gets new cases in the lifecycle sub-helpers, not in the flagged canonicalizeUpstreamCommand or canonicalizeAgentCommand, so this failure looks unrelated to the change. I did not re-run the author's reproduction on main, so I can't confirm main actually reproduces the failure being fixed here. I also did not run the unit suites; the regression read above comes from reading the diff and the pre-change code, not from a run. I can't say which Android images in the fleet lack pidof or emit stderr noise from it, so the probe-hardening impact is plausible, not confirmed. And I don't know whether upstream Maestro's killApp also refuses a foreground app.

The remaining requirement before this can merge is the live Android emulator replay described above: killApp after Home must cold-kill the app (empty pidof, cold relaunch), and killApp on a foreground app must fail with android-kill-requires-background-app.