Repository navigation
fix(pi): run pi under a Node that meets its engine floor - #22883
Conversation
…e naming it pi's bin is '#!/usr/bin/env node' and pi declares engines.node >=22.19.0. When the PATH the pi child inherits puts an older node first, pi died at module load and the gate read-back refused with only 'exit 1: its configuration could not be parsed'. Before the read-back, resolve the node pi's shebang would find on the child's PATH and compare its version to the floor read from pi's own package.json (fallback constant only when none is declared). Below the floor, run pi under a node that meets it (beside the pi link, in pi's npm prefix, or later on the PATH) through the gate launcher; refuse with the node path, its version and the floor when none qualifies.
bolichen97
left a comment
There was a problem hiding this comment.
Reviewed at 4c09690.
The guard is well scoped. It reads the shebang and the engine floor from files Crew already trusts, and it refuses with facts Crew read itself, not with child output. It leaves the launcher byte-identical when the first Node meets the floor. The gate read-back still runs on the exact launcher the session gets, so a chosen Node that the sandbox cannot reach still fails closed. The tests drive real files and fake node executables, and the cache key change covers the new launcher variant.
One hardening request, inline: the new node --version probe runs outside the sandbox in the session directory, so it should not execute a node found through a relative PATH entry.
Checked: the probe PATH matches the read-back PATH (the spawn env resolver does not change PATH), the Windows path is untouched, and no file is on the security path denylist. Not yet possible: readiness is still checking and the AI review lanes are pending on this head, so this is a comment, not an approval. I will re-check after readiness settles.
| """Every executable ``node`` on *search_path*, in the order ``env`` tries them.""" | ||
| found: list[str] = [] | ||
| for entry in search_path.split(os.pathsep): | ||
| candidate = os.path.join(entry, _NODE) if entry else "" |
There was a problem hiding this comment.
The version probe can run a work-dir-relative node outside the sandbox.
_nodes_on_path joins every PATH entry as given, and _node_version runs each candidate with cwd set to the session directory and no sandbox wrap. augmented_path validates the directories it adds as absolute, but it passes the inherited PATH through unchanged. So a relative entry such as . or bin resolves against the session directory, and the probe executes a node file from the project tree with the gateway's own privileges. pi itself would also hit that entry through env, but inside the sandbox; the probe also runs "later on PATH" candidates that pi would never run.
for entry in search_path.split(os.pathsep):
candidate = os.path.join(entry, _NODE) if entry else ""Suggestion: skip non-absolute entries here (if entry and os.path.isabs(entry)), the same rule augmented_path applies to its own directories. pi still runs under its shebang lookup for that case, and the read-back decides as before. If the inherited PATH is already filtered to absolute entries somewhere upstream of this call, point me at it and I will withdraw this.
Rule: a probe that runs before the sandbox must not execute anything the session directory can supply.
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check. The change is backend-only: no file under Notes
[UX-REVIEWED] 2201193 Description read[DESCRIPTION-READ] 802c60f9ec4122ba10ac924e5e83d91a8974620c9ae6fdaeb1508d2c723a7630 That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks. The guard reads the floor from pi's own manifest instead of guessing one. It leaves pi alone whenever it can't read a fact, and the read-back still checks the exact launcher the session runs. Notes
[DESIGN-REVIEWED] 2201193 Description read[DESCRIPTION-READ] 3a2da8b20a30cdd4480a4df6c6aa6db02816e10bdcc379225099fb9c834b08a2 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks: each item serves the frozen Goal, is fail-safe when anything is unreadable, and the PATH-order root cause is explicitly deferred to #22542. What this change shipsInventory (7 items) — 7 justifiedIntent: let someone whose PATH puts an old Node first either run pi under a supported Node or get a refusal naming the Node, its version and the floor — FIX.
[FIRST-PRINCIPLES-REVIEWED] 2201193 Description read[DESCRIPTION-READ] 9d89f794382dc2b9bd95848b70d3e477ba28f74f15471801d2be68be59854784 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findings (all downgraded on adjudication)GPT 6.1 flagged blocking issues on This comment is updated in place on each push. Review detailsBLOCKING -- src/kiro_crew/change_card_catalog.py:1816 -- Fence the interval shown when enabling heartbeat
Adjudication (Opus 5.5) — is blocking on each finding proportionate?F1 is downgraded, so nothing in this run keeps the merge blocked. F1: harm is LOW to MEDIUM.
False positive or not applicable? A repository writer can comment: |
Each node --version probe now runs under the session's sandbox and credential mask (wrap_argv with the read-back's hidden/expose set), after the floor check, because the Node comes off the session's PATH and a version-manager shim reads config from the agent's work dir. The probe is listed in the spawn audit beside the opencode version probe it mirrors. Without a readable engines.node in pi's manifest no floor is assumed and the read-back decides, as it does for an unreadable Node version. Version parsing reuses kiro_crew.constants.
bolichen97
left a comment
There was a problem hiding this comment.
Re-reviewed at 2201193, incremental from 4c09690.
My earlier note on the version probe is resolved, by a different route than I suggested. _nodes_on_path still accepts relative PATH entries, but every node --version child now runs through _pi_probe_wrap, which is wrap_argv with the same mode, hidden dirs and exposed files the gate read-back gets. So a node that a relative entry finds in the session directory runs confined exactly as pi would run it, not with the gateway's own privileges. The probe also now runs after the sandbox preflight, the wrap's launcher file is removed once the child exits, and _node_version is listed in the spawn audit next to the opencode version probe. I withdraw the hardening request.
The other change looks right too: with no readable engines.node in pi's manifest, no floor is guessed and the read-back decides, which matches how an unreadable Node version is already handled. Version parsing now reuses the shared helpers in kiro_crew.constants.
Not approving yet:
- PR Hygiene is red on this head. It asks for a reader list under
## Backwards compatibility, one line per reader in the formReader: <path>:<symbol> -- <entry> -- <why>, because the diff removes something. - Readiness is still
checking, and backend, frontend and E2E tests are still running.
I will re-check once those settle.
bolichen97
left a comment
There was a problem hiding this comment.
Approving at 2201193.
Gates checked on this head: readiness label is passed, the required PR Readiness check is green, PR Hygiene is green on its latest run, every reviewer lane (Opus, GPT, Design, First Principles, UX, Sensitive Change, Security Scope) is green with no block, no required check is red, no other reviewer has requested changes, and there is no linked issue.
[Security: the change adds a child process (the node version probe). It runs through the same sandbox wrap as the gate read-back, with only PATH and HOME in its environment, stdin closed and a 10s timeout, and its fixed argv takes nothing from a turn. No auth, secret, approval gate or trust boundary is touched.]
The earlier note on the probe running unconfined is resolved by the probe wrap. Merging with squash once the queue allows.
…2951) * test(pi): stand in for the Node probe's sync sandbox wrap in the real-adapter lane #22883's node-engine guard confines each 'node --version' probe through _pi_probe_wrap, which calls the sync pi_mod.wrap_argv. The lane (#22807) replaced only wrap_argv_async and the preflight, so on a runner without user namespaces every pi_session test errored at setup with SandboxUnavailableError. Replace the sync wrap by identity too, and say so in the module docstring. * fix(acp): decide pi's zero-tool record from its declared MCP projection #22808 gated _mirrorless_member_mounts on two new 'backend in ACP_BACKENDS_SESSION_MCP_ARRAY' tests, which #22489's set-gate ratchet (shrink-only, allowlist 2 for this file) counts, so main reds test_no_new_runtime_site_gates_a_field_backed_line_on_a_set. The question those sites ask is who reads this backend's spec, which registry.PROJECTIONS declares per backend: BROKER_ONLY (pi) means no projection is written and the harness reads no spec of Crew's. Read that record, as this file already does for per_tool_deny, so the file is back to its 2 allowed sites and the zero-tool ban is unchanged. --------- Co-authored-by: Kyle Seaman <kseam@dev-dsk-kseam-1b-55230d27.us-east-1.amazon.com>
Problem / Motivation
Goal: a pi session on a host whose PATH puts an old Node.js first either starts under a Node that pi supports, or is refused with a message that names the Node, its version and the version pi needs.
pi's bin is
#!/usr/bin/env nodeand pi declares"engines": {"node": ">=22.19.0"}. The PATH the pi child inherits isaugmented_path(...), which puts directories like/usr/local/binand/opt/homebrew/binahead of the inherited PATH. When an older system Node lives there, every pi session runs pi under it: pi dies at module load and the gate read-back refuses with onlyexit 1: its configuration could not be parsed. Found by #22807's real-adapter lane (its "Observation" and line-33 notes); reproduced on a dev desktop whose global mise default is Node 16.Why it matters
Anyone with an older Node first on that PATH (a system Node in
/usr/local/bin, a Homebrew Node, a version manager's global default) cannot use pi at all, and the error points at a config file rather than at Node, so nothing tells them what to fix.Not a goal
augmented_path/src/kiro_crew/env.py: Gary Jennings' open fix(env): stop augmented_path re-prepending dirs the inherited PATH already has #22542 owns the general PATH-order fix. This PR is the pi-side guard it complements; with fix(env): stop augmented_path re-prepending dirs the inherited PATH already has #22542 in, this guard simply finds a good Node first more often.PI_MIN_VERSION), or the install probe.pi.cmdshim picks its own Node, so the guard leaves it unmanaged.What changed (motivation → approach → change)
Symptom: pi under too old a Node → read-back
exit 1: its configuration could not be parsed. Root cause: the shebang'senvtakes the firstnodeon the child's PATH, and nothing compared that Node with pi's declared engine. Fix, before the seal, the launcher and the read-back:src/kiro_crew/acp/harness/pi_node.py(new):choose_pi_nodereads the shebang of pi's resolved script (#!/usr/bin/env node→ the first executablenodeon the child's PATH, the same lookupenvdoes; an absolute#!/…/node→ that file), runsnode --versionand compares it with the floor.piexactly as before.pilink, in pi's npm prefix (<prefix>/bin/node), then later on the same PATH, and returns(node, pi's script)for the launcher.pi needs Node.js 22.19.0 or newer (the 'engines' floor in its package.json), but the Node.js it would run under is /usr/local/bin/node, v18.20.4, and no Node.js that new was found beside pi or later on that PATH. Install Node.js 22.19.0 or newer and put it ahead of /usr/local/bin on PATH, then start a new chat.pithat is not a plain Node script, a shebang with interpreter arguments, a Node whose version cannot be read, and a pi whose manifest declares no readableengines.node. No floor is guessed: every pi release fromPI_MIN_VERSION(0.99.2) through 1.3.0 declares>=22.19.0(npm view @earendil-works/pi-coding-agent@<v> engines.nodefor 0.99.2, 1.0.0, 1.1.0, 1.2.0, 1.3.0), so the guard reads it rather than hard-coding it.node_engine_floorreads the lower bound ofengines.node(>=,^,~, bare/xversions,||alternatives → their minimum, upper bounds ignored); anything else is unreadable. Version parsing and formatting reusekiro_crew.constants.parse_node_version/format_node_version.PATHandHOME, stdin closed, 10s timeout, cwd = the session's directory (so a version-manager shim answers as it will for pi), and run through a caller-supplied wrap for the life of the child.src/kiro_crew/acp/harness/pi.py:_pi_manifestfactored out of_pi_installed_versionso the version and the engine floor read the same manifest;_pi_node_floorreturns the declared floor orNone._pi_probe_wrapconfines eachnode --versionchild withwrap_argvin the session's sandbox mode with the sameextra_hidden_dirs/extra_expose_filesas the gate read-back, and reclaims the launcher file when the child exits. The Node comes off the session's PATH (some of whose directories the agent can write) and a shim reads config from the agent's work dir, so the probe gets the read-back's confinement, as the opencode version probe does.resolve_spawnruns_pi_node_choiceright after the sandbox floor check (the probe is a child) and before the seal; an issue raisesAcpErrorbefore the launcher or read-back child._pi_gate_launcher_body/_ensure_pi_gate_launchertake an optionalprogram:exec <node> <pi script> "$@" --extension <sealed gate>. The launcher cache is keyed on it. The read-back runs this same launcher, so the gate is still verified on exactly the process the session gets.test/spawn_audit_helpers.py:acp/harness/pi_node.py::_node_versionlisted beside_opencode_reported_major, with the same justification shape (fixed--versionargv, wrapped by the caller, nothing from a turn).docs/system-specs/modules/agent-host-contract.md: pi's failure-mode cell names the guard.Read-back stderr: the refusal already carries pi's stderr as a diagnosis drawn from the closed vocabulary in
acp/launch.py(_READBACK_FAULT_SHAPES), and on purpose never echoes the child's bytes (the comment there gives the measured credential-leak reason). This PR keeps that. It makes the Node cause visible by refusing earlier with a message built from facts Crew read itself (path, version, floor), not by printing child output.Known limit: in the chosen-Node path only pi's own interpreter changes; the child's PATH still lists the old
nodefirst for anything pi's tools spawn. #22542's PATH-order fix is the general answer to that.Strings: the new refusal follows the convention of every other
AcpErrorinacp/harness/pi.py, which are English backend messages outside the i18n catalogs; no frontend string changed, soi18n:checkis not affected.Sensitive Change Review: no watched file touched (checked the diff against
SENSITIVE_GLOBSwith fnmatch). Stays out of #22808's files.Backwards compatibility
Compatible: on a host where the shebang already finds a Node at or above the floor, or where pi declares no floor, the launcher body is byte-identical to main; the only added work is the sandboxed
node --versionprobe. The new outcomes are for sessions that used to fail at the read-back: they now start under a qualifying Node, or fail earlier with a clearer message.The one take-away shape is the credential mask (
extra_hidden_dirs=) on the newnode --versionprobe child. Nothing that runs on main gains a mask: the mask is the gate read-back's, applied only to the new probe. Readers of what it hides, i.e. the probe itself on every entry that starts a pi session:Reader: src/kiro_crew/acp/harness/pi_node.py:_node_version -- chat -- a Node pi can already run under, inside this same mask on main (the read-back and the session), can still print its version under it; test_the_node_probe_runs_after_the_sandbox_floor_under_its_mask
Reader: src/kiro_crew/acp/harness/pi.py:PiLaunch.resolve_spawn -- subagent -- a pi subagent spawns through the same resolve_spawn and sandbox mode, so its probe gets the same mask as its own read-back; test_the_spawn_hands_the_chosen_node_to_the_launcher
Reader: src/kiro_crew/acp/harness/pi.py:PiLaunch.resolve_spawn -- cron -- a cron turn on pi spawns the same way; an unreadable version under the mask leaves the launch unchanged (test_a_node_whose_version_cannot_be_read_is_left_to_the_read_back)
Otherwise no key, path, function or check is removed;
_pi_installed_versionkeeps its signature and results (its manifest walk moved into_pi_manifest; existing tests unchanged and passing).Tests
test/test_acp_pi_node_guard.py(new; real files: a fake npm prefix holding pi's manifest/script/link and fakenodeexecutables):||, upper bounds, hyphen ranges, junk → unreadable);v18.20.4,22.19.0, theenginessource; no Node on PATH → refuse;#!/…/nodeshebang is checked; non-Node / interpreter-arg shebangs and an unreadable version are left to the read-back;{}/>22/ non-dictengines→ no floor, and_pi_node_choicethen probes nothing and changes nothing even under Node 18;NODE_OPTIONS, other vars), and every version child goes through the wrap;resolve_spawn: the probe runs after the sandbox floor check and before the seal, throughwrap_argvwith the read-back's mode/hidden/expose, its launcher reclaimed only after the child; an issue refuses before seal/launcher/wrap/read-back; the chosen program reaches the launcher; all off the loop;Mutation check (each applied, the file re-run, reverted): 17/17 killed: current-meets-floor, refuse-when-none, candidate-must-meet-floor, beside-pi candidates, later-on-PATH candidates, absolute shebang, minimal probe env, floor-from-manifest, no-floor-leaves-pi-alone, spawn refuses, launcher gets program, body uses program, cache keyed on program, range upper-bound check, probe goes through wrap, spawn passes the sandbox wrap, wrap reclaims its launcher.
Updated:
test/acp_pi_backend_helpers.py(the launch rig stubs the node choice and records a program),test/acp_launch_capture.py(goldens pin the node choice so they do not depend on the host's Node).Also run:
test_acp_pi_backend*.py,test_acp_pi_crew_tools.py,test_acp_refactor_facade.py,test_acp_launch_goldens.py,test_spawn_audit.py(717 passed);HARNESS_BASE_REF=origin/main check_harness_parity.py, brand, comment-history, file-line-cap, feature-map, cwd-relative reads, subprocess-encoding, sync-io-in-async, agent-sdk-boundary, docs-lint (pass); black, isort, flake8, mypy on the changed files (clean).Manual verification
On a dev desktop with pi 1.3.0 installed under mise Node 24.18.0 and Node 16.20.2 first on the PATH:
get_commands→exit 1, diagnosisits configuration could not be parsed(the reported symptom);choose_pi_nodewith the real_pi_probe_wrappicks…/node/24.18.0/bin/nodebeside pi; the launcher with that program answersget_commandswith the gate's commands, exit 0.Related Issues
Complements #22542 (general PATH order). Found by #22807.
Pattern harvest
Not generalizable: the defect is specific to a harness shipped as an
env nodescript with a declared engine floor; the only such harness is pi, and the guard now lives in its launch.Checklist
Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license.