[Cedric Vidal (cedricvidal)]

Summary

Clean dependency installs in minimal Node images attempted two optional native builds from the transitive ssh2 dependency chain: ssh2's bundled crypto binding and cpu-features. When Python, a compiler, or node-gyp prerequisites were unavailable, those scripts printed alarming error-shaped diagnostics before correctly continuing with ssh2's supported JavaScript implementation. The install succeeded, but the output looked like a genuine dependency failure.

This change makes that fallback deliberate and quiet by moving only ssh2 and cpu-features from pnpm's onlyBuiltDependencies allowlist to ignoredBuiltDependencies. This is safe for Scope because ssh2 is reached only through Docker test tooling, its package documents the native addons as optional optimizations, and Dockerode's local-socket path works through the JavaScript implementation. Required dependency scripts remain explicitly allowlisted, including esbuild, keytar, and protobufjs. No install command uses --ignore-scripts, ignoreDepScripts, stderr suppression, error filtering, or a success-shaped wrapper around a failing install.

Regression assertions verify the narrow ignored list, preserve required build allowlisting, and reject broad lifecycle-script suppression. CONTRIBUTING.md documents the explicit fallback policy.

This is layer 4 of the six-PR native stack #1610 and depends directly on #1603. The branch has been synchronized with the current lower-layer base using normal commits; this PR is based on cedricvidal-decouple-pnpm-bootstrap and does not include the later Portal Git metadata or storage-guidance layers.

Demos

N/A — dependency installation behavior only; validation is captured in build and test output.

Before

N/A — clean minimal Node image installs emitted node-gyp/Python/compiler failures from optional ssh2 and cpu-features native builds, then continued with the valid JavaScript fallback.

After

N/A — a clean dependency-layer install deliberately omits those two optional native scripts, emits no native compiler failure output, still runs required lifecycle scripts, and loads the Dockerode JavaScript path successfully.

Testing

• PASS — pnpm exec vitest run scripts/bootstrap-pnpm.test.ts --reporter=default: 1 file, 8 tests. The suite asserts ssh2/cpu-features are narrowly ignored, required scripts remain allowlisted, and Docker install commands do not use --ignore-scripts.
• PASS — pnpm --filter shared build && pnpm --filter telemetry build && pnpm --filter test-utils build && pnpm --filter coder-acp-copilot build && pnpm --filter coder-acp-claude-code build.
• PASS — pnpm --filter test-utils exec node --input-type=module -e "...": Dockerode local-socket client initialized through the JavaScript path.
• PASS — clean no-cache dependency-layer image build from the locally cached Node 24 / pnpm 10.29.1 Copilot worker image, using a fresh /validation workspace and pnpm install --offline --force --frozen-lockfile. The required esbuild postinstall ran successfully; ssh2 and cpu-features produced no install-script output.
• PASS — captured build-log assertion found no node-gyp, gyp ERR, Failed to build optional crypto binding, missing Python/compiler, or cpu-features build output.
• PASS — container assertion found installed ssh2 and cpu-features package trees and confirmed they contain no native .node bindings.
• PASS — pnpm headers:check: all 967 in-scope files have the required header after final-base synchronization.
• PASS — git diff --check.
• PASS — final-base CI on head 66dd8c65e09a87b8dfb2a09d626dd091e5d192ae: CI Summary, Windows Worker Build, Unit Tests (22; 3,257/3,257), Build Applications, Lint Code, CLI Bundle Integration Tests, Third-party NOTICE, License Headers, detect-changes, gitleaks, CLA, and changed-file labeling. Integration, LLM evaluation, and gateway jobs were skipped by their normal change-detection conditions.

Environment limitation: the first fully fresh node:24-slim validation reached the unchanged pinned pnpm bootstrap, but this Docker runtime could not establish TLS to registry.npmjs.org (ECONNRESET) through either Corepack or npm. The successful no-cache dependency-layer validation therefore reused the local pnpm content-addressable store in offline mode while creating a fresh workspace and node_modules. No credentials were used or captured, and the layer-3 registry/bootstrap contract was not changed.

Documentation and compatibility

Updated CONTRIBUTING.md to document the explicit pure-JavaScript fallback and the requirement to keep unrelated dependency build scripts enabled. No dependency versions or lockfile entries changed, so NOTICE regeneration was not required. There are no breaking changes, runtime API changes, Portal/CLI behavior changes, database migrations, or upgrade steps.

Checklist

• If Portal features changed, keep CLI capabilities in sync. N/A — no Portal changes.
• If Portal components changed, update their Storybook stories. N/A — no Portal components changed.
• If database changes require a migration, include up() / down() and keep it CosmosDB-compatible. N/A — no database changes.
• If dependencies changed, update the lockfile and regenerate NOTICE / NOTICE-REVIEW.txt with pnpm notice as needed. N/A — dependency versions and lockfile are unchanged; Third-party NOTICE passed in final-base CI.
• Video showing the behavior before the suggested change. N/A — build-log-only behavior.
• Video showing the behavior after the suggested change. N/A — build-log-only behavior.

[github-actions]

Test Results (Node.js 22)

test: Run #446

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
3257	3257	0	0	0	0	0	1m30s

🎉 All tests passed!

Github Test Reporter

[github-actions]

Test Results (Node.js 22)

test: Run #449

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
3259	3259	0	0	0	0	0	1m13s

🎉 All tests passed!

Github Test Reporter

[github-actions]

Test Results (Node.js 22)

test: Run #455

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
3259	3259	0	0	0	0	0	1m29s

🎉 All tests passed!

Github Test Reporter

[github-actions]

Test Results (Node.js 22)

test: Run #457

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
3246	3246	0	0	0	0	0	1m29s

🎉 All tests passed!

Github Test Reporter

[github-actions]

Test Results (Node.js 22)

test: Run #461

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
3246	3246	0	0	0	0	0	1m29s

🎉 All tests passed!

Github Test Reporter

[Wassim Chegham (manekinekko)]

LGTM. The optional native-build fallback is narrowly scoped and preserves the required dependency build scripts. One non-blocking test-hardening observation inline.

[github-actions]

Test Results (Node.js 22)

test: Run #479

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
3246	3246	0	0	0	0	0	1m23s

🎉 All tests passed!

Github Test Reporter

[github-actions]

Test Results (Node.js 22)

test: Run #499

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
3246	3246	0	0	0	0	0	1m35s

🎉 All tests passed!

Github Test Reporter