Skip to content

refactor(web,vega): run each plugin's commands on its setup host - #4874

Merged
thymikee merged 11 commits into
0.22from
fix/0.22-web-vega-plugin-host-routing
Nov 21, 2026
Merged

thymikee merged 11 commits into
0.22from
fix/0.22-web-vega-plugin-host-routing

Conversation

@thymikee

@thymikee thymikee commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Summary

The managed web and Vega plugins run every spawn, process-table read, install lock and diagnostic through the PlatformHost handed to setup(), as HarmonyOS does, so neither packed bundle carries its own host-kit exec or diagnostics scope. PlatformHost gains isExecutableOnPath and a processes facet (table, identities, executable paths, owned-record reap, withLock), answered only by the core. The layering rule now derives from the host-kit module graph which exports reach exec or diagnostics, so a new exec-backed export is refused without editing a list. Fixes #4862. Stacked on #4857.

Value

metric base head
runtime host-kit/command|diagnostics imports in managed plugins 11 files 0
exec-backed host-kit reads reachable from a managed plugin 5 sites 0
hand-kept host-kit debt/export list entries 11 0

Validation

Head bde31446a0, rebased onto 0.22 at 9a12ab0ebb (HarmonyOS and Linux merged); the Linux plugin now also reads the host OS from PlatformHost and paces input without host-kit. Local: build, typecheck, lint, layering, command-docs, daemon-wire-compat, full vitest --project unit-core, check:package with packed web and Vega gates (argv, child env, one exec record per call; web asserts the ps lock and table reads). Packed web setup --debug traces the install-lock ps reads under the request with no bundled spawn. Live Vega Virtual Device run in docs/evidence/vega-managed-platform-2026-11-21.md; web used a fixture backend. CI: hosted checks at this head.


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

View guided diff Turn on auto-fix

@thymikee
thymikee marked this pull request as draft November 21, 2026 01:44
@thymikee

Copy link
Copy Markdown
Member Author

Live packed-plugin run — Vega Virtual Device (2026-11-21)

Packed core + packed @agent-device/vega, driven against a real Vega Virtual Device on this host (SDK 0.23.9221, Vega CLI 1.3.2 at /Users/thymikee/vega/bin/vega), in an isolated store whose PATH carried the CLI directory. Full transcript: docs/evidence/vega-managed-platform-2026-11-21.md.

  • vega virtual-device status before: {"running":false,"process_ids":{"qemu":-1}}
  • vega virtual-device start → Virtual device ready.
  • agent-device devices --platform vega → VirtualDevice (tv emulator, booted) — CLI resolved through host.isExecutableOnPath
  • agent-device open com.amazondeveloper.keplersampleapp.main --platform vega --target tv → Opened, selection single-booted-local, startup round-trip 1321 ms
  • agent-device tv-remote press down --platform vega --target tv → Pressed TV remote down
  • agent-device close com.amazondeveloper.keplersampleapp.main --platform vega --target tv → Closed: default
  • Corroborated with the SDK on the device: is-app-running reported the Kepler sample app running after open and not running after close; a direct inputd-cli button_press KEY_DOWN answered Injecting Button Press As Driver: KEY_DOWN State: short
  • Each request's own --debug trace carried its vega spawn/exit pairs (devices 1, open 2, tv-remote 1, close 1), all exit 0
  • agent-device daemon stop clean, then vega virtual-device stop; status afterwards: {"running":false,"process_ids":{"qemu":-1}}

The packed web family is covered the same way over the fixture managed-backend install in packages/platform-web/test/package-smoke.mjs (no real browser: the route under test is the host, not the page), with a manual transcript in docs/evidence/web-managed-platform-2026-11-21.md — including the ps fleet-record read going through host.listHostProcesses and landing in the request's exec trace.

@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.13 MB 6.14 MB +10.1 kB
Package (unpacked) 6.13 MB 6.14 MB +10.1 kB
Package (download) 1.87 MB 1.87 MB +2.9 kB

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 19.4 ms 18.9 ms -0.5 ms
CLI --help 38.8 ms 36.3 ms -2.5 ms

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on 536d508. The verdict and the full list are in the summary comment.

@thymikee
thymikee marked this pull request as ready for review November 21, 2026 02:32
@thymikee

Copy link
Copy Markdown
Member Author

At 536d508 the web plugin still spawns process-table reads outside the host, so the PR body claim that every spawn goes through the PlatformHost does not hold yet.

Only listHostProcesses moved to the host. The web fleet record and the startup reaper still call host-kit/process helpers that spawn through the bundled internal/exec.ts copy: readProcessIdentities (ps -p … -o pid=,state=,lstart=) and readProcessExecutablePaths (osascript or powershell) in agent-browser-process-record.ts:145, readHostProcessIdentityObservationsAsync at line 230, and reapOwnedProcessRecordsAtStartup -> stopProcessAndConfirmExit in agent-browser-lifecycle.ts:92. In the packed bundle the daemon's withCommandHost scope never reaches that copy. So on every web open that refreshes the record, and on every orphan reap, these reads run with the daemon's process.env and trace into the plugin's own diagnostics store. Users see this as --debug for open --platform web missing the ps/osascript identity reads. The layering rule stays green because it bans only host-kit/command and /diagnostics, not host-kit/process, which re-exports exec-backed helpers.

The rule to satisfy: no exec-backed host-kit helper is reachable at runtime from a managed plugin, and MANAGED_HOST_KIT_SCOPES enumerates every such site. Either route the identity reads through the host (widen the port to the few process reads the fleet needs, or pass host.runCommand into the helpers that already accept a runCommand option, as listHostProcesses does in internal/host-process.ts:558), then add the exec-backed host-kit/process exports to MANAGED_HOST_KIT_SCOPES. Or narrow the PR claim and the issue text to command and diagnostics imports, and file the process reads as a follow-up. Validation: a web open run with --debug that reaches the fleet-record refresh and an orphan reap, with the ps/osascript calls visible in the host trace. The current web evidence uses a stub backend over the fixture install, so that route was never exercised live.

Code reading plus the evidence in the PR; the reviewed commit is 536d508. The failing Smoke Tests check on this head is only the 'Require both Apple jobs to succeed' gate reporting cancelled. The Apple, Android and Linux runs created at 01:44:37 were all cancelled within about 2 s of starting, before any test step, by a concurrency cancel from duplicate pull_request events. The later Apple, Android and Linux runs on the same head all passed, and the diff touches no route those smokes exercise, so this failure looks unrelated to the change. The next step before merge is the host-kit/process decision above.

One lower-priority inline thread still applies, and no high-priority thread is open.

Not blocking, and fine to take or leave: createWebCommandRunner in command-host.ts:40 and WebToolbox only re-spell PlatformHost, so web could take host: PlatformHost directly; vegaToolbox (platform-vega/src/index.ts:25) and webToolbox (platform-web/src/index.ts:24) copy harmonyToolbox and could share one exported lazy-bind helper; commandFailureDetails and requireCommandSuccess in kernel/src/errors.ts:475 repeat host-kit execFailureDetails and requireExecSuccess, which could compose the kernel pair; VegaToolbox.host and withDiagnosticTimer in platform-vega/src/toolbox.ts:14 are never read; an orphaned JSDoc block sits above managedStatusOptions in platform-web/src/agent-browser-tool.ts:141 and belongs above getManagedAgentBrowserStatus; and the !== undefined check in harmonyos index.test.ts:44 is always true because whichCmd returns a boolean.

Of the 823 net production lines, about 247 are docs and evidence, about 340 are the two package-smoke gates and about 256 are the two fixture files, while plugin source nets only +188. Could web take host: PlatformHost directly with no toolbox or command runner, Vega keep only createVegaCommandRunner (which adds real resolution), one lazy-bind helper replace the three copies, and the host-kit failure helpers compose the kernel pair? That would remove about 120-150 lines and leave 'toolbox' as a HarmonyOS-only concept, where it holds an HDC runner. The first decision is whether host-kit/process exec-backed helpers join MANAGED_HOST_KIT_SCOPES, since that settles whether a process port is widened or runCommand is threaded.

Not verified here: the package-smoke gates on base or head (the red-on-base claim is taken from the PR body), the Vega live run (read from the evidence doc), whether host-kit runCmdSync emits exec-trace events, and the Limrun provider 'clean' claim. The issue asks for a decision with a test, and the PR gives a decision without a test.

@thymikee
thymikee force-pushed the fix/0.22-web-vega-plugin-host-routing branch from 80f9c66 to afffaee Compare November 21, 2026 09:27
@thymikee

Copy link
Copy Markdown
Member Author

Reply to the blocking finding on 536d508 — process reads now go through the host, and the gate enforces it. Head afffaee78d.

What moved to the host. PlatformHost answers process questions through one processes facet instead of the single listHostProcesses port, served only by the core's own host-kit copy in src/platform-runtime/plugin-host.ts: list, readIdentities, readIdentityObservations, readExecutablePaths, reapOwnedRecords. Every site the finding named is converted: the fleet scan's readProcessIdentities / readProcessExecutablePaths, the record's liveness probe (readHostProcessIdentityObservationsAsync), the install lock's claim on this process's start time (readProcessStartTime), and both reapers' reapOwnedProcessRecordsAtStartup → stopProcessAndConfirmExit. The facet is reads plus that one reap: a plugin still signals nothing it merely saw, only pids a record it owns names. The non-exec helpers stay imported directly (hostPlatform, hostProcessId, isProcessAlive, expandProcessTree, processStartTimesDiffer) — they read this process's globals or compute from what the caller holds, so they cannot leave the request's scope. Vega and HarmonyOS read no host processes, so no other family needed wiring.

Gate. MANAGED_HOST_KIT_SCOPES is now per-export, not per-scope: host-kit/process joined with its 16 exec-backed exports listed (readProcessIdentities, listHostProcesses, readProcessExecutablePaths, stopProcessAndConfirmExit, reapOwnedProcessRecordsAtStartup, …), and a namespace or bare import of that scope is refused because it names no export and could reach any of them. The claim is no longer narrower than the rule: any exec-backed host-kit helper reachable at runtime from web, vega or harmonyos fails check:layering.

Tests. src/platform-runtime/plugin-host.test.ts (4) answers a table read, an identity read and a real reap of a spawned child through the host under --debug, asserting ps in that request's trace and the record emptied. agent-browser-process-record-host-routing.test.ts (2) refuses spawn/spawnSync for the whole web fleet module graph and asserts the scan acts on the pids its host answered for, and that the reap is handed the host's store and this family's purpose. Reverse-tested: pointing the scan back at the bundled readProcessIdentities turns the routing test red on this guard. Layering policy tests: 50 pass / 0 fail. Focused vitest (platform-web, platform-vega, platform-harmonyos, plugins, host-kit, src/platform-runtime): 168 files, 1596 passed / 7 skipped. lint, typecheck, format, check:layering, check:package (11) clean.

Live route, packed, on this head. One open --platform web --debug against the fixture managed install traced, under the requesting open: 1 backend node spawn, 6 ps spawns, 1 osascript spawn — the identity and executable-path reads the finding said were missing. The packed gate now asserts both kinds per request (the ps assertion existed; the osascript one is new). The reap runs at daemon startup, outside any request trace, so its proof is the host-side test above rather than a live request line.

Cleanups from the same list. Done: the always-true !== undefined in the HarmonyOS test host (whichCmd returns a boolean, as the inline thread said); the orphaned JSDoc now sits above getManagedAgentBrowserStatus; VegaToolbox dropped host and withDiagnosticTimer, which nothing read. Skipped deliberately: collapsing WebToolbox/createWebCommandRunner to a bare host: PlatformHost, the shared lazy-bind helper for the three toolboxes, and composing the kernel commandFailureDetails pair onto host-kit's execFailureDetails. Those are shape-only and each reaches a second family's tests; they read better as their own change than as extra churn in a routing fix.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

The earlier finding on the per-plugin process reads is mostly fixed at afffaee: the fleet record and reaper now run through the host, and the harmonyos test now returns the boolean from whichCmd. One high-priority gap remains: the web install lock still spawns ps and writes diagnostics from the plugin's own host-kit copy.

setupManagedAgentBrowser calls acquireProcessLock and withProcessLock from @agent-device/host-kit/file (line 2). In the packed web bundle that is the bundled copy. On the first acquire, acquireProcessLockAcquisition reads the current owner identity through a ps -p <pid> spawn. On a held or stale install lock it also probes owner and guard-holder liveness on every poll, with ps or PowerShell on Windows. The emitDiagnostic calls at process-lock.ts:232, :520 and :697 go to the bundle's own store. The change moved only the owner startTime field at line 88 to host.processes, so the lock still spawns its own ps beside it. check:layering stays green because the policy does not police host-kit/file.

This breaks the issue invariant that every spawn, process-table read and diagnostic goes through the PlatformHost. On a managed web install, or any setup that meets a held or stale install lock, these ps reads run with the daemon process.env and are missing from that request's --debug exec trace. It is the same class as the earlier finding, reached through a scope the per-export list does not enumerate.

The rule the code must satisfy: no host-kit module that a managed plugin imports at runtime may reach internal/exec.ts or internal/diagnostics.ts through the bundled copy, directly or transitively. Derive that from the host-kit module graph, with a pure-export allowlist derived the same way, so host-kit/file process-lock and classifyOwnerLivenessFromObservation are caught. Then serve the install lock from the core, for example PlatformHost.processes.withLock backed by the core's acquireProcessLock. That also removes the startTime hop at lines 86-91. If the lock stays out of this change, narrow the PR claim and the issue to the fleet record and reaper, and file the install lock as a follow-up.

Could the hand-kept execExports list be replaced by that graph rule? It would cover process, file and any future scope without a second list to maintain. Could readIdentities and readIdentityObservations also be one method, since both are the same ps read? The earlier shape-only asks stay closed as deferred.

Before merge, one packed open --platform web --debug run on a clean state dir is required. It must trigger the managed install and show the install-lock ps identity read in that request's exec trace via the host, with no ps spawn from the bundle. The fleet-record route evidence in the author comment is accepted as reported.

CI is green: 15 checks, 0 not passing at afffaee. No conflicts. Not verified here: tests and packed runs were not executed, and the live-trace counts, the 1596-test vitest run and the reverse test are taken from the author comment. The reachability above comes from reading the code and was not observed live. Not verified here: whether the packed bundle tree-shakes process-lock, though the runtime import at line 2 makes it reachable either way.

The earlier harmonyos thread is fixed at this head and can be resolved: #4874 (comment). The earlier review is at #4874 (comment). The remaining step before merge is routing the web install lock through the host.

@thymikee
thymikee force-pushed the refactor/0.22-harmonyos-platform-plugin branch from 327e188 to de014dd Compare November 21, 2026 11:34
@thymikee

Copy link
Copy Markdown
Member Author

This head (afffaee) now conflicts with the base branch. Please rebase onto it and push; the open finding from #4874 (comment) (route the web install lock through the host) still applies to the rebased head.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

Install lock now goes through the host, and the per-export list is gone. Head: 5644fa6e9c.

What moved

setupManagedAgentBrowser no longer imports acquireProcessLock / withProcessLock from @agent-device/host-kit/file, and no longer reads hostProcessId to hand a startTime to the lock. It calls host.processes.withLock({ lockDirPath, timeoutMs, description, task }) (agent-browser-tool.ts:80). The contract is PlatformHostProcesses.withLock in packages/plugins/src/platform.ts:113; the core answers it in src/platform-runtime/plugin-host.ts:73 with the core's own acquireProcessLock / withProcessLock. The startTime hop at the old lines 86-91 is removed: the host is the process that takes the claim, so it names its own identity rather than being told it.

The host answers with readCurrentOwnerIdentityAsync, not the synchronous probe. The sync probe uses runCmdSync, which emits no exec record, so the lock's identity read would have stayed invisible in --debug; the async read goes through runCmd and is traced. That is the difference the requested trace evidence depends on.

No bundled-copy ps spawn remains on this route: every ps the lock makes now comes from the core, in the request's command-host and diagnostic scope.

How the gate derives reachability

MANAGED_HOST_KIT_SCOPES.execExports and its hand-kept messages are deleted. The rule is in scripts/layering/host-kit-runtime-reach.ts: it indexes the host-kit module graph per exported subpath, and an exported name is refused unless the graph proves its declaring module loads neither internal/exec.ts nor the diagnostics store, directly or transitively. The pure allowlist is the same derivation, not a second list, so process, file and any future scope are covered by one rule. Namespace and bare imports are refused (the graph cannot bound what they load), an unknown subpath is refused, and a missing exec-root source is reported as stale against packages/host-kit/package.json instead of quietly widening the permission.

Per-specifier type markers are erased at runtime, so ImportEdge gained typeSymbols (model.ts:38) and the reach rule judges only the value names an import binds. Without that, import { type HostProcessInfo, readProcessIdentities } would have been judged as loading HostProcessInfo.

Derived today, from the tracked tree:

  • host-kit/host-file — entirely pure.
  • host-kit/file — pure: the path, verified-file and script-destination helpers. Refused: acquireProcessLock, acquireProcessLockAcquisition, tryAcquireProcessLock, inspectProcessLock, withProcessLock — through the bundled copy, exactly the names this review named.
  • host-kit/process — judged name by name, not per subpath. Refused: classifyOwnerLivenessFromObservation, readProcessIdentities, listHostProcesses, the owned-record store and the stop/kill helpers. Allowed: hostProcessId, hostPlatform, hostNodeVersion, uniquePositivePids, expandProcessTree, captureHostEnvironment — the pid and platform arithmetic whose declaring module loads neither root.
  • host-kit/retry — pure: sleep alone. host-kit/command and host-kit/diagnostics — fully refused.

To keep that honest without widening any ban, two leaves came out of host-kit: internal/host-process-facts.ts (self-knowledge and pid arithmetic, re-exported by internal/host-process.ts, which keeps the process-tool reads) and internal/sleep.ts (dependency-free timer, re-published from host-kit/retry). retry's sleep and the pure process exports are allowed because their declaring modules are genuinely clean, not because a list says so.

Tests

  • scripts/layering/platform-package-policy.test.ts — 56/56. Covers the lock names per family (web, vega, harmonyos), name-by-name judgment (classifyOwnerLivenessFromObservation refused while uniquePositivePids is allowed), a derivation flip test (an allowed export becomes refused once its declaring module gains an exec import, with no list edited), and the stale exec-root fail-closed case.
  • scripts/layering/model.test.ts — 33/33, including the new per-specifier type marker test.
  • pnpm check:layering — 540 node tests pass; guard reports OK on 2029 source files, R13/R11 wording intact.
  • src/platform-runtime/plugin-host.test.ts — 5/5. The lock test proves the claim names this pid with a truthy startTime, the lock dir is gone after release, and ps is in that request's traced commands.
  • packages/platform-web/src/agent-browser-tool.test.ts — 11/11, asserting exactly one host lock request with the expected lockDirPath, timeoutMs: 5 * 60_000 and description.
  • pnpm run check:package — 11/11. The packed web gate now also asserts every packed plugin chunk carries no node:child_process, and that a --debug managed install on a clean state dir traces both the lock's ps read and the managed-backend install into that request.
  • Scoped vitest (platform-web, platform-vega, platform-harmonyos, platform-linux, host-kit, plugins, src/platform-runtime, scripts/layering): 179 files, 1658 passed | 9 skipped.
  • pnpm lint, pnpm format, pnpm typecheck, pnpm check:fallow clean (fallow: 0 dead code, 0 complexity, 1 six-line clone group in two test fixtures, no issues in changed files).

Packed trace

Read this first: the requested open --platform web --debug on a clean state dir does not take the install lock. Measured at this head, packed core plus packed plugin, plugin installed and the managed package absent, it refuses without installing:

"code": "TOOL_MISSING",
"message": "Managed web browser backend is not installed.",
"hint": "Run `agent-device web setup` to install the managed web backend.",
"diagnosticId": "mwqemki4-7cf84ce1"

So the same packed scratch, same clean state dir, is run through the request that does take the lock — web setup --debug, with a stand-in npm on PATH that only answers the managed-backend install. --json keeps stdout as the reply alone, so the request's exec trace is its own --debug stream. Request 27ff44e2892e557e, command web:

"web" ps   spawn   pid=82299                 exec=41f517e2
"web" ps   spawn   pid=82300                 exec=fcbd1f40
"web" ps   settled pid=82299 reason=success  exec=41f517e2
"web" ps   settled pid=82300 reason=success  exec=fcbd1f40
"web" npm  spawn   pid=82301                 exec=96f10f5b
"web" npm  settled pid=82301 reason=success  exec=96f10f5b
"web" node spawn   pid=82305                 exec=9cb638fc
"web" node settled pid=82305 reason=success  exec=9cb638fc
"web" node spawn   pid=82307                 exec=47eb19b6
"web" node settled pid=82307 reason=success  exec=47eb19b6

The two ps reads precede the install: one names this process's identity for the claim, one proves the guard holder. Both are attributed to the setup request, both reason=success, and both go through runCmd in the core. The lock dir is gone afterwards, and no .lock remains anywhere under the state dir. Before this change the same scratch traced zero ps and zero /bin/ps for that request — the packed agent-browser-tool.mjs held the lock, and the packed agent-browser-lifecycle.mjs held /bin/ps; rebuilt dist now shows both counts at 0 across every chunk.

On your two questions

Replacing the hand-kept list with the graph rule: done, as above — one derivation decides both the refusal and the allowlist, so nothing needs a second list.

readIdentities and readIdentityObservations are the same tool but not the same read, so I kept both. readIdentities makes two ps calls (-o pid=,state=,lstart= and -o pid=,command=) and answers every pid it was given, with all-null facts where the host said nothing, because a caller deciding whether to signal must not read "no command" as "no process". readIdentityObservations makes one ps call (-o pid=,state=,lstart=) and omits pids the snapshot did not list, which is what the liveness classifier needs to tell "dead" from "not observed". One method would need a flag for the shape difference and would spawn two ps reads where one is wanted today. Happy to collapse them if you would rather carry the flag.

The earlier harmonyos thread stays resolved at this head; the shape-only asks stay closed as deferred.

Base automatically changed from refactor/0.22-harmonyos-platform-plugin to 0.22 November 21, 2026 16:32
@thymikee
thymikee force-pushed the fix/0.22-web-vega-plugin-host-routing branch from 5644fa6 to 39361c9 Compare November 21, 2026 16:39
Every process spawn, process-table read and diagnostic in @agent-device/web and
@agent-device/vega now goes through the PlatformHost the core hands setup(): one command route per
family is built there and handed to inventory, runtime, interactor, recorder and doctor, so neither
packed bundle carries a separate host-kit command or diagnostics scope. Each family gets a
`command-host.ts` that owns its argv and a `toolbox.ts` that binds the host, lazily and once per
setup, matching the shape the HarmonyOS plugin set in #4857.

Two host-kit reads the web and Vega plugins made directly became host ports rather than plugin code:
`isExecutableOnPath`, which is how Vega prefers a CLI from the host `PATH` before its home install,
and `listHostProcesses`, which is how the web provider derives the owned-process record for the fleet
it starts. The latter answers through the host's own executable resolution and apart from any command
override one request carries. The web plugin's `ManagedBrowserHost` and its optional-command and
optional-diagnostic fallbacks are gone: a toolbox is required, so a plugin surface can no longer run
a command nobody asked it to run.

Vega's inventory now loads with no core host at all, as HarmonyOS's already does, and its tool
provider takes the family's command runner instead of building ambient ones. The kernel gained
`commandFailureDetails` and `requireCommandSuccess` for a caller that holds a command answer and no
host, which is what a plugin on `PlatformHost.runCommand` holds; the exec-wrap guard accepts either
pair so neither family spreads the stdout/stderr/exitCode trio by hand.

With both families converted, the layering policy's per-file debt list is deleted rather than
emptied: a managed platform package is bound to its host from its first commit, and a file that
wants a host-kit command or diagnostic helper is a bug at that file.
The web fleet record still read processes through the plugin's own copy of the host kit:
`readProcessIdentities`, `readProcessExecutablePaths`, `readHostProcessIdentityObservationsAsync`, and
the startup reaper's `reapOwnedProcessRecordsAtStartup`. A managed plugin is bundled with its own copy
of that kit, and a request's command-host and diagnostic scopes never enter it, so each of those reads
answered with the daemon process environment and traced into the plugin's own store instead of the
request's. `--debug` for a web `open` that refreshed the record showed the backend spawn and nothing of
the reads that derived the record.

`PlatformHost` now answers these through a `processes` facet: the host's process table, per-pid identity
facts and observations, executable paths, and the reap of an owned-process record. It is served by the
core's own copy of the kit in `src/platform-runtime/plugin-host.ts`, where the request's scopes live, so
the read is in the environment and exec trace the request opened. `listHostProcesses` became
`processes.list`, and the fleet scan, the record's liveness probe, the install lock's claim on this
process's start time, and both orphan reapers now ask the host. The facet is reads plus that one reap: a
plugin never signals a pid it merely saw, only the ones a record it owns names.

The layering policy polices `host-kit/process` export by export now. Its 16 exports that reach the exec
layer join the ban for every managed family; the ones that read this process's own globals or compute
from what the caller holds (`hostPlatform`, `hostProcessId`, `isProcessAlive`, `expandProcessTree`,
`processStartTimesDiffer`) stay reachable, because they cannot leave the request's scope. A runtime edge
that names no export could reach any of them, so a namespace or bare import of the scope is refused.

Proof, in both directions: the core's host answers a table read, an identity read and a real reap of a
spawned child inside a `--debug` request's exec trace (`src/platform-runtime/plugin-host.test.ts`), and
the web fleet scan and startup reap make no process tool of their own — `spawn` and `spawnSync` are
refused for that module graph, and the reads it acts on are the ones its host answered
(`agent-browser-process-record-host-routing.test.ts`).

Also drops what the route made dead or wrong: `VegaToolbox` carried a host and a timer nothing read; the
HarmonyOS test host answered "on PATH" for every name because `whichCmd` returns a boolean; and an
orphaned JSDoc block sat above `managedStatusOptions` rather than the status reader it describes.

The packed-plugin gate names the reads too. It refused an `open` request that traced no process-table
read already; on macOS the scan also asks the host for each candidate's executable, which answers
through `osascript` (through a CIM query on Windows). A live packed run on this head traced six `ps`
reads and one `osascript` read under the one `open` request, so both kinds are asserted per request
rather than kept only in the evidence file.
Claiming the install lock reads this process's identity with `ps`, and every
poll of a held or stale lock re-proves the recorded owner and the guard holder
with another read. The plugin took the lock from its bundled host-kit copy, so
those reads ran with the daemon environment and traced into the bundle's own
store: a request that waited out another process's install showed no wait.

The host answers `processes.withLock`, and names its own identity there rather
than being told it. The async identity read is the one the request sees: it runs
`ps` through the command host, where the synchronous probe's `spawnSync` never
appears in the exec trace.

The packed web gate now asserts the plugin bundle carries no process tool, and
that a `web setup --debug` on a clean state dir traces both the lock's `ps` read
and the managed-backend install into the request that asked for it.
The platform package policy refused a managed platform's runtime import of a
host-kit export by looking the name up in a hand-kept per-scope list. A new
export that reached the exec layer escaped until someone added it, which is the
same failure the rule exists to catch.

The rule now reads the host-kit module graph: an export is refused unless the
graph proves its declaring module loads neither `internal/exec.ts` nor the
diagnostic store, and the allowed set is the same derivation. Namespace and bare
imports are refused, an unknown subpath is refused, and a missing exec root is
reported as stale instead of quietly widening the permission. Per-specifier
`type` markers are erased at runtime, so `ImportEdge` carries `typeSymbols` and
the reach rule judges only the value names an import binds.

`internal/host-process-facts.ts` and `internal/sleep.ts` split out of
`internal/host-process.ts` and `internal/retry.ts`: the pid arithmetic and the
timer import nothing, so those exports stay on the clean side of the line, and
the process tool's reads stay where they were.
Splitting `internal/host-process-facts.ts` and `internal/sleep.ts` out of the
host kit moved two eager modules into the closure of every entry that imports
them, which is what the eager-closure budget refuses: a clean leaf is not free,
it costs one evaluated module per closure that already evaluated the parent.
Both modules are merged back, so the process scope has no pure export left and
the derived rule refuses it wholesale — which is the sound verdict anyway: a
re-export of `isProcessAlive` still evaluates the module that loads the exec
layer, so no per-name permission for that scope could be honest.

The three managed plugins now ask their host instead of their bundled copy:

- `PlatformHost` carries the machine its commands run on — `hostOs`,
  `nodeExecutablePath`, `nodeVersion`, `temporaryDirectory`, `processId` — read
  once when the core builds the host. The web family builds its managed install
  layout, its npm argv, its launch executable, its Node capability read and the
  pid its fleet scan must skip from these.
- `PlatformHost.processes` answers two more questions the plugin cannot derive
  from rows it was given: `expandTree`, because only the host knows which
  parent-child relation its own table records, and `judgeRecordedLiveness`,
  because the fail-closed reading of a written record depends on the host's own
  start-time format and its own liveness probe. The host answers both from the
  core's copy, inside the request's exec trace.
- Pacing uses `node:timers/promises`, the timer the core's host waits on too.
  The retry scope of the bundled copy carries that scope's diagnostic store, and
  a wait between two backend sends belongs to no scope.

`readIdentityObservations` leaves the contract with no caller left: the record
probe asks the host to judge the records rather than reading observations it
would have to compare itself.

The policy tests now assert the merged truth: the file scope is still judged
name by name (the pure path helper imports, the lock helper does not), and the
process and retry scopes are refused for every managed family.
`WebStatusHost` restated the five machine facts the host answers instead of
naming the type the family already gives them to, so the list had two owners.
@apex-sentinel-staging

This comment has been minimized.

@thymikee
thymikee force-pushed the fix/0.22-web-vega-plugin-host-routing branch from 39361c9 to bde3144 Compare November 21, 2026 16:53
@thymikee

Copy link
Copy Markdown
Member Author

Rebased onto 0.22 at 9a12ab0 now that #4857 and #4872 merged; head bde3144. Conflicts resolved: the layering policy (debt list deleted), its tests (Linux joins the managed families in the shared fixtures), and one import list in packages/plugins/src/platform.ts. The stricter host-kit rule from this PR then flagged two Linux imports, fixed here: atspi-bridge.ts reads the OS from PlatformHost.hostOs instead of host-kit hostPlatform (also covers a #4878 item), and input pacing uses node:timers/promises instead of host-kit sleep. The Linux plugin test host answers the new machine and process facts. Local: build, typecheck, lint, layering, command-docs, daemon-wire-compat, check:package, full unit-core 20965 passed.

@blacksmith-sh

This comment has been minimized.

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on 1b94a43. The verdict and the full list are in the summary comment.

Comment thread packages/platform-vega/src/doctor.ts Resolved
@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of b283468

Since the review of 1b94a43: 0 new · 0 still open · 1 no longer raised (1 marked fixed)

No open findings.

Not in the reviewers' prompt (6 files)
  • docs/evidence/vega-managed-platform-2026-11-21.md: left out as an asset or for its size; reviewers could still search it
  • docs/evidence/web-managed-platform-2026-11-21.md: left out as an asset or for its size; reviewers could still search it
  • packages/platform-vega/src/__tests__/tool-provider-host-isolation.test.ts: left out as an asset or for its size; reviewers could still search it
  • packages/platform-web/src/agent-browser-lifecycle.test.ts: left out as an asset or for its size; reviewers could still search it
  • packages/platform-web/test/package-smoke.mjs: left out as an asset or for its size; reviewers could still search it
  • scripts/layering/platform-package-policy.test.ts: left out as an asset or for its size; reviewers could still search it

1 finding below minor hidden (user_settings.min_severity).

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

💬 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

This PR is ready at b283468. The install lock now goes through the host, the layering rule derives from the import graph, and the exec-backed reach policy reads correctly. All 15 checks pass, and the earlier replay-suite failure was on a previous head and touched no route in this delta. The conflict from the earlier review is resolved. Nothing else must happen before merge.

Not blocking, and fine to take or leave: plugin-host.ts:94 repeats the same five-key machine-fact list that WebMachine declares in packages/platform-web/src/toolbox.ts, so one exported PlatformHostMachine type in packages/plugins/src/platform.ts could serve all three. The PR body lists the processes facet without expandTree, judgeRecordedLiveness and the new machine facts, and it still says it is stacked on #4857, which has merged.

Both earlier inline threads no longer apply and can be resolved: the Vega doctor hint is now a fixed string with no host-separator join (thread), and the HarmonyOS test host still answers from whichCmd (thread).

Not verified here: tests and the packed web and vega gates were not run. The packed web setup --debug ps trace and the absence of node:child_process from the bundle come from reading package-smoke.mjs and from green CI, and the author reports a local check:package pass. Liveness polls on a held or stale install lock still use the core host-kit synchronous probes, which now run in the host copy and emit no exec record in --debug. That lock mechanism is only called by this PR, not introduced by it. The derived reach rule was not run against a synthetic new exec-backed export, so its coverage comes from reading host-kit-runtime-reach.ts and the policy tests.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 21, 2026
@thymikee
thymikee merged commit 5271581 into 0.22 Nov 21, 2026
15 checks passed
@thymikee
thymikee deleted the fix/0.22-web-vega-plugin-host-routing branch November 21, 2026 18:17
thymikee added a commit that referenced this pull request Nov 21, 2026
* refactor(web,vega): run each plugin's commands on its setup host

Every process spawn, process-table read and diagnostic in @agent-device/web and
@agent-device/vega now goes through the PlatformHost the core hands setup(): one command route per
family is built there and handed to inventory, runtime, interactor, recorder and doctor, so neither
packed bundle carries a separate host-kit command or diagnostics scope. Each family gets a
`command-host.ts` that owns its argv and a `toolbox.ts` that binds the host, lazily and once per
setup, matching the shape the HarmonyOS plugin set in #4857.

Two host-kit reads the web and Vega plugins made directly became host ports rather than plugin code:
`isExecutableOnPath`, which is how Vega prefers a CLI from the host `PATH` before its home install,
and `listHostProcesses`, which is how the web provider derives the owned-process record for the fleet
it starts. The latter answers through the host's own executable resolution and apart from any command
override one request carries. The web plugin's `ManagedBrowserHost` and its optional-command and
optional-diagnostic fallbacks are gone: a toolbox is required, so a plugin surface can no longer run
a command nobody asked it to run.

Vega's inventory now loads with no core host at all, as HarmonyOS's already does, and its tool
provider takes the family's command runner instead of building ambient ones. The kernel gained
`commandFailureDetails` and `requireCommandSuccess` for a caller that holds a command answer and no
host, which is what a plugin on `PlatformHost.runCommand` holds; the exec-wrap guard accepts either
pair so neither family spreads the stdout/stderr/exitCode trio by hand.

With both families converted, the layering policy's per-file debt list is deleted rather than
emptied: a managed platform package is bound to its host from its first commit, and a file that
wants a host-kit command or diagnostic helper is a bug at that file.

* refactor(web): read the browser fleet's processes through its host

The web fleet record still read processes through the plugin's own copy of the host kit:
`readProcessIdentities`, `readProcessExecutablePaths`, `readHostProcessIdentityObservationsAsync`, and
the startup reaper's `reapOwnedProcessRecordsAtStartup`. A managed plugin is bundled with its own copy
of that kit, and a request's command-host and diagnostic scopes never enter it, so each of those reads
answered with the daemon process environment and traced into the plugin's own store instead of the
request's. `--debug` for a web `open` that refreshed the record showed the backend spawn and nothing of
the reads that derived the record.

`PlatformHost` now answers these through a `processes` facet: the host's process table, per-pid identity
facts and observations, executable paths, and the reap of an owned-process record. It is served by the
core's own copy of the kit in `src/platform-runtime/plugin-host.ts`, where the request's scopes live, so
the read is in the environment and exec trace the request opened. `listHostProcesses` became
`processes.list`, and the fleet scan, the record's liveness probe, the install lock's claim on this
process's start time, and both orphan reapers now ask the host. The facet is reads plus that one reap: a
plugin never signals a pid it merely saw, only the ones a record it owns names.

The layering policy polices `host-kit/process` export by export now. Its 16 exports that reach the exec
layer join the ban for every managed family; the ones that read this process's own globals or compute
from what the caller holds (`hostPlatform`, `hostProcessId`, `isProcessAlive`, `expandProcessTree`,
`processStartTimesDiffer`) stay reachable, because they cannot leave the request's scope. A runtime edge
that names no export could reach any of them, so a namespace or bare import of the scope is refused.

Proof, in both directions: the core's host answers a table read, an identity read and a real reap of a
spawned child inside a `--debug` request's exec trace (`src/platform-runtime/plugin-host.test.ts`), and
the web fleet scan and startup reap make no process tool of their own — `spawn` and `spawnSync` are
refused for that module graph, and the reads it acts on are the ones its host answered
(`agent-browser-process-record-host-routing.test.ts`).

Also drops what the route made dead or wrong: `VegaToolbox` carried a host and a timer nothing read; the
HarmonyOS test host answered "on PATH" for every name because `whichCmd` returns a boolean; and an
orphaned JSDoc block sat above `managedStatusOptions` rather than the status reader it describes.

The packed-plugin gate names the reads too. It refused an `open` request that traced no process-table
read already; on macOS the scan also asks the host for each candidate's executable, which answers
through `osascript` (through a CIM query on Windows). A live packed run on this head traced six `ps`
reads and one `osascript` read under the one `open` request, so both kinds are asserted per request
rather than kept only in the evidence file.

* refactor(web): take the managed install lock through its host

Claiming the install lock reads this process's identity with `ps`, and every
poll of a held or stale lock re-proves the recorded owner and the guard holder
with another read. The plugin took the lock from its bundled host-kit copy, so
those reads ran with the daemon environment and traced into the bundle's own
store: a request that waited out another process's install showed no wait.

The host answers `processes.withLock`, and names its own identity there rather
than being told it. The async identity read is the one the request sees: it runs
`ps` through the command host, where the synchronous probe's `spawnSync` never
appears in the exec trace.

The packed web gate now asserts the plugin bundle carries no process tool, and
that a `web setup --debug` on a clean state dir traces both the lock's `ps` read
and the managed-backend install into the request that asked for it.

* refactor(scripts): derive the host-kit exports a managed plugin may load

The platform package policy refused a managed platform's runtime import of a
host-kit export by looking the name up in a hand-kept per-scope list. A new
export that reached the exec layer escaped until someone added it, which is the
same failure the rule exists to catch.

The rule now reads the host-kit module graph: an export is refused unless the
graph proves its declaring module loads neither `internal/exec.ts` nor the
diagnostic store, and the allowed set is the same derivation. Namespace and bare
imports are refused, an unknown subpath is refused, and a missing exec root is
reported as stale instead of quietly widening the permission. Per-specifier
`type` markers are erased at runtime, so `ImportEdge` carries `typeSymbols` and
the reach rule judges only the value names an import binds.

`internal/host-process-facts.ts` and `internal/sleep.ts` split out of
`internal/host-process.ts` and `internal/retry.ts`: the pid arithmetic and the
timer import nothing, so those exports stay on the clean side of the line, and
the process tool's reads stay where they were.

* refactor(plugins): answer every machine and process fact on the host

Splitting `internal/host-process-facts.ts` and `internal/sleep.ts` out of the
host kit moved two eager modules into the closure of every entry that imports
them, which is what the eager-closure budget refuses: a clean leaf is not free,
it costs one evaluated module per closure that already evaluated the parent.
Both modules are merged back, so the process scope has no pure export left and
the derived rule refuses it wholesale — which is the sound verdict anyway: a
re-export of `isProcessAlive` still evaluates the module that loads the exec
layer, so no per-name permission for that scope could be honest.

The three managed plugins now ask their host instead of their bundled copy:

- `PlatformHost` carries the machine its commands run on — `hostOs`,
  `nodeExecutablePath`, `nodeVersion`, `temporaryDirectory`, `processId` — read
  once when the core builds the host. The web family builds its managed install
  layout, its npm argv, its launch executable, its Node capability read and the
  pid its fleet scan must skip from these.
- `PlatformHost.processes` answers two more questions the plugin cannot derive
  from rows it was given: `expandTree`, because only the host knows which
  parent-child relation its own table records, and `judgeRecordedLiveness`,
  because the fail-closed reading of a written record depends on the host's own
  start-time format and its own liveness probe. The host answers both from the
  core's copy, inside the request's exec trace.
- Pacing uses `node:timers/promises`, the timer the core's host waits on too.
  The retry scope of the bundled copy carries that scope's diagnostic store, and
  a wait between two backend sends belongs to no scope.

`readIdentityObservations` leaves the contract with no caller left: the record
probe asks the host to judge the records rather than reading observations it
would have to compare itself.

The policy tests now assert the merged truth: the file scope is still judged
name by name (the pure path helper imports, the lock helper does not), and the
process and retry scopes are refused for every managed family.

* refactor(web): name the host's machine facts at its own type

`WebStatusHost` restated the five machine facts the host answers instead of
naming the type the family already gives them to, so the list had two owners.

* test(linux): answer the host's machine and process facts in the plugin test host

* test(layering): fit the policy test within its line cap

* refactor(linux): read the host OS and pace input without the bundled host kit

* style(layering): format the policy test within its line cap

* fix(vega): print the doctor install hint with POSIX separators on every host
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