feat(cli): add pfterminal-acp, a stable ACP entry point

[0xzoz]

Summary

Adds pfterminal-acp, a stable entry point that lets PFTerminal be registered as an agent in ACP hosts (Buzz, Zed, and anything else speaking the Agent Client Protocol).

ACP clients speak JSON-RPC over stdio. PFTerminal exposes the Codex app-server protocol instead, so it cannot be registered with an ACP host directly. The maintained codex-acp adapter bridges the two and honours CODEX_PATH to choose which Codex-compatible binary it drives:

ACP host --ACP/stdio--> pfterminal-acp --CODEX_PATH--> codex-acp --app-server--> PFTerminal

This binary is deliberately not an ACP implementation — it is a thin launcher that resolves the PFTerminal executable, sets CODEX_PATH, and hands off to the adapter.

Why a shipped command rather than documentation

The alternative is telling users to register codex-acp with CODEX_PATH=pfterminal in the host's env. That works mechanically but is the wrong shape: ACP hosts key runtime identity off the command. Buzz's built-in Codex runtime is already defined around codex-acp, so two different runtimes sharing that executable risks incorrect runtime identity, stale persona pins, and merged usage attribution.

Shipping the command also means the host preset can declare underlying_cli: "pfterminal", so a user who has PFTerminal installed but not the bridge sees adapter missing rather than not installed.

Implementation notes

Three decisions worth calling out, each with a failure mode behind it:

• Resolution order is PFTERMINAL_PATH → sibling-of-self → PATH. Sibling first because the two binaries ship together: on a machine with several PFTerminal installs, the adapter should drive the one it was installed beside, not whichever wins PATH.
• CODEX_PATH is overridden, never inherited. An inherited value would silently point the adapter at a different agent while the client still believed it was talking to PFTerminal.
• All diagnostics go to stderr. After handoff, stdout carries ACP frames exclusively — a single stray line corrupts the stream and the client fails to parse it. On Unix the handoff uses exec() so the adapter becomes the process and signals and exit codes need no forwarding logic that could get them subtly wrong; Windows spawns and propagates the exit code.

--version reports the launcher plus both resolved paths, which is what makes it useful when an install is broken — a bare version number tells you nothing.

Testing

cargo build, cargo test (3/3), cargo fmt --check, and cargo clippy all clean; clippy reports no lints on the new file.

Live ACP handshake against a real install (PFTerminal 0.1.20, codex-acp 1.1.9), driven through the compiled binary over stdio:

Step	Result
initialize	OK — protocolVersion: 1, authMethods [api-key, chat-gpt]
session/new	OK — session created in a real workspace
model catalogue	80 models enumerated, current gpt-5.5[xhigh]
session/prompt	streamed text back, stopReason: end_turn
state isolation	used ~/.pfterminal; stock Codex's ~/.codex untouched
adapter missing	exit 127, message on stderr, stdout clean

Note: cargo clippy -- -D warnings fails on codex-http-client (unused variable: trace_bytes). That is pre-existing on main and unrelated to this change — the flag merely escalates an existing warning in a dependency.

Related

Downstream consumer, opened as a draft pending a release that includes this command: block/buzz#4956 adds PFTerminal as a tier-2 preset harness. That preset points at pfterminal-acp, so it stays draft until this ships.