test(onboard): add a child-process harness for four pilot suites

[JulienAu]

Summary

Four onboarding suites each hand-rolled the same child-process mechanics: a mkdtemp workspace with a fake bin directory, a 0o755 stub writer, HOME and PATH environment composition, a synchronous node spawn from the repository root, and trailing JSON payload extraction. This is sequential PR 1 of issue #8289: it moves those mechanics into test/helpers/onboard-child-process-harness.ts and migrates the four pilot suites, leaving stub script contents, scenario environment values, and assertions in each test.

Related Issue

Refs #8289 (sequential PR 1 of 4; the issue stays open for the remaining slices)

Changes

• Add test/helpers/onboard-child-process-harness.ts: createOnboardProcessWorkspace (disposable workspace with created bin and optional separate home), workspaceEnv and minimalSpawnEnv (fresh environment objects; the minimal variant carries the Windows spawn keys), runOnboardProcess (synchronous node spawn from the repository root with decoded output), and trailingJsonPayload. Requirement and consumers: the four pilot suites below, with the remaining onboard suites planned as follow-ups in Establish root test fixtures for repeated process and environment setup #8289. A direct change cannot remove the duplication because each suite owns an inline copy; the protecting tests are the migrated suites themselves.
• Migrate test/onboard-remote-recreate-credential-reuse.test.ts (four near-identical env blocks become one scenario env factory), test/onboard-prepared-gateway-handoff.test.ts, test/onboard-gateway-port-conflict-fast-fail.test.ts, and test/onboard-reservation-recreate.test.ts. Every migrated file has a negative line delta; the security-relevant scenario values (blanked credential env vars, probe logs) stay explicit in the tests.
• Register the reservation fixture's disposable workspace for cleanup after every test completion.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification: test-only consolidation; the four migrated suites are the protected behavior and pass unchanged.
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: test harness only; no user-facing surface or documented behavior changes.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: maintainer security review passed for the test-only harness, preserved environment/stub behavior, and cleanup lifecycle; see test(onboard): add a child-process harness for four pilot suites #8537 (comment).
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: an independent writer reviewed all five changed test paths, the completed cleanup, and the new helper docstrings. The change is internal test infrastructure with no user-facing surface or documented behavior change.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable — contributor validation passed except for the documented pre-existing hadolint information message on an unchanged Dockerfile; the maintainer cleanup commit passed normal pre-commit, commit-msg, and pre-push hooks.
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — contributor result: three migrated suites pass fully (7 tests) in normal and shuffled order. onboard-gateway-port-conflict-fast-fail times out identically on unmodified main in the contributor's WSL2 environment, so hosted CI is the arbiter for that suite. Maintainer result: all three reservation cleanup scenarios pass after the lifecycle fix.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: JulienAu 16043912+JulienAu@users.noreply.github.com

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 19362ca1-6b98-4223-9bea-7b0707e87180

📥 Commits

Reviewing files that changed from the base of the PR and between bfa3edb and 93123b6.

📒 Files selected for processing (1)

• test/onboard-reservation-recreate.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• test/onboard-reservation-recreate.test.ts

---

📝 Walkthrough

Walkthrough

The pull request adds a reusable onboarding child-process harness. Four onboarding tests now use shared workspace creation, fake executable setup, environment construction, process execution, output capture, JSON extraction, and cleanup.

Changes

Onboard child-process harness

Layer / File(s)	Summary
Workspace and environment utilities test/helpers/onboard-child-process-harness.ts	Adds temporary workspace creation, fake executable writing, cleanup, and workspace or minimal spawn environments.
Process execution and payload handling test/helpers/onboard-child-process-harness.ts	Adds typed process options and results, synchronous Node execution with timeout handling, output normalization, and trailing JSON extraction.

Onboarding test migration

Layer / File(s)	Summary
Gateway and handoff test migration test/onboard-gateway-port-conflict-fast-fail.test.ts, test/onboard-prepared-gateway-handoff.test.ts	Replaces manual temporary directories, environment setup, process execution, payload parsing, and cleanup with shared harness utilities.
Recreate scenario test migration test/onboard-remote-recreate-credential-reuse.test.ts, test/onboard-reservation-recreate.test.ts	Uses shared workspace, executable, environment, process, JSON payload, and cleanup helpers while preserving scenario assertions.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested labels: refactor, chore

Suggested reviewers: apurvvkumaria

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding a reusable child-process harness for four onboarding test suites.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed after a partial review · low confidence · 0 blockers · 0 warnings · 0 suggestions

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• justified — minimal spawn environment at test/helpers/onboard-child-process-harness.ts:86: Keep this test-local term because it names the constrained inheritance behavior.
• justified — trailing JSON payload at test/helpers/onboard-child-process-harness.ts:13: Keep this test-local term because it identifies the parser selection rule.
• established — fake bin at test/helpers/onboard-child-process-harness.ts:12: Keep the established term and meaning.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite against this exact revision.

Recommended E2E: None

3 optional E2E recommendations

• onboard-resume
• onboard-repair
• concurrent-gateway-ports

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[apurvvkumaria]

Maintainer validation and security disposition

• Addressed the remaining cleanup gap by registering the reservation fixture's disposable workspace with Vitest's test-finished cleanup.
• Failure classification: under local Node.js 26, the gateway fast-fail case and two prepared-handoff cases time out on both this branch and current main; the other five pilot cases pass. That is a local runtime/baseline limitation, not a regression introduced here. The repository's Node.js 22 CI is rerunning for the updated branch.
• Focused evidence: reservation cleanup scenarios 3/3 passed; Vitest project membership, test-title checks, CLI type checking, repository checks, formatting, lint, secret scanning, commit lint, and pre-push checks passed.
• Security review: PASS across secrets, input handling, authorization, dependencies, error/logging behavior, cryptography, configuration, security testing, and holistic posture. This is test-only infrastructure with no production, dependency, workflow, policy, or public API change. Existing environment inheritance and local stub behavior are preserved, and the temporary workspace is now cleaned on every reservation-test completion.
• Documentation writer review: no-docs-needed. An independent writer reviewed all five changed test paths and the helper docstrings; no user-facing behavior or documentation surface changed.
• Contributor and maintainer commits both include DCO sign-off and appear as Verified on GitHub. No actionable review threads remain.