fix(acp): require trusted preinstalled adapters

[herikwebb]

Starting experimental ACP mode could let files in an opened workspace determine which adapter code runs before an approval prompt. ACP now starts an administrator-installed adapter and reports missing or invalid configuration before startup. Existing ACP users must install the adapter and its runtime before upgrading; ACP remains disabled by default.

Closes #514.

Technical changes

• Replace automatic npx startup with discovery of preinstalled codex-acp executables through absolute server PATH entries outside the workspace. Check lexical paths, resolved targets and filesystem identities; reject paths that could introduce additional entries when serialized into PATH.
• Filter the default adapter's inherited PATH, and share bounded, nonexecuting checks of declared script interpreters between readiness and startup. Keep launch failures inside startup cleanup.
• Start the process in NBI's user directory while preserving the notebook workspace explicitly through ACP session parameters and the MCP workspace tool.
• Keep absolute administrator command overrides as an explicit trust decision, preserving their executable name and inherited PATH.
• Add regression tests for workspace aliases, interpreter lookup, malformed or missing commands, path separators, and startup cleanup. Update setup guidance, settings text, privacy documentation, and an Unreleased changelog entry.

Required migration

Install the tested @zed-industries/codex-acp@0.16.0 and Node.js in trusted locations outside the workspace, then expose the adapter on the server's PATH. NBI does not verify or update installed versions.

Replace package-runner overrides with the absolute path to the installed adapter itself. Unset NBI_ACP_AGENT_COMMAND to restore discovery; an empty value is invalid. Default filtering also removes workspace tool directories such as .venv/bin, so agent commands may need trusted tools installed elsewhere. The admin guide includes a concrete POSIX installation example and guidance for home-directory workspaces.

Validation

On macOS with Python 3.12, after applying the fix to upstream cfb130130af90b51abd9ae22c4c19783acef7b84:

• pytest tests/ -q: 2,407 passed; four event-loop teardown warnings.
• jlpm tsc --noEmit: passed.
• jlpm lint:check: passed.
• jlpm jest: 54 suites and 631 tests passed.
• git diff --check: passed.

Limitations

• Explicit command overrides trust the complete installation and inherited environment. Absolute package-runner overrides are technically accepted, even though setup guidance advises against them; this path is not constrained by default workspace filtering.
• Windows ACP startup has not been validated. Override parsing uses POSIX shell splitting, so Windows paths should use forward slashes or quote the entire path to preserve backslashes.
• Interpreter preflight does not recursively validate native dependencies or shim internals. Installation directories, parent directories and mount layout remain administrator responsibilities.
• Readiness diagnostics could give clearer recovery instructions, and filesystem identity checks on resolved-target ancestors would benefit from an additional portable regression test.