[ViperJuice]

See #195.

origin/main moved while this was in flight (2.5.2 and the workflow guards);
merged in, with the 2.5.2 nullable-spelling tests re-pointed at the two-path
fixture rather than dropped. No version bump originates here.

What this does

detect_package_type(command, args) derives a package identity from a server's
launch command line, and the freshness gate reads a matching identity as
positive confirmation that a cached tool description still describes the
configured package. A wrong identity therefore serves one server another
server's tool descriptions.

That parser has been repaired five times in production (#180 → #192 → #194 →
#195 → the 2.5.2 nullable-boolean spelling). Every defect was in the rules
around the hand-written flag tables rather than a missing entry, and every one
produced a confident wrong answer. This replaces the guessing with npm's own
parser plus aggressive refusal.

For an npx/npm server, a persistent node child (src/pmcp/manifest/_npm_resolve.js)
loads the host npm's own nopt, its own @npmcli/config definitions and its
own npm-package-arg — through a createRequire rooted at the resolved
bin/npx-cli.js, so the modules always come from the same npm the pre-scan was
read from — and runs a verbatim port of npx-cli.js lines 10–123, including
all three of its flag sets, with switches recomputed from the host's live
definitions. The identity is remain[1], not remain[0]: npx-cli.js:7 splices
exec into argv, and exec is a real published package, so reading remain[0]
would have made gateway.update_server probe npx -y exec@latest --help for all
79 npx servers in the manifest.

The refusal gates

An allowlist of plain shapes, not a denylist of dangerous ones — three
adversarial rounds on a denylist each found another way for a confident answer
to be wrong, because every npm_config_* option is equally settable as a
command-line flag and npm keeps adding new ones.

Gate	Refuses when
parsed config keys	any key beyond --yes/--package. That includes --registry, --userconfig, --prefix, --cache, --call, --workspace, a shorthand like --silent (which expands to --loglevel), and unknown flags, which nopt reports as boolean keys
server env overlay	npm_config_* (case-insensitive), PATH, HOME, NODE_PATH, NODE_OPTIONS, PREFIX, NVM_*
gateway process env	npm_config_* or NODE_OPTIONS — sticky for the process
effective cwd	npm would set a local prefix (package.json or node_modules in any ancestor), because a project .npmrc can rename the package and a node_modules/.bin entry means npm never reaches the registry
npm subcommand	no package operand: npm run/start/test/create, a typo, bare npm -y pkg, and npm dlx (pnpm/yarn spelling — npm dlx probe is Unknown command, yet it sat in the tables' subcommand allowlist)
npm-package-arg type	anything but tag/version/range. Notably alias: npx -y myalias@npm:left-pad really runs left-pad, and the corpus confirms it against the binary — the tables mint myalias-zz, a squattable different package
--package	zero, or more than one distinct value
package operand	it starts with -. The npm majors disagree about what such a token names — see below — so it cannot be named with certainty
npm subcommand, again	the subcommand check runs first and unconditionally, so --package cannot short-circuit it. npm run/start/test/create/dlx/rum --package=X and bare npm --package=X all refuse
npm install/i/add	a package config key is present (npm reads it for exec/x only), or the operand list is not exactly one package. npm install a b and npm install a c are two configurations, not one
npm locatability	an npx/npm entry point is on PATH but its package root cannot be found. That is not absence, so it must not reach the tables
drift	the spawn-time self-test fails, bin/npx-cli.js is not one this port was verified against, or npm's parser will not load

Tri-state, and only one state may consult the tables. IDENTITY returns the
spec raw (_strip_npm_tag stays in detect_package_type, because
update_server's pin detection needs the suffix). REFUSED returns None and
never scans the tables. UNAVAILABLE — spawn failed, i.e. no node or no
npm root — falls through to the tables, which is the pre-2.5.2 behaviour and all
a node-less host can do.

A failed self-test refuses; it does not degrade to the tables. A failed
self-test is precisely the evidence that the tables' model of npm is wrong, so
consulting them there is fail-open.

Resolved an internal contradiction in the plan's Drift section. It said both
"a hash mismatch takes the same REFUSED path — there is no UNAVAILABLE-with-reason
state; that phrasing was rev 3's and is gone" and, two sentences later, "a
mismatch produces the same UNAVAILABLE-with-reason + WARNING". Implemented as
REFUSED-for-lifetime + one WARNING, matching the sentence that declares the other
phrasing gone and matching acceptance criterion 5.

Measured cost

Zero on the shipped manifest. All 79 npm-family servers use the plain
npx -y <pkg> shape; all 79 resolve, and all 79 match the package the real npx
binary fetches.

The cost lands on unusual forms, and it is real — these are cases where the
resolver refuses and the binary would have resolved:

form	binary fetches	tables said
npx --pack zz bin	zz	(refused)
npx --frobnicate valpkg realbin	valpkg	(refused)
npm exec --loglevel silly aaa	aaa	aaa
npm exec --global true aaa	aaa	aaa
npx --userconfig X probe-a	probe-a	probe-a
npx --prefix X probe-a	probe-a	probe-a
npx --cache X probe-a	probe-a	probe-a
npx --package=p --call='echo hi'	p	p
npm create foo	create-foo	(refused)
npx -y myalias@npm:left-pad	left-pad	myalias-zz ← wrong

A refused server keeps running. It loses auto-update and version reporting, its
descriptions regenerate every refresh cycle, and check_staleness lists it
permanently stale. That is a cost, not a correctness problem — and it is why the
allowlist is drawn to cover the plain shape rather than as tightly as possible.

Runtime. 43 ms of one-time child startup (including the self-test corpus) and
~0.9 ms per query; 200 distinct resolves in 0.188 s with one spawn.
detect_package_type is synchronous and called from inside async coroutines, so
one-shot invocation (4.02 s for 79) was not an option.

Accepted residual

A package= or registry= line in a user or global .npmrc changes what npm
resolves and the resolver cannot see it. Project-level .npmrc is covered by the
local-prefix refusal, and npm_config_* in the gateway's own environment is now
covered by the process-environment check. The user/global rc file is the one
input that remains unguarded, and it is stated here rather than discovered later.

Operational note: a sticky refusal does not recover on its own — a
disabled resolver keeps no child, so nothing re-checks the host. It logs one
WARNING that now names the restart requirement, and gateway.health →
gateway_diagnostics.npm_identity reports the state on demand. Those two are the
only surfaces; without them a fleet-wide loss of auto-update would be invisible.
A transient child death is different: the respawn budget is time-based (60 s,
re-arming), so it cannot strand a long-running gateway.

Verification (measured, this branch)

pytest, everything except tests/runtime   3129 passed, 3 skipped, 25 deselected  (262.42s)
pytest tests/runtime -k "not stdio"       52 passed, 8 deselected                (63.03s)
ruff check src/ tests/                    All checks passed!
ruff format --check src/ tests/           118 files already formatted
mypy src/                                 Success: no issues found in 43 source files
differential corpus, seed 561426559       227 rows, 0 UNSAFE  -- on BOTH majors
  npm 11.19.0                             126 IDENTITY, 126 == binary, 5 beat the tables
  npm 10.8.2                              126 IDENTITY, 126 == binary, 5 beat the tables
  AC1 required-to-resolve (enforced)       89/89 IDENTITY and matching (79 manifest + 10)
cross-major invariance (same child,        286 cases, 0 diverging
  same corpus, 10.8.2 vs 11.19.0)
98-entry manifest, node-less PATH         98 pairs compared, 0 differing vs 2.5.2
node-less pytest (identity suites)        235 passed, 134 skipped
wheel install into a clean venv           helper OK: left-pad

The corpus now enforces AC1's positive half: every manifest row and every
req-* row must be IDENTITY and match the binary. Before, "zero unsafe rows"
judged every refusal safe, so a refuse-everything resolver passed — verified by a
negative control that stubs the resolver to refuse everything and now exits 1.

Where the resolver beats the tables, confirmed against the binary:

form	resolver	tables	binary
npx --yes=maybe tok bin2	maybe	tok	maybe
npx --yes null aaa	null	(refused)	null
npx --no-install -y=false --userconfig 1 --pack (fuzz)	false	(refused)	false

Acceptance criterion 6 — an unconverted call site must be a type error:

$ # one caller reverted in memory, mypy run, original bytes written back
src/pmcp/manifest/refresher.py:308: error: Missing positional arguments "env",
    "cwd" in call to "get_package_version"  [call-arg]
Found 1 error in 1 file (checked 43 source files)

env/cwd are required and undefaulted on detect_package_type,
_npm_package_arg, get_package_version and _detect_effective_version_pin; a
test asserts they carry no default, so a habitual = None cannot creep back.

Deviations from the amendment of record

The coordinator's amendment (D1–D12) is reproduced verbatim below. Three
deviations, all measured:

1. D9's discriminator does not discriminate. D9 asked for npx --pack zz bin
   → zz node-ful, ("unknown", None) node-less. Measured: nopt reports an
   unknown flag as a boolean config key ({pack: true}), which the step-1
   allowlist refuses — so it is ("unknown", None) on both paths. Substituted
   npx --yes=maybe tok (yes is allowlisted, so it survives the gate):
   node-ful maybe, node-less tok, binary maybe. The coordinator verified
   and accepted this.
2. D6's set sizes are wrong (removedSwitches has 3 entries, not 10).
   Immaterial — the port is verbatim from the real file, all three sets included.
   Also accepted.
3. D10/D5 classifications, chosen and stated rather than inferred: npm root
   not found → UNAVAILABLE (the plan names it); parser-load failure and a
   pre-handshake protocol violation → REFUSED-for-lifetime (npm is present and
   unmodellable, which is the self-test situation, not "we learned nothing").
   Sticky recovery needs a gateway restart; the transient-death budget is
   time-based.

Board findings on the diff, and what they changed

The diff was boarded twice. Six must-fixes, every one reproduced before it was
touched and re-measured after.

#	Defect	Before	After
1	--package short-circuited the npm subcommand allowlist — #183 fully reopened	npm run --package=pkg-a -- bin → ('npm','pkg-a'); same for start/test/create/dlx/rum/bare npm	all ('unknown', None); npx --package=X -- bin still resolves
2	UNAVAILABLE assigned too broadly, and it is the one state that may use the tables	missing packaged helper, and any Popen OSError, fell through to the tables and resolved npx --registry https://private.invalid probe → ('npm','probe')	both REFUSE; only FileNotFoundError on node is UNAVAILABLE
3	The corpus did not enforce AC1	a refuse-everything resolver scored 0 unsafe and passed	negative control now exits 1; 89 required rows must be IDENTITY and match
4	Memo hits bypassed the per-resolve npm re-stat	an in-place npm upgrade mid-session served a stale identity indefinitely	the memo is gone; every query re-stats (~0.5 ms)
5	The install family read --package and discarded extra operands	npm install pkg-real --package=pkg-other → pkg-other (npm fetches pkg-real); npm install --package → true (npm fetches nothing); npm install a b and npm install a c → both a, one identity for two configs	all ('unknown', None); npm install a, npm exec pkg-one pkg-two and npx -y pkg-one pkg-two still resolve
6	A legal spec containing a space killed a healthy child	npx -y 'pkg@>=1.0 <2.0' → REFUSED + teardown, and the next server in the same cycle got "cooling down after a failure"	resolves to pkg@>=1.0 <2.0; teardown is now reserved for a genuinely desynchronized stream

Finding 5 was caught by this harness's own randomized fuzz seed — which is why
that requirement existed. Three follow-ups were also closed: the refresher's
identity overlay now carries the credential variable name (an env_var of
npm_config_registry is manifest-controlled, passes validate_env_var_name, and
would have redirected npm without the gate seeing it); a parent-side spawn
failure is no longer sticky, since permission and resource errors are repairable
under a running gateway; and the one-per-process WARNING no longer claims
identity is disabled in the UNAVAILABLE case, where the tables still mint
identities.

Separately, running the board's requested npm 10.8.2 verification surfaced a
layout the resolver could not handle: the GitHub Actions runner's bundled node20
ships <prefix>/bin/npx as a copy of npx-cli.js rather than a symlink, so
walking up from it never reached the npm package and the resolver fell back to
the tables. It now also checks npm's own global layout — against the entry
point's own prefix only, because checking every level of the walk made a stray
npx in a temp directory adopt this host's unrelated /lib/node_modules/npm.

A cross-major divergence CI caught and this host could not

The first CI run failed, and the failure was correct. On npm 10.9.4 the
spawn-time self-test reported npm exec -- --flag-thing: expected null, got "--flag-thing" and disabled the resolver. Measured against both real
binaries with a dead registry:

npm	npa	npm exec -- --flag-thing fetches	npa says
10.9.4	12.0.2	/--flag-thing	{type: 'range', name: '--flag-thing'}
11.19.0	13.0.2	/undefined	{type: 'tag', name: undefined}

Two installed npms, two different packages, one command line. The original code
happened to refuse on npm 11 only because npa 13 returns no name — so it would
have minted --flag-thing as a confident identity on every npm 10 host, the
F2 defect the design set out to close, reopened through a version difference.

The fix refuses a package operand beginning with - before npa is consulted.
That is the only answer true on both majors, and it is what makes the
spawn-time self-test an invariant rather than a description of whichever npm
the author happened to have installed. Verified afterwards by running the
child's whole corpus — 248 cases, named + manifest + fuzz — under npm 10.9.4 and
npm 11.19.0 and diffing: 0 diverging.

This is worth stating plainly because the self-test is the mechanism that turns
a modelling error into a loud refusal rather than a quiet wrong answer, and it
did exactly that on its first exposure to an npm this machine does not have.

An environment finding worth recording

This development host has /tmp/package.json and /tmp/node_modules/.bin
containing real executables. Two consequences, both verified:

• A dead registry stops npm fetching but not executing — libnpmexec runs a
  matching local or global bin and returns into execution before any fetch. A
  differential harness rooted in /tmp would therefore have launched installed
  binaries. differential_npm_corpus.py refuses to run unless it finds a temp
  base with no npm local prefix, and aborts loudly naming every candidate it
  tried rather than silently relocating.
• pytest puts tmp_path under /tmp, so any monkeypatch.chdir(tmp_path) test
  silently flips from resolving to refusing. That is nasty in one direction only:
  a test asserting a refusal then passes for the wrong reason and looks green
  forever. tests/conftest.py now documents this at the top of the file, and the
  one affected test class pins its identity path explicitly.

Pre-existing failure, not from this change

tests/runtime's stdio-harness tests (test_downstream_stdio.py and
TestStdioEmitterReachesDispatch) hang on this host. Proven not to be this
change:

• they hang with a genuinely node-less PATH, where the resolver spawns no child
  at all and identity is byte-for-byte 2.5.2;
• they hang identically at the base commit ea8333c, run from a clean
  git archive export with PYTHONPATH pointed at it (exit=124 for both);
• nothing in those tests touches package identity.

The remaining 52 runtime tests pass. This wants its own investigation.

---

Amendment of record (coordinator, quoted verbatim)

D1 — NEW HOLE, design-side. Gate the gateway's OWN process environment too. env npm_config_package=evil-pkg-abcz npm_config_registry=http://127.0.0.1:9 npx -y probe-abcz fetches http://127.0.0.1:9/evil-pkg-abcz. Add a one-time startup check of os.environ for any npm_config_* (case-insensitive) or NODE_OPTIONS; if present, the resolver REFUSES for its lifetime and logs exactly one WARNING naming the offending key.

D2 — AC3 must be parametrized, not a three-item list. Required for every step-1/step-4 refusal path for which the 2.5.2 tables return non-None, keeping the two-distinct---package carve-out.

D3 — AC2 has no pass condition. Add: zero unsafe rows — every recorded verdict must show resolver == binary OR resolver == REFUSED; rows where the binary made no fetch or crashed require REFUSED.

D4 — Randomize the fuzz seed per run and print it.

D5 — The memo defeats the drift defence. Include the child generation / handshake npmVersion in the memo key, or flush the memo on every respawn and npm-version change. Also specify: (a) does a REFUSED-for-lifetime resolver still re-stat, or does recovery need a gateway restart? (b) respawn-once with no re-arm strands a days-running gateway after two transient child deaths — make the budget time-based or re-armed.

D6 — The npx-cli port spec is wrong about ranges and sets. The loop is lines 66–124, and removedSwitches, switches and opts all live outside the cited 63–124. Read the real file and enumerate all three sets.

D7 — parsed.package is a LIST. "A single --package value" means len(...) == 1, not truthiness. --package="" must be tested by key presence, not JS truthiness.

D8 — AC4 mixes return conventions. Name the function per clause.

D9 — AC7 cannot detect a resolver that ignores PATH removal. Add one discriminating form: npx --pack zz bin must be zz node-ful and ("unknown", None) node-less.

D10 — Two failure modes are unclassified: a pre-handshake protocol violation, and loadParser() failing to require. Classify each as REFUSED-lifetime or UNAVAILABLE and say which.

D11 — The hung-child criterion is vacuous where it runs. Split into two criteria on two hosts.

D12 — Factual fix: the manifest is 79/79 plain shape, not 78/79.

Also worth surfacing: a fleet-wide auto-update disable behind a single WARNING is easy to miss — if gateway.health has a natural place to report resolver state, add it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01T61zMNiPF4K29186r3uqc3