fix(test): narrow appless-session cleanup guard to the mic-permission step

Scope sessionAlreadyClean's INVALID_ARGS tolerance to the microphone-
permission reset step and its exact known message instead of matching
any cleanup step whose message contains "requires an active app in
session" — that substring is also thrown by the unrelated location
setting, so the old check could have hidden a real failure there.

Extract the per-step retry policy into an exported retryCleanupStep so
it's unit-testable without spawning the CLI, and add a deterministic
regression (test/integration/ios-simulator-e2e-cleanup.test.ts)
covering: a dead session (SESSION_NOT_FOUND) stops retrying on any
step, the known mic-permission appless response stops retrying, and a
different INVALID_ARGS (wrong step or wrong message) still exhausts
all three retries and fails.

Author: thymikee

test/integration/ios-simulator-e2e-cleanup.test.ts

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import type { CliJsonResult } from './cli-json.ts';
+import { retryCleanupStep } from './ios-simulator-e2e/live-harness.ts';
+
+// Deterministic regression for the retry/guard policy behind #1548: a full-tier iOS
+// e2e run's cleanup must tolerate a dead session and the known appless mic-permission
+// reset without swallowing an unrelated failure. `retryCleanupStep` runs the exact
+// per-step policy `cleanupSession` uses, driven here by a scripted `runAttempt` instead
+// of the real CLI subprocess, so these cases run in milliseconds with no simulator.
+
+const MIC_STEP = 'reset microphone permission';
+const OTHER_STEP = 'restore portrait orientation';
+const MIC_APPLESS_MESSAGE = 'permission setting requires an active app in session';
+
+function invalidArgsResult(message: string): CliJsonResult {
+  return { json: { error: { code: 'INVALID_ARGS', message } }, status: 1, stderr: '', stdout: '' };
+}
+
+function sessionNotFoundResult(): CliJsonResult {
+  return {
+    json: { error: { code: 'SESSION_NOT_FOUND', message: 'No active session' } },
+    status: 1,
+    stderr: '',
+    stdout: '',
+  };
+}
+
+// retryCleanupStep sleeps 500ms between attempts. Drive fake timers instead of waiting
+// real time: repeatedly flush the microtask queue and advance the mocked clock until
+// the retry promise settles.
+async function drainRetry(
+  t: { mock: { timers: { tick: (ms: number) => void } } },
+  promise: Promise<unknown>,
+): Promise<unknown> {
+  let settled = false;
+  promise.finally(() => {
+    settled = true;
+  });
+  while (!settled) {
+    await new Promise((resolve) => setImmediate(resolve));
+    t.mock.timers.tick(500);
+  }
+  return promise;
+}
+
+test('a dead session (SESSION_NOT_FOUND) skips cleanup without error, on any step', async () => {
+  let attempts = 0;
+  const failure = await retryCleanupStep(MIC_STEP, async () => {
+    attempts += 1;
+    return sessionNotFoundResult();
+  });
+  assert.equal(failure, undefined);
+  assert.equal(attempts, 1, 'should not retry once the session is confirmed gone');
+});
+
+test('the known mic-permission appless response stops retrying immediately', async () => {
+  let attempts = 0;
+  const failure = await retryCleanupStep(MIC_STEP, async () => {
+    attempts += 1;
+    return invalidArgsResult(MIC_APPLESS_MESSAGE);
+  });
+  assert.equal(failure, undefined);
+  assert.equal(attempts, 1, 'should not retry the known appless response');
+});
+
+test('a different INVALID_ARGS still fails after exhausting retries', async (t) => {
+  // Same message, wrong step: proves the guard is scoped to the mic-permission reset
+  // and does not tolerate the identical string on another step.
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  let attempts = 0;
+  const failure = await drainRetry(
+    t,
+    retryCleanupStep(OTHER_STEP, async (attempt) => {
+      attempts += 1;
+      if (attempt < 3) return invalidArgsResult(MIC_APPLESS_MESSAGE);
+      // Mirrors runStep(..., { allowFailure: false }) on the final attempt: it throws
+      // instead of returning a failed result.
+      throw new Error(`cleanup: ${OTHER_STEP} (attempt 3) failed`);
+    }),
+  );
+  assert.ok(failure instanceof Error, `expected a propagated failure, got ${String(failure)}`);
+  assert.equal(attempts, 3, 'should exhaust all three attempts');
+});
+
+test('a different INVALID_ARGS message on the mic-permission step still fails after retries', async (t) => {
+  // Same step, a message sharing the "requires an active app in session" suffix with
+  // the location-setting call site (app-settings.ts): proves the match is the exact
+  // known string, not any INVALID_ARGS message that happens to overlap it.
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  let attempts = 0;
+  const failure = await drainRetry(
+    t,
+    retryCleanupStep(MIC_STEP, async (attempt) => {
+      attempts += 1;
+      if (attempt < 3)
+        return invalidArgsResult('location setting requires an active app in session');
+      throw new Error(`cleanup: ${MIC_STEP} (attempt 3) failed`);
+    }),
+  );
+  assert.ok(failure instanceof Error, `expected a propagated failure, got ${String(failure)}`);
+  assert.equal(attempts, 3, 'should exhaust all three attempts');
+});

test/integration/ios-simulator-e2e/live-harness.ts

@@ -76,42 +76,66 @@ export function verifyNestedReplayCommand(
   harness.verifyNestedCommand(context, command, executedVia, evidence);
 }
 
+// Shared between the step list and the guard below so the two can't drift apart.
+const MICROPHONE_PERMISSION_RESET_STEP = 'reset microphone permission';
+
 export async function cleanupSession(context: LiveContext): Promise<void> {
   const failures: unknown[] = [];
   const cleanupSteps: Array<[string, string[]]> = [];
   if (context.tier === 'full') {
     cleanupSteps.push(
-      ['reset microphone permission', ['settings', 'permission', 'reset', 'microphone']],
+      [MICROPHONE_PERMISSION_RESET_STEP, ['settings', 'permission', 'reset', 'microphone']],
       ['restore light appearance', ['settings', 'appearance', 'light']],
       ['restore portrait orientation', ['orientation', 'portrait']],
     );
   }
   cleanupSteps.push(['close fixture session', ['close']]);
   for (const [step, args] of cleanupSteps) {
-    for (let attempt = 1; attempt <= 3; attempt += 1) {
-      try {
-        const result = await runStep(context, `cleanup: ${step} (attempt ${attempt})`, args, {
-          allowFailure: attempt < 3,
-        });
-        if (result.status === 0 || sessionAlreadyClean(result)) break;
-        await new Promise((resolve) => setTimeout(resolve, 500));
-      } catch (error) {
-        failures.push(error);
-        break;
-      }
-    }
+    const failure = await retryCleanupStep(step, (attempt) =>
+      runStep(context, `cleanup: ${step} (attempt ${attempt})`, args, {
+        allowFailure: attempt < 3,
+      }),
+    );
+    if (failure !== undefined) failures.push(failure);
   }
   if (failures.length === 0) return;
   const errorPath = path.join(context.artifactDir, 'cleanup-error.txt');
   fs.writeFileSync(errorPath, failures.map(String).join('\n\n'));
   throw new AggregateError(failures, `iOS E2E cleanup failed; details: ${errorPath}`);
 }
 
-// A dead or appless session has nothing left to reset: the simulator reboot in
-// full:device-lifecycle kills the session in some environments but not others.
-function sessionAlreadyClean(result: CliJsonResult): boolean {
+/**
+ * Runs one cleanup step's 3-attempt retry policy: success or an already-clean session
+ * stops immediately, anything else waits and retries. `runAttempt` mirrors the real
+ * `runStep(..., { allowFailure: attempt < 3 })` contract, including that the final
+ * attempt throws instead of returning a failed result. Exported so the retry/guard
+ * behavior is unit-testable without spawning the CLI (see
+ * `test/integration/ios-simulator-e2e-cleanup.test.ts`).
+ */
+export async function retryCleanupStep(
+  step: string,
+  runAttempt: (attempt: number) => Promise<CliJsonResult>,
+): Promise<unknown> {
+  for (let attempt = 1; attempt <= 3; attempt += 1) {
+    try {
+      const result = await runAttempt(attempt);
+      if (result.status === 0 || sessionAlreadyClean(step, result)) return undefined;
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    } catch (error) {
+      return error;
+    }
+  }
+  return undefined;
+}
+
+// SESSION_NOT_FOUND: nothing left to reset, any step. INVALID_ARGS: only the
+// mic-permission reset needs an app bundle and app-settings.ts has no reason code for
+// it, so we match its exact message — scoped to this step so it can't hide another failure.
+function sessionAlreadyClean(step: string, result: CliJsonResult): boolean {
+  if (result.json?.error?.code === 'SESSION_NOT_FOUND') return true;
   return (
-    result.json?.error?.code === 'SESSION_NOT_FOUND' ||
-    String(result.json?.error?.message ?? '').includes('requires an active app in session')
+    step === MICROPHONE_PERMISSION_RESET_STEP &&
+    result.json?.error?.code === 'INVALID_ARGS' &&
+    result.json?.error?.message === 'permission setting requires an active app in session'
   );
 }