Desktop: remote-backend agents are gated on the local PATH — readiness probe and provider spawn see different environments

[jdrolls]

Summary

For agents created with a remote "Run on" backend (buzz-backend-* provider), the desktop evaluates harness availability against the local machine's login-shell PATH, while it spawns the provider itself without that PATH. Discovery and spawn see different environments, and neither consults the machine the agent will actually run on. Two concrete failures from operating a remote (SSH systemd) backend provider in production:

Symptom 1: create-mode Save gated on a local binary for a remote agent

AgentDefinitionDialog's create-mode submit requires selectedRuntime?.availability === "available", and availability comes from local prereq discovery (useManagedAgentPrereqsQuery) — the remote provider is never asked. To create a "Run on: " agent whose harness (e.g. a custom ACP adapter) exists only on the remote host, you must install the binary locally (or a stub that exits 1) purely to satisfy the probe. The stub workaround works but means the gate is validating the wrong machine.

Symptom 2: provider shims fail exit-127 depending on how the desktop was launched

The provider subprocess is spawned with the bare GUI environment. A buzz-backend-* shim whose first line is exec bun /path/to/provider.ts fails:

Could not probe provider: provider failed (exit code 127).
stderr: .../buzz-backend-jarvis: line 2: exec: bun: not found

…but only when the desktop was launched from Finder/Dock; launched from a terminal it inherits the login PATH and works. Since harness-readiness detection DOES probe the login-shell PATH, the same install can pass discovery and fail spawn. (Workaround: shims must hardcode absolute interpreter paths.)

Proposed direction

• For remote backends, delegate harness availability to the provider — providers already answer a probe op ({"op":"info"}), so an {"op":"check-harness","command":...} (or including harness inventory in info) would let the dialog gate on the machine that matters, and the local stub workaround disappears.
• Spawn provider subprocesses through the user's login shell (matching how readiness detection resolves binaries), or document that buzz-backend-* shims must use absolute paths.

Happy to work on a PR for either piece if maintainers agree on a direction.

Closest existing issues (not duplicates, adjacent provider seams): #3034 (provider-backed agents display local config), #2798 (config saves don't redeploy).

[iroiro147]

Confirmed the mechanism in-source — the differential the issue calls out is real:

Readiness probe is local-only (desktop/src/features/agents/hooks.ts:299):

discoverManagedAgentPrereqs({ acpCommand, mcpCommand })
  → invokeTauri<RawManagedAgentPrereqs>("discover_managed_agent_prereqs", ...)

This runs a local PATH probe for the acp/mcp commands no matter what backend the agent targets.

Create-mode Save is gated on that local availability (desktop/src/features/agents/ui/AgentDefinitionDialog.tsx:499):

const selectedRuntimeIsAvailable =
  runtime.trim().length === 0 ||
  selectedRuntime?.availability === "available";
// ...
(!isCreateMode || selectedRuntimeIsAvailable)  // <- blocks canSubmit

So for a "Run on: remote (buzz-backend-*)" agent, Save still demands the harness resolve on the local machine's PATH — even though the provider will spawn on the remote host.

Spawn augments PATH separately (desktop/src-tauri/src/managed_agents/runtime.rs:543-577): the provider spawn path builds its own PATH (login-shell PATH for runtimes), so discovery and spawn genuinely do see different environments — matching the report.

So the fix is a design decision, not a one-liner: either (a) the readiness probe for a remote "Run on" backend should probe the remote host (via the provider), or (b) local availability should not gate Save for remote-run agents at all. Those are meaningfully different behaviors for users whose harness lives only remotely; I'd rather not guess the intended contract. Which shape do the maintainers prefer?

[ianschreuder]

Corroborating this from a second, independent substrate: we run agents on AWS
ECS/Fargate behind a buzz-backend-* provider, and hit the create-mode gate exactly
as described.

The shape of the workaround may be useful evidence. Because availability is "command on
PATH → Available, else NotInstalled" and never consults Run on, we ship a stub
executable on the operator's machine whose only purpose is to be found by the probe. It
is not the harness — the real harness is a container image in the client's cloud
account, and this stub can never run anything. It exists solely to satisfy a readiness
check about a machine the agent will never execute on, and it fails loudly if it is ever
actually invoked.

So the defect reproduces across at least two unrelated remote substrates (SSH/systemd
and ECS/Fargate), and in both cases the fix on the integrator's side is a decoy binary,
which seems worth avoiding.

[jyrialeksi]

Third substrate, same two symptoms — plus a regression that has landed since this
was filed and which breaks the stub workaround both previous reports rely on.

Setup: SSH/systemd buzz-backend-* provider onto a single VPS; agents run as
systemd units under per-person accounts. Desktop 0.5.18, macOS 26.5.1 (Apple
Silicon).

Confirming both original symptoms

Symptom 2 reproduced exactly, and @iroiro147's remedy is the right one: our
adapter is an npm global whose shebang is #!/usr/bin/env node, with node under
nvm. Launched from Finder the probe fails; from a terminal it succeeds. Wrapping
the adapter in a shim that execs an absolute node path fixed it, matching the
"shims must hardcode absolute interpreter paths" workaround.

Symptom 1 reproduced as described — but with a twist that turns out to be the
more interesting half.

New: the gate now fails even when the local binary is present

Since #6330 (perf(desktop): split discover_acp_providers into cheap and forced paths, merged 2026-08-20 — after this issue was opened), command resolution has
two paths. The create dialog uses the cache-only one, which on a miss reports the
command absent without touching the filesystem:

// desktop/src-tauri/src/managed_agents/discovery.rs
/// Cache-only command resolution for the cheap discovery path.
///
/// ... on a miss it reports the command absent rather than resolving live via
/// `resolve_command_uncached` → `find_via_login_shell` ...
/// `resolve_command` (the forced path) is the sole prober and cache populator.
pub fn resolve_command_cached(command: &str) -> Option<PathBuf> { ... }

The cache is populated only by forced discovery, which runs on Settings → Agents.
After a fresh launch it is empty, so the dialog answers "missing" regardless of
what is installed.

Repro (every launch):

1. Install the Claude Code CLI and adapter; confirm command -v claude and
   command -v claude-agent-acp both resolve.
2. Quit Buzz (⌘Q), reopen.
3. Agents → New agent without visiting Settings: harness reads
   Claude Code (CLI missing), hint says "Visit Settings > Agents to set it up",
   Add agent disabled.
4. Open Settings → Agents: the row shows the runtime missing, then refreshes
   to Ready a moment later.
5. Back to New agent: harness resolves, Add agent enabled.

Why this matters for this issue specifically: the decoy-binary workaround both
previous reports depend on no longer clears the gate on first launch. The stub is
present on disk and still reports absent, because the lookup never reaches disk.
The workaround now also requires a Settings visit per app launch.

Worth noting the existing bypass does not cover this case.
buzz_managed_command_path does a filesystem stat before the cache in both
paths, but is restricted to:

"codex-acp" | "claude-agent-acp" | "claude-code-acp" | "node" | "npm"

The command reported missing here is the Claude Code runtime's
underlying_cli: Some("claude"), which is not in that list.

Verified the binaries are genuinely fine, so the false negative is purely the cold
cache:

$ env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin HOME="$HOME" claude --version
2.1.177 (Claude Code)

Symlinking both into /usr/local/bin (scanned by common_binary_paths()) changes
nothing, as expected.

On the design question

I don't have a view on whether (a) remote readiness should be delegated to the
provider or (b) local availability simply shouldn't gate Save for remote-run
agents — that's the maintainers' contract to set, and @iroiro147 put the tradeoff
better than I could.

The cold-cache behaviour seems separable from that decision though: whichever way
the remote gate goes, a dialog that blocks submission on a cache it never warms
will keep producing false negatives for local agents too. Warming the cache when
the dialog opens, or falling back to a live resolve on a miss for a command that
gates submission, would fix that half independently.

Happy to test any patch against the SSH/systemd substrate.

[iroiro147]

@jyrialeksi Third independent substrate is worth a lot on its own, but the regression is the more valuable half and I have verified it against current main. Apologies for the slow reply — you posted this two days ago and it deserved a faster read.

Confirmed, and the mechanism is exactly as you describe.

• resolve_command_cached (managed_agents/discovery.rs:592) checks resolve_buzz_managed_command, then reads the cache and returns None on a miss. No filesystem access, no find_via_login_shell.
• The cache is written in exactly one place — discovery.rs:578, inside resolve_command, the forced path.
• Both cheap-path call sites (discover_acp_runtime_phase1 at :1121 and the catalog builder at :1280) select resolve_command_cached when force is false.

So after a cold launch the map is empty, and any cheap discovery answers "absent" for a binary that is installed and on PATH. Your repro is the general case, not a corner: quit, reopen, go straight to Agents → New agent, and the gate reports missing until something forces discovery and populates the cache.

Worth noting the comment at discovery.rs:570 names the invalidation seam — clear_resolve_cache runs on every forced discovery, "so a newly-installed binary is still found on refresh". That reasoning holds for invalidation, but the empty-at-startup case is a different state: there is nothing stale to invalidate, there is simply nothing there yet, and a miss is indistinguishable from a confirmed absence. That looks like the gap #6330 left rather than anything it got wrong — the cheap path was protecting the channel-switch hot path from a login-shell spawn, which is a real cost.

On symptom 2 — thank you for confirming the absolute-interpreter-path workaround holds on a third setup. #!/usr/bin/env node under nvm launched from Finder is the same shape as the earlier two reports, which makes it a property of GUI launch context rather than of any one machine.

I am not going to open a PR for this: it is a regression in someone else's recent change, and this repository already has more open PRs from me than is reasonable to put in front of one reviewer. But the diagnosis above is precise enough to act on, and it belongs on the record whoever picks it up. If a maintainer would rather I did send a fix, I am happy to — say so and I will.

One thing that would strengthen it further if you have a moment: whether visiting Settings → Agents once and returning to the dialog clears it for the rest of the session. That would confirm population-on-forced-discovery is the only path and rule out a second cause.