[Bug]: ACP Registry binary agents break on every upstream release — prepared version is not pinned #26531

Area

apps/server (packages/provider-acp-registry)

Steps to reproduce

1. Settings → Providers → Add provider → ACP Registry → add an agent with a binary-only distribution (e.g. devin). Prepare succeeds and threads work.
2. Wait until the upstream vendor publishes a new release and the ACP Registry index advances to a newer version (Devin CLI releases every few days, so this happens quickly).
3. Start a thread with the same provider instance.

Expected behavior

The provider instance keeps working on the version that was prepared, or T3 Code automatically prepares the new version / offers a repair action.

Actual behavior

The provider snapshot reports:

ACP Registry agent 'devin' has not been prepared on this environment.

and starting a thread fails (surfaced as Not found). Re-adding the agent via the registry search is the only in-app recovery, which also creates a second provider instance.

Root cause (verified on main)

inspect() in packages/provider-acp-registry/src/server/AcpRegistrySupport.ts derives the expected executable path from agent.version taken from the current registry index:

• binaryPaths() → ~/.t3/tools/<agentId>/<version>/<platformTarget>/<cmd>
• if exists(executablePath) is false → { status: "unprepared" } → installed: false + the message above in driver.ts (acpRegistrySnapshotReadiness).

AcpRegistrySettings (packages/provider-acp-registry/src/settings.ts) has no field recording which version was prepared, so after any registry version bump the previously prepared directory (tools/<agentId>/<oldVersion>/) no longer matches and the instance is dead in the water.

The block is artificial — resolve() already self-heals

The spawn path used at turn start (AcpRegistryCatalog.resolve, AcpRegistrySupport.ts ~L1810) calls installBinary(agent, target) for binary agents with no command override. installBinary checks exists(executablePath) and downloads+extracts the current registry version if missing. So the code already knows how to recover — the instance just never gets that far:

• installed: false → enrichSnapshot early-returns (driver.ts:637), so no probe/models/auth state is populated.
• installed: false → availability constraints push "Provider executable is not installed." (apps/server/src/mcp/OrchestratorMcpService.ts:356), and the web client (ChatView.logic.ts, ProviderStatusBanner, ModelPickerContent) treats the provider as unusable.

Only binary agents are affected

For npx/uvx distributions, inspect only checks that the runner exists, and resolve calls ensureGlobalPackage, which reconciles the pinned package@version at launch. Binary is the only distribution that demands an exact-versioned directory at inspect time while recording no prepared version anywhere.

Cache semantics make the failure sudden, not gradual

inspect reads loadCachedRegistry() (in-memory ref → disk cache), while prepare and resolve call refreshRegistry()/loadRegistry(). The first search/prepare/resolve that fetches a newer index flips every prepared instance of that agent to unprepared at the next snapshot — with no prepare having failed.

No repair path for existing instances

• serverPrepareAcpRegistryAgent is only invoked from the Add-provider search step (AcpRegistrySearchStep.tsx); an existing instance's settings form offers no Prepare/Repair action.
• MAINTENANCE = makeManualOnlyProviderMaintenanceCapabilities({ packageName: null }) → no update check or maintenance affordance for acpRegistry providers.
• uninstallManagedBinary removes the whole tools/<agentId>/ tree only when no instance references the agent; there is no per-version GC, so stale versioned dirs accumulate anyway.

Suggested fixes (any of)

• Have inspect for binary agents accept the newest versioned dir actually present under tools/<agentId>/<version>/<target>/ instead of requiring registry-latest — resolve will still transparently install the latest version on next launch, matching npx/uvx behavior.
• Record the prepared agentVersion on the provider instance at prepare time and resolve against it.
• Since resolve already auto-installs, inspect could report ready whenever any version is prepared (surfacing the prepared version in the snapshot), or
• Add a Prepare/Repair action on the instance card that calls the existing serverPrepareAcpRegistryAgent RPC.

Impact

Major degradation or frequent failure — binary-only registry agents (e.g. Devin) silently become unusable on every upstream release.

Version or commit

main @ 5211acf (verified against a fresh source pull of main)

Environment

macOS 27 (Apple Silicon), T3 Code desktop, devin ACP Registry agent — prepared 3000.11.205, registry later moved to 3000.11.228.

Workaround

Three options:

1. Settings → Providers → Add provider → ACP Registry → Add the same agent again (runs prepare for the new version; creates a second instance).
2. Set Executable override on the instance to an existing agent binary on PATH (keeps the registry's args/env).
3. Manually download the registry-pinned archive into ~/.t3/tools/<agentId>/<newVersion>/<platformTarget>/ so bin/<cmd> exists.