Hosted and vendored pnpm scans add keys to an empty or comment-only pnpm-workspace.yaml without packages:, so every pnpm 8.x–10.4 command then fails with "packages field missing or empty" #1096

[agent] Found by the scheduled pnpm bug-hunt routine (ledger #303).

Summary

When a single-package pnpm project has a pnpm-workspace.yaml that is empty or holds only comments (a common placeholder for settings), pnpm ≤ 10.4 treats it as "no workspace" and installs normally. After a hosted or vendored scan:

• scan --mode hosted appends only trustLockfile: true (the TrustPlan::Append path), and
• scan --mode vendored appends only an overrides: block,

neither adds packages:. pnpm 9.0.0–10.4.1 then refuse every command in the project (install, install --frozen-lockfile, run, …):

 ERROR  packages field missing or empty

Both scans report status: success. The hosted warning even says "pnpm <=10 ignores the setting and installs work unchanged", which is false here. When no workspace file exists, both modes write the packages: ['.'] scaffold for exactly this reason (WS_SCAFFOLD_PACKAGES comment: "pnpm 9 refuses a workspace file whose packages field is missing or empty"). The append path into an existing file skips that guard.

Hosted rollback restores the lock byte-exactly but keeps the appended trustLockfile: true (it warns pnpm_trust_lockfile_left), so the project stays broken on pnpm 9 after rollback too. Vendored rollback restores the workspace file.

Impact

Every developer and CI job on pnpm 9.x or 10.0–10.4 gets a hard install failure on the next checkout of the scanned commit. The scan gives no hint that it changed pnpm's workspace semantics.

Repro (pnpm 9.15.9, Linux)

mkdir proj && cd proj
echo '{"name":"fx","version":"1.0.0","dependencies":{"left-pad":"1.3.0","ms":"2.1.3"}}' > package.json
pnpm install                      # pnpm 9.15.9, lockfileVersion 9.0
printf '# pnpm settings go here\n' > pnpm-workspace.yaml   # or an empty file
pnpm install                      # still fine: exit 0
socket-patch scan --mode hosted --json --yes   # (or --mode vendored) -> status success
cat pnpm-workspace.yaml
# # pnpm settings go here
# trustLockfile: true
rm -rf node_modules && pnpm install --frozen-lockfile
#  ERROR  packages field missing or empty      (exit 1)

(Run against a local mock of the patch API serving patches for left-pad@1.3.0 and ms@2.1.3. The same happens with --mode vendored, which appends overrides: instead.)

Expected vs actual

• Expected: hosted mode's trust config is harmless on pnpm ≤ 10. docs/ecosystems.md says "pnpm <=10 does not need the setting", and the scan's own warning says "pnpm <=10 ignores the setting and installs work unchanged". A scan that reports success should leave a project that pnpm can still install (CLI_CONTRACT: hosted/vendored rewrites must keep the next frozen install working).
• Actual: pnpm 9.0–10.4 can no longer install or run anything in the project. Hosted rollback doesn't undo it.

Matrix (Linux, main 05ecc6e)

Each failing cell reproduced at least twice (empty and comment-only file, pnpm 9.15.9 and 10.4.1, fresh frozen install with an empty store and in-place pnpm install / pnpm run).

Not a regression: release 4.0.0 (npm @socketsecurity/socket-patch@4.0.0) behaves the same. With an empty file it even writes \ntrustLockfile: true with no trailing newline.

Suspect code

• crates/socket-patch-core/src/hosted/guidance.rs:276-280: plan_workspace_trust inserts trustLockfile: true into an existing document that has no packages: key. Only the Create branch (line 252) adds packages: ['.'].
• crates/socket-patch-core/src/vendor/pnpm_lock.rs:1899 (apply_workspace_override): when the workspace file exists, it adds the overrides: section without WS_SCAFFOLD_PACKAGES (line 99), which is used only when it creates a file.
• crates/socket-patch-core/src/formats/pnpm/workspace.rs:62 (block_insert_point) accepts "" and "# only a comment\n" as insertable documents (unit-tested), so nothing flags the missing key.

Related but different: #734 covers the packages: ['.'] scaffold that hosted mode creates when no file exists (pnpm add fails with ERR_PNPM_ADDING_TO_ROOT). This issue is the opposite path: an existing file gets appended to without packages:, and every install fails.

No probe runs: Linux-only this run.

Backlog review — 2026-10-08

Priority: P1 → P2. An empty pnpm-workspace.yaml causes older supported pnpm commands to refuse. Visible compatibility failure.