mirror of https://github.com/stablyai/orca.git synced 2026-10-23 16:03:49 +00:00

Files

T

Neil 9a6a59d98b perf(windows): read the process table natively instead of forking PowerShell

Seven independent readers each forked powershell.exe to run
Get-CimInstance Win32_Process, with a wmic fallback that Windows 11 24H2
has removed. On a domain-joined host with PowerShell Transcription
enabled by policy, one of them running every ~2s recorded ~289GB across
1.4 million files (#15209). The same scan cost ~700ms and ran per pane
(#15036), and a Group Policy or AV block turned it into 'unavailable',
which callers read as 'no evidence' -- which is how a PTY tree survives
its own teardown (#9045, #10475).

A Toolhelp32 snapshot answers the same question with no child process.
Measured on Windows 11 with 1050 processes, p50/p95:

  pid+ppid+name          15.9 / 17.5 ms
  +memory +command line  30.6 / 33.7 ms
  Get-CimInstance         706 / 723  ms

Two upstream defects needed patching, both found by running it on real
hardware. The binding requires Spectre-mitigated libraries our agents do
not carry (node-pty is patched the same way). And enumeration stopped
after 1024 processes: on a host with 1051 the module returned exactly
1024, and the querying process was itself among the 27 missing -- a
truncated snapshot silently hides the descendants teardown is looking
for, which is the failure this whole change exists to remove.

Migrated: the foreground/descendant reader (the #15209 scraper and the
teardown identity gate) and the port scanner's PID attribution. NOT
migrated: the memory collector and three identity probes, which need
Win32_Process.CreationDate and have no native equivalent. Start time is
a proxy for identity anyway; an inherited job handle is the real answer,
so those belong with the job-object work rather than here.

Packaging follows the windows-native-registry contract exactly:
optional, absent from onlyBuiltDependencies so macOS/Linux never run
node-gyp, win32-only in the packaged runtime. Asserted by the existing
contract test, which also stops pinning a whole source literal that only
tested its own formatting.

2026-08-21 21:21:19 -07:00

3.8 KiB

Raw Blame History

Reading the Windows process table

Orca needs three things from the Windows process table: who a PID's parent is (descendant walks and teardown identity), what a process is running (agent recognition), and how much memory/CPU it uses (Resource Manager).

Node cannot answer the first one without native code. That is why seven independent readers existed, each forking powershell.exe to run Get-CimInstance Win32_Process, with a wmic fallback that Windows 11 24H2 has since removed.

Use the native snapshot

src/main/windows/windows-process-table.ts is the only module that may read the table. It wraps a Toolhelp32 snapshot from @vscode/windows-process-tree.

import { readWindowsProcessTable, readWindowsProcessTableFresh } from '../windows/windows-process-table'

readWindowsProcessTable() — shared TTL cache. Use for anything periodic.
readWindowsProcessTableFresh() — a snapshot that starts after the call. Use for teardown identity, where a cached row can predate the exit it is being asked about.

Both reject when the table cannot be read. Do not convert that into an empty array. An empty table is a claim that nothing is running, and callers act on that claim by declaring a tree dead or a shell childless. "Unavailable" has to stay distinguishable from "empty" — collapsing the two is how a PTY tree survived its own teardown (#9045).

Measured on Windows 11 with 1050 processes (p50 / p95):

	p50	p95
pid + ppid + name	15.9 ms	17.5 ms
+ memory + command line	30.6 ms	33.7 ms
`Get-CimInstance` via PowerShell	706 ms	723 ms

Why the package is patched

config/patches/@vscode__windows-process-tree@0.8.0.patch carries two hunks.

Spectre mitigation. The upstream binding.gyp requires Spectre-mitigated libraries, which Orca's Windows build agents do not install. node-pty is patched the same way for the same reason.
The 1024-process cap. GetRawProcessList stopped after 1024 entries. Measured on a real host with 1051 processes, the module returned exactly 1024 and the querying process was itself among the 27 missing. A truncated snapshot silently hides the descendants a teardown is trying to reap — the exact failure the native path exists to remove.

The typings claim commandLine is truncated at 512 characters. Measured, it is not: the longest observed on a real host was 26,059.

Packaging

The addon is Windows-only, so it follows the same contract as windows-native-registry (asserted by config/scripts/package-electron-runtime-contract.test.mjs):

an optionalDependency, so a macOS/Linux install tolerates its absence;
not in pnpm.onlyBuiltDependencies — pnpm installs optional dependencies on every host, and macOS/Linux must never run node-gyp for it;
listed in the win32 branch of rebuild-native-deps.mjs and ensure-native-runtime.mjs;
copied into the packaged node_modules for win32 only.

What the snapshot does not provide

CreationDate (process start time) has no equivalent. Anything using a start time to prove a PID has not been recycled — daemon identity, managed-hook ownership, and CPU accounting in the memory collector — still reads it through its own query. Those callers are not migrated.

Start time is a proxy for identity, not identity. The durable answer for the process trees Orca itself spawns is an inherited handle: a job object names the tree Orca created, so no start-time comparison is needed. Those readers should be resolved that way rather than by adding a start time to this module.

Do not adopt getProcessCpuUsage() from the package. It takes both CPU samples inside one call with a blocking Sleep(1000) in the middle, which would hold a libuv threadpool slot for a full second out of the Resource Manager's two-second poll.

3.8 KiB Raw Blame History