bug(install): gentle-pi ships host-provided @earendil-works/pi-tui as a dependency, hoisting a duplicate 0.85.1 copy over the host 0.99.0

[nicoarias81]

Before submitting

• I searched open and closed issues and did not find a report of this problem.
• I reviewed this report and removed credentials, tokens, private paths, hostnames, and other sensitive data.

Problem

gentle-pi@3.7.0 declares @earendil-works/pi-tui in dependencies:

"dependencies": {
  "@earendil-works/pi-tui": "0.85.1",
  "@heyhuynhgiabuu/pi-pretty": "0.6.27"
},
"peerDependencies": {
  "@earendil-works/pi-coding-agent": ">=0.85.1",
  "typebox": "*"
}

pi-tui is a host-provided module: the Pi installation always supplies it, and this package already peer-declares pi-coding-agent for exactly the same reason. Declaring it as a hard dependency gives npm a legal reason to install a second copy into the extension tree, and Pi's extension loader reports it on every startup:

Warning: Extension package "<npm-root>/node_modules/gentle-pi/package.json":
Host-provided extension packages must be declared in peerDependencies with a "*"
range, not dependencies: @earendil-works/pi-tui. Installed copies can bypass the
extension loader and create duplicate runtime modules.

The duplicate is not inert — it shadows the host's copy at import time, and the two copies are different versions:

module	resolved from gentle-pi	host copy
@earendil-works/pi-tui	0.85.1	0.99.0

The package imports pi-tui directly in roughly 20 modules (extensions/gentle-ai.ts:33, the other extensions under extensions/, and lib/agents-view.ts, lib/shell-bar.ts, lib/native-choice-list.ts, lib/questionnaire/questionnaire-view.ts, lib/review-consent-component.ts). Symbols crossing that boundary — Key constants, matchesKey, KeybindingsManager, truncateToWidth — come from a different module instance than the one rendering the UI, which is precisely the duplicate-runtime-module failure the warning describes.

Steps to reproduce

1. Install gentle-pi@3.7.0 into a Pi npm extension tree (~/.pi/agent/npm).
2. Start Pi.
3. Observe the Host-provided extension packages ... @earendil-works/pi-tui warning on stderr.
4. Confirm that bare imports resolve the duplicate, not the host copy:

$ cd ~/.pi/agent/npm/node_modules/gentle-pi
$ node -e "console.log(require.resolve('@earendil-works/pi-tui'))"
<npm-root>/node_modules/@earendil-works/pi-tui/dist/index.js
$ node -e "console.log(require(require.resolve('@earendil-works/pi-tui/package.json')).version)"
0.85.1
$ node -e "console.log(require('<pi-install-root>/node_modules/@earendil-works/pi-tui/package.json').version)"
0.99.0

Expected and actual behavior

Expected: @earendil-works/pi-tui is declared in peerDependencies with a "*" range and never in dependencies — exactly how this package already declares typebox. npm installs no second copy, the host's pi-tui is the only one in the module graph, and the loader emits no warning.

Actual: npm installs @earendil-works/pi-tui@0.85.1 into the extension tree, it shadows the host's 0.99.0 copy for every bare import in the package, and the extension loader emits the duplicate-runtime-module warning on every startup.

gentle-pi version

3.7.0 (npm view gentle-pi version -> 3.7.0)

Pi version

0.99.0

Operating system

Windows

Relevant logs or error output (optional)

Warning: Extension package "<npm-root>/node_modules/gentle-pi/package.json": Host-provided extension packages must be declared in peerDependencies with a "*" range, not dependencies:
 @earendil-works/pi-tui. Installed copies can bypass the extension loader and create duplicate runtime modules.

[nicoarias81]

Note for triage: this report was filed through the GitHub API rather than the web form, so the template's labels could not be applied. The account that opened it has no push/triage permission on this repository, and GitHub silently drops the labels field for non-collaborators instead of returning an error.

The report should carry bug and status:needs-review, and currently has neither. The body itself is unaffected.

[MatiasJoaquinAlfonso]

Cross-platform confirmation from macOS (arm64): Pi 0.99.0 with gentle-pi 3.7.0, duplicate copy 0.85.1, host copy 0.99.0. The manifest defect is real and the extra copy should not be installed at all.

One correction for triage. On a global npm install the loader alias wins over the duplicate even when Node can resolve it from the extension directory, so the copy is dead weight rather than active shadowing. Pi loads extensions with jiti and passes alias: getAliases(), which includes piTuiEntry = resolveWorkspaceOrImport("tui/dist/index.js", "@earendil-works/pi-tui").

Measured with a throwaway extension that dumps the namespace keys, with node_modules/@earendil-works/pi-tui present and resolvable (0.85.1):

// loaded with: pi -e /tmp/pi-alias-probe -p "ok"
import { writeFileSync } from "node:fs";
import { createRequire } from "node:module";

const tui: Record<string, unknown> = await import("@earendil-works/pi-tui");
writeFileSync("/tmp/pi-alias-probe/out.json", JSON.stringify({
  keys: Object.keys(tui).sort(),
  nodeResolve: createRequire(import.meta.url).resolve("@earendil-works/pi-tui"),
}));

• createRequire(import.meta.url).resolve(...) returned the 0.85.1 copy
• the extension's import() returned 87 exports, identical to the host 0.99.0 namespace
• the 0.85.1 copy exposes 71 (missing oklchColor, getNativeClipboard, parseColor, and others)

The probe module body runs before Pi validates the extension factory, so that probe also logs does not export a valid factory function. Expected under pi -e, and it does not affect the measurement.

So require.resolve shows Node resolution, not what the extension actually imports. That does not make the fix optional: the stale copy is still a latent hazard on the paths without the alias (tryNative, native ESM, the embedded binary). It only changes the severity today.

[aresinodev]

Current main still ships this defect, and it now ships a second one. Both live in the same field, so a fix that moves only @earendil-works/pi-tui leaves the warning alive.

package.json on main (version string is still 3.7.0, so this is unreleased work):

"dependencies": {
  "@earendil-works/pi-ai": "0.87.1",
  "@earendil-works/pi-tui": "0.87.1",
  "@heyhuynhgiabuu/pi-pretty": "0.6.27"
},
"peerDependencies": {
  "@earendil-works/pi-coding-agent": ">=0.85.1",
  "typebox": "*"
}

@earendil-works/pi-ai is in Pi's HOST_PROVIDED_EXTENSION_PACKAGES alongside @earendil-works/pi-tui. collectExtensionPackageWarnings intersects that set with dependencies, sorts, and joins, so main emits a single warning naming both:

Host-provided extension packages must be declared in peerDependencies with a "*"
range, not dependencies: @earendil-works/pi-ai, @earendil-works/pi-tui.
Installed copies can bypass the extension loader and create duplicate runtime modules.

The pi-ai entry is test-locked, and its stated reason does not hold on main

Unlike the pi-tui entry, this one is deliberate. tests/package-manifest.test.ts:134 pins it by name:

test("packed runtime declares its pi-ai compat import as a direct exact dependency", () => {
	const manifest = readPackageJson();
	assert.equal(manifest.dependencies?.["@earendil-works/pi-ai"], "0.87.1");
});

So fixing this is not just an edit to package.json — that assertion has to be re-pointed, and whoever does it should know that the premise in its title does not appear to hold for the generated runtime.

The packed runtime is the eight modules produced by scripts/build-runtime-modules.mjs from lib/*.ts by type-stripping:

gentle-ai-binary, review-relay-contract, review-integration-v2, review-risk-assessment,
native-review-cli, telemetry-trigger, gentle-shell-launcher, gentle-shell-resume-hint

On main, none of those eight runtime/*.mjs files and none of their lib/*.ts sources reference @earendil-works/pi-ai. A repository-wide code search for the specifier returns only:

lib/inprocess-reviewer.ts
lib/review-host-relay.ts
package.json
tests/package-manifest.test.ts
tests/inprocess-reviewer.test.ts
tests/devbinary/pi-host-relay.devtest.ts
scripts/maintainer/provider-relay-matrix.mjs

Both import sites are TypeScript modules that Pi loads through jiti, where the host alias already supplies the module — Pi maps both @earendil-works/pi-ai and the /compat subpath to its bundled copy in dist/core/extensions/virtual-modules.js. The import at lib/review-host-relay.ts:36 is @earendil-works/pi-ai/compat, which is aliased as well.

If some step outside this repository genuinely needs a resolvable pi-ai at pack time, that requirement belongs to the build or to the packed artifact, not to the manifest field Pi lints for extensions. The two consumers want opposite things from one field, and the extension contract is the one Pi enforces on every startup.

Worth adding: the pin is already stale. It names 0.87.1 while the host supplies 0.99.1, so the duplicate it installs is a version behind the code that will actually validate against it.

Suggested scope

1. Move @earendil-works/pi-tui and @earendil-works/pi-ai out of dependencies into peerDependencies with "*", leaving @heyhuynhgiabuu/pi-pretty as the only real dependency.
2. Replace the assertion at tests/package-manifest.test.ts:134 rather than deleting it — assert that both specifiers are peers, and that the intersection of dependencies with HOST_PROVIDED_EXTENSION_PACKAGES is empty. A guard that locks one name at a time cannot stop the next host package from landing in dependencies, which is exactly what happened here inside one release cycle: pi-tui was reported, and pi-ai was added.
3. If the packed path truly needs a concrete pi-ai, give it its own resolution in the build step and keep the published extension manifest clean.

I agree with the alias correction already posted in this thread: under an aliased load the host namespace wins and the stale copy is dead weight rather than active shadowing. That does not change the outcome — the copy is still installed, still resolvable through bare require, and still a latent hazard on the paths that bypass the alias.

[KapsCa]

Linux data point (not covered by the reports above), plus a confirmation that the defect is still on the pushed main.

Environment: WSL2 Ubuntu 24.04, Pi 0.99.1, gentle-pi@3.7.0 installed globally through npm.

$ ls gentle-pi/node_modules/@earendil-works/
@earendil-works/pi-ai  @earendil-works/pi-coding-agent  @earendil-works/pi-telemetry  @earendil-works/pi-tui
$ cat gentle-pi/node_modules/@earendil-works/pi-tui/package.json | jq -r .version
0.85.1
$ cat <pi-install-root>/node_modules/@earendil-works/pi-tui/package.json | jq -r .version
0.99.1

So the nested copy is materialized here too, and the skew is 0.85.1 vs 0.99.1 — wider than the 0.85.1 vs 0.99.0 in the report.

This is consistent with @MatiasJoaquinAlfonso's alias measurement: this is a global npm install, and the nested copy is dead weight rather than active shadowing — the loader alias still resolves the host copy. On this machine the startup warning is the only observable symptom; nothing broke, and the four MCP servers and the extensions all still load.

Confirming @aresinodev: the pushed main still carries both entries, so a fix that moves only @earendil-works/pi-tui leaves the warning alive.

"dependencies": {
  "@earendil-works/pi-ai": "0.87.1",
  "@earendil-works/pi-tui": "0.87.1",
  "@heyhuynhgiabuu/pi-pretty": "0.6.27"
}

One caveat on reading main: that is the pushed main as of today. A fix sitting in local commits or an unmerged branch would not be visible there. I searched the open PRs for one carrying it and found none.

[jgarcialaneitor]

One more install path, not covered above: installed from git (pi install git:github.com/Gentleman-Programming/gentle-shell), not npm.

Environment: Linux, Pi 0.99.1 (global npm), gentle-shell checkout at main 08de420c (gentle-pi 3.7.0).

Startup shows the combined warning @aresinodev predicted for main:

Warning: Extension package "<agent-home>/git/github.com/Gentleman-Programming/gentle-shell/package.json":
Host-provided extension packages must be declared in peerDependencies with a "*" range,
not dependencies: @earendil-works/pi-ai, @earendil-works/pi-tui.

On the git path the checkout gets its own node_modules, so the pinned copies sit next to the extension sources:

$ cd <agent-home>/git/github.com/Gentleman-Programming/gentle-shell
$ for p in pi-ai pi-tui pi-coding-agent; do jq -r '"\(.name) \(.version)"' node_modules/@earendil-works/$p/package.json; done
@earendil-works/pi-ai 0.87.1
@earendil-works/pi-tui 0.87.1
@earendil-works/pi-coding-agent 0.87.1
$ jq -r .version <pi-install-root>/node_modules/@earendil-works/{pi-ai,pi-tui}/package.json
0.99.1
0.99.1

So on this path the skew is 0.87.1 vs 0.99.1 for both packages. The install also leaves an untracked package-lock.json in the checkout (git status → ?? package-lock.json).

Extensions still load and their tools are available in-session, so the warning is the only visible symptom here, consistent with the alias measurement above. The git path is still worth covering in the fix's regression test, since there is no hoisting here.

[rafaga2469]

Independent confirmation on a third platform, plus one finding that narrows the fix.

Environment: Linux, Pi 0.99.1, Pi extension store at <agent-home>/npm (flat layout), gentle-pi@3.7.0.

I reproduced the manifest defect, and I agree with the alias correction already measured in this thread: the stale copy is dead weight, not active shadowing. I found no evidence of shadowing. The point below is about what is on disk and why.

The manifest declaration is the only control point

In this store, npm does not materialize declared peer dependencies. @earendil-works/pi-coding-agent is a peer of most installed extensions here and is not in the store at all:

$ test -d node_modules/@earendil-works/pi-coding-agent && echo SI || echo NO
NO

The entire @earendil-works namespace in the store contains exactly one directory:

$ ls node_modules/@earendil-works/
pi-tui

The lockfile says why. Cross-referencing every entry against dependencies and peerDependencies:

package	pi-tui in dependencies	pi-tui in peerDependencies	materialized
gentle-pi	0.85.1	—	yes, 0.85.1
gentle-engram	—	>=0.74.0	no
pi-intercom	—	*	no
pi-mcp-adapter	—	*	no
pi-ollama-cloud	—	*	no
pi-web-access	—	*	no
@heyhuynhgiabuu/pi-pretty	—	*	no
@juicesharp/rpiv-todo	—	*	no

gentle-pi is the only row that materializes, and it is the only row with an entry under dependencies. The copy hoisted to node_modules/@earendil-works/pi-tui is at the store root, so the install is not even nesting it — a second extension declaring pi-tui as a dependency would share that same hoisted copy rather than get its own.

So the fix is not only about avoiding the warning. Moving the entry to peerDependencies is what stops the copy from being installed at all; on this layout nothing else does.

The pi-ai entry and the pinned test

I confirm @aresinodev's finding on unreleased main. Adding to it: gentle-pi is the only package in this store that materializes a host copy through dependencies, so the pi-ai entry would produce a second such copy, and the assertion at tests/package-manifest.test.ts:134 would keep it pinned to 0.87.1 against a host that supplies 0.99.1.

Narrowing the fix

One assumption worth removing before someone scopes this: the pi-tui move does not require touching @heyhuynhgiabuu/pi-pretty, which gentle-pi loads at extensions/pi-pretty.ts:14. Its manifest declares no pi-tui dependency at all:

"dependencies": { "@ff-labs/fff-node": "^0.10.0", "@shikijs/cli": "^4.0.2", "shiki": "4.0.2" },
"peerDependencies": {
  "@earendil-works/pi-ai": "*",
  "@earendil-works/pi-coding-agent": "*",
  "@earendil-works/pi-tui": "*"
}

It already uses the "*" peer form that collectExtensionPackageWarnings asks for, and it resolves through the host alias today. The pi-tui entry in gentle-pi is the only hard-dependency declaration of a host package in that field, so the change is confined to that one entry plus the pinned assertion.

[viniciosrab]

Same result on Arch Linux (Omarchy), Pi 0.99.1, gentle-pi@3.7.0 installed through Pi's npm: source into the flat store at <agent-home>/npm.

$ node -e "console.log(require.resolve('@earendil-works/pi-tui',{paths:['node_modules/gentle-pi']}))"
<agent-home>/npm/node_modules/@earendil-works/pi-tui/dist/index.js
$ jq -r .version node_modules/@earendil-works/pi-tui/package.json
0.85.1

The startup warning appears on every launch. Nothing new beyond the confirmations above; +1 for moving @earendil-works/pi-tui to peerDependencies with "*".

[ArnoldA123]

Confirming the declaration defect and the on-disk duplicate, with one correction to the runtime-impact claim and two reconciliations.

The duplicate is not on the loader's path, so the skew is not live

pi-tui is imported from TypeScript in this package only. Measured on the published gentle-pi@3.7.0:

scope	files importing the specifier
production (extensions/ 8, lib/ 21)	29
tests/	33
total	62

All 29 production sites are .ts; lib/ holds 98 .ts files and no .js or .mjs. One further file, lib/shell-hover.ts, mentions the path only inside a comment.

That matters because Pi does not load extensions through bare Node resolution. For unbundled Node builds, loadExtensionFromFactory creates jiti with { alias: getAliases() } (dist/core/extensions/loader.js), and getAliases() maps @earendil-works/pi-tui, typebox, @sinclair/typebox, the @earendil-works/* set, and the @mariozechner/* equivalents onto the host's own resolved entries. Compiled and bundled builds take the other branch and pass virtualModules with tryNative: false, which also supplies host modules.

I checked loaded module identity rather than resolved paths, using the Text export from the host's @earendil-works/pi-tui/dist/index.js as the discriminator. Anchoring jiti at the installed package with Pi's exact alias map:

module jiti loads	got the host instance?
.ts importing the specifier directly	yes — host 0.99.1
.ts importing it across a relative hop (mid.ts -> inner.ts)	yes — host 0.99.1
.mjs importing the specifier	no — tree copy 0.85.1
.js inside an ESM package importing the specifier	no — tree copy 0.85.1

So the alias applies to what jiti transpiles (.ts, .tsx) and does not apply to natively loadable modules (.mjs, and .js in an ESM package), which jiti hands to native resolution. Every import site in this package is TypeScript, so the host's single instance is what loads and the 14-minor skew does not currently reach the UI or the key handling.

Worth flagging as a trap: jiti.resolve("@earendil-works/pi-tui") from the package context returns the host path and looks like proof the alias covers everything. It is not — it is what sent me to check the loaded instance instead. The .mjs and .js rows above fail that check while returning an aliased path from jiti.resolve.

Why this should still be treated as a real defect

The alias is an implementation detail of the current loader, not a contract, and the loader warns precisely because an extension cannot rely on it. The exposure is narrower than this issue states, but it is one file away from being live:

• any .js or .mjs file added to the shipped path that imports a host-provided module loads the stale copy immediately, which the rows above demonstrate;
• createRequire(...) executed inside the package bypasses the alias. In gentle-pi@3.7.0 that pattern appears only under tests/, never in lib/ or extensions/, so it is currently unexercised by shipped behavior;
• anything evaluated outside the extension loader — child processes, wrapper scripts, tooling reaching bare imports through plain Node — resolves the hoisted copy.

The declaration still contradicts the host's contract, typebox is already declared correctly in the same file, and nothing prevents a future native-loadable module from turning the skew into a live divergence.

Two reconciliations

Host version. This issue reports 0.99.0 while #1564 reports 0.99.1. On Pi 0.99.1 the host copy is 0.99.1; 0.99.0 reads as the Pi version at the time of the report.

Import count. This issue says roughly 20 modules and #1564 says 61. Both are defensible because they measure different scopes, and each is close to correct within its own:

scope	files
production only (extensions/ + lib/)	29
whole published package, including tests/	62

tests/ accounts for 33 of the 62, which explains the gap between the two reports.

[chepekin]

Confirming the startup warning on Windows with Pi 0.99.1 and gentle-pi 3.7.0 (the current npm latest version checked for this report).

The published package declares @earendil-works/pi-tui 0.85.1 in dependencies. Pi reports: Host-provided extension packages must be declared in peerDependencies with a * range, not dependencies: @earendil-works/pi-tui. Installed copies can bypass the extension loader and create duplicate runtime modules.

Expected: the extension loads without this host-provided dependency warning. Observed: the startup warning above; no runtime failure has been observed in this occurrence. Pi documentation requires host-provided packages to use peerDependencies with the literal range * and not be bundled.

[alenicomar]

This looks resolved on main by 14f77e6 (feat(shell)!: require Pi 0.99.1, merged in #1582), so it could be closed as fixed there.

That commit removes both @earendil-works/pi-tui and @earendil-works/pi-ai from dependencies, declares them as optional "*" peers with 0.99.1 dev pins, and adds a manifest test (packed runtime uses optional Pi host peers with exact development pins and no duplicate direct dependencies) that guards against the regression.

The published gentle-pi@3.7.0 on npm still ships the old manifest, so the warning stays for users until the next release goes out.

[dnlrsls]

Status note: on main, 14f77e68 already moved @earendil-works/pi-tui and @earendil-works/pi-ai to optional peerDependencies ("*"), leaving only @heyhuynhgiabuu/pi-pretty in dependencies. This is unreleased (package is still 3.7.0 on npm).

That change exposed a crash for git installs, tracked as the root issue #1586 (fix in #1594), because the Vim adapter still resolved pi-tui through Node instead of the host alias. Once #1594 lands, the peer-only manifest works for both npm and git installs.