fix(flow): raise the flow tree's depth cap and say why targeting failed

[hubgan]

Stacked on #720.

Depth cap: 40 → 100

The flow selector tree capped raw UIView nesting at 40. That does not clear the invisible wrapper layers React Native stacks on every screen — nested navigators (RNSScreenStackView → RNSScreenView, often two deep) plus a drawer/root wrapper routinely bury on-screen content 40–60 levels down before the first tappable view.

In a deeply nested production app, plainly visible interactive elements sat at depths 41–62. So id: and text: selectors silently failed to resolve, and only coordinate taps worked — which is the origin of coordinate-heavy flows on those apps.

The overflow is silent: nothing reports "truncated", selectors just stop matching. So the new cap carries generous headroom rather than hugging the deepest observed measurement.

What it costs. The tree itself is internal to selector resolution — consumed by selectorToFrame/evaluateCondition, never returned — so no tool result carries it. Text derived from it does reach the agent, though: assertReason's text arm quotes the matched node's hoisted subtreeText verbatim into a failing assert/await reason, and nothing truncates it downstream. Descendants a depth-40 read dropped now hoist, so that quoted string grows with the cap — and on one arm compatibilityMissNote quotes the same hoisted string a second time, doubling the rate. That is the trade — under the old cap those selectors did not resolve at all. Otherwise the cap only grows the getFullHierarchy payload over the native-devtools socket, which is already field-limited: ~11KB at depth 40, ~15KB at 48, and nothing at all past the tree's real depth.

Targeting errors that could not be acted on

Provide bundleId explicitly — resolveNativeTargetApp's own errors close with that advice. A flow selector step cannot follow it: the call hardcodes auto-targeting. Each failure now carries the remedy that actually exists:

• ambiguous connected set — foreground the intended app with launch-app (which does not terminate, so the instrumentation it already has survives), and clear the others with xcrun simctl terminate (argent exposes no terminate tool, and restart-app would just bring that app back to the front). The command is addressed to the device's own CoreSimulator set, so it resolves for a simulator from a configured ios.additionalDeviceSets.
• a lone connected app that is not foreground — same foreground remedy; it is already instrumented, so a relaunch would only discard state.
• the state probe failed while connections are live — do not relaunch; the apps are instrumented and a suspended one simply stopped answering.
• no connected app — this is the one state a relaunch fixes, through restart-app or a flow launch step.

launch-app, or a flow launch step — this was wrong in a way that wastes a cycle. launch-app does not terminate first, so against an app already running from Metro/Expo, Xcode, or its home-screen icon it only foregrounds that same uninstrumented process, and the next read fails identically. Only restart-app (terminate + relaunch) guarantees an instrumented launch whatever was already running.

These reasons are repeated per step — the recorder embeds one in the warning for every captured tap, and a failing await: repeats it per poll — so the two that enumerate connected apps are capped at two entries plus a count of what was left out, and the whole set is held under a documented ceiling by a test that iterates every branch.

FailureError data is preserved when these messages wrap an underlying error, so the failure code still reaches callers that switch on it.

Launch gate: same wait for every bundle, different fallback

Argent treats an Apple system app as non-injectable and guarantees it nothing — but it does not follow that one never connects. On iOS 18.3 and 26.5 simulators, Preferences/Maps/Contacts/Health/Photos and Safari all connect after the restart-app a launch step runs, and a flow assert against the view hierarchy passes: the simulator applies no library validation, so the injected dylib does load.

So the gate waits for every bundle. That wait is also what ties the launched bundle to the app a later selector step auto-targets — resolveNativeTargetApp(api, undefined) never compares the two — so skipping it per bundle could hand the next step a different app's hierarchy and still report the run green.

Only the fallback advice differs. For an injectable bundle the suspect is a stale or duplicate argent server holding the connection. For a com.apple.* one that keeps failing, the launch directive itself is what stops the run, so the remedy names the edit that gets past it: replace it with a raw tool: restart-app step (same terminate + relaunch, dispatched through the registry without the gate) and drive the app with point taps and tool: await-ui-element steps, which read the AX tree instead of selectors.

[j-piasecki]

Adversarial pass over the three changes (depth cap, targeting messages, launch gate skip). The substance holds up under the checks I could actually run:

• restart-app / launch-app take the 2-arg precheckNativeDevtools, so a com.apple.* launch step really does execute rather than throwing at the precheck — the gate skip is reachable.
• describeIos reads the ax-service first and only falls back to native-devtools on an empty tree, so the "raw point taps + tool: await-ui-element" story for a system app is real, not aspirational.
• launch-app is simctl launch with no terminate, and the recorder only rewrites restart-app into a launch: step (flow-add-step.ts:1067) — the SKILL.md wording and the error-message advice both match the code.
• withoutExplicitBundleIdAdvice matches both wordings resolveNativeTargetApp emits, firstClause leaves a dotted identifier intact, and getFailureSignal's BFS keeps the code reaching callers either way.
• Typecheck and prettier are clean; test/flows/ is green.

Two findings survive, both about the new tests' coverage rather than the shipped behaviour.

[latekvo]

[Diplomat]: Reviewed on 588c68bb. I built the branch and drove the real flow-execute, flow-start-recording and flow-add-step tools through a real Registry against the built dist, faking only the device/service seam with a NativeDevtools blueprint that truncates its subtree the way the on-device serializer does. vitest run in packages/tool-server is green apart from test/ios-instruments/malloc-stack-logging.test.ts, which timed out under parallel load and is unrelated to this diff.

The depth raise itself checks out end to end: with the device serving a view at raw depth 45, tap: { id: deep-button } resolves and dispatches gesture-tap at the button's centre (0.5, 0.525); the same fixture read at a device cap of 40 fails to resolve. I also checked the recorder claim that the raise weakens captured selectors and could not sustain it - a shallow app with the same testID-host-plus-<Text>-child shape already records {text: "Submit"} at cap 40, so the {identifier} capture in a deep tree was the truncation artifact, not a baseline the raise regresses.

[latekvo]

[Diplomat]: "Returns null when ready" no longer holds for the skipped bundle: nothing on this path establishes that the app was launched at all.

restart-app's iOS handler returns - rather than throws - {status: "init_failed", …} when precheckNativeDevtools(nativeDevtools, udid) blocks, and that return happens before any simctl terminate / simctl launch (restart-app/platforms/ios.ts:36-44; RestartAppResult in restart-app/types.ts includes NativeDevtoolsInitFailedResult). runLaunch discards the value. The block is reachable from a single ensureEnvReady() rejection - the tool's own remedy text ("re-boot the simulator, or restart CoreSimulatorService") concedes it happens on working machines. A repo-wide grep finds init_failed handled only inside the native-devtools/* tools, nowhere on the flow path.

Reproduced through the real flow-execute, with restart-app returning the blocked result its real handler returns:

A) com.apple.* + restart-app BLOCKED   tools called: restart-app, gesture-tap
   steps: launch:pass, tap:pass | ok: true          <- never terminated or launched
B) injectable  + restart-app BLOCKED   tools called: restart-app
   steps: launch:error, tap:skip | ok: false

This lands on the flow shape the skip exists to enable: raw point taps plus tool: steps have no selector step that would fail later, so the run reports ok: true against whatever screen the simulator happened to be showing. The discarded-result gap itself predates the PR, but on iOS the gate masked it for every bundle until now.

[hubgan]

Not fixed here, and not introduced here. runLaunch discarding restart-app's init_failed return predates this branch - the same discard is on the base commit - and with 77c112c the gate runs for every bundle again, so this PR no longer changes what is exposed. Worth its own issue rather than a fix folded into this one.

[j-piasecki]

Checked on cac4fc5c:

• launch-app does not terminate. launch-app/platforms/ios.ts:38 runs simctl launch only; restart-app/platforms/ios.ts:39-44 runs terminate then launch. Both build argv through simctlArgsForUdid, so the --set-aware terminate command the reasons hand out is the same shape argent itself issues.
• argent has no terminate tool. 73 registered tool ids across src/tools; nothing matching terminate/kill/quit. The only stop-* are stop-metro, stop-simulator-server, stop-all-simulator-servers and the profiler/recording stops.
• the native-devtools feature tools refuse it too. NON_INJECTABLE_NATIVE_WARNING (blueprints/native-devtools.ts:53) enumerates exactly the six that throw; native-devtools-status runs the 2-arg precheck and the native-profiler-* tools do not precheck.
• tool: await-ui-element reads the AX tree. await-ui-element/index.ts:284 calls describeIos, whose non-injectable gate (describe/platforms/ios/index.ts:135) returns the ax-service tree with a hint rather than failing.
• The requiresAppRestart branch is only a disconnect race. listConnectedBundleIds is [...connections.keys()] and requiresAppRestart returns false for anything in connections (blueprints/native-devtools.ts:646, :649), so the app was instrumented and the new wording is the only one that fits.
• Device-wide DYLD / nextLaunchWillBeInjected. native-devtools-status.ts:127 reports nextLaunchWillBeInjected: envSetup, matching the SKILL.md parenthetical.
• selectorMissNote never touches subtreeText. ui-tree-match.ts:767-769 collects label and value only, so the cost note's carve-out for the exists/visible arm holds.
• The reason budget holds on every branch. Driven through the real queryFullHierarchyTree for all eight throw sites plus the service-unresolvable wrap, bundle ids 37 chars:

branch	1 app	2 apps	4 apps
ambiguous connected set	(resolves as single)	702	729
single app not foreground	555	555	555
state probe failed, connections live	359	560	570
no connected app	594	594	594
target requires a restart	359	359	359
no windows	232	232	232
getFullHierarchy errored	82	82	82
service unresolvable	134	134	134

Worst case 729 against MAX_TARGETING_REASON_CHARS 760; 2 → 4 apps costs only the (+N more connected apps) line. "Every other branch has well over 100 chars of slack" holds — tightest is no connected app at 166.

• Local state: test/flows/ 1065/1065, full tool-server suite 3875 passed / 1 skipped, tsc --noEmit -p tsconfig.test.json clean, prettier --check clean on all eight changed files. gates a com.apple.* launch on the connection like any other iOS bundle measures 9536 ms against its explicit 15000 ms budget; next slowest in that file is 1508 ms.

Nothing survived to an inline comment.