Repository navigation
Description
What happened?
On Linux with npm 12, opening the Agent tab in an Annotate session shows:
Agent unavailable
Agent terminal runtime could not load WebTUI
(at Object.<anonymous> (.../node-pty/lib/index.js:15:20) Node.js v24.18.0)
The annotation UI otherwise works. The integrated agent terminal does not load.
Expected behavior: the managed terminal runtime provisions successfully and the Agent tab opens. If provisioning cannot complete, the installer should fail with an actionable error instead of leaving a runtime that appears installed but cannot load.
Environment
- Plannotator: 0.27.8
- OS: Ubuntu 26.04 under WSL2
- Agent: Codex
- Surface: Annotate
- Node.js: 24.18.0
- npm: 12.0.1
Reproduction
- Provision a fresh managed agent-terminal runtime.
- Run plannotator annotate on a Markdown file.
- Open the Agent tab.
- Observe the Agent unavailable message.
Root cause
The installed node-pty 1.1.0 package contains prebuilds for macOS and Windows, but no Linux x64 native binary. Linux therefore needs its install script to compile pty.node.
npm 12 blocks dependency lifecycle scripts unless they are explicitly approved. The npm installation log contains:
npm warn install-scripts 1 package had install scripts blocked because they are not covered by allowScripts:
npm warn install-scripts node-pty@1.1.0 (install: node scripts/prebuild.js || node-gyp rebuild; postinstall: node scripts/post-install.js)
Run npm install-scripts ls to review, or npm install-scripts approve <pkg> to allow.
The managed runtime package.json does not define allowScripts. Runtime provisioning then runs:
npm install --omit=dev --no-audit --no-fund @plannotator/webtui@0.1.0
npm installs the package tree without building node-pty. Loading WebTUI later fails because node-pty cannot find pty.node in build/Release, build/Debug, or prebuilds/linux-x64.
The relevant code is in agent-terminal-runtime.ts, while writeRuntimePackageJson generates no install-script approval. The current main branch appears to retain the same provisioning behavior.
Proposed solution
Generate the managed runtime package.json with a narrowly pinned approval for the required native dependency before running npm install. For example:
{
"private": true,
"type": "module",
"dependencies": {
"@plannotator/webtui": "0.1.0"
},
"allowScripts": {
"node-pty@1.1.0": true
}
}
The approval should remain limited to the exact node-pty version. A blanket approval of all dependency scripts would weaken the security benefit of npm 12.
It would also help to:
- Add a Linux test using npm 12 that provisions a clean managed runtime and verifies the WebTUI server entry point can be imported.
- Make runtime installation fail immediately with the blocked-script diagnostic when the native module was not built.
Local workaround
The affected runtime can be repaired locally with:
cd ~/.plannotator/vendor/agent-terminal/webtui-0.1.0
npm install-scripts approve node-pty
npm rebuild node-pty
This workaround was not applied while preparing this report.
Activity
fix(agent-terminal): approve node-pty install scripts for npm 12 (#1411)