Skip to content

fix(contracts): pair open runtime hints with their apply operation - #4754

Merged
thymikee merged 2 commits into
mainfrom
t3/q3-runtime-hints-invariant
Nov 19, 2026
Merged

thymikee merged 2 commits into
mainfrom
t3/q3-runtime-hints-invariant

Conversation

@thymikee

@thymikee thymikee commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Summary

Fixes #4408's class of bug at the owning type. The invariant "runtime hints are optional only when no transport hint is requested" was prose-only on OpenApplicationInput, so three producers threw reason: 'runtime-hints-operation-missing' without dispatched, forcing a consumer reason exclusion in session-open-execution.ts.

OpenApplicationInput.runtimeHints is now one optional field, OpenApplicationRuntimeHints, pairing the requested values with the fact-admitted apply callback — a hints request cannot exist without its transport. The daemon pairs them via openApplicationRuntimeHints (session-runtime.ts); the Apple/Android throw sites are deleted (facts admission already refuses the open earlier, so the unadmitted state is unconstructible). The clear-hints refusal in session-open-prepare.ts sets dispatched: 'no', so the relaunch catch keys only on the dispatch disclosure. 17 files touched.

BEFORE: prose + 3 producer throw sites + 1 consumer reason exclusion. AFTER: one typed pairing at the contract. The input is not plugin-exposed (ADR 0034) and not on the wire surface, so no digest or protocol change.

SIZE: +21 net lines; removes 2 throw sites + 1 exclusion clause, adds one typed declaration. PERF: none. COLLOCATION: the invariant moves from prose + 3 producers + 1 consumer into one typed declaration at the owning contract.

Validation

Tested SHA: d585a237f9a9c9e4306f6944ef82d042669b121a (base e766e8890f). Focused vitest all pass (session-open runtime/relaunch, contracts, apple/android lifecycle, expo, limrun, revyl, wire-compat: 694 tests). pnpm check:quick and pnpm check:layering pass; pnpm format before commit.

pnpm check:affected --run --head d585a237f9... receipt (exactCommit: true): format, lint, typecheck, layering, fallow, build, vitest-related passed; unit failed; CI lanes skipped as GitHub-authoritative. Base-blocked: unit fails only in release-publish, fuzz/harness, macos-helper-package-contents, release-assets tests (5s timeouts under concurrent gate load from other worktrees); the same 4 files fail identically on unchanged base e766e8890f, and depgraph shows no path from the changed files to them. Not looped per testing.md. CI owns coverage/smoke/replay/provider lanes; re-read unit there. Unresolved risks: none for the change itself.

The invariant "runtime hints are optional only when no transport hint is
requested" existed only as prose on OpenApplicationInput, so three producers
threw reason 'runtime-hints-operation-missing' without setting dispatched,
forcing a consumer-side reason exclusion in session-open-execution.

OpenApplicationInput.runtimeHints is now one optional field pairing the
requested values with the fact-admitted apply callback
(OpenApplicationRuntimeHints), so a hints request cannot exist without its
transport. The daemon producer pairs them in session-runtime; the Apple and
Android lifecycle throw sites are deleted because the type makes the
unadmitted state unconstructible (facts admission already refuses the open
earlier). The clear-hints refusal in session-open-prepare sets
dispatched: 'no' (it fires before any native effect), so the relaunch catch
keys only on the dispatch disclosure and needs no reason-based exclusion.

OpenApplicationInput is in-process only: it is absent from the wire-compat
surface and from the agent-device/plugins type-only contract (ADR 0034),
so no wire digest or plugin shape moves.
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.41 MB 6.41 MB -3.1 kB
Package (unpacked) 6.41 MB 6.41 MB -3.1 kB
Package (download) 1.95 MB 1.95 MB -984 B

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 33.1 ms 34.4 ms +1.2 ms
CLI --help 70.9 ms 59.5 ms -11.3 ms

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

The pairing change in d585a23 looks right, but the changed hint-apply route has no live run yet. All 18 checks pass at this head, and there are no conflicts. Before merge, we need that live run.

The PR changes the native hint-apply step of app open on Android (lifecycle.ts:124) and on Apple (lifecycle.ts:255-269 and expo-dev-client-launch.ts). The PR body reports only mocked unit tests. The daemon tests replace the platform lifecycle with a fixture, and no Android lifecycle test passes runtimeHints. A mistake in the new presence gate or in the arguments to apply would show up only as hints silently not landing on a real open. Please run the checkout-built CLI (pnpm build, pnpm clean:daemon, node bin/agent-device.mjs) on one Android emulator and one iOS simulator, with a transport hint on open <app> (open --help shows the exact flags). On Android, open an app with a Metro host and port, with and without --relaunch. Show that the open succeeds, that timing carries runtimeHintsDurationMs, and that the host write is visible (the applied debug_http_host pref or its equivalent). On the iOS simulator, take the non-dev-client path, where resolveDevClientLaunchUrl returns undefined, so runtimeHints.apply runs, and show the hints land. Also show that a launchUrl-only open and a plain open apply nothing. Please record the commands, device, daemon version and head SHA in the PR.

Not blocking, and you can take or leave these: (1) openApplicationRuntimeHints returns undefined when apply is missing, even if the open asks for transport hints, so the unpaired state still exists one layer up in completeOpenCommand and openNewSessionWithDeviceClaim. The builder could state the rule itself: transport hints without apply is a caller bug and must refuse, or the admission result could carry the pair as one value. (2) The dispatched: 'no' line and its comment in session-open-prepare.ts:189 rest on removing a consumer exclusion that never covered this throw, and prepareApplicationOpen may already have booted a device. Could you drop the line, or state why it is correct? (3) The Apple test re-declares the daemon producer rule inline, so the shipped builder is not exercised; passing the pair directly per case would fix that.

…ispatch disclosure

Review follow-ups on the runtime-hints pairing:
- openApplicationRuntimeHints now refuses transport hints without the
  fact-admitted apply operation as a caller bug (dispatched: 'no', thrown
  while building the open input, before any dispatch) instead of silently
  dropping the request one layer up.
- The clear-hints refusal in session-open-prepare now discloses
  dispatched: 'unknown': prepareApplicationOpen above may already have
  booted the device, a device-reaching step, so 'no' would overstate.
- lifecycle-expo-dev-client.test passes the { values, apply } pair
  directly per case instead of re-declaring the producer rule inline.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
@thymikee

Copy link
Copy Markdown
Member Author

Review follow-ups applied + live device verification (head c7f36a9cb9)

Recommended items (all applied in c7f36a9cb9)

  1. openApplicationRuntimeHints no longer silently drops an unpaired request (packages/daemon/src/sessions/session-runtime.ts:64). Transport hints requested without the fact-admitted apply now throw AppError reason: 'runtime-hints-operation-missing', dispatched: 'no' at the builder — before any dispatch, so 'no' is honest and the relaunch consumer keys only on the disclosure. Covered by 3 new unit tests in session-runtime.test.ts (pair returned; absent without transport hints; refusal details).
  2. dispatched: 'no' corrected to 'unknown' on the clear-hints refusal in session-open-prepare.ts. prepareApplicationOpen runs above the throw and can boot the device (ensureReady/ensureAndroidReady, cold-boot path), a device-reaching step — per the kernel contract 'no' holds only while no step was dispatched, so the refusal now discloses 'unknown' and the relaunch consumer conservatively marks close-effects unconfirmed.
  3. lifecycle-expo-dev-client.test.ts passes the pair directly per case — the { values, apply } rows are built in the test.each table with a hoisted applyRuntimeHints mock; the inline re-declaration of the producer rule (hasRuntimeTransportHintValues(...) ? ... : undefined) is gone.

Live runs (checkout-built CLI at c7f36a9cb9, pnpm build, version 0.21.40-dev; worktree /Users/michal/.t3/worktrees/agent-device/ad-q3; isolated --state-dir per run under /private/tmp; all sessions closed afterwards)

Android emulator — "ReactNative API 35B", serial emulator-5556, Android 15.0 (unclaimed; emulator-5554 is held by another worktree's session and was not touched). App com.callstack.agentdevicelab.

adb -s emulator-5556 reverse tcp:8081 tcp:8081
node bin/agent-device.mjs --state-dir /private/tmp/ad-q3-android open com.callstack.agentdevicelab \
  --serial emulator-5556 --metro-host 10.0.2.2 --metro-port 8081 --verbose --json     # exit 0
node bin/agent-device.mjs ... open com.callstack.agentdevicelab --serial emulator-5556 \
  --metro-host 10.0.2.2 --metro-port 8081 --relaunch --verbose --json                  # exit 0
  • open (no --relaunch): open_timing → runtimeHintsDurationMs: 162 (no relaunchCloseDurationMs)
  • open --relaunch: open_timing → relaunchCloseDurationMs: 510, runtimeHintsDurationMs: 242
  • host write visible afterwards, both files:
    adb -s emulator-5556 shell run-as com.callstack.agentdevicelab cat shared_prefs/com.callstack.agentdevicelab_preferences.xml
    → <string name="debug_http_host">10.0.2.2:8081</string> + <boolean name="dev_server_https" value="false"/> (same in legacy shared_prefs/ReactNativeDevPrefs.xml)
  • plain open without hints (fresh session): exit 0, open_timing has no runtimeHintsDurationMs, pref absent; close clears the pref again (empty <map>)

iOS simulator — "iPhone 17 Pro", UDID BC54AC11-CD86-4C10-8C4E-5101C773FFEB, iOS 27.0 (unclaimed; iPhone 17/iPhone 17e are claimed by other sessions and were not touched).

  • Non-dev-client path (com.example.miniapp — no exp+ scheme, so resolveDevClientLaunchUrl returns undefined and runtimeHints.apply runs), fresh state dir:
    open com.example.miniapp --udid BC54AC11-... --metro-host 127.0.0.1 --metro-port 8081 --verbose --json → exit 0, open_timing → runtimeHintsDurationMs: 948;
    xcrun simctl spawn BC54AC11-... defaults read com.example.miniapp RCT_jsLocation → 127.0.0.1:8081, RCT_packager_scheme → http (domain was empty before the open)
  • Plain open, fresh state dir: exit 0, runtime: null, no runtimeHintsDurationMs in open_timing, RCT_jsLocation absent
  • launchUrl-only open (open com.callstack.agentdevicelab --launch-url agent-device-test-app://settle-lab, fresh state dir): exit 0, runtime stores only launchUrl, no runtimeHintsDurationMs, RCT_jsLocation absent — applies nothing
  • Dev-client path still intact: open com.callstack.agentdevicelab --metro-host 127.0.0.1 --metro-port 8081 → exit 0, runtimeHintsDurationMs: 925 (scheme probe); the app declares exp+agent-device-test-app, so the dev-client URL path is taken and no defaults write happens — apply is skipped by design there

Validation

Head c7f36a9cb97e9479b702528da86072ad6b96fe74 (base e766e8890f): pnpm typecheck OK, pnpm lint 0 warnings, pnpm check:layering OK, pnpm build OK, pnpm format applied; 1296 tests pass (171 files: daemon sessions, platform-apple/android lifecycle, contracts). Limitation: snapshot -i on the emulator refused because the Android helper APK is not built in this worktree (pnpm build:android needs the Android SDK); open itself does not need the helper and succeeded. The full check:affected --run --head could not run to completion inside this session (no background processes available + heavy shared-host load); per docs/agents/pull-requests.md the serialized CI gate validates the pushed head.

@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of c7f36a9

Since the review of d585a23: 0 new · 0 still open · 0 no longer raised

No open findings.

1 finding below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (a620da022cf0).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

@thymikee

Copy link
Copy Markdown
Member Author

The PR is ready at c7f36a9. The live device output you posted covers the evidence the earlier review asked for, there are no remaining code problems, and the builder refusal test fails against the pre-change code as it should.

Not blocking: the doc comment at https://github.com/callstack/agent-device/blob/c7f36a9/packages/daemon/src/sessions/session-runtime.ts#L62 says the builder refuses before any dispatch, but its only caller runs after prepareApplicationOpen, which may boot the device. The clear-hints refusal in session-open-prepare.ts uses dispatched: 'unknown' for that reason. The branch cannot fire today, so you can reword the comment to "before the open dispatch or any relaunch close", use 'unknown' to match, or leave it.

The Runner Build (tvOS + visionOS + watchOS) job failed during action setup with a missing actions/cache file and a "Directory not empty" error. That looks like a download race on the runner, and this PR touches no runner sources or workflow files. Please rerun that job.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 19, 2026
@thymikee
thymikee merged commit 394da74 into main Nov 19, 2026
21 of 22 checks passed
@thymikee
thymikee deleted the t3/q3-runtime-hints-invariant branch November 19, 2026 19:04
thymikee added a commit to pcbeingused333/agent-device that referenced this pull request Nov 20, 2026
* origin/main: (70 commits)
  refactor(apple-runner): one RUNNER_ERROR_CODES row per runner error code with parity/docs gates (callstack#4774)
  fix(android): require acknowledgements for test IME typing (callstack#4722)
  feat(scroll): add scroll refresh for pull-to-refresh (callstack#4770)
  refactor(host-kit): add request Scope and use it for the wait capture deadline (callstack#4794)
  fix(android): let permission all change nothing on an app that declares no permissions (callstack#4796)
  fix(cli): replace the CLI session and generated remote config instead of rewriting them in place (callstack#4797)
  fix(host-kit): accept a group-writable script directory the user owns (callstack#4799)
  fix(cli): escape control characters at the CLI's stdout and stderr writes (callstack#4778)
  fix(audit): do not report rows under a persistent bar that scrolling reveals (callstack#4775)
  fix(daemon): refuse an unsafe state directory before first use (callstack#4783)
  refactor: settle remaining single-deadline races through settleWithin (callstack#4788)
  refactor(host-kit): settle deadline races via settleWithin with R87 race ratchet (callstack#4766)
  fix(android): authenticate and bound persistent snapshot helper sessions (callstack#4729)
  fix(daemon): bound upload ingress and finalization (callstack#4721)
  chore(gates): ratchet wire-published reason literals by value (R89) (callstack#4779)
  feat(audit): evaluate role-less clickable views on Android (callstack#4780)
  fix(mutation): keep umask-setting tests out of Stryker's thread pool (callstack#4785)
  feat(audit): report controls that share one accessible name (callstack#4771)
  fix(contracts): pair open runtime hints with their apply operation (callstack#4754)
  refactor(daemon): report startup progress over the launch channel instead of marker files (callstack#4777)
  ...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-human Valid work that needs human implementation, judgment, or maintainer merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant