Skip to content

fix(windows): preserve caller affinity only within one processor group - #2202

Merged
morluto merged 3 commits into
morluto:mainfrom
Rinkia:fix/windows-affinity-processor-groups
Oct 13, 2026
Merged

morluto merged 3 commits into
morluto:mainfrom
Rinkia:fix/windows-affinity-processor-groups

Conversation

@Rinkia

@Rinkia Rinkia commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Fixes #2181.

Cause

spawnProcess read the caller's affinity mask and applied it to the suspended
child unconditionally:

require(GetProcessAffinityMask(GetCurrentProcess(), &affinity, &systemAffinity), ...);
if (affinity != 0)
  require(SetProcessAffinityMask(result->process.get(), affinity), ...);

A mask names processors relative to one processor group, and Windows assigns
each new process to a group of its own choosing. On a host whose logical
processors span more than one group, the child is often placed in a group whose
active processors are not a superset of the caller's mask, so
SetProcessAffinityMask rejects it with ERROR_INVALID_PARAMETER (87). The
require made that fatal, so every owned provider spawn — the JavaScript
analysis worker and the other owned helpers — failed randomly depending on
which group Windows picked.

Change

Affinity is a scheduling nicety, not an authority, ownership or isolation
control, so it is now applied only when the caller and the suspended child both
occupy the same single processor group. A child placed in another group keeps
that group's default affinity and the spawn proceeds.

GetProcessGroupAffinity establishes membership for both processes. A process
whose threads span groups, or whose membership cannot be read, has no single
group to compare and is treated as unknown rather than as aligned, so no mask is
applied. Within a shared group the mask failure stays fatal, because there it is
not expected.

Unchanged: Job Object membership and kill-on-owner-close verification, breakaway
denial, child default-owner normalization, priority preservation, and the
suspended-create-then-resume sequence.

Single-group hosts — every host with 64 or fewer logical processors, and any
larger host whose caller and child land in the same group — behave exactly as
before: one group is reported for both processes and the same mask is applied.

Note for the >64-processor case on current Windows: since Windows 11 and Server
2022 a process's affinity spans all groups by default, so GetProcessAffinityMask
reports 0 and the existing affinity != 0 guard already skipped the call. The
reported host is Windows 10 19045, where the legacy per-group assignment applies
and the failure is reachable.

Tests and docs

  • tests/fixtures/windows/processBoundary.cc gains an affinity observation
    reporting the process's own mask, whether it occupies a single processor group,
    and which group.
  • scripts/verify-windows-native.mjs asserts that an owned spawn of that
    fixture succeeds, and that the child's mask equals the caller's whenever both
    report the same single group. On a multi-group host the exit-code assertion is
    the regression test for this issue; the mask comparison is correctly skipped
    because no mask is expected to carry across groups.
  • native/windows/README.md and docs/windows-ghidra-p0.md both stated that
    caller CPU affinity is preserved without qualification. They now state the
    processor-group condition and what a child in another group gets instead.

Validation

Windows 11 Pro 26100 x64, Node 24.16.0:

  • npm run docs:check — 6/6 tasks pass, including check-doc-facts.mjs.
  • npx oxfmt --check scripts/verify-windows-native.mjs — clean.
  • npm run lint — clean, module boundaries checked across 1,568 source files.
    The max-lines warning on scripts/verify-windows-native.mjs predates this
    change.
  • npm run build:cached — passes.
  • Windows x64 native artifact cross-built with the documented lane
    (node scripts/build-windows-native.mjs on Linux with MinGW-w64 g++ 12 in a
    container, since this host has no C++ toolchain). process.cc compiles
    without new warnings. npm run verify:windows-native:artifact reports
    ok: true for ABI 1 / Node-API 8, SHA-256
    a036a9e4…5606e4, 842,929 bytes.
  • node scripts/verify-windows-native.mjs . <process-boundary.exe> on this real
    Windows host against that artifact and an independently cross-built boundary
    fixture: ok: true, all 20 filesystem controls and all 12 process
    observations pass, including the new
    callerAffinityPreservedWithinProcessorGroup. The caller observation was
    {"affinityMask":4095,"singleProcessorGroup":true,"processorGroup":0} and the
    child reported the same, so the mask-equality assertion ran rather than being
    skipped.

Explicitly not verified: the failing multi-group path itself. This host has 12
logical processors, which is one processor group, so the rejected-mask branch
cannot occur here and only the unchanged single-group path is exercised. The
reasoning for the multi-group branch comes from the Win32 contract for
processor groups
and GetProcessGroupAffinity, plus the experimental analysis in #2181.
Confirmation on a host whose processors span more than one group — @hzh666kevin-hue's
88-processor, 2-group machine would do it — is still wanted, and the new
assertion is written to cover exactly that case.

🤖 Generated with Claude Code

`spawnProcess` read the caller's affinity mask and applied it to the
suspended child unconditionally. A mask names processors relative to one
processor group, and Windows assigns each new process to a group of its
own choosing, so on hosts with more than 64 logical processors the child
is often placed in another group. `SetProcessAffinityMask` then rejects
the mask with ERROR_INVALID_PARAMETER (87) and the spawn fails, making
every owned provider process start intermittently on such hosts.

Affinity is a nicety, not an authority or isolation control, so it is now
applied only when the caller and the suspended child both occupy the same
single processor group. A child placed in another group keeps that group's
default affinity and the spawn proceeds. Job Object membership,
kill-on-owner-close policy, owner normalization and priority preservation
are unchanged, and the mask failure remains fatal within a shared group,
where it is not expected.

Single-group hosts, including every host with 64 or fewer logical
processors, are unaffected: `GetProcessGroupAffinity` reports one group
for both processes and the same mask is applied as before.

The optional process-boundary fixture gains an `affinity` observation,
and the native verification lane asserts that an owned spawn succeeds and
that the child's mask matches the caller's whenever both share a single
group.

Fixes morluto#2181

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-12T14:31:38.798288Z 699a640 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aca0503d51

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread native/windows/src/process.cc Resolved
Comment thread scripts/verify-windows-native.mjs Resolved
Addresses review feedback on the first commit.

An unconstrained caller loses nothing when Windows places an owned child
in another processor group, so that spawn proceeds with the group's
default. A caller deliberately pinned to fewer processors than its group
holds is a different case: silently accepting the default would hand the
provider tree the whole group, which `docs/installation.md` tells
operators to rely on affinity to prevent. Such a spawn now fails naming
the constraint instead. `GetProcessAffinityMask` already reports the
group's active set, which distinguishes the two without another query.

Selecting the caller's group at creation through
PROC_THREAD_ATTRIBUTE_GROUP_AFFINITY was tried first and rejected:
`CreateProcessW` fails with ERROR_INVALID_PARAMETER on a host with a
single processor group, both alongside PROC_THREAD_ATTRIBUTE_JOB_LIST and
on its own, so it cannot carry the ordinary path.

The boundary fixture's affinity observation now reports a process id's
own mask rather than its own, because a separate probe process is
assigned its own group and cannot stand in for the process that spawns
the child. Masks and the group's active set cross as fixed-width
hexadecimal strings: a mask can set bits above the safe-integer range,
where `JSON.parse` would round two different masks to one value.

The verification lane asserts the mask is inherited exactly when caller
and child share a group, and otherwise that the caller was unconstrained.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 699a64034c

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread native/windows/src/process.cc Resolved
A mask covering its group's whole active set does not distinguish a
caller the system placed in that group from one that selected the group
deliberately, so an owned child can still be placed elsewhere with its
processor count bounded and its group placement lost. Treating that case
as constrained instead is not available: on a multi-group host an
ordinary process is assigned a group by the system and its mask is that
group's active set, so refusing it would fail every owned spawn there.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

@baron baron left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Exact-head review: e1a2f2c. No confirmed additional source defect: explicit narrow affinity is kept within one applicable group or refused when not representable, while a full default mask is not misrepresented as a caller-selected CPU-count restriction.

Merge is held for matching native affinity-boundary verification. The inspected green current-head Windows job runs verify:windows-native without its optional boundary fixture, so it does not execute the new processor-group observation/assertion path. Please provide exact-head caller/group observations and the changed cross-group/refusal evidence, or an explicit maintainer verification decision. The earlier single-group report has older mask/report-key wording and does not settle this final candidate. No local Windows/affinity operation or verification waiver was performed.

@morluto

morluto commented Oct 13, 2026

Copy link
Copy Markdown
Owner

@greptileai review

@greptile-apps

greptile-apps Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[High impact] The PR appears safe to merge; no actionable defect or security issue was established.

Summary

The PR applies caller CPU affinity only when caller and child share one processor group.

  • Owned Windows spawns apply caller CPU limits only when groups match.

No actionable issue was established. Available local history shows no later replacement for this change; live PR status could not be checked because GitHub authentication was unavailable.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Create suspended child inside owned job] --> B[Read caller mask and both process groups]
  B --> C{Nonzero mask and same single group?}
  C -->|Yes| D[Apply caller mask]
  C -->|No| E{Zero mask or full group mask?}
  E -->|Yes| F[Keep child default affinity]
  E -->|No| G[Throw and close owned job]
  D --> H[Preserve priority and verify job membership]
  F --> H
  H --> I[Resume child]
Loading

Reviews (1) · Last reviewed commit: "docs(windows): record what owned-process..." · Reviewed by Greptile

@morluto
morluto merged commit ab62ee9 into morluto:main Oct 13, 2026
33 checks passed
@morluto morluto added bug Something isn't working area: runtime Process capture and runtime observation labels Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: runtime Process capture and runtime observation bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] Windows: owned process spawn fails intermittently with Win32 87 (ERROR_INVALID_PARAMETER) on multi-processor-group systems

3 participants