feat(zcode): distinguish interactive and prompt-only runtimes

[guanbear]

Summary

Adds the macOS launch adapter for ZCode runtimes that are not equivalent:

• A separately installed zcode-app-cli remains available as an interactive TUI.
• ZCode Desktop's bundled runtime is used only for prompted one-shot tasks.
• An empty launch against a prompt-only runtime fails with a clear message instead of opening a broken terminal.

Dependency

Draft follow-up to #13965. Review the single follow-up commit after the core PR.

Why

Current ZCode Desktop bundles expose --prompt, but their no-prompt TUI path fails because @zcode/tui is unavailable. Treating the bundle as a full interactive client makes Orca show a selectable agent that cannot actually start. The adapter now detects the runtime capability before choosing a launch path.

Capability Matrix

Runtime	Initial prompt	Empty interactive launch
zcode-app-cli on PATH	Yes	Yes
Prompt-only zcode on PATH	Yes	Rejected with guidance
ZCode Desktop bundle	Yes	Rejected with guidance

Validation

• ZCode startup tests cover prompt quoting, multiline input, Desktop fallback, interactive PATH launch, and prompt-only rejection.
• Node, web, and CLI typechecks pass on Node 24.
• Formatting, lint, and git diff --check pass.

External Limitation

The missing Desktop TUI dependency is tracked in zai-org/feedback#51. This PR does not bundle or endorse a third-party CLI; it only distinguishes capabilities when a user has installed one.

[guanbear]

Restacked onto the refreshed #13965 head rebased on current main (6faaf3af); no new conflicts. Validation: stack-tip Node/Web typecheck passes; tui-agent-startup-zcode suite passes (5 tests).

[guanbear]

Restacked onto the refreshed #13965 core on current upstream main (ee61e3bd4).

Fresh validation:

• Node/CLI/Web/mobile TypeScript projects pass typecheck.
• ZCode startup capability suite: 5/5 tests pass.
• Scope remains limited to distinguishing interactive TUI runtimes from prompt-only Desktop/bundled runtimes; orchestration supervision stays in feat(zcode): supervise orchestration workers and transcripts #16228.

[nwparker]

Closing — this problem is now solved on main in #22730.

You identified it first, and correctly: ZCode Desktop's bundled runtime is prompt-only because its @zcode/tui dependency isn't there, so an interactive launch opens a dead terminal. That framing is exactly right, and it's a nasty one to spot because Orca's own setup all reports success — the agent is detected, the hooks install correctly — and the only thing that fails is ZCode drawing itself.

#22730 took a different route to it, for one specific reason. Your version keys on zcode --version starting with zcode-app-cli , which is one distribution's package name; now that Z.ai ships a first-party CLI (it prints a bare version like 0.16.9), that check would reject the official build. So it keys on the failure instead: run zcode with stdin at EOF and look for Node's Cannot find package '@zcode/tui'.

That turns out to be guaranteed rather than lucky, which I only trusted after reading the source: runTuiCommand calls loadTuiRuntime() before anything else, and the TTY check lives inside runTui — after the module has already loaded. So a build without the TUI fails in the loader, and one with it loads and then declines the missing TTY. The two can't overlap. It's also distribution-neutral and has no hardcoded /Applications path, so it works on Linux and Windows too.

Your diagnosis is what made that search worth doing. Credited in #22730. Thank you.

[guanbear]

@nwparker Thank you for the explanation and for the credit. The failure-based @zcode/tui probe in #22730 handles first-party and community builds more robustly than my package-name check. I agree that the closed branch needs no further change now that the fix is on main.