refactor(host): read every configuration value from an explicit host (#3794)

[thymikee]

Summary

Every non-test configuration read on the converted routes now takes an explicit HostEnvironment instead of the ambient commandHostEnvironment(): 34 ambient reads outside host-kit command execution became required-host parameters, per-runtime state, or construction-bound ports. The boundary reads are two whichCmd PATH lookups — apple whichCommand and linux whichOnPath — which read the command-host scope (the runtime host plus the per-request env overlay) at the point of spawning a host command. They are part of the command-execution boundary that #3753's gate will allow; they are not configuration owners. One out-of-composition fallback remains: the Linux display decision for standalone leaf callers that name no host, reading the command host at call time with no memo. Composed routes never reach it — the Linux interactor always enters the provider bound to its own host. Vega has no ambient read at all any more: inventory, doctor and the interactor adapter share one resolver over the runtime host, and the un-bound scope default refuses.

Every platform package now derives display, tool, and home configuration from the host bound at construction of its local tool provider: the Linux interactor builds createLocalLinuxToolProvider({ host }) per instance and owns its display decision on that object (no module cache, no reset helper; input resolution is not memoized because the interactor itself lives one request); the Vega plugin builds createLocalVegaCliAdapter(host) per interactor, and inventory, doctor and the adapter all resolve the executable through ONE resolver (vega-executable.ts) over that runtime host's PATH and host-derived home — createDeviceInventoryHost derives its homeDirectory from host.env (hostHomeDirectoryFromEnv — HOME ?? USERPROFILE, never the process home; a host that names none yields homeDirectory: undefined, which turns off only the home-derived default paths — Android's ~/Android/Sdk root and Vega's default-install probe — never the whole host, so inventory still works for every family), createHostDiagnostics passes its host into vegaToolchainCheck, and the un-bound scope default refuses with vega-adapter-host-unbound instead of reading an ambient environment; the Apple runner reads its configuration through the per-runtime host slot entered by the daemon route. platform-web exports one policy for the provider of a web request, resolveWebProviderForHost(host) — request-scoped provider wins, else the agent-browser provider bound to the composing host — and the interactor, the network transport and the audio probe all resolve through it, so every reader of one web request agrees on one provider. The un-scoped fallback stays fail-closed (web-provider-missing).

Work is split into four commits by layer: contracts + shared test-kit, Apple, Linux/Vega/web/HarmonyOS, root composition.

Part of #3747. Part of #3794 — part 2 (one entered runtime store, collapsing the per-module runtimeStates aggregation) is the next PR.

Validation

• Tested SHA c466c4ee0a: pnpm check:affected --run --head passed (receipt run-LwZ5BO), exactCommit=true.
• Non-test commandHostEnvironment() reads outside host-kit: 34 at base c966724bea → 2 spawn-bound whichCmd PATH lookups + 1 memo-less out-of-composition display fallback (standalone Linux leaves) at head. For composed runtimes none of these is a configuration read: display, tool and home configuration is bound at provider construction from the runtime host.
• Public contract kept additive for 0.21.x: DebugSymbolsOptions.cwd stays optional and AgentDeviceClient gains no host; the CLI and MCP surfaces pass their own captured host env into formatCliOutput.
• New tests: two runtimes route the same macOS device by their own host (interactors.test.ts); the composed daemon route configures interactors from its host, not the process (daemon-composition.test.ts); two runner runtime states with different AGENT_DEVICE_IOS_RUNNER_LEASE_DIR each resolve their own value and neither the process value, plus a read outside any entered runtime refusing with apple_runner_host_unbound (runner-lease-runtime-host.test.ts, runner-owner-state.test.ts); the web-provider-missing refusal for every un-scoped web provider operation (provider-composition-fallback.test.ts); two interactors on different hosts keep their own display decision across A(X11) → B(Wayland) → A with an opposing process env (interactor-host-isolation.test.ts); two Vega hosts resolve the CLI executable from their own PATH and HOME, each adapter memoizes on its own instance, and neither reuses the other's answer (tool-provider-host-isolation.test.ts); vegaPlugin.createInteractor binds each caller's host so the returned interactor runs that host's executable, against a process command host naming a third location — removing the binding makes it fall through to the vega-adapter-host-unbound refusal (index.test.ts); createVegaInventory(createDeviceInventoryHost(host)) lists devices through a host whose HOME differs from the process HOME and names the only vega (platform-runtime-host.test.ts), and createHostDiagnostics(host).toolchainCheck reports the CLI found for the same host with no provider scope (platform-runtime-host-diagnostics.test.ts) — both go red when the host-derived home or the doctor host binding is reverted.

CI obligations

Full CI on this head; device lanes run there. The macOS helper lane and the native-backend refusal were run live on 17ac24fb79 — see the evidence comment; the Apple routes are unchanged since.

Unresolved risks

None known beyond the review.

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.42 MB	5.40 MB	-13.3 kB
Package (unpacked)	5.41 MB	5.40 MB	-13.3 kB
Package (download)	1.63 MB	1.63 MB	-4.2 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.2 ms	27.0 ms	+0.8 ms
CLI --help	49.4 ms	51.5 ms	+2.1 ms

[thymikee]

Reviewed 7c10533. The refactor looks sound, but the macOS helper route has no live run, and typecheck fails against current main.

Typecheck fails with TS2741 because of a real semantic conflict. This PR makes env required on runMacOsScreenshotAction options (helper.ts:607-612). Main's feca8cb (#3761) adds a call in helper.test.ts that passes only {surface: nativeApp, bundleId}. Please rebase onto 11de319 and pass env in that call. The Coverage check failure is unclear from the log excerpt I have, so please re-check it after the rebase. The Smoke failure is in the Swift RunnerTests (testPlanMovesPastATreeTierWhoseCollapsedTabQueryCannotStart, a tree_processing main-thread timeout). This PR changes only .ts files, so that failure is likely unrelated.

The macOS helper and native-app routes changed, but the PR's live run covers only the iOS simulator runner route. The env is now threaded into runMacOsHelper, the ghost-cursor and helper-path overrides, and the native-app backend choice. That choice now reads AGENT_DEVICE_MACOS_APP_BACKEND from the runtime host (interactor.ts:67, runtime.ts:268). If the helper-path or backend env is missing or wrong on that route, a helper-routed snapshot or press breaks on real macOS. helper.test.ts would not catch it because it stubs the helper provider. Please run a macOS daemon session on the head SHA: open <bundle> --platform macos with a helper-routed surface (app or frontmost-app), then snapshot and press. The output must show helper nodes. Then start the daemon with AGENT_DEVICE_MACOS_APP_BACKEND=native while the shell env differs, and show back refused with reason unsupported-device-backend. That proves the backend is read from the runtime host.

Not blocking, and you can take or leave these: (1) the Apple runner host slot (runner-host.ts:78) feeds about 20 runner config reads, yet every test binds it to the live env or process.env, so swapping the slot read for captureHostEnvironment(process) leaves the suite green and nothing reaches apple_runner_host_unbound. A test that composes two runner runtime states with different AGENT_DEVICE_IOS_RUNNER_LEASE_DIR values, and checks that each resolves its own and neither the process value, would cover it, plus one read outside any entered state expecting details.reason === 'apple_runner_host_unbound'; (2) unscoped web requests now follow two policies: createWebInteractor (interactor.ts:20) builds a host-bound provider, while the network transport and audio-probe resolvers get uncomposedWebProvider with no dumpNetwork or probeAudio, and nothing tests the web-provider-missing refusal, so every reader in one unscoped web request should resolve the same provider; (3) DebugSymbolsOptions.cwd (debug-symbols.ts:8) goes from optional to required and AgentDeviceClient gains a required public host, both public since v0.21.28 and without a CHANGELOG entry, so either keep cwd optional and take the formatter env from the CLI or MCP surface's own host, or document both; (4) the PR says "Closes #3794" but part 2 (the runtimeStates aggregation) remains and is not mentioned, so "Part of #3794" with part 2 noted as deferred would be accurate; (5) the exitWithHelp extraction (cli.ts:304) and the removed fallow-ignore comments in client-types.ts are unrelated, and the PR is one 219-file commit of about 3,900 gross lines, so splitting by layer (contracts and plugin port, Apple, Linux/Vega/web, root composition) would ease review.

Could the env be bound when the local Linux and Apple tool providers are built (for example createLocalLinuxToolProvider(host) inside createLinuxInteractor(host)) instead of being added to every port method and helper? Could runCliOnHost and the MCP executor deps pass their own host env into formatCliOutput, so the public AgentDeviceClient.host is not needed? Could one Apple runner runtime state be entered at each process entry that already calls withCommandHost (src/cli.ts:140 and the two scripts), instead of setters in runStaleDeviceClaimRelease and createDaemonOwnerCleanup? With DebugSymbolsOptions left unchanged, that would remove the four setter sites and most positional env parameters. What would need to change first is part 2 of #3794: one entered runtime store where slots take the runtime's host as their initial value, so the runner host needs no wrapper or setters.

I did not review every Linux, Vega and web leaf for a missed host thread, though the required parameter types turn a miss into a compile error. Some ambient process.env configuration reads remain outside this change (for example src/platform-runtime-android-adb-host.ts:30), so "every configuration value" in the title overstates the scope a little.

Before merge, please rebase onto 11de319 and pass env in the #3761 helper.test.ts call. Then add the macOS helper-surface live run.

[thymikee]

All items from the 12:41Z review applied. Rebased onto 11de319, restructured into four layer commits, force-pushed as 17ac24fb79.

Blocking

1. Typecheck vs main — done: rebased onto 11de319aad, and the fix(apple): refuse captures whose window or panel identity is unknown #3761 runMacOsScreenshotAction call in helper.test.ts now passes env. pnpm typecheck passes.

2. Live macOS evidence on this head — both runs below are on 17ac24fb79 (local build + pnpm build:macos-helper), macOS host INV-0357-Michal-Pierzchala, separate state dirs.

   a. Helper-routed surface (frontmost-app → macos-helper backend per macOsSurfaceBackend), then snapshot and press — helper nodes visible:

   $ agent-device open --platform macos --surface frontmost-app --state-dir /private/tmp/ad-3798-a
   Opened: Finder
   
   $ agent-device snapshot --platform macos --state-dir /private/tmp/ad-3798-a
   Page: Finder
   App: com.apple.finder
   Snapshot: 1496 nodes (truncated)
   @e1 [application] "Finder"
     @e2 [window] "Applications"
       @e3 [axsplitgroup]
         @e4 [scroll-area] "_NS:61" [scrollable]
           @e5 [axoutline] "sidebar"
             @e6 [axoutlinerow]
               @e7 [axcell]
                 @e8 [text] "Recents"
   
   $ agent-device press @e8~s539313 --platform macos --state-dir /private/tmp/ad-3798-a
   Tapped @e8 (384, 215)

   The AX-role node shape (axoutline/axoutlinerow/axcell, _NS: identifiers) is the helper traversal's output — the xctest runner route does not emit these. The press resolved a helper ref and acted through the helper's AX path.

   b. Backend read from the runtime host, not the shell: daemon started with AGENT_DEVICE_MACOS_APP_BACKEND=native in its own env; the back command ran from a shell where that variable is unset, and the daemon's runtime-host value still governed the route:

   $ AGENT_DEVICE_MACOS_APP_BACKEND=native agent-device open --platform macos --state-dir /private/tmp/ad-3798-b
   Opened: default
   
   $ env | grep MACOS_APP_BACKEND        # (nothing: shell env differs from the daemon's)
   $ agent-device back --platform macos --state-dir /private/tmp/ad-3798-b --json
   {
     "success": false,
     "error": {
       "code": "UNSUPPORTED_OPERATION",
       "message": "back is not supported on this device",
       "hint": "The native macOS app backend never starts the XCTest runner, which this command needs. Unset AGENT_DEVICE_MACOS_APP_BACKEND to use XCTest.",
       "details": { "reason": "unsupported-device-backend", "dispatched": "no" }
     }
   }

   The refusal reason comes from the daemon's runtime-host read of AGENT_DEVICE_MACOS_APP_BACKEND (runtime.ts macOsAppBackend → host.hostEnvironment.env), proving the native-app backend choice is host-threaded end to end. Sessions closed and both daemons stopped after the runs.

Contract (0.21.x additive)

3. DebugSymbolsOptions.cwd is optional again; AgentDeviceClient no longer exposes host (the field and the type import are removed from the published surface). The client resolves cwd from its own host/config as before. runCliCommand and the MCP tool executor capture their own host per call and pass its env into formatCliOutput — no public host surface.

Simplify

4. Local tool providers no longer take env through their port methods: LinuxToolProvider.whichCommand(cmd), LinuxDesktopProvider.openTarget/closeApp, LinuxClipboardProvider, LinuxScreenshotProvider.capture, the Apple whichCommand port, and the Vega provider all lost the env parameter. What remains ambient in those providers is five commandHostEnvironment() reads at the point of spawning a host command (apple whichCommand, linux whichOnPath/isLinuxWayland/detectDisplayServer, vega resolveVegaCliExecutable). Per the coordinator ruling these stay: they read the command-host scope (runtime host plus the per-request overlay) exactly where host-kit materializes a spawn, so they are the command-execution boundary chore(layering): forbid process globals outside entry points #3753's gate will allow, not configuration owners. Named as such in the PR body.
5. One policy per unscoped web request: resolveWebNetworkTransport and the audio-probe resolver now build the same host-bound createAgentBrowserWebProvider({ host }) that createWebInteractor builds when no provider is scoped; only an actual provider-less scope inside a request keeps the fail-closed uncomposedWebProvider. The web-provider-missing refusal is now tested for every provider operation.

Tests and hygiene

6. runner-lease-runtime-host.test.ts: two runner runtime states with different AGENT_DEVICE_IOS_RUNNER_LEASE_DIR — A's lease resolves only inside A, B and the process default resolve neither. runner-owner-state.test.ts: a read outside any entered runtime refuses with details.reason === 'apple_runner_host_unbound'.
7. PR body says "Part of refactor(host): explicit host for configuration reads and one entered runtime store #3794" and names part 2 (one entered runtime store) as the next PR.
8. exitWithHelp is back inline in cli.ts; the client-types.ts fallow-ignore comments are restored unchanged. The work is now four commits by layer: contracts + shared test-kit, Apple, Linux/Vega/web/HarmonyOS, root composition.

Also noted

• The Smoke Swift failure (testPlanMovesPastATreeTierWhoseCollapsedTabQueryCannotStart) is the known intermittent runner-timing test; that job is being re-run for this head.
• On the title overstatement: agreed — the Android adb-host reads and other ambient process.env lookups are outside this change; chore(layering): forbid process globals outside entry points #3753's gate is what bounds the remaining surface.

Gate: pnpm check:affected --run --head 17ac24fb79 passed — all runnable checks, receipt run-PYGQAj, exactCommit=true.

[thymikee]

Coverage failure on 17ac24fb79 fixed and pushed as 0968cb7343 (same four layer commits, one amended).

The job was not a coverage gap: the unit-ci lane's scripts/__tests__/test-file-size-ratchet.test.ts guard failed — src/mcp/__tests__/command-tools.test.ts measured 1047 lines vs 1029 at the merge-base. The growth came from this round's review fixes: ~30 MCP createClient stubs were widened with a fake host ({ host: { env: process.env, cwd: process.cwd() } }) across four MCP test files. That was unnecessary — after the item-3 change nothing reads client.host; the executor captures its own host per call and passes host.env into formatCliOutput directly. The four files are restored to their exact main versions; the executor still receives its host from captureHostEnvironment(process).

• Focused MCP tests pass (4 files, 66 tests), as does the ratchet guard and pnpm typecheck.
• pnpm check:affected --run --head 0968cb7343: all runnable checks passed, receipt run-XwnP22, exactCommit=true.

Live macOS evidence and the item-by-item replies above are unchanged by this push (the diff only reverts MCP test-file stubs).

[thymikee]

One remaining issue at 0968cb7343: the earlier coordinator exception for all five ambient reads was too broad.

P1 — Linux host isolation: packages/platform-linux/src/linux-env.ts:15-38 chooses X11/Wayland via commandHostEnvironment() and caches the chosen input tool solely by provider identity. tool-provider.ts:305-314 independently repeats the display decision. These are configuration decisions, not host-kit spawn materialization. With two host runtimes using the default local provider, run an X11 input first, then a Wayland input: both resolve the same singleton provider, so the second ensureInputTool() returns the first runtime's cached xdotool selection before reading its own host. The current isolation test constructs distinct providers and resets the cache, so it does not cover this route.

Please bind display configuration to the runtime host/provider at construction and scope the input-tool cache to that owner (or remove the cache if it is unnecessary). Reuse one display detector for input, clipboard and screenshot selection. Keep env out of individual port methods. Add an A(X11) → B(Wayland) → A test with independent explicit hosts and an opposing process env, without cache resets between calls. The gate in #3753 must not exempt these configuration reads as command execution.

This corrects the coordinator's earlier ruling; the PR's macOS evidence and exact-head validation receipt remain useful. I have inspected this path read-only and have not run a Linux device session.

[thymikee]

Reviewed 0968cb7. Two Linux and Vega configuration reads still depend on process-wide stored state, so the host is not the only source of configuration yet. The CI checks are green: 17 checks, 0 failing at 0968cb7. The earlier Coverage failure (the test-file-size limit on command-tools.test.ts) is fixed by the MCP stub revert. Before merge, the Linux and Vega tool providers need to be bound to their host.

The first problem is in linux-env.ts. The Linux plugin's createInteractor drops the host it receives (register-builtins.ts:35). ensureInputTool then keeps {tool, display} in a module-global variable keyed only by provider identity, and without a scoped provider every runtime shares one localLinuxToolProvider. Take two runtimes in one process: A has an X11 host, B has WAYLAND_DISPLAY set. B's first press gets A's stored xdotool before B's host is read. Clipboard and screenshot make a separate display decision (isLinuxWayland, tool-provider.ts:305). So in B, input uses xdotool while screenshot uses grim, and input can silently do nothing. The code is unchanged from main, so this is not a regression. But the PR body calls these reads the command-execution boundary, and they are not, so #3794 is not done for Linux. The rule: every platform package derives display, tool and home configuration from the host bound when its local tool provider is built, and any memo lives on that owner, not in a module global. Please build the provider inside createLinuxInteractor(host), compute the display once on it for input, clipboard and screenshot, and delete the input-tool reset helper. A regression test should run A(X11), then B(Wayland), then A through the plugin's createInteractor route, with explicit hosts, an opposing process env and no reset between runs. It should fail on the current code.

The second problem is the same rule in the Vega tool provider. resolveVegaCliExecutable stores the result in an unkeyed module global, so the first runtime's PATH lookup answers for all later runtimes. The fallback at line 101 uses hostHomeDirectory(), which is os.homedir(), not the host's HOME. A second runtime with a different PATH or HOME can run the first runtime's vega binary, or miss its own. The Vega plugin already receives the host at index.ts:49, so please bind it into the provider there and resolve the executable from host PATH and HOME on that instance.

Not blocking, and you can take or leave these: the "scoped ? resolveWebProvider() : createAgentBrowserWebProvider({host})" rule appears three times (platform-web interactor.ts:20, network-web-transport.ts:14 and audio-probe-host.ts:68), so one resolveWebProviderForHost(host) export in platform-web would own it. Also, once the two fixes land, the PR body should list only the two whichCmd PATH lookups as boundary reads, and the commit dcece50 title names Linux and Vega, which this head does not change.

Could the host the plugin port already delivers be enough here? If createLinuxInteractor(host) builds the provider, with the display computed once and the input memo on that instance, the module globals and the isLinuxWayland duplicate go away. The port methods stay free of env parameters, and the ambient reads shrink to the two whichCmd lookups. Nothing needs to change first, because the host argument already reaches register-builtins.ts:35.

On evidence: the live macOS run was on 17ac24f, which I could not find locally, so I did not confirm that the range to 0968cb7 touches only MCP test files. The native-backend live run starts the daemon with its own process env, so it cannot tell the runtime host from the process env. The unit daemon-composition test carries that proof, and I did not re-run it. I did not run a two-runtime Linux or Vega session; both findings come from reading the code, and the memo key and singleton resolution are confirmed by grep. The macOS evidence the PR needs is in place. No conflicts are known.

[thymikee]

Coordinator note for the #3794 owner. The 16:35Z review is only partly covered by the local round I see (613e66bdf5, not pushed yet). Before the next push, or in the round right after it:

1. Linux: keep the input-tool selection on the provider instance that createLinuxInteractor(host) builds, not in the module-level cachedInputTools WeakMap. Delete the reset helper (linux-env.ts:65).
2. Vega: resolveVegaCliExecutable still caches its result in an unkeyed module global. tool-provider.ts:101 still calls hostHomeDirectory(). Bind the host into the provider at platform-vega/src/index.ts:49, then resolve the executable from the host's PATH and HOME on that instance. Add a test with two hosts.
3. Web (recommended, apply): add one resolveWebProviderForHost(host) export in platform-web. Replace the three copies of the scoped-or-agent-browser rule with it.
4. PR body and commits (recommended, apply): the PR body lists only the two whichCmd PATH lookups as boundary reads. Each commit title names what that commit changes.

When done, post one comment that maps each item to its commit.

[thymikee]

Linux host-isolation P1 from the coordinator review fixed and pushed as 613e66bdf5 (same four layer commits, Linux and root-composition commits amended).

What changed:

• One display detector, bound at construction. New packages/platform-linux/src/display.ts owns the DisplayServer vocabulary, detectLinuxDisplayServer(env), and LinuxDisplayConfig — a display decision closed over one HostEnvironment. createLocalLinuxToolProvider({ host, ... }) now requires the host and binds the config into the provider; input, clipboard and screenshot selection all read that one bound answer. No port method gained an env parameter.
• The ambient reads are gone. linux-env.ts detectDisplayServer and tool-provider.ts isLinuxWayland no longer call commandHostEnvironment(). Linux ambient reads outside spawn materialization: whichOnPath only (the per-spawn which lookup, which the R13 substrate scan accepts alongside runCmd). The platform package now reads no process and no ambient host for configuration — the layering guard enforces exactly that (R13 flagged my first draft for a process fallback here, so the out-of-scope fallback provider reads the command host at call time instead, reachable only by standalone leaf callers, never by a composed runtime, which always binds its host-bound provider).
• The cache is per provider. ensureInputTool caches in a WeakMap keyed by the resolved provider object, so the cache belongs to the host-bound provider that made the decision and dies with it. The composing route: createLinuxInteractor(host) resolves hostBoundLinuxToolProvider(host) (one provider per host object) and enters it per interactor method unless the request scopes a provider, so a scoped test/provider override still wins.
• The test you asked for: packages/platform-linux/src/__tests__/interactor-host-isolation.test.ts drives two createLinuxInteractor interactors over the plain (non-overridden) provider surface with independent explicit hosts — A(X11) → B(Wayland) → A resolves xdotool → ydotool → xdotool, with the process environment claiming a third Wayland display that neither host names, and no cache resets between the calls. On the old singleton-keyed cache, phase B answered A's cached xdotool. The old scope test remains (now with bound hosts) and resetInputToolCache only clears the fallback provider's entry.

Validation: pnpm check:affected --run --head 613e66b: receipt run-W7ZqY7, exactCommit=true; platform-linux suite 55/55; typecheck and layering guard pass. No allowlists added anywhere.

[thymikee]

Round 3 — the 16:35Z review items and the four remaining items from the 17:23Z note, each mapped to its commit at head 5b1d1a5213:

1. Linux input-tool memo on the provider instance; reset helper dropped — 75e05d46fa.
The cachedInputTools WeakMap and resetInputToolCache are deleted. ensureInputTool now memoizes on the resolved provider itself (provider.inputSelection, tagged with the display decision it resolved for; a refusal is never cached and a display change re-resolves). createLinuxInteractor(host) builds its own createLocalLinuxToolProvider({ host }) per interactor — no host-keyed module map, no reset hook — and a request-scoped provider still wins. input-actions.test.ts, tool-provider.test.ts and interactor-host-isolation.test.ts no longer reset anything between tests; the isolation test passes A(X11) → B(Wayland) → A with a fresh interactor per phase and an opposing process env.

2. Vega host bound at the plugin route — 75e05d46fa.
vegaPlugin.createInteractor(device, runner, host) builds createLocalVegaCliAdapter(host) per interactor and enters it around every method unless the request already scopes a provider. The adapter resolves the executable from host.env PATH (whichCmd('vega', host.env)) and the default install from host.env.HOME/USERPROFILE — os.homedir() is gone — and memoizes the found executable in its own closure; misses are not memoized. The module global cachedVegaCliExecutable is deleted; the un-composed fallback adapter answers from the command host at call time with no memo, reachable only outside composed runtimes (host diagnostics), like the Linux display fallback. New tool-provider-host-isolation.test.ts: host A carries vega on PATH, host B only under its own HOME default install (real executable files), the process PATH/HOME name a third location with nothing; B resolves its absolute default-install binary, A resolves its PATH entry, neither reuses the other's answer, and later calls never re-probe — the shared module cache at the previous head failed this test.

3. One web provider policy — resolver added in 75e05d46fa, call sites replaced in 5b1d1a5213.
platform-web exports resolveWebProviderForHost(host, provider?): explicit provider wins, else the request-scoped provider, else the agent-browser provider bound to the composing host. The web interactor, the network transport and the audio probe all resolve through it; the transport keeps its own hasScopedWebProvider() read only to report mode: 'transport-composed' | 'local', not to pick a provider.

4. PR body + commit titles — body rewritten at this push. Boundary reads are now exactly the two whichCmd PATH lookups (apple whichCommand, linux whichOnPath); the two remaining out-of-composition fallbacks (Linux display for standalone leaves, Vega executable for host diagnostics) are stated separately as memo-less command-host reads unreachable from composed runtimes. With items 1–2 landed, the Linux/Vega/web/HarmonyOS commit title now names only packages that commit changes.

Two dead-code removals the fallow gate flagged on this round's diff: the DisplayServer/InputTool re-exports on linux-env.ts (75e05d46fa; consumers read the types from display.ts/input-tool.ts directly), and src/__tests__/daemon-composition/platform-services-fixture.ts (5b1d1a5213), which had no consumer at base or head — #3544 moved that fixture package-local and left this copy behind; the package-local copy's comment now names src/daemon-composition.ts as the composition lane's real-port owner.

Evidence notes: on the live-run observation — agreed, the native-backend refusal run starts the daemon from its own process env, so it cannot separate runtime host from process env there; the composed-route proof stays the daemon-composition.test.ts unit. On the ratchet — the earlier Coverage failure was the test-file size ratchet on src/mcp/__tests__/command-tools.test.ts after item 3 restored four MCP test files to their main versions; green since.

pnpm check:affected --run --head 5b1d1a5213 passed with exactCommit=true receipt run-Oq5N07. CI runs the full lanes on this head.

[thymikee]

Coverage failure on 5b1d1a5213 fixed at head 22ce5974cd (same tree except this fix; squashed into the Linux/Vega/web commit, check:affected --run --head 22ce5974cd passed, receipt run-i6wvDF, exactCommit=true).

The Coverage gate flagged resolveVegaCliExecutable at CRAP 30 (cyclomatic 5, 0% coverage): after the round-3 rework, only the out-of-composition fallback adapter called that helper, and no test route reaches the fallback — the two-host test drove the adapter's own inlined copy. The fix deduplicates rather than adds a parallel test: createLocalVegaCliAdapter now keeps only the instance memo and delegates the lookup to the shared resolveVegaCliExecutable, so one function owns PATH-then-HOME resolution and both adapters share it. The two-host test now measures that shared helper through the bound adapter (PATH hit, HOME default-install hit), and a new case covers the miss routes: a host with no HOME and a host whose HOME carries no default install both report unavailable, and a later call re-probes instead of trusting a memoized refusal.

[thymikee]

The earlier findings from 0968cb7 are mostly fixed at 22ce597, but two things remain before merge. The Vega executable lookup now gives different answers inside one runtime, and the plugin binding added this round has no test.

The adapter's default-install lookup in tool-provider.ts now uses host.env.HOME ?? USERPROFILE. The inventory resolver in inventory.ts still uses DeviceInventoryHost.homeDirectory, which is os.homedir() at platform-runtime-host.ts:48, even though the same factory reads PATH from host.env. Doctor adds a third answer: isAvailable uses the fallback adapter, and the devices line uses the inventory reader. Take a runtime whose host HOME differs from the process HOME, with vega only under the host HOME default install. Then devices --platform vega fails with TOOL_MISSING "Vega CLI not found in PATH", while the interactor runs that binary and doctor reports the CLI found. Every Vega executable lookup in a runtime (inventory, doctor, interactor) should go through one resolver over that runtime host's PATH and one host-derived home. Please derive homeDirectory from host.env in createDeviceInventoryHost with the same rule the adapter uses. Please also pass the host that createHostDiagnostics(host) already holds into vegaToolchainCheck, so doctor builds createLocalVegaCliAdapter(host) instead of the fallback. Would one resolver that takes the inventory-host ports (commands.which, files.isExecutable, homeDirectory) from createDeviceInventoryHost(host) be simpler? Inventory, doctor and the adapter would all call it, and the adapter would need no home logic or doctor fallback of its own.

The fix for the earlier second finding binds the host-bound provider in vegaPlugin.createInteractor (index.ts:56). tool-provider-host-isolation.test.ts drives createLocalVegaCliAdapter directly, and index.test.ts:19-27 only asserts that interactor.tvRemote is a function. If you delete the withMethodScope wrap, every test stays green and the interactor silently reads the fallback. Please add a test that calls vegaPlugin.createInteractor(VVD, {}, hostA) and createInteractor(VVD, {}, hostB) with a bound test command host whose PATH and HOME name a third location. Call one interactor method on each and assert the runCmd executable each one used (PATH entry for A, HOME default install for B). The test must go red when the wrap in index.ts is removed.

Not blocking, and you can take or leave these: ensureInputTool in linux-env.ts still writes inputSelection onto the module singleton localLinuxToolProvider, which contradicts the header's "no module state"; the interactor is built per resolve at daemon-composition.ts:158, so the instance memos last one request and could go; completedLocalProvider is a symbol marker plus a cast; and the PR body's "unreachable from a composed runtime" wording is wrong for Vega doctor.

CI is green with 17 checks and none failing at 22ce597, and the Linux Smoke workflow covers the reworked X11 interactor route. There are no conflicts. I ran no tests and did not run a two-HOME Vega session; the first finding comes from reading the inventory, doctor and adapter code at this commit. No Wayland or Vega device lane exists in CI, so those routes are proven only by unit tests. I also did not check whether production embeddings ever set HOME apart from the process, which the divergence needs. Before merge, please route Vega inventory, doctor and the interactor adapter through one host-derived resolver and add the two-host createInteractor test.

[thymikee]

Round 4 — the 22:39Z review, each item mapped to its commit at head 4a6c731c1a:

1. BLOCKING — one Vega executable resolver — resolver + call sites in ef95bbda7e, inventory-host and diagnostics wiring in 4a6c731c1a, home rule in bb6b98a053.
Adopted the simpler shape: new packages/platform-vega/src/vega-executable.ts exports resolveVegaExecutable(host) over exactly the inventory-host ports (which, isExecutableFile, homeDirectory), plus createVegaExecutableHostFromEnv(env) deriving them from a runtime host. inventory.ts, the CLI adapter, and doctor all call the one resolver; the adapter keeps no home logic and no fallback of its own. createDeviceInventoryHost now derives homeDirectory from host.env through the new shared hostHomeDirectoryFromEnv(env) (HOME ?? USERPROFILE ?? process home) in host-kit — the same rule the adapter uses — so devices --platform vega, the interactor, and doctor answer from one host PATH and one host-derived home. createHostDiagnostics(host) passes its host into vegaToolchainCheck(context, host), which builds createLocalVegaCliAdapter(host) (a scoped test provider still wins). The Vega scope default is now a fail-closed unbound adapter refusing with vega-adapter-host-unbound: every composed route enters its host-bound provider first, so no ambient Vega read remains anywhere.

2. BLOCKING — test the plugin binding — ef95bbda7e (index.test.ts).
createInteractor binds each caller host into the interactor it returns: inside a bound process command host whose PATH and HOME name a third location with no vega, vegaPlugin.createInteractor(VEGA_VVD, {}, hostA) and (…, hostB) each run back(), and the test asserts the runCmd executable per call — A the PATH entry vega, B the absolute HOME default-install path. Verified red when the withMethodScope wrap in index.ts is removed: the calls then fall through to the unbound scope default and refuse (vega-adapter-host-unbound).

3. Recommended (all applied) — Linux items in ef95bbda7e, body fixed at this push.

• ensureInputTool no longer writes anything onto any provider; the inputSelection field is deleted from LinuxToolProvider, and linux-env holds no module state.
• The instance memo is gone entirely, not just moved: interactorResolution.resolve builds a fresh interactor per request, so a per-provider memo never outlived the request it served; ensureInputTool now resolves display + tool per call and simply throws on refusal. The A(X11)→B(Wayland)→A isolation test passes without any cache.
• completedLocalProvider (symbol + Object.defineProperty + cast) is replaced by a typed completion shape: LinuxToolProviderParts in, full LinuxToolProvider out, no marker and no cast.
• PR body corrected: doctor is host-bound (createHostDiagnostics passes the host); the boundary reads are the two whichCmd PATH lookups plus one memo-less Linux display fallback for standalone leaf callers only; Vega has no ambient read at all now.

Commit titles stayed accurate: the contracts commit is retitled …on contracts, host-kit and shared test-kit because the shared home rule lives in host-kit.

Validation: pnpm check:affected --run --head 4a6c731c1a passed, receipt run-hi0F6Y, exactCommit=true; the red/green check for item 2 was run with the wrap removed. Full CI runs the device lanes on this head.

[thymikee]

The Vega fix from the earlier review (22ce597) is in at 4a6c731, but it has no test that fails without it. Please add one before merge.

Reverting homeDirectory: hostHomeDirectoryFromEnv(env) to os.homedir() at src/platform-runtime-host.ts:50 breaks no test. platform-runtime-host.test.ts covers only Apple and warmup, and inventory.test.ts builds homeDirectory by hand. Reverting doctor.ts:26-28 to a bare resolveVegaToolProvider() also breaks no test. Every doctor.test.ts case runs inside withVegaToolProvider, so the scoped branch wins and DOCTOR_HOST is never read. Nothing checks that createHostDiagnostics forwards its host either. The rule is: every Vega executable lookup in one runtime resolves from that runtime host's PATH and home. Today only the interactor adapter is tested for it. A regression would bring back the reported case, where devices --platform vega gives TOOL_MISSING while the interactor finds the binary. An unscoped doctor run would hit the vega-adapter-host-unbound refusal instead of a diagnostic. Please add two tests through the production constructors, using a host whose HOME differs from the process HOME and has vega only at <hostHOME>/vega/bin/vega. First, createVegaInventory(createDeviceInventoryHost(host)) must list devices, not TOOL_MISSING. Second, createHostDiagnostics(host).toolchainCheck for vega must report the CLI found, with no withVegaToolProvider scope. Both must go red when the two lines above are reverted.

All 17 checks pass at 4a6c731, and Linux Smoke covers the reworked X11 interactor route. No Vega or Wayland lane exists, so those routes are proven only by unit tests. There are no conflicts. I ran no tests, so the red and green claims above come from reading the code. I did not run a live Vega session with two hosts. In production the router's withCommandHost host and the composition host are the same daemon host, so the HOME divergence needs an embedding I did not find. I could not check your check:affected receipt. Once the two tests land and go red on the reverts, nothing else is open from my side.

[thymikee]

Round 5 — the 07:39Z review, each item mapped to its commit at head c466c4ee0a:

1. Inventory test through the production constructor — c466c4ee0a (src/platform-runtime-host.test.ts).
vega inventory resolves the CLI from the host home, not the process home: builds createDeviceInventoryHost({ env: { PATH: <empty dir>, HOME: <hostHome> }, cwd }) whose HOME differs from the process HOME and names a real executable only at <hostHOME>/vega/bin/vega, then inventoryModule.loadInventory(host) (the production createVegaInventory route) + discover(...) lists the VVD. Verified red: reverting homeDirectory to os.homedir() in src/platform-runtime-host.ts fails it with TOOL_MISSING: Vega CLI not found in PATH.

2. Doctor test through the production constructor, unscoped — c466c4ee0a (src/platform-runtime-host-diagnostics.test.ts).
vega toolchain check finds the CLI through the host it was composed with: same host shape, createHostDiagnostics(host).toolchainCheck('vega', context) with no withVegaToolProvider anywhere in the file, asserting the check passes with the host binary's version line. Verified red: reverting doctor.ts to a bare resolveVegaToolProvider() fails it with the vega-adapter-host-unbound refusal.

3. hostHomeDirectoryFromEnv process-home fallback removed (fail closed) — rule in 730eba6c48, resolver port in c0dbad4c5d, constructor refusal in c466c4ee0a.
The helper now returns string | undefined (env.HOME ?? env.USERPROFILE, never os.homedir()). Each caller handles the miss fail-closed without guessing: the Vega resolver skips the default-install probe when the host names no home (homeDirectory?: string on the ports, PATH-only answer); createDeviceInventoryHost requires the contract's homeDirectory: string, so it throws AppError('COMMAND_FAILED', …, { reason: 'host_home_unbound' }) at construction for a host env naming no home. The reason for refusing rather than defaulting: the process home is exactly the ambient read #3753 will forbid, and in every composed runtime the host env is a captureHostEnvironment snapshot, which names HOME (or USERPROFILE) whenever the process has one.

Validation: both red/green checks were run by reverting the two cited lines and restoring them, on the exact code now pushed. pnpm check:affected --run --head c466c4ee0a passed, receipt run-LwZ5BO, exactCommit=true. Pushed with --force-with-lease; PR body updated for the fail-closed home rule and the two new tests.

[thymikee]

The earlier findings from 4a6c731 are mostly fixed, but one problem remains at c466c4e. When the captured host env has neither HOME nor USERPROFILE (env -i, a systemd unit without User=, some launchd or MDM contexts), createDeviceInventoryHost throws COMMAND_FAILED host_home_unbound. createPlatformDeviceInventoryGateways (src/platform-runtime.ts) loads this one host for every family through requiredHost in composed-inventory-gateways.ts. So Apple, HarmonyOS, Linux and web inventory, which never read the home, now fail too. On main, os.homedir() resolved the home from passwd and these routes worked. In a process with no HOME, devices and device resolution regress from working to COMMAND_FAILED for every platform, with no docs entry and no hint. The same state also gets two policies: the Vega resolver skips the default-install probe (vega-executable.ts:26), while the constructor refuses outright. The rule the code must satisfy is that a host that names no home turns off only the default paths derived from the home, never the whole host. Please make DeviceInventoryHost.homeDirectory string | undefined in platform-runtime-host.ts, and have Android inventory (inventory.ts:61) leave out the ~/Android/Sdk root when it is undefined. Vega already skips. Then delete the constructor refusal, and the compiler will list every consumer of the type. Would this one rule, with the guard removed, be simpler than two policies? It needs only the contracts type change, and no ADR. CI is green: all 17 checks pass at c466c4e, but no lane runs with HOME unset, so this route is not exercised. I ran no tests, so the red/green claims for the two new tests come from reading the code, and I could not check the author's check:affected receipt run-LwZ5BO. I also did not measure how many real daemon launch contexts have no HOME, and I did not check whether a Windows lane runs the new /bin/sh-based tests. Not blocking, and you can take or leave it: add a no-HOME case through createPlatformDeviceInventoryGateways in platform-runtime-host.test.ts that asserts a non-home family still discovers devices, since no test covers host_home_unbound or the Vega PATH-only answer today. Before merge, the host_home_unbound refusal must be replaced by an optional homeDirectory so a host with no home still inventories every family.

[thymikee]

Round 6 — the 09:35Z review, each item mapped to its commit at head e2501b1023. All three changes are in the root-composition layer commit, which is the commit that introduced both the required-type consumer and the refusal.

1. BLOCKING — a host that names no home turned off the whole host (host_home_unbound). Adopted your rule instead of my earlier fail-closed suggestion: a host that names no home turns off only the default paths derived from the home, never the whole host. Your diagnosis is confirmed — createPlatformDeviceInventoryGateways loads the one host for every family through requiredHost, so the constructor refusal regressed devices and device resolution to COMMAND_FAILED for Apple, HarmonyOS, Linux and web too, which never read the home. That was two policies for one state, and the single rule is simpler.

• packages/contracts/src/platform-runtime-host.ts — DeviceInventoryHost.homeDirectory is now string | undefined, documented as "the home this host names, or undefined when it names none", with the rule stated at the type. No ADR, as you noted.
• src/platform-runtime-host.ts — the constructor refusal and the host_home_unbound reason are deleted, along with the now-unused AppError import. homeDirectory is whatever hostHomeDirectoryFromEnv answers, which already returns env.HOME ?? env.USERPROFILE and never os.homedir().
• packages/platform-android/src/inventory.ts — Android appends the ~/Android/Sdk root only when the host names a home; the configured roots (ANDROID_SDK_ROOT, ANDROID_HOME) and the PATH lookup still run, so adb resolves and devices list. Vega already skipped its default-install probe, so it needs no change and now agrees with Android under one policy rather than two.
• packages/platform-apple / harmonyos / linux / web — no change needed. The compiler listed Android as the only consumer of the tightened field: the Apple and Linux host picks name hostName/hostOs, HarmonyOS names commands/files/toolchains, and web takes no host at all. DeviceInventoryHostByFamily is unchanged, so each family still sees exactly the ports it did before.

2. Recommended (applied) — a no-HOME case through the gateways. src/platform-runtime-host.test.ts gains "a host env with no home still inventories every family through the gateways": it composes the real createPlatformDeviceInventoryGateways with env: {} — no HOME, no USERPROFILE — and asserts the non-home Apple route still answers the host-Mac device, which is the exact route the refusal broke, and that Vega answers TOOL_MISSING from PATH only rather than the made-up COMMAND_FAILED.

I also covered the Android branch directly in packages/platform-android/src/inventory.test.ts: "Android inventory omits the home SDK root when the host names no home" gives the family homeDirectory: undefined with one configured root and asserts the configured root is still probed while no Android path is ever probed. Without the guard path.join(undefined, 'Android', 'Sdk') throws before adb is resolved.

Red/green evidence (your claims from reading the code held, and I verified both directions rather than asserting them):

• Android test with the guard reverted to path.join(host.homeDirectory, …): red. With the guard: green.
• Gateways test with the host_home_unbound refusal restored: red, both the Apple and the Vega assertion. With the refusal deleted: green.

Gate. pnpm check:affected --run --head e2501b1023 passed on the exact head, exactCommit=true, receipt .tmp/validation/run-mPINhy/receipt.json. Focused suites first: src/platform-runtime*, platform-android, platform-vega, device-selection — 187 files, 1515 tests green — plus pnpm typecheck, which is the check that enumerates the consumers of the type change.

On the notes you flagged as not checked: no lane runs with HOME unset, which is exactly the gap this adds a test for, and your reading that the Windows lanes were not exercised is right — the two new tests are the only new coverage on this route, neither spawns a shell, and both run on every OS lane.

[thymikee]

Thanks, e2501b1 resolves the last blocker. homeDirectory is now string | undefined, the host_home_unbound refusal is gone, and Android leaves out only the ~/Android/Sdk root when the host names no home, which matches Vega. The new gateway test shows that a host env with no home still inventories every family. The delta from c466c4e is only these five files.

Smoke Tests was still running when I checked, and there are no conflicts. This is ready for human review.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-19 10:56 UTC