refactor(platforms): read host settings from HostEnvironment in platform and capture packages

[thymikee]

Summary

Platform and capture packages read the host's environment and working directory from a HostEnvironment instead of process. No behavior change. Closes #3750 (part of #3747; stacked on #3763). 92 files, mostly tests.

• react-native, provision-kit, maestro: the host or environment is a parameter. Released agent-device/metro binds the process host at its boundary; the client passes its own.
• Android and Apple install artifacts take environment from their caller (the root deployment executors pass the command host's), so a host whose env differs from the process's gets its own proxy settings.
• Apple runner reads through its host port (hostEnvironment, R77 intact); detached children get an explicit env and cwd. resolveRunnerContainerBundleIds(env) replaces the import-time constant.
• capture-kit takes the host for the Swift cache and recording paths; cached helper paths are keyed per cache root and directory. The PNG worker starts with an empty env and reports unavailability in the first diagnostics scope that sees it.
• The app-log marker takes the request host's env.

Still ambient commandHostEnvironment(): root seams (app-log output, deployment executors, recording finalizer, Android recording, contact sheet, runner bundle-id check) and Apple screenshot, file copy and snapshot-bridge spawn.

Validation

pnpm check:affected --run --head f0b20fae1b: passed, exactCommit: true; CI green at that head.

Device (earlier head): Android emulator and iOS 27.0 simulator passed runner snapshot, screenshot, PNG-worker diff, recording overlay, and app log. Not rerun since; runner detach/adopt across a daemon restart not run.

🤖 Generated with Claude Code

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.38 MB	5.38 MB	+1.8 kB
Package (unpacked)	5.38 MB	5.38 MB	+1.8 kB
Package (download)	1.62 MB	1.62 MB	+750 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	42.6 ms	43.0 ms	+0.4 ms
CLI --help	82.8 ms	82.1 ms	-0.7 ms

[cubic-dev-ai]

All reported issues were addressed across 70 files

_{You’re at about 96% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

Thanks for the PR. At bc06e18, one change is needed before merge. The checks show 12 passing and none failing.

bindTestCommandHost in capture-kit is a verbatim copy of the one in packages/test-kit/src/host-environment.ts. That leaves two copies of the test-host binding policy. If one changes, for example to snapshot env through createTestHostEnvironment, the capture-kit suites would silently run with a different host shape than every other suite. Please move it to the package that owns withCommandHost. host-kit already ships fixture subpaths (./archive-fixtures, ./audio-probe-fixtures), so add a ./command-host-fixtures export there, import it from both capture-kit and test-kit, and delete the copy.

Not blocking, and you can take or leave these: prewarmPngWorker() runs at daemon startup outside a diagnostics scope, so a failed spawn latches warnedWorkerUnavailable and later scoped requests never report png_worker_unavailable (an unavailable worker should be reported in the first diagnostics scope that sees it, and wrapping the prewarm in a scope, as you deferred to #3752, would also work), and the two runCmdBackground env assertions in runner-process-launch.test.ts and snapshot-source/host.test.ts check call shape, because resolveSpawnEnv already gives an un-env'd spawn the same host.env.

On the open threads, this one on the PNG worker diagnostics is marked resolved but still applies. These threads are fixed at this head, so please resolve them: run-script-http-child.ts:9 passes process.env with no cwd lookup, platform-runtime-app-log-output.ts:26 uses the command host's redaction patterns, install-source.ts:87 passes { env }, swift-cache.ts:45-46 has the updated comment, http-server-proxy.test.ts:193 passes env, and runner-process-launch.ts:63-64 has the lookup inside the try.

The PR has merge conflicts with its base refactor/host-environment. I reviewed the patch against the merge-base and did not examine the conflicts. I read the daemon shutdown wrapper but did not run runner detach/adopt across a daemon restart, and I did not audit every async continuation for AsyncLocalStorage propagation. The live device evidence is your report at 457bd1b, which I did not reproduce.

Before merge, replace the copied helper with the shared host-kit export, then rebase onto the updated refactor/host-environment.

[thymikee]

Rebased onto the narrowed base and converted configuration reads to explicit passing (f547d8895e, gate passed at that commit).

Ambient commandHostEnvironment() sites added by this PR: 35 in 22 files before, 10 in 6 files now.

Converted: react-native (host is a parameter; the client and agent-device/metro supply it), platform-android install artifacts (Android adb host port), provision-kit/maestro/capture-kit app-log (environment parameter), Apple install artifacts (option from the root executor), the daemon app-log marker (request host), and the Apple runner (13 files read through its host port as hostEnvironment, adapter bound once in core/runner-host.ts).

Still ambient, and why:

• capture-kit/recording/swift-cache.ts (3): the Swift cache root and tool env. Making them explicit means threading a host through isPlayableVideo, the overlay and contact-sheet paths, and createPlatformRuntimeHost/createPlatformRuntimeGateway (no host there yet) plus ClaimRecoveryGatewayInput in daemon-contracts, and AgentDeviceRuntime for record contact-sheet. That is refactor: read host settings from HostEnvironment in root src and remaining packages #3751/refactor(host-kit): capture HostEnvironment once at entry points #3749 contract surface, so I left it rather than grow this PR past the size limit.
• platform-apple screenshot and physical-device file copy (2) and the snapshot bridge spawn (1): they run inside a request, next to the xcrun/simctl calls they feed.
• Root composition seam (4, refactor: read host settings from HostEnvironment in root src and remaining packages #3751): app-log output sink, Apple deployment executor, Apple runner recording bundle-id check.

Both gaps close with one change: a HostEnvironment on createPlatformRuntimeGateway/PlatformRuntimeHost. I can do it as a follow-up on this branch if wanted.

[thymikee]

Answering the 09:43Z review (bc06e18) at 70d321146d (gate passed at that commit).

Duplicate bindTestCommandHost (blocking): not changed yet, because the suggested homes both break a rule.

• A host-kit ./command-host-fixtures export is a test export from a production package, which R83 ratchets down.
• Importing test-kit from capture-kit's tests makes a cycle: test-kit depends on capture-kit (packages/test-kit/package.json; src/keyboard-occlusion.fixtures.ts and src/app-log-live-handle.ts import it), and docs/agents/test-authoring.md says packages test-kit depends on keep helpers local.

Waiting on the coordinator to choose: keep the local copy, or move those two test-kit fixtures out so capture-kit can depend on test-kit.

prewarmPngWorker latch (taken): the unavailable report no longer latches outside a diagnostics scope, so the first request scope that reaches the fallback reports png_worker_unavailable; a test covers it and fails against the old latch.

Spawn env assertions (left): they pin the explicit env/cwd that #3750 asks detached children to carry; the call shape is the contract there.

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

_{You’re at about 97% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

At 70d3211 I found no blocking defects. Not blocking: prepareAndroidInstallArtifact in https://github.com/callstack/agent-device/blob/70d3211/packages/platform-android/src/install-artifact.ts#L24 now reads requireAndroidAdbHost().environment, which is bound to the live process env when the module loads, so a host whose env differs from process.env (for example the provider-scenario harness) would get process proxy settings on an Android network install. The rule is that every platform or capture read of host env or cwd comes from the injected HostEnvironment. You could pass environment in from the caller, as the Apple deployment executor does, or make the adb port's environment a getter over commandHostEnvironment().env. Take it or leave it.

The earlier findings from the bc06e18 review (#3777 (comment)) are fixed. I withdraw the duplicate bindTestCommandHost finding, because the local copy in capture-kit is the sanctioned one and a host-kit export would break the layering rule.

I read the code and did not run it on a device. The live device evidence is still your earlier report, and the runner change in this delta is a rename. I also did not trace that the production daemon's request host is the process host for every route, so "no CLI-visible change today" is inferred.

Smoke Tests was still running when I checked, so I cannot attribute CI yet. There are no conflicts. Before merge, wait for Smoke Tests to finish and reply to the open P3 thread on mid-request worker failure (#3777 (comment)): reportWorkerUnavailable() is not called in the PngWorkerUnavailableError branch before runSync, so the request that hit the failure reports nothing.

The other review threads are fixed at this head and you can resolve them: #3777 (comment) (prewarm no longer latches the report, and a test covers it), #3777 (comment) (run-script-http-child.ts passes process.env with no cwd lookup), #3777 (comment) (the delta does not touch the app-log output sink), #3777 (comment) (install-source.ts is not in the delta), #3777 (comment) (the swift-cache.ts doc comment was updated), #3777 (comment) (http-server-proxy.test.ts passes env), #3777 (comment) (runner-process-launch.ts reads the host inside the try).

[thymikee]

Applied the review follow-ups at 320af90109 (gate passed at that commit).

• Duplicate bindTestCommandHost: deleted the capture-kit copy; its tests import the helper from @agent-device/test-kit (new devDependency). To avoid the cycle, test-kit no longer depends on capture-kit: its keyboard fixture builds its own snapshot state, and createTestAppLogLiveHandle now implements the handle contract itself instead of calling capture-kit. No host-kit export was added.
• PNG worker diagnostics: an unavailable worker is reported by the first diagnostics scope that reaches the fallback; a startup pre-warm outside a scope no longer latches the report. png-worker-client-unavailable.test.ts covers it and fails against the old latch.
• Spawn env assertions: replaced the runner one with a behavior test: a fake xcodebuild on the bound host's PATH records the host's env and directory, which the old code (no explicit env/cwd) fails because the child would inherit the ambient scope. Deleted the snapshot-bridge one: inside a command host an explicit and an implicit env are identical, so no test can tell them apart there.
• Threads: all seven review threads are resolved at this head, including the PNG one.

[cubic-dev-ai]

All reported issues were addressed across 15 files (changes from recent commits).

_{You’re at about 97% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-17 18:23 UTC

[thymikee]

Coordinator review at 320af90: please revert the test-kit cycle-break and keep the capture-kit-local bindTestCommandHost.

To drop test-kit's dependency on capture-kit, this head re-implements production behaviour in test-kit:

• createTestAppLogLiveHandle (packages/test-kit/src/app-log-live-handle.ts) now reproduces capture-kit's createAppLogLiveHandle contract: idempotent finish and cleanup, disposal that confirms cleanup, and the AppError it throws. Suites that use it no longer exercise the real handle, and the two will drift.
• keyboard-occlusion.fixtures.ts replaces makeSnapshotState with its own state builder.

Both trade one three-line duplicated test helper for duplicated production semantics. docs/agents/test-authoring.md already sanctions a local helper in a package that test-kit depends on, and the 11:38Z review withdrew the duplicate-helper finding on that basis.

Requested shape:

• Restore test-kit's capture-kit dependency, along with its createAppLogLiveHandle and makeSnapshotState uses.
• Keep the local bindTestCommandHost in capture-kit.
• Make both copies build the host with the production captureHostEnvironment(process), so the host shape has one owner.

The PNG-worker and spawn-env changes in this push are good; keep them.

[thymikee]

Applied the coordinator's ruling at 3fbabc3e8e (rebased onto the base after #3763's last merge of main; gate passed at that commit).

• Duplicate bindTestCommandHost: no copy is left. Per docs/agents/test-authoring.md ("packages that test-kit depends on keep helpers local"), capture-kit does not import test-kit, and test-kit depends on capture-kit again. Instead capture-kit now takes the host explicitly (Swift cache root, tool env, script search directory, and the recording, overlay, contact-sheet and playable-video paths), so its suites need no bound command host and the local helper is deleted. The tests' hosts come from captureHostEnvironment(process) (createTestHost), the one owner of the host shape. The root recording seams (finalizer, Android recording, contact-sheet command) supply commandHostEnvironment().
• Single-owner capture in test-kit: I changed bindTestCommandHost to captureHostEnvironment(process) and reverted it. captureHostEnvironment copies the environment when the test starts, so every suite that calls vi.stubEnv afterwards stopped seeing it: 82 tests in 32 files failed (platform-apple, linux, harmonyos, web, cloud-connect and others). The live-environment binding stays until those suites pass a host explicitly.
• Spawn-env assertions: the runner one is now a behavior test (a fake xcodebuild on the bound host's PATH records its env and directory; the old code fails it). The snapshot-bridge call-shape assertion is deleted. The explicit env/cwd on detached children is the refactor(platforms): read host settings from HostEnvironment in platform and capture packages #3750 contract: the child can't receive a live host object.

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

_{You’re at about 97% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

Applied the 11:38Z recommendation at f3ddfe3add (on the current base; gate passed at that commit).

• Android install environment: prepareAndroidInstallArtifact no longer reads requireAndroidAdbHost().environment (bound to the process env at module load). It takes environment from its caller, as the Apple executor does; the root Android deployment executor passes the command host's env. The cancellation test now passes an env with a proxy the adb host lacks and asserts the download request carries it.
• Single-owner host capture: see my earlier comment: capture-kit builds its test hosts with captureHostEnvironment(process) and needs no bound host; test-kit's bindTestCommandHost stays live because snapshotting breaks 82 tests in 32 suites that use vi.stubEnv.

[thymikee]

Reply to the review at 320af90109: that head is old. At 1efe26fec7 (gate passed, base unchanged) the state is:

• test-kit cycle-break reverted: test-kit's tree is identical to the one before the cycle-break (git diff 70d321146d -- packages/test-kit is empty). It depends on capture-kit again, createTestAppLogLiveHandle wraps capture-kit's constructor, and the keyboard fixture uses makeSnapshotState. capture-kit has no test-kit dependency.
• Local bindTestCommandHost in capture-kit: not restored, because nothing would call it. capture-kit no longer reads the command host: its Swift cache and recording code take the host as a parameter, and its tests build one with captureHostEnvironment(process) (createTestHost). A bound host there would be dead code.
• Host capture in both copies: capture-kit's does. test-kit's bindTestCommandHost still uses the live process env: switching it to captureHostEnvironment(process) fails 82 tests in 32 suites that call vi.stubEnv after the test starts. That needs those suites to pass a host explicitly first.
• Android install environment: applied in f3ddfe3add (environment comes from the caller).
• Kept: the PNG-worker and spawn-env changes.

Say if you still want the unused local helper restored.

[thymikee]

Rebased onto refactor/host-environment (d8a9bd4) at 867301dfed; gate passed at that commit. One conflict, in the provider scenario harness: the base now has its own scenario env override and iOS recording fix, so I took its version. Android and macOS recording scenarios set the Swift cache on the process before the harness starts, so the harness host still carries AGENT_DEVICE_SWIFT_CACHE_DIR from the process; without it the full provider-integration project failed 5 tests.

[thymikee]

Rebased onto refactor/host-environment (870cf663c4, with current main and #3775) at d6273a3d05; gate passed at that commit, with no conflicts. No review has landed since 14:27Z, so there was nothing else to apply. The ambient commandHostEnvironment() reads this PR still adds are the Apple screenshot and physical-device file copy (2), the snapshot-bridge spawn (1), and the root seams: app-log output, Apple and Android deployment executors, the recording finalizer, Android recording, the contact-sheet command and the Apple runner bundle-id check.

[thymikee]

The PR is ready at 8b5e97f. The earlier clean review at 70d3211 still holds, and the four inline threads from cubic-dev-ai are now fixed at this commit: the worker-unavailable event in png-worker-client.ts, the restored host env and cwd test in snapshot-source/host.test.ts, the throwing FakeWorker.last check, and the app-log live handle that now delegates to capture-kit.

Not blocking, and you can take or leave these: the memoised paths in packages/capture-kit/src/recording/video.ts#L97 and overlay.ts#L53-L62 come from the first caller's host, so a later host with a different Swift build directory or cwd reuses them; keying the memo on that directory, or documenting that the first host wins, would fix it. The Android and macOS recording scenarios in test/integration/provider-scenarios/android-recording-fixtures.ts#L42 still set PATH and AGENT_DEVICE_SWIFT_CACHE_DIR on the process, and passing env: { PATH, AGENT_DEVICE_SWIFT_CACHE_DIR } through the base env override would let you drop harness.ts lines 114-115.

I ran no tests, so the report that 5 provider-integration tests fail without harness.ts:115 is unverified. I could not separate commits 17-18 from base drift, so I checked that result by reading test-kit/src/app-log-live-handle.ts at head.

Smoke Tests is still queued, not failed. It may reach the recording finalize and Android install-artifact routes this PR touches, so it needs to finish green before merge. There are no known conflicts.

All four cubic-dev-ai threads are fixed at this commit, so you can resolve them: png-worker-client unavailable event (#3777 (comment)), host env and cwd test (#3777 (comment)), FakeWorker.last check (#3777 (comment)), and the app-log live handle (#3777 (comment)).

This review covers 8b5e97f. The branch has since been rebased onto 870cf66 as d6273a3; a range-diff shows the PR's own commits unchanged apart from one context line in the Android deployment executor, so this verdict should carry over. I will confirm it on the new head.

[thymikee]

Applied the 15:36Z recommendations at 3279ad2cf4 (rebased onto refactor/host-environment 9f3e58ffbb; gate passed at that commit).

1. Memoised helper paths: the Swift video validator is now cached per Swift cache root, and the overlay and export-support script paths per host working directory, instead of once per process. video.test.ts runs two cache roots (one compile each, reused on a repeat) and overlay-script-paths.test.ts runs two working directories; both fail against the old process-wide memo.
2. Scenario host env: the Android recording scenarios no longer set PATH or AGENT_DEVICE_SWIFT_CACHE_DIR on the process; their harness helper passes both through the harness env. The iOS recording scenario's process-env block (which the base had re-added) is gone for the same reason, and the harness no longer forwards the process's Swift cache. One deviation: the macOS recording scenario now passes the process's warm Swift cache through its own env (in macos-world.ts), because without it recording finalization compiled the validator into a cold default cache and timed out at 5 s.

[thymikee]

Rebased onto refactor/host-environment (cb17bb3051, with #3760, #3762, #3784 and #3785) at f0b20fae1b; gate passed at that commit. No review has landed since 16:14Z, so nothing else to apply. The only conflicts were in the iOS recording scenario test, where the base re-added a process PATH/Swift-cache block with a note that capture-kit would move to the host in this PR; it has, so the block is gone and the scenario's harness env carries both.

[thymikee]

Reviewed f0b20fa. The code looks good. Since the earlier review at 70d3211, Android install takes its environment from the caller as intended, and the rebase conflict in the iOS recording scenario is resolved correctly: the process PATH/Swift-cache block is gone, and the harness env carries both.

The three cubic threads are fixed at this head, so you can resolve them: the test-kit app-log handle now wraps the capture-kit handle (#3777 (comment)), the detached bridge test pins host env and cwd again (#3777 (comment)), and the PNG worker test fails with a clear message when no worker starts (#3777 (comment)).

Not blocking: the PR body still says Android reads its adb host port and cites the validation head f547d88, which the rebase dropped.

The device validation is from an earlier head. That still covers this change, because the delta only moves the same host-environment read from capture-kit defaults up to the root seams. Smoke Tests is still running; the other 11 checks pass. There are no conflicts.