Skip to content

fix(memory): report the Windows number that predicts paging, not just resident pages (#16211) - #16589

Merged
nwparker merged 2 commits into
mainfrom
nwparker/win-16211-private-bytes
Aug 26, 2026
Merged

nwparker merged 2 commits into
mainfrom
nwparker/win-16211-private-bytes

Conversation

@nwparker

@nwparker nwparker commented Aug 26, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 5 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​920 $\color{#cf222e}{\Huge{\mathbf{−}}}$​430 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​490
Prod 14 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​516 $\color{#cf222e}{\Huge{\mathbf{−}}}$​230 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​286

ELI5

On Windows, Orca was reading the wrong number when it told you how much memory your agents were using. It only counted the memory sitting in RAM right now — so when Windows shoved an agent's memory onto the disk to cope, the agent looked like it had shrunk, even though it was the thing making the machine crawl. Orca now also reads the number that counts everything an agent has claimed, paged out or not, and shows it next to the old one. When Orca's own claimed memory gets large compared to the machine's RAM, the figure goes yellow and then red instead of sitting there looking innocent.

What Changed

Original commit (bf5ffa2a258)

  • Reads committed private bytes on both Windows backends: one extra -Property PageFileUsage on the Get-CimInstance Win32_Process sweep that already runs (one more tab field, near-zero added cost), and \Process(*)\Private Bytes on the typeperf fallback.
  • Publishes it as a strictly additive parallel quantity — UsageValues.privateMemory?, MemorySnapshot.totalPrivateMemory?, MemorySnapshot.processCommitMetric?: 'private-bytes' (src/shared/process-stats-types.ts). totalMemory and processMemoryMetric keep their exact prior meaning.
  • Absence means unmeasured, never zero. Presence is data-driven (ProcIndex.hasPrivateMemory, set from the rows), not platform-driven, because the typeperf fallback can lack the counter. Unix and pre-field hosts emit no key at all; every reader guards on optional.
  • Surfaces: orca diagnostics memory gains totalPrivateMemory, processCommitMetric and a per-worktree committed figure (--json emits them verbatim); Resource Manager shows Σ Private beside Σ WS with its own tooltip, tinted with the existing usageTextColorClass 60/80 bands. Copy landed in all 5 locale catalogs with real translations.
  • Two files crossed max-lines and were split, not suppressed: parsers into windows-process-sample-parsing.ts, Windows sweep tests into collector-windows-sweep.test.ts. No max-lines disable added anywhere.

Fix round after review (8b4129fb5f8, +20 net lines: +26 test, −6 prod)

  • Fallback-path regression fixed. Adding a 4th typeperf counter against the fixed TYPEPERF_MAX_FIELDS = 8_192 had cut the parsable process count from ~2730 to ~2047, and overrun is a blackout (parseTypeperfCsvLine returns []), not truncation — every worktree would have read 0 B / 0% for a full 30 s CIM cooldown. TYPEPERF_COUNTERS moved into windows-process-sample-parsing.ts beside the decoder that reads those names back out of the PDH header, and the cap is now derived: 1 + TYPEPERF_COUNTERS.length * TYPEPERF_MAX_INSTANCES (4096 instances). The 1 MB line cap bounds memory independently.
  • Regression test still parses a busy host once a fourth counter widens every sample line (2100 instances × 4 counters = 8401 header fields).
  • collector.ts: the four different spellings of "omit privateMemory when the sweep could not measure it" collapsed onto one commitField(has, value) helper; the MeasuredUsage type and the destructure-then-respread are gone.
  • getResourceCommitMetricCopy lost its never-read _metric parameter; getCommitPressurePercent folded into getCommitPressureToneClass and unexported; columnLabel: 'Private' removed — nothing rendered it, and the return type is now Omit<ResourceMemoryMetricCopy, 'columnLabel'> so the type system enforces that there is no column until one exists.
  • The tint's doc comment no longer claims to predict paging (see Why).
  • Reverted unrelated Prettier churn in docs/reference/windows-process-enumeration.md; that diff is now only the 7-line committed-bytes paragraph.

Why

The metric structurally could not see the problem. WorkingSetSize counts resident pages, so an agent whose pages Windows has trimmed to the pagefile shrinks its working set while still holding the commit that caused the trim. No PageFileUsage, no PrivateMemorySize64, no Private Bytes existed anywhere under src/.

Measured on the reporter's 16 GB Windows host: 9 codex.exe showed 1.4 GB working set against 13.4 GB private bytes; 47 node.exe showed 5.3 GB against 9.2 GB — while the box committed 42 GB of a 46 GB limit at 27k–38k pages/sec. Orca reported ~2 GB of agents.

One claim in the issue is refuted, not implemented. The descendant walk already exists on main: collector.ts:218-240 collectSubtree does a full inclusive BFS and the per-PTY sum uses a claimed set to guard shared ancestors, so codex.exe and its MCP children were always included. Per AGENTS.md reuse-before-reimplementing, nothing was rebuilt.

Why additive and not a redefinition. Redefining 'working-set' to mean private bytes would make totalMemory mean different things per platform, break the deliberate Unix-RSS / Windows-working-set symmetry, turn the shipped "shared pages may repeat" copy into a lie, and reintroduce #10768 (over-counting virtual size).

Correction to this PR's previous description. The old body said "tracked commit is now shown as a percentage of physical RAM". No percentage is rendered anywhere — the share only drives the tint. The old body also framed the tint as a paging predictor ("committed bytes beyond RAM must be backed by the pagefile"). That is not what it measures: getCommitPressureToneClass compares Orca's own tracked commit to os.totalmem() (resource-memory-metric-copy.ts:43-66), which is neither the numerator nor the denominator Windows uses — Windows pages when system commit charge approaches the commit limit (RAM + pagefile). So it can tint yellow on a 64 GB host with a large pagefile that is paging nothing, and stay silent on a 16 GB host that other apps are thrashing. The fix round rewrote the doc comment to say what it actually measures and named host commit charge / commit limit as the follow-up; see Review.

Risk & Trade-offs

Merge risk: Low. The change is additive — every new key is optional and absent means unmeasured — and the two things that could have made it wrong are now measured on real Windows 11 hardware rather than argued about. (Was Medium; a correctness pass found no concrete defects, the end-to-end CIM path and the tint were captured on hardware, and the 32-bit PDH counter-width question — the one way this could have reported a badly wrong number — was ruled out by measurement. What is left is one honestly-labelled judgement call about the tint's denominator, which colours a number and changes no behaviour.)

What could go wrong

  • The tint cries wolf, or stays quiet when it shouldn't. getCommitPressureToneClass compares Orca's tracked commit to os.totalmem(), but Windows pages when system commit charge nears the commit limit (RAM + pagefile). On a 64 GB host with a big pagefile that is paging nothing, a heavy Codex session can tint yellow/red for no reason; on a 16 GB host that Chrome is thrashing, Orca's own share can stay under 60% and show nothing. Likely — not a corner case, it is what the formula does. Surfaces as "why is this red / why wasn't it red" reports from Windows users. Bounded: it is a colour on a number, no behaviour changes, nothing is throttled or killed.
  • The number is under-reported and still looks measured. hasPrivateMemory is decided sweep-wide — if any row carries PageFileUsage, the whole sweep is labelled private-bytes, while a row missing the field contributes 0. A user would see a Σ Private total that is quietly too low, with no indication it is partial. Practically unreachable: a dedicated correctness pass could not construct a case where Win32_Process returns a null PageFileUsage for a row that survives the existing date parse, and the hardware run never produced one. Left as a documented latent asymmetry on ProcIndex.hasPrivateMemory, not a defect. Would surface as Σ Private sitting implausibly close to (or below) Σ WS.
  • A >4 GB agent could report ~1.4 GB on the typeperf fallback. Measured and ruled out. On the same Windows 11 host, a node process holding 5.04 GiB reported \Process(node#42)\Private Bytes = 5.03 GiB — no wrap. Two unrelated live processes on that box corroborate above the boundary: vmmemWSL 4.95 GiB and codex#11 4.19 GiB, with _Total at 47.49 GiB. The PDH counter is 64-bit clean, so the @vscode/windows-process-tree DWORD truncation this PR documents does not apply to the typeperf path.
  • Σ Private blinks in and out every 30 s on the fallback path. If typeperf cannot resolve the counter name (localized Windows — the fallback is already English-only on main), the figure and its tint disappear during CIM cooldown and come back after. Self-healing and correct per "absent means unmeasured", but visually jumpy.
  • Two things remain unrun on Windows, and both are narrow. All 1270 tests are macOS unit tests against synthetic CIM/typeperf fixtures, but the parts that carried real risk have since run on a real Windows 11 host: the CIM path end to end (real PageFileUsage → Σ Private in the rendered popover), the 60-band tint on a real snapshot, and the PDH counter width above 4 GB (above). What is still unexercised in situ is (a) Orca's typeperf fallback code path — the counter itself was read on that host and is correct, but the fallback never took over during the capture — and (b) the red band, which was not reachable on a shared host and was explicitly not simulated (see Visual Proof).

What a user gets in exchange

On the reporter's 16 GB Windows host, Orca reported ~2 GB of agent memory while the machine was committing 42 GB of a 46 GB limit at 27k–38k pages/sec. The real figures: 9 codex.exe at 1.4 GB working set but 13.4 GB private bytes; 47 node.exe at 5.3 GB vs 9.2 GB. After this PR those numbers exist — in Σ Private in Resource Manager, and per worktree in orca diagnostics memory --json. The old totalMemory / working-set meaning is untouched, so nothing that reads it changes. Cost is one extra -Property on a CIM query that already runs and one extra counter on a typeperf call that already runs: no new poll, no new process spawn.

Trade-offs accepted

  • The tint ships knowing its denominator is wrong. Only the honest-labelling half of that review finding was applied — the doc comment no longer claims to predict paging. The real fix needs host-wide \Memory\Committed Bytes + Commit Limit on a slower cadence than the 2 s poll, plus new snapshot fields and plumbing, on top of an already ~1400-line PR. Follow-up owed: the remaining half of @sanshengai's slice 1 in [Bug]: Windows 16GB hosts page-thrash while diagnostics only report agent working-set #16211 — surface host commit charge / commit limit and threshold on host commit (~80%) instead of Orca's share of RAM.
  • No per-row attribution in the UI. privateMemory is collected, summed and shipped over IPC per worktree and per session, but only the total is rendered. The badge tells you something is wrong without telling you which worktree holds the commit; today the answer is CLI-only via orca diagnostics memory. Declined because every row metric goes through one shared <MetricPair cpu memory> at five call sites — a third value means a popover layout change, six construction sites, repo-group aggregation and two sort comparators. The dead columnLabel: 'Private' was removed rather than left as an unrendered promise.
  • #16211 is only half-closed. Linked as "Addresses part of", not Fixes. Host-wide memory and the hibernation-planner half remain open; the issue's claim that session accounting stops at the PTY is refuted, not implemented.
  • Two different Windows quantities under one label. CIM's PageFileUsage (VM_COUNTERS.PagefileUsage) and typeperf's Private Bytes (PrivateUsage) both publish as processCommitMetric: 'private-bytes'. Usually equal, not identical.
  • powershell.exe fork stays. windows-process-resource-collector.ts keeps the direct fork that windows-process-enumeration.md forbids, because @vscode/windows-process-tree exposes neither commit figures nor CPU times — migrating would cost both. Now recorded in the doc.
  • collector.ts grew from ~337 to ~384 effective lines under a max-lines disable that already existed on main. No new disable was added and two files were split rather than suppressed, but that file is drifting further from budget.

How to back it out

Clean revert. Nothing is persisted — the history ring is in-memory — so upgrade and rollback are both no-ops, and no migration is involved. Old CLI + new daemon ignores the extra JSON keys; new CLI + old daemon renders nothing. Paired web clients never receive this snapshot over the relay, so there is no wire change to unwind. The one thing a revert does not undo is the two max-lines file splits, which are independently fine to keep.

Linked Issue

Addresses part of #16211 — deliberately not Fixes.

  • This PR: the diagnostics half — Orca now reads and reports the Windows number that tracks commit, per app bucket, per session and per worktree.
  • Not in this PR: host-wide commit charge / commit limit and available RAM, and warning on host commit > ~80% rather than on Orca's share of physical RAM. That is item 1's remaining half in the issue's own "Proposed slices" and is the follow-up to inherit (see Review).
  • Separate branch: the hibernation-planner half of [Bug]: Windows 16GB hosts page-thrash while diagnostics only report agent working-set #16211 (the planner skipping the entire active worktree).

Visual Proof

Captured on a real Windows 11 host (32 GB RAM, 76.5 GB commit limit), because this surface does not exist anywhere else: getProcessMemoryMetric() returns 'working-set' only on win32, and totalPrivateMemory / processCommitMetric are emitted only when the Windows sweep actually measured them. Two dev builds were run side by side on that host, each with its own --user-data-dir and CDP port — one at origin/main (691759540a), one at this branch's tip (8b4129fb5f).

How the host state was produced — real memory, no simulation. Each instance opened a folder workspace with one terminal, which ran four node children that each Buffer.allocUnsafe 2 GB and fill it, so 8.85 GiB of genuine private commit sits in that terminal's process subtree. Then EmptyWorkingSet (psapi) was called on every process in that instance's own tree — which is precisely what Windows does to a process under memory pressure: the pages leave RAM for the pagefile and stay committed. Measured across the tree: working set 9.06 GiB → 0.02 GiB, private bytes 8.82 GiB → 8.85 GiB (unmoved), host free RAM 0.8 GB → 5.2 GB.

Before — origin/main After — this branch
1.3% · 223.5 MB Σ WS — one memory figure, no commit figure anywhere. Tooltip open on it, showing today's copy: "Summed working set (WS). Shared pages can appear in more than one process." 0.2% · 272.2 MB Σ WS · 8.76 GB Σ Private — same host, same workload, same trim. Tooltip open on the new figure: "…counted whether it is resident or paged out. This is what the host charges against its commit limit, so it keeps rising while the working set above shrinks under paging."

That is the whole bug in one line: main reports 223.5 MB for a process tree that is holding 8.85 GiB of committed memory, and it reports it lower the harder Windows pages that tree out.

Commit-pressure tint

Resource Manager with the commit figure tinted yellow

0.4% · 646.8 MB Σ WS · 20.88 GB Σ Private, with the commit figure and the status-bar badge tinted text-yellow-500: 20.88 GB against this host's RAM is 66.5%, over the 60 band. Produced by adding 12 GB of committed-but-untouched private bytes to the same subtree, which is why Σ WS barely moves while Σ Private nearly triples.

The red band (≥ 80%) was not captured, and nothing has been faked to stand in for it. It needs Orca's own tracked commit to reach 25.1 GiB on this host. The machine is shared with other agents' live work and was already committing ~52 GB of its 76.5 GB limit before this run (codex.exe 6.9 GB, claude.exe 5.9 GB, WSL 5.0 GB, orca-terminal-daemon.exe 4.3 GB, chrome.exe 3.9 GB, …); total free commit at the start was 24.0 GiB, so even driving the host's commit limit to exactly zero — and failing other people's allocations on the way — lands ~0.5 GiB short of the red threshold. It was not attempted. Yellow and red are the same call, usageTextColorClass((privateMemory / os.totalmem()) * 100), and the ≥ 80 → text-red-500 branch is covered by resource-memory-metric-copy.test.ts.

Testing

Ran in the fix worktree after the review fixes:

$ pnpm tc                                          → EXIT=0
$ pnpm test src/main/memory src/cli src/renderer/src/components/status-bar
   Test Files  141 passed (141)
        Tests  1270 passed (1270)
   Duration    5.79s                               → EXIT=0
$ npx oxlint <7 changed ts/tsx files>              → EXIT=0

(The earlier body quoted 1269 tests; it is 1270 after the new regression test.)

Non-vacuity, verified by running the new test against the pre-fix constant (TYPEPERF_MAX_FIELDS = 8_192):

 FAIL  windows-process-sample-parsing.test.ts > still parses a busy host once a fourth counter widens every sample line
AssertionError: expected [] to have a length of 2100 but got +0

Constant restored, suite green.

Reviewer independently re-ran pnpm tc, the memory/CLI/status-bar suites and oxlint on a clean checkout of the branch, and separately confirmed via comm over extracted it(...) names that the 430-line deletion from collector.test.ts lost zero tests — every name reappears in the two new files, so the max-lines split was a move, not a trim.

Correctness pass (post-fix round). A full correctness review of the branch found no concrete defects — no reachable case where a wrong number is produced. Two non-blocking observations came out of it: getResourceCommitMetricCopy returns the private-bytes wording unconditionally rather than switching on processCommitMetric (fine today — 'private-bytes' is the only value that exists — and its dead _metric parameter was already removed in 8b4129fb5f8), and the per-row absence asymmetry below, which is documented on ProcIndex.hasPrivateMemory rather than coded around because no reachable trigger for it could be constructed.

Windows 11 hardware run (32 GB RAM, 76.5 GB commit limit). Two dev builds side by side, origin/main (691759540a) vs this branch's tip (8b4129fb5f), each with its own --user-data-dir/CDP port — see Visual Proof for the captures.

  • CIM path, end to end: real Win32_Process.PageFileUsage values flowed through enumerateWindows → hasPrivateMemory → totalPrivateMemory into the rendered popover. 8.85 GiB of genuine private commit was allocated in a terminal subtree and then forced out of RAM with EmptyWorkingSet: across the tree, working set 9.06 GiB → 0.02 GiB while private bytes held at 8.82 → 8.85 GiB. main reported 223.5 MB for that tree; this branch reported the commit alongside it.
  • 60-band tint fired on that real snapshot (20.88 GB against 32 GB = 66.5%). The red band was not reached and was not simulated — the host had 24.0 GiB of free commit at the start, ~0.5 GiB short of the 25.1 GiB the red threshold needs.
  • 32-bit PDH counter width: ruled out by measurement. A node process holding 5.04 GiB reported \Process(node#42)\Private Bytes = 5.03 GiB — no wrap at the 4 GB boundary. Corroborated on the same host by two unrelated live processes above the boundary: vmmemWSL 4.95 GiB and codex#11 4.19 GiB (_Total 47.49 GiB). The typeperf path is 64-bit clean, so the @vscode/windows-process-tree DWORD truncation this PR documents does not apply to it. This closes what the earlier version of this description listed as an unmeasured risk.

Platforms: the suite above is macOS-host unit testing against synthetic CIM/typeperf fixtures. Still unexercised in situ: Orca's typeperf fallback code path (the counter was read directly on the host and is correct, but the fallback never took over during the capture) and the red tint band. SSH/remote: paired web clients build createEmptyMemorySnapshot() locally and never receive this snapshot over the relay, so there is no new stream opcode and nothing to capability-negotiate.

  • I manually tested these changes locally (unit/typecheck/lint on macOS, plus a real Windows 11 hardware run of both builds — see Visual Proof)
  • Automated tests added/updated

AI Disclosure

Review

Credit

@sanshengai — #16211 and #16219. They did not just report this; they specified it. #16211 arrives with a fully instrumented Windows host (working set vs private bytes broken out per process family, commit charge, pagefile usage, pages/sec), and its "Proposed slices" item 1 is almost verbatim what this PR ships: query PageFileUsage / private bytes alongside WorkingSetSize, add a parallel field, keep today's memory as working set so #10768 does not regress. The additive-field design, the field name, and the explicit refusal to redefine memory all originate with them — this PR implemented their spec, it did not discover it. Their #16219 is a separate attack on Orca's own footprint under the same umbrella (41.4 MiB Codex + 20.4 MiB Claude startup JSON down to ~2 MiB by partitioning the cold ownership ledger into a schema- and fingerprint-bound sidecar). Zero file overlap with this PR (src/main/usage/* vs src/main/memory/*), so no code was inherited — it should be reviewed on its own merits.

Inherited from @sanshengai's #16211 as the follow-up: the two undelivered parts of their slice 1 — surface host Committed Bytes / Commit Limit and available RAM, and threshold the warning on host commit rather than on Orca's share of physical RAM. That is exactly the correct fix for the P2 declined below; naming it here rather than pretending the current tint covers it.

@sanshengai — #16220, also under the #16211 umbrella: an optional sourceProjectionChanged signal so a no-op 5-minute usage refresh stops rewriting up to 61.8 MiB of provider JSON. Different subsystem, nothing to inherit, but it is real pressure on the same constrained hosts. Their optional-field-with-conservative-default stance (missing signal means "write") is the same discipline this PR applies to processCommitMetric (absent means unmeasured, never zero) — independent convergence, and worth noting that they got there first in their own PR.

One point in #16211 is respectfully refuted with evidence: "session accounting stops at the PTY" is not accurate — collectSubtree already does the inclusive BFS on main.

Correctness pass — no defects found

A full correctness review of the branch after the fix round found no concrete defects. Two non-blocking observations, neither of which changes a reported number: getResourceCommitMetricCopy hardcodes the private-bytes wording instead of switching on processCommitMetric (there is only one value today, and the dead _metric parameter was already removed in 8b4129fb5f8), and the per-row absence asymmetry below, documented rather than coded around.

Declined in the fix round — reviewers should know

  1. P2: the warning tint thresholds on the wrong quantity. Only the honest-labelling half was applied (doc comment rewritten, no code claims paging prediction). The real fix needs a new host-wide measurement (\Memory\Committed Bytes + Commit Limit, or Win32_OperatingSystem TotalVirtualMemorySize/FreeVirtualMemorySize) on a slower cadence than the 2 s poll, plus new snapshot fields and wire plumbing — a substantial addition to an already ~1400-line PR, and it is the inherited follow-up above. Until then the tint can false-alarm on a large-pagefile host and stay silent on a host other apps are thrashing.
  2. P2: per-worktree/per-session privateMemory is collected, summed and shipped over IPC but never rendered per row. The badge tells you something is wrong without telling you which worktree holds the commit; attribution is currently CLI-only via orca diagnostics memory. Declined on diff-growth/layout risk: every row metric goes through one shared <MetricPair cpu memory> at five call sites, so a third value is a popover layout change plus six construction sites, the repo-group aggregation and two sort comparators. The finding's dead-code evidence was taken — columnLabel: 'Private' is removed rather than left as an unrendered promise.

Residual risks, unproven rather than confirmed

  • Row-level under-count masked as measured. hasPrivateMemory is sweep-wide (collector.ts:187: true if any row has the field), but a row lacking it contributes clampNumber(undefined) === 0. If even one process yields an empty PageFileUsage while others do not, the total silently under-reports while still labelled private-bytes. Absence-means-unmeasured is enforced sweep-wide, not per row. Neither review round could construct a reachable case — no evidence Win32_Process ever returns a null PageFileUsage for a row that survives the CreationDate try/catch, and the hardware run produced none — so this stands as a documented latent asymmetry on ProcIndex.hasPrivateMemory, not a confirmed defect; rows.every(...) or a per-row "partial" flag would close it.
  • PDH counter width, unmeasured. Measured on hardware — closed. The open question was whether perflib emits \Process(*)\Private Bytes 32-bit, which would make a 5.7 GB codex.exe report ~1.4 GB. On a real Windows 11 host a node process holding 5.04 GiB reported 5.03 GiB through that counter, with vmmemWSL at 4.95 GiB and codex#11 at 4.19 GiB corroborating above the boundary. The typeperf path is 64-bit clean and the @vscode/windows-process-tree DWORD truncation (src/process.cc:59, still worth filing separately) does not apply to it. The CIM path was already safe (PageFileUsage is UInt32 in KB).
  • Two backends, one label. Win32_Process.PageFileUsage maps to VM_COUNTERS.PagefileUsage; \Process(*)\Private Bytes maps to PrivateUsage. Both are private commit and usually equal, but they are not the same Windows quantity, and both publish under the single processCommitMetric: 'private-bytes' label.
  • Backend flap. If typeperf cannot resolve Private Bytes (localized counter names — the typeperf fallback is already English-only on main, so pre-existing), hasPrivateMemory flips false during CIM cooldown and the Σ Private figure plus its tint vanish and reappear every 30 s. Correct per the absence semantics, visually jumpy.
  • collector.ts drift: ~337 → ~384 effective lines under a max-lines disable that already existed on main. No new disable was added, and the helper consolidation paid some back, but the file is moving away from the 300-line budget.
  • i18n: the tooltip summary is assembled by concatenating fragments with a hardcoded ' - ' separator (ResourceUsageStatusSegment.tsx), directly under a comment in resource-manager-terminal-copy.ts:53-54 warning that locales reorder and repunctuate that summary. Pre-existing pattern, now doing more work than that comment allows for.

Known deviation, deliberate

execFileText('powershell.exe', …) in windows-process-resource-collector.ts stays. It does violate windows-process-enumeration.md:14-15 and is the last non-test direct fork under src/main (#15749 migrated the others and missed it). Migrating conflicts head-on with this fix: @vscode/windows-process-tree exposes neither commit figures nor CPU times, so the migration would cost both. The doc's "what the snapshot does not provide" section now records this.

Agent skill upstream boundary

  • Not applicable — no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments or documentation is copied or translated here.

Notes

Security: no new inputs, no new process spawns — one extra -Property on an existing CIM query and one extra counter path on an existing typeperf invocation. Backwards compatibility: nothing is persisted (the history ring is in-memory), so upgrade and rollback are both no-ops; old CLI + new daemon ignores the extra JSON keys, new CLI + old daemon renders nothing (formatCommitLines returns []). Performance: no additional query per poll. Mobile/remote: paired clients never receive this snapshot.

Checklist

  • This PR is small and focused
  • I explained what changed and why (including ELI5)
  • Before/after screenshots or videos attached for UI changes (Windows 11 host; red-band tint explicitly not captured and not simulated — see Visual Proof)
  • Self-reviewed for correctness, security, and performance
  • Cross-platform, SSH/remote, and path/shortcut impact considered
  • pnpm lint, pnpm typecheck, pnpm test pass locally (pnpm build left to CI)

On Windows the per-process figure was working set — resident pages only.
An agent whose pages Windows has trimmed to the pagefile shrinks its
working set while still holding the commit that pushes the host into
paging, so Resource Manager and `orca diagnostics memory` understated an
owned tree by 10-40x (9 codex.exe: 1.4 GB working set, 13.4 GB private)
and could not warn before the host was already thrashing.

Add committed private bytes as a second, separately-labelled quantity
rather than redefining the existing one:

- CIM sweep gains one property (PageFileUsage, UInt32 KB); the typeperf
  fallback gains one counter (\Process(*)\Private Bytes). Both ride the
  sweep that already runs.
- MemorySnapshot gains optional `privateMemory` per app/worktree/session
  plus `processCommitMetric` and `totalPrivateMemory`. Rule 1 additive
  optional fields: old clients ignore them, and absence reads as "not
  measured", never as zero — Unix hosts and older hosts send nothing.
- `totalMemory` and `processMemoryMetric` keep their exact meaning, so
  the "shared pages may repeat" copy stays true; the working-set copy now
  also says paged-out memory is not counted.
- Resource Manager shows "Σ Private" beside "Σ WS", and tints the badge
  yellow/red once tracked commit passes 60/80% of physical RAM — the same
  thresholds `usageTextColorClass` already uses for host usage. Tint and
  tooltip only; no toast, and the badge number is unchanged.

The parsers move to windows-process-sample-parsing.ts and the Windows
sweep tests to their own file to stay under max-lines.

Not migrating the collector to windows-process-table.ts: the native
snapshot exposes no commit figure and no CPU times, and truncates
WorkingSetSize through a DWORD. Documented in the enumeration reference.
The fallback parser's 8192-field cap was sized for three `\Process(*)`
counters. Adding `Private Bytes` cut the parsable process count from ~2730
to ~2047, and overrun is a blackout (`parseTypeperfCsvLine` returns `[]`, so
the whole sweep reports nothing) rather than a truncation. The counter list
now lives beside the decoder that reads those names back out of the PDH
header, and the cap is derived from it.

Also collapses the four spellings of "omit privateMemory when unmeasured"
in collector.ts onto one `commitField` helper, drops the unread parameter
and the never-rendered `columnLabel` from `getResourceCommitMetricCopy`,
folds `getCommitPressurePercent` into the only function that called it, and
reverts unrelated Prettier churn in the Windows enumeration doc.

The commit tint's doc comment no longer claims to predict host paging: it
measures Orca's own share of physical RAM. Host commit charge / commit
limit stays a follow-up (#16211).
@nwparker
nwparker marked this pull request as ready for review August 26, 2026 22:36
@nwparker
nwparker requested a review from brennanb2025 as a code owner August 26, 2026 22:36
@nwparker
nwparker merged commit 64c992c into main Aug 26, 2026
58 checks passed
@nwparker
nwparker deleted the nwparker/win-16211-private-bytes branch August 26, 2026 22:43
@coderabbitai

coderabbitai Bot commented Aug 26, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

The change adds optional Windows private-memory collection based on committed bytes. New parsers process CIM and Typeperf output, and the collector aggregates values across applications, PTY sessions, and worktrees. Memory snapshots, CLI diagnostics, and remote probe summaries expose the new fields when available. The renderer displays committed memory with pressure-based coloring and localized descriptions. Tests cover parsing, aggregation, compatibility, formatting, fallback behavior, and renderer metric helpers.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 27.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 40 functions across 13 files. (6 skipped:… Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly and concisely describes the primary change: reporting Windows committed memory instead of only resident working-set memory.
Description check ✅ Passed The description follows the repository template and provides complete ELI5, change rationale, linked issue, visual proof, testing results, risks, compatibility notes, and checklist status. It also cle…
Full details: Docstring Coverage

Explanation

Docstring coverage is 27.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 40 functions across 13 files. (6 skipped: 6 unsupported.)

Full details: Description check

Explanation

The description follows the repository template and provides complete ELI5, change rationale, linked issue, visual proof, testing results, risks, compatibility notes, and checklist status. It also clearly documents known limitations and follow-up work.

  • Fix all pre-merge checks with AI
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e1acf316-34ef-4090-a7b2-e4b11eb32473

📥 Commits

Reviewing files that changed from the base of the PR and between 5e900b1 and 8b4129f.

📒 Files selected for processing (19)
  • config/scripts/remote-shared-control-retirement-probe.ts
  • docs/reference/windows-process-enumeration.md
  • src/cli/index-memory-diagnostics.test.ts
  • src/cli/workspace-format.ts
  • src/main/memory/collector-windows-sweep.test.ts
  • src/main/memory/collector.test.ts
  • src/main/memory/collector.ts
  • src/main/memory/windows-process-resource-collector.ts
  • src/main/memory/windows-process-sample-parsing.test.ts
  • src/main/memory/windows-process-sample-parsing.ts
  • src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
  • src/renderer/src/components/status-bar/resource-memory-metric-copy.test.ts
  • src/renderer/src/components/status-bar/resource-memory-metric-copy.ts
  • src/renderer/src/i18n/locales/en.json
  • src/renderer/src/i18n/locales/es.json
  • src/renderer/src/i18n/locales/ja.json
  • src/renderer/src/i18n/locales/ko.json
  • src/renderer/src/i18n/locales/zh.json
  • src/shared/process-stats-types.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 7 remain after this review.

"metric": {
"workingSetDescription": "Suma del conjunto de trabajo (WS). Las páginas compartidas pueden aparecer en más de un proceso.",
"workingSetDescription": "Suma del conjunto de trabajo (WS): las páginas residentes en RAM en este momento. Las páginas compartidas pueden aparecer en más de un proceso, y la memoria que Windows ha paginado a disco no se cuenta aquí.",
"privateBytesDescription": "Suma de bytes privados: la memoria que estos procesos han confirmado, contada tanto si está residente como si está paginada a disco. Es lo que el host imputa a su límite de confirmación, así que sigue subiendo mientras el conjunto de trabajo de arriba se reduce por la paginación.",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Remove the positional reference.

Line 3505 says el conjunto de trabajo de arriba, but the PR objective places Σ Private beside Σ WS. Remove de arriba so the description remains correct in the current layout.

The PR objective states that Σ Private appears beside Σ WS.

Proposed fix
-                "privateBytesDescription": "Suma de bytes privados: la memoria que estos procesos han confirmado, contada tanto si está residente como si está paginada a disco. Es lo que el host imputa a su límite de confirmación, así que sigue subiendo mientras el conjunto de trabajo de arriba se reduce por la paginación.",
+                "privateBytesDescription": "Suma de bytes privados: la memoria que estos procesos han confirmado, contada tanto si está residente como si está paginada a disco. Es lo que el host imputa a su límite de confirmación, así que sigue subiendo mientras el conjunto de trabajo se reduce por la paginación.",
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
"privateBytesDescription": "Suma de bytes privados: la memoria que estos procesos han confirmado, contada tanto si está residente como si está paginada a disco. Es lo que el host imputa a su límite de confirmación, así que sigue subiendo mientras el conjunto de trabajo de arriba se reduce por la paginación.",
"privateBytesDescription": "Suma de bytes privados: la memoria que estos procesos han confirmado, contada tanto si está residente como si está paginada a disco. Es lo que el host imputa a su límite de confirmación, así que sigue subiendo mientras el conjunto de trabajo se reduce por la paginación.",

dallascrilley pushed a commit to dallascrilley/orca that referenced this pull request Aug 27, 2026
… resident pages (stablyai#16211) (stablyai#16589)

* fix(memory): report Windows commit charge, not just working set (stablyai#16211)

On Windows the per-process figure was working set — resident pages only.
An agent whose pages Windows has trimmed to the pagefile shrinks its
working set while still holding the commit that pushes the host into
paging, so Resource Manager and `orca diagnostics memory` understated an
owned tree by 10-40x (9 codex.exe: 1.4 GB working set, 13.4 GB private)
and could not warn before the host was already thrashing.

Add committed private bytes as a second, separately-labelled quantity
rather than redefining the existing one:

- CIM sweep gains one property (PageFileUsage, UInt32 KB); the typeperf
  fallback gains one counter (\Process(*)\Private Bytes). Both ride the
  sweep that already runs.
- MemorySnapshot gains optional `privateMemory` per app/worktree/session
  plus `processCommitMetric` and `totalPrivateMemory`. Rule 1 additive
  optional fields: old clients ignore them, and absence reads as "not
  measured", never as zero — Unix hosts and older hosts send nothing.
- `totalMemory` and `processMemoryMetric` keep their exact meaning, so
  the "shared pages may repeat" copy stays true; the working-set copy now
  also says paged-out memory is not counted.
- Resource Manager shows "Σ Private" beside "Σ WS", and tints the badge
  yellow/red once tracked commit passes 60/80% of physical RAM — the same
  thresholds `usageTextColorClass` already uses for host usage. Tint and
  tooltip only; no toast, and the badge number is unchanged.

The parsers move to windows-process-sample-parsing.ts and the Windows
sweep tests to their own file to stay under max-lines.

Not migrating the collector to windows-process-table.ts: the native
snapshot exposes no commit figure and no CPU times, and truncates
WorkingSetSize through a DWORD. Documented in the enumeration reference.

* fix(memory): derive the typeperf field cap from the counter list

The fallback parser's 8192-field cap was sized for three `\Process(*)`
counters. Adding `Private Bytes` cut the parsable process count from ~2730
to ~2047, and overrun is a blackout (`parseTypeperfCsvLine` returns `[]`, so
the whole sweep reports nothing) rather than a truncation. The counter list
now lives beside the decoder that reads those names back out of the PDH
header, and the cap is derived from it.

Also collapses the four spellings of "omit privateMemory when unmeasured"
in collector.ts onto one `commitField` helper, drops the unread parameter
and the never-rendered `columnLabel` from `getResourceCommitMetricCopy`,
folds `getCommitPressurePercent` into the only function that called it, and
reverts unrelated Prettier churn in the Windows enumeration doc.

The commit tint's doc comment no longer claims to predict host paging: it
measures Orca's own share of physical RAM. Host commit charge / commit
limit stays a follow-up (stablyai#16211).
rahuljangirworks pushed a commit to rahuljangirworks/veer that referenced this pull request Aug 27, 2026
… resident pages (stablyai#16211) (stablyai#16589)

* fix(memory): report Windows commit charge, not just working set (stablyai#16211)

On Windows the per-process figure was working set — resident pages only.
An agent whose pages Windows has trimmed to the pagefile shrinks its
working set while still holding the commit that pushes the host into
paging, so Resource Manager and `orca diagnostics memory` understated an
owned tree by 10-40x (9 codex.exe: 1.4 GB working set, 13.4 GB private)
and could not warn before the host was already thrashing.

Add committed private bytes as a second, separately-labelled quantity
rather than redefining the existing one:

- CIM sweep gains one property (PageFileUsage, UInt32 KB); the typeperf
  fallback gains one counter (\Process(*)\Private Bytes). Both ride the
  sweep that already runs.
- MemorySnapshot gains optional `privateMemory` per app/worktree/session
  plus `processCommitMetric` and `totalPrivateMemory`. Rule 1 additive
  optional fields: old clients ignore them, and absence reads as "not
  measured", never as zero — Unix hosts and older hosts send nothing.
- `totalMemory` and `processMemoryMetric` keep their exact meaning, so
  the "shared pages may repeat" copy stays true; the working-set copy now
  also says paged-out memory is not counted.
- Resource Manager shows "Σ Private" beside "Σ WS", and tints the badge
  yellow/red once tracked commit passes 60/80% of physical RAM — the same
  thresholds `usageTextColorClass` already uses for host usage. Tint and
  tooltip only; no toast, and the badge number is unchanged.

The parsers move to windows-process-sample-parsing.ts and the Windows
sweep tests to their own file to stay under max-lines.

Not migrating the collector to windows-process-table.ts: the native
snapshot exposes no commit figure and no CPU times, and truncates
WorkingSetSize through a DWORD. Documented in the enumeration reference.

* fix(memory): derive the typeperf field cap from the counter list

The fallback parser's 8192-field cap was sized for three `\Process(*)`
counters. Adding `Private Bytes` cut the parsable process count from ~2730
to ~2047, and overrun is a blackout (`parseTypeperfCsvLine` returns `[]`, so
the whole sweep reports nothing) rather than a truncation. The counter list
now lives beside the decoder that reads those names back out of the PDH
header, and the cap is derived from it.

Also collapses the four spellings of "omit privateMemory when unmeasured"
in collector.ts onto one `commitField` helper, drops the unread parameter
and the never-rendered `columnLabel` from `getResourceCommitMetricCopy`,
folds `getCommitPressurePercent` into the only function that called it, and
reverts unrelated Prettier churn in the Windows enumeration doc.

The commit tint's doc comment no longer claims to predict host paging: it
measures Orca's own share of physical RAM. Host commit charge / commit
limit stays a follow-up (stablyai#16211).
paidaxingyo666 pushed a commit to paidaxingyo666/Manta that referenced this pull request Aug 28, 2026
… resident pages (stablyai#16211) (stablyai#16589)

* fix(memory): report Windows commit charge, not just working set (stablyai#16211)

On Windows the per-process figure was working set — resident pages only.
An agent whose pages Windows has trimmed to the pagefile shrinks its
working set while still holding the commit that pushes the host into
paging, so Resource Manager and `orca diagnostics memory` understated an
owned tree by 10-40x (9 codex.exe: 1.4 GB working set, 13.4 GB private)
and could not warn before the host was already thrashing.

Add committed private bytes as a second, separately-labelled quantity
rather than redefining the existing one:

- CIM sweep gains one property (PageFileUsage, UInt32 KB); the typeperf
  fallback gains one counter (\Process(*)\Private Bytes). Both ride the
  sweep that already runs.
- MemorySnapshot gains optional `privateMemory` per app/worktree/session
  plus `processCommitMetric` and `totalPrivateMemory`. Rule 1 additive
  optional fields: old clients ignore them, and absence reads as "not
  measured", never as zero — Unix hosts and older hosts send nothing.
- `totalMemory` and `processMemoryMetric` keep their exact meaning, so
  the "shared pages may repeat" copy stays true; the working-set copy now
  also says paged-out memory is not counted.
- Resource Manager shows "Σ Private" beside "Σ WS", and tints the badge
  yellow/red once tracked commit passes 60/80% of physical RAM — the same
  thresholds `usageTextColorClass` already uses for host usage. Tint and
  tooltip only; no toast, and the badge number is unchanged.

The parsers move to windows-process-sample-parsing.ts and the Windows
sweep tests to their own file to stay under max-lines.

Not migrating the collector to windows-process-table.ts: the native
snapshot exposes no commit figure and no CPU times, and truncates
WorkingSetSize through a DWORD. Documented in the enumeration reference.

* fix(memory): derive the typeperf field cap from the counter list

The fallback parser's 8192-field cap was sized for three `\Process(*)`
counters. Adding `Private Bytes` cut the parsable process count from ~2730
to ~2047, and overrun is a blackout (`parseTypeperfCsvLine` returns `[]`, so
the whole sweep reports nothing) rather than a truncation. The counter list
now lives beside the decoder that reads those names back out of the PDH
header, and the cap is derived from it.

Also collapses the four spellings of "omit privateMemory when unmeasured"
in collector.ts onto one `commitField` helper, drops the unread parameter
and the never-rendered `columnLabel` from `getResourceCommitMetricCopy`,
folds `getCommitPressurePercent` into the only function that called it, and
reverts unrelated Prettier churn in the Windows enumeration doc.

The commit tint's doc comment no longer claims to predict host paging: it
measures Orca's own share of physical RAM. Host commit charge / commit
limit stays a follow-up (stablyai#16211).

(cherry picked from commit 64c992c)
enrick-dev pushed a commit to enrick-dev/orca that referenced this pull request Oct 15, 2026
… resident pages (stablyai#16211) (stablyai#16589)

* fix(memory): report Windows commit charge, not just working set (stablyai#16211)

On Windows the per-process figure was working set — resident pages only.
An agent whose pages Windows has trimmed to the pagefile shrinks its
working set while still holding the commit that pushes the host into
paging, so Resource Manager and `orca diagnostics memory` understated an
owned tree by 10-40x (9 codex.exe: 1.4 GB working set, 13.4 GB private)
and could not warn before the host was already thrashing.

Add committed private bytes as a second, separately-labelled quantity
rather than redefining the existing one:

- CIM sweep gains one property (PageFileUsage, UInt32 KB); the typeperf
  fallback gains one counter (\Process(*)\Private Bytes). Both ride the
  sweep that already runs.
- MemorySnapshot gains optional `privateMemory` per app/worktree/session
  plus `processCommitMetric` and `totalPrivateMemory`. Rule 1 additive
  optional fields: old clients ignore them, and absence reads as "not
  measured", never as zero — Unix hosts and older hosts send nothing.
- `totalMemory` and `processMemoryMetric` keep their exact meaning, so
  the "shared pages may repeat" copy stays true; the working-set copy now
  also says paged-out memory is not counted.
- Resource Manager shows "Σ Private" beside "Σ WS", and tints the badge
  yellow/red once tracked commit passes 60/80% of physical RAM — the same
  thresholds `usageTextColorClass` already uses for host usage. Tint and
  tooltip only; no toast, and the badge number is unchanged.

The parsers move to windows-process-sample-parsing.ts and the Windows
sweep tests to their own file to stay under max-lines.

Not migrating the collector to windows-process-table.ts: the native
snapshot exposes no commit figure and no CPU times, and truncates
WorkingSetSize through a DWORD. Documented in the enumeration reference.

* fix(memory): derive the typeperf field cap from the counter list

The fallback parser's 8192-field cap was sized for three `\Process(*)`
counters. Adding `Private Bytes` cut the parsable process count from ~2730
to ~2047, and overrun is a blackout (`parseTypeperfCsvLine` returns `[]`, so
the whole sweep reports nothing) rather than a truncation. The counter list
now lives beside the decoder that reads those names back out of the PDH
header, and the cap is derived from it.

Also collapses the four spellings of "omit privateMemory when unmeasured"
in collector.ts onto one `commitField` helper, drops the unread parameter
and the never-rendered `columnLabel` from `getResourceCommitMetricCopy`,
folds `getCommitPressurePercent` into the only function that called it, and
reverts unrelated Prettier churn in the Windows enumeration doc.

The commit tint's doc comment no longer claims to predict host paging: it
measures Orca's own share of physical RAM. Host commit charge / commit
limit stays a follow-up (stablyai#16211).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant