Merge pull request #37 from Lykhoyda/fix/b119-runner-leak-recovery

fix(b119): detect + auto-recover from agent-device runner leak (GH #35)

Author: Lykhoyda

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "rn-dev-agent",
       "description": "AI agent that fully tests React Native features on simulator/emulator — navigates the app, verifies UI, walks user flows, and confirms internal state.",
-      "version": "0.25.0",
+      "version": "0.25.1",
       "source": "./",
       "category": "mobile-development",
       "homepage": "https://github.com/Lykhoyda/rn-dev-agent"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rn-dev-agent",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "AI agent that fully tests React Native features on simulator/emulator — navigates the app, verifies UI, walks user flows, and confirms internal state.",
   "author": {
     "name": "Anton Lykhoyda",

scripts/cdp-bridge/dist/tools/device-interact.js

@@ -5,6 +5,8 @@ import { isFastRunnerAvailable, fastSwipe } from '../fast-runner-session.js';
 import { withSession } from '../utils.js';
 import { okResult, failResult } from '../utils.js';
 import { runMaestroInline, yamlEscape } from '../maestro-invoke.js';
+import { isAgentDeviceRunnerSentinel, recoverFromRunnerLeak } from './runner-leak-recovery.js';
+import { reopenSessionForRecovery } from './device-session.js';
 const execFile = promisify(execFileCb);
 const ANDROID_UNSAFE_CHARS = /[+@#$%^&*(){}|\\<>~`[\]?*]/;
 const ANDROID_FILL_MAX_SAFE_LEN = 30;
@@ -18,30 +20,54 @@ function candidateFromNode(n) {
         position: n.rect ? { x: n.rect.x, y: n.rect.y } : undefined,
     };
 }
-async function fetchSnapshotNodes() {
+function parseSnapshotEnvelope(result) {
+    if (result.isError)
+        return null;
     try {
-        const snapshotResult = await runAgentDevice(['snapshot', '-i']);
-        if (snapshotResult.isError)
-            return null;
-        const envelope = JSON.parse(snapshotResult.content[0].text);
+        const envelope = JSON.parse(result.content[0].text);
         if (!envelope.ok || !envelope.data?.nodes)
             return null;
-        const nodes = envelope.data.nodes;
-        const platform = getActiveSession()?.platform;
-        if (platform)
-            cacheSnapshot(platform, nodes);
-        return nodes;
+        return envelope.data.nodes;
     }
     catch {
         return null;
     }
 }
+async function fetchSnapshotNodes() {
+    const first = await runAgentDevice(['snapshot', '-i']);
+    const initialNodes = parseSnapshotEnvelope(first);
+    if (initialNodes === null)
+        return { ok: false, reason: 'fetch-failed' };
+    if (!isAgentDeviceRunnerSentinel(initialNodes)) {
+        const platform = getActiveSession()?.platform;
+        if (platform)
+            cacheSnapshot(platform, initialNodes);
+        return { ok: true, nodes: initialNodes };
+    }
+    const session = getActiveSession();
+    const recovery = await recoverFromRunnerLeak({ platform: session?.platform, appId: session?.appId, sessionName: session?.name }, {
+        closeSession: () => runAgentDevice(['close']),
+        openSession: ({ appId, platform, attachOnly }) => reopenSessionForRecovery(appId, platform, attachOnly),
+        resnapshot: () => runAgentDevice(['snapshot', '-i']),
+        parseNodes: parseSnapshotEnvelope,
+    });
+    if (!recovery.recovered) {
+        return { ok: false, reason: 'runner-leak-unrecovered', recoveryReason: recovery.reason };
+    }
+    const recoveredNodes = parseSnapshotEnvelope(recovery.result);
+    if (recoveredNodes === null)
+        return { ok: false, reason: 'fetch-failed' };
+    const platform = getActiveSession()?.platform;
+    if (platform)
+        cacheSnapshot(platform, recoveredNodes);
+    return { ok: true, nodes: recoveredNodes, recoveredTier: recovery.tier };
+}
 async function fetchFindCandidates(query, exact) {
-    const nodes = await fetchSnapshotNodes();
-    if (!nodes)
-        return null;
+    const snap = await fetchSnapshotNodes();
+    if (!snap.ok)
+        return snap;
     const needle = query.toLowerCase();
-    return nodes
+    const candidates = snap.nodes
         .filter((n) => {
         const label = n.label ?? '';
         const id = n.identifier ?? '';
@@ -51,6 +77,15 @@ async function fetchFindCandidates(query, exact) {
     })
         .slice(0, 10)
         .map(candidateFromNode);
+    return { ok: true, candidates, recoveredTier: snap.recoveredTier };
+}
+function runnerLeakFailResult(query, recoveryReason) {
+    const queryHint = query ? ` (while resolving "${query}")` : '';
+    return failResult(`device_find/snapshot returned AgentDeviceRunner's own UI tree instead of the target app${queryHint} (B119 / GH #35 — agent-device daemon dropped appBundleId on dispatch). Auto-recovery did not restore the target.`, {
+        code: 'RUNNER_LEAK',
+        recoveryReason,
+        hint: 'Manually close + reopen the session with device_snapshot action=open appId=<your.bundle.id> platform=ios (full launch, not attachOnly). The recovery may have killed the JS context — re-establish CDP via cdp_connect before reading state. Upstream: Callstack/agent-device, see B119/GH#35.',
+    });
 }
 async function pressCandidate(candidate, action) {
     const ref = candidate.ref.startsWith('@') ? candidate.ref : `@${candidate.ref}`;
@@ -59,31 +94,50 @@ async function pressCandidate(candidate, action) {
     }
     return okResult({ ref: candidate.ref, label: candidate.label, testID: candidate.testID });
 }
+// B119: when an underlying snapshot triggered runner-leak recovery, surface
+// that side-effect on the wrapping result so callers (LLM agents) know the
+// app may have been relaunched and CDP/state may have been invalidated.
+function tagPressIfRecovered(result, tier) {
+    if (!tier || result.isError)
+        return result;
+    try {
+        const envelope = JSON.parse(result.content[0].text);
+        envelope.meta = { ...envelope.meta, recovered: 'agent-device-runner-leak', recoveryTier: tier };
+        return { content: [{ type: 'text', text: JSON.stringify(envelope) }] };
+    }
+    catch {
+        return result;
+    }
+}
 export function createDeviceFindHandler() {
     return withSession(async (args) => {
         // Fast path when caller already knows they want exact or a specific index:
         // go straight to a snapshot-based client-side match so we never roll the dice
         // on agent-device's fuzzy matcher returning AMBIGUOUS_MATCH.
         if (args.exact === true || args.index !== undefined) {
-            const candidates = await fetchFindCandidates(args.text, args.exact === true);
-            if (candidates === null) {
+            const find = await fetchFindCandidates(args.text, args.exact === true);
+            if (!find.ok) {
+                if (find.reason === 'runner-leak-unrecovered') {
+                    return runnerLeakFailResult(args.text, find.recoveryReason);
+                }
                 // Snapshot failed and caller has strict requirements — do NOT fall through
                 // to the fuzzy agent-device path because it cannot honor exact/index. Fail
                 // cleanly so the caller knows exact/index semantics aren't reachable.
                 return failResult(`Snapshot unavailable — cannot resolve ${args.exact ? 'exact' : 'index-based'} match for "${args.text}". Retry after device_snapshot action=open/snapshot.`, { code: 'SNAPSHOT_UNAVAILABLE', query: args.text });
             }
+            const { candidates, recoveredTier } = find;
             if (candidates.length === 0) {
                 return failResult(`No element matches "${args.text}" (exact=${args.exact === true})`, { code: 'NOT_FOUND', query: args.text });
             }
             if (args.index !== undefined) {
                 if (args.index < 0 || args.index >= candidates.length) {
                     return failResult(`index ${args.index} out of range (got ${candidates.length} candidates)`, { code: 'INDEX_OUT_OF_RANGE', count: candidates.length, candidates });
                 }
-                return pressCandidate(candidates[args.index], args.action);
+                return tagPressIfRecovered(await pressCandidate(candidates[args.index], args.action), recoveredTier);
             }
             // exact=true, no index: require single match
             if (candidates.length === 1) {
-                return pressCandidate(candidates[0], args.action);
+                return tagPressIfRecovered(await pressCandidate(candidates[0], args.action), recoveredTier);
             }
             return failResult(`AMBIGUOUS_MATCH: exact "${args.text}" matched ${candidates.length} elements`, { code: 'AMBIGUOUS_MATCH', query: args.text, candidates, hint: 'Add index: N to pick one.' });
         }
@@ -95,8 +149,12 @@ export function createDeviceFindHandler() {
         if (result.isError) {
             const text = result.content?.[0]?.text ?? '';
             if (text.includes('AMBIGUOUS_MATCH') || (text.includes('matched') && text.includes('elements'))) {
-                const candidates = await fetchFindCandidates(args.text, false);
-                if (candidates) {
+                const find = await fetchFindCandidates(args.text, false);
+                if (!find.ok && find.reason === 'runner-leak-unrecovered') {
+                    return runnerLeakFailResult(args.text, find.recoveryReason);
+                }
+                if (find.ok) {
+                    const candidates = find.candidates;
                     return failResult(`AMBIGUOUS_MATCH: "${args.text}" matched ${candidates.length} elements. Use device_press with one of these refs, or retry with index: N.`, {
                         code: 'AMBIGUOUS_MATCH',
                         query: args.text,
@@ -455,10 +513,14 @@ export function createDeviceFocusNextHandler() {
         // Benchmark data: 4 serial finds = 10-22s on no-keyboard case; single
         // snapshot = 3-5s on the same case. Also more reliable — one accessibility
         // query races keyboard animations less than four sequential queries.
-        const nodes = await fetchSnapshotNodes();
-        if (!nodes) {
+        const snap = await fetchSnapshotNodes();
+        if (!snap.ok) {
+            if (snap.reason === 'runner-leak-unrecovered') {
+                return runnerLeakFailResult(undefined, snap.recoveryReason);
+            }
             return failResult('Snapshot unavailable — cannot look for keyboard key. Retry after device_snapshot action=open/snapshot.', { code: 'SNAPSHOT_UNAVAILABLE' });
         }
+        const { nodes, recoveredTier } = snap;
         for (const label of NEXT_KEY_LABELS) {
             const match = nodes.find((n) => n.label === label);
             if (!match)
@@ -468,7 +530,12 @@ export function createDeviceFocusNextHandler() {
                 continue; // Match found but tap failed — try next label
             try {
                 const envelope = JSON.parse(pressResult.content[0].text);
-                return okResult(envelope.data, { meta: { keyUsed: label, ref: match.ref } });
+                const meta = { keyUsed: label, ref: match.ref };
+                if (recoveredTier) {
+                    meta.recovered = 'agent-device-runner-leak';
+                    meta.recoveryTier = recoveredTier;
+                }
+                return okResult(envelope.data, { meta });
             }
             catch {
                 return pressResult;

scripts/cdp-bridge/dist/tools/device-session.js

@@ -4,6 +4,7 @@ import { runAgentDevice, setActiveSession, clearActiveSession, getActiveSession,
 import { stopFastRunner } from '../fast-runner-session.js';
 import { okResult, failResult, warnResult } from '../utils.js';
 import { resolveBundleId } from '../project-config.js';
+import { isAgentDeviceRunnerSentinel, recoverFromRunnerLeak, } from './runner-leak-recovery.js';
 const execFile = promisify(execFileCb);
 /**
  * B112 (D641): check whether a given bundleId is currently running on the
@@ -103,6 +104,7 @@ export function createDeviceSnapshotHandler() {
                     platform: args.platform,
                     deviceId,
                     openedAt: new Date().toISOString(),
+                    appId,
                 });
                 if (args.platform === 'ios' && deviceId) {
                     ensureFastRunner(deviceId, appId).catch(() => { });
@@ -129,17 +131,125 @@ export function createDeviceSnapshotHandler() {
         if (!getActiveSession()) {
             return failResult('No device session open. Call device_snapshot with action="open" first.', { hint: 'Provide appId and platform to start a session.' });
         }
-        const result = await runAgentDevice(['snapshot', '-i']);
-        if (!result.isError) {
-            try {
-                const envelope = JSON.parse(result.content[0].text);
-                const platform = getActiveSession()?.platform;
-                if (platform && envelope.ok && envelope.data?.nodes) {
-                    cacheSnapshot(platform, envelope.data.nodes);
-                }
+        const result = await rawSnapshot();
+        const nodes = parseSnapshotNodes(result);
+        if (!result.isError && nodes && isAgentDeviceRunnerSentinel(nodes)) {
+            const session = getActiveSession();
+            const recovery = await recoverFromRunnerLeak({ platform: session?.platform, appId: session?.appId, sessionName: session?.name }, {
+                closeSession: () => runAgentDevice(['close']),
+                openSession: ({ appId, platform, attachOnly }) => reopenSessionForRecovery(appId, platform, attachOnly),
+                resnapshot: () => rawSnapshot(),
+                parseNodes: parseSnapshotNodes,
+            });
+            if (recovery.recovered) {
+                cacheSnapshotIfPossible(recovery.result);
+                return wrapWithMeta(recovery.result, {
+                    recovered: 'agent-device-runner-leak',
+                    recoveryTier: recovery.tier,
+                });
             }
-            catch { /* best-effort cache */ }
+            return failResult(runnerLeakFailureMessage(recovery.reason, session), {
+                code: 'RUNNER_LEAK',
+                recoveryReason: recovery.reason,
+                hint: runnerLeakFailureHint(recovery.reason, session),
+            });
         }
+        cacheSnapshotIfPossible(result);
         return result;
     };
 }
+export function runnerLeakFailureMessage(reason, session) {
+    if (reason === 'no-session-context' && session && !session.appId) {
+        return 'device_snapshot returned AgentDeviceRunner\'s own UI tree, but auto-recovery cannot run because the active session has no stored appId. This usually means the session was opened by a plugin version from before B119 / GH #35 landed.';
+    }
+    return 'device_snapshot returned AgentDeviceRunner\'s own UI tree instead of the target app (B119 / GH #35 — agent-device daemon dropped appBundleId on dispatch). Auto-recovery did not restore the target.';
+}
+export function runnerLeakFailureHint(reason, session) {
+    if (reason === 'no-session-context' && session && !session.appId) {
+        return 'Run device_snapshot action=close, then action=open appId=<your.bundle.id> platform=ios to start a session that supports auto-recovery.';
+    }
+    return 'Manually close + reopen the session with action=open appId=<your.bundle.id> platform=ios (full launch, not attachOnly). Upstream: Callstack/agent-device, see B119/GH#35.';
+}
+async function rawSnapshot() {
+    return runAgentDevice(['snapshot', '-i']);
+}
+function parseSnapshotNodes(result) {
+    if (result.isError)
+        return null;
+    try {
+        const envelope = JSON.parse(result.content[0].text);
+        if (!envelope.ok || !envelope.data?.nodes)
+            return null;
+        return envelope.data.nodes;
+    }
+    catch {
+        return null;
+    }
+}
+function cacheSnapshotIfPossible(result) {
+    if (result.isError)
+        return;
+    try {
+        const envelope = JSON.parse(result.content[0].text);
+        const platform = getActiveSession()?.platform;
+        if (platform && envelope.ok && envelope.data?.nodes) {
+            cacheSnapshot(platform, envelope.data.nodes);
+        }
+    }
+    catch { /* best-effort cache */ }
+}
+function wrapWithMeta(result, meta) {
+    if (result.isError)
+        return result;
+    try {
+        const envelope = JSON.parse(result.content[0].text);
+        envelope.meta = { ...envelope.meta, ...meta };
+        return { content: [{ type: 'text', text: JSON.stringify(envelope) }] };
+    }
+    catch {
+        return result;
+    }
+}
+export async function reopenSessionForRecovery(appId, platform, attachOnly) {
+    // Always mint a fresh recovery name (Gemini G3): reusing the original
+    // session name risks the daemon either rejecting as "already exists" or
+    // silently re-attaching to the corrupted session, defeating the rebuild.
+    const recoveryName = `rn-agent-recovery-${Date.now()}`;
+    let cliArgs;
+    if (attachOnly) {
+        // attachOnly only makes sense if the target app is already running.
+        // Otherwise there's nothing to attach to and we should let the caller
+        // escalate (typically to the full-relaunch tier).
+        const running = await isAppRunning(platform, appId);
+        if (!running) {
+            return failResult(`attachOnly recovery aborted: ${appId} is not running on ${platform}.`, { code: 'NOT_CONNECTED', recoveryAbort: true });
+        }
+        cliArgs = ['open', '--session', recoveryName, '--platform', platform];
+    }
+    else {
+        cliArgs = ['open', appId, '--session', recoveryName, '--platform', platform];
+    }
+    const result = await runAgentDevice(cliArgs, { skipSession: true });
+    if (result.isError)
+        return result;
+    let deviceId;
+    try {
+        const envelope = JSON.parse(result.content[0].text);
+        const data = envelope?.data;
+        const rawId = data?.deviceId
+            ?? data?.device_udid
+            ?? data?.id
+            ?? (typeof data?.device === 'object' ? data?.device?.id : undefined);
+        const UDID_RE = /^[0-9A-Fa-f-]{25,}$/;
+        deviceId = typeof rawId === 'string' && UDID_RE.test(rawId) ? rawId : undefined;
+    }
+    catch { /* best-effort */ }
+    setActiveSession({
+        name: recoveryName,
+        platform,
+        deviceId,
+        openedAt: new Date().toISOString(),
+        appId,
+    });
+    return result;
+}