How to Recover From a Broken Provider Bridge

How to Recover From a Broken Provider Bridge

A broken provider bridge is not one single failure. In AxiOwl, it can mean the provider extension did not load, the MCP config is stale, a registry row points at the wrong session, a patch is missing, the provider app was not restarted, or the target accepted a local AxiOwl receipt but never received the message. Good recovery starts by identifying which boundary failed instead of reinstalling everything blindly.

AxiOwl's Windows desktop implementation is built around a small coordinator, a durable local registry, discovery, provider-specific edges, and delivery evidence. The core send path is:

axiowl.exe
-> MessagePipeline
-> registry sender and target resolution
-> targeted discovery repair when needed
-> provider edge dispatch
-> provider-specific bridge delivery
-> delivery logs and provider proof

That shape matters during recovery because the middle of AxiOwl should stay boring. Strange behavior belongs at the provider edge, and each edge has its own install, config, patch, bridge, and proof requirements.

First, name the failed boundary

The most common recovery mistake is treating an early success as end-to-end proof. AxiOwl separates these events on purpose:

MSI install succeeded
accepted_by_axiowl
provider accepted
MCP reply received

An MSI success means selected installer actions completed. It does not prove that VS Code, Cursor, Codex, or another provider can receive a message. An accepted_by_axiowl receipt means AxiOwl validated the request, resolved a route, and handed work to the delivery layer. It is still not the same as provider delivery proof.

For a full recovery, look for the strongest evidence available: a provider result, persisted session evidence where that provider supports it, and finally a reply that comes back through AxiOwl MCP with correct provider-owned sender identity.

Collect the local evidence before changing anything

Start with the AxiOwl state directories:

%LOCALAPPDATA%\AxiOwl\logs
%LOCALAPPDATA%\AxiOwl\registry
%LOCALAPPDATA%\AxiOwl\runtime

Then collect the provider-side evidence for the bridge involved:

This evidence tells you whether the bridge was never installed, installed but not loaded, loaded but unable to find its patch command, pointed at the wrong session, or working but blocked by provider auth/model/session state.

Check AxiOwl's view of the world

Use the CLI to inspect local state:

axiowl status
axiowl list agents
axiowl discover all --json

For a single suspected target, use targeted discovery:

axiowl discover vscode-native --target "<chat name>" --json
axiowl discover vscode-copilot --target "<chat name>" --json
axiowl discover cursor --target "<agent name>" --json

The registry row you care about should have the right provider, provider session id, node id, and sendable state. In AxiOwl's registry model, provider + provider_session_id + node_id is the stable identity. Display names are useful for humans, but they can be renamed, reused, or duplicated. A stale friendly name can route to the wrong row if the registry has not been refreshed.

When discovery finds the same provider session again, AxiOwl is designed to update the existing registry row rather than duplicate it. When a new session has the same display name, it can remain a separate row, and name lookup prefers the newest matching sendable row. That behavior is useful during recovery because it lets discovery repair stale names without erasing the identity boundary.

Recover the selected bridge, not every provider

The installer behavior matrix is explicit: each provider feature should behave like its own install unit. Unchecked provider features should not be installed, patched, closed, restarted, removed, or "fixed" as collateral damage.

For VS Code native or VS Code Copilot, check that the selected feature installed the bridge extension and MCP server definition, that old legacy AxiOwl bridge folders were cleaned, and that VS Code was restarted after the change. VS Code native recovery also needs correct bridge ownership: the bridge must target the right VS Code window and native session. A legacy bridge registry is not enough. The native provider test suite specifically checks that create fails fast when only a legacy bridge exists and no active native bridge is registered.

For Cursor, check that the Cursor feature was selected, the Cursor bridge extension is present, Cursor MCP config exists, the command watcher is active, and the required patched command exists:

glass.axiowlSubmitToAgent

If that command is missing, the bridge may be alive but unable to deliver. AxiOwl treats that as a loud failure, not as a reason to silently fall back. Cursor URI wake-up is fallback only when the command-file watcher path is unavailable; it should not become the normal recovery path.

For Codex, Antigravity, and CLI-style providers, check that the MCP config is in the provider's expected location, that the provider session was restarted after install, and that sender identity comes from provider-owned metadata. AxiOwl does not consider environment-only identity injection final support for CLI providers.

Repair stale or wrong registry rows carefully

If discovery shows that a target is stale, first try targeted discovery and a normal send. AxiOwl's message pipeline already performs one targeted discovery repair when a target is missing or appears to require repair.

If a bad manual row remains, remove only the row you mean to remove. The CLI requires a name plus a provider or session filter:

axiowl registry remove-agent --name "<agent>" --provider "<provider>" --session "<provider-session-id>" --node local

Then rediscover or re-add the intended row:

axiowl discover <provider> --target "<agent>" --json
axiowl registry add-agent --name "<agent>" --provider <provider> --session "<provider-session-id>" --node local --source manual

Avoid broad cleanup when the only problem is one stale row. The registry can contain multiple valid sessions with the same display name, and unrelated provider sessions should be preserved.

Prove recovery with the right test

After the bridge is repaired, test from AxiOwl through the provider edge:

"Please reply through AxiOwl with a short confirmation." | axiowl send --to "<agent>" --from "<sender>" --stdin --strict

Read the receipt carefully. If it says accepted_by_axiowl, that is a good local boundary, but recovery is not complete yet. Look for delivery-worker logs, provider result files, provider output channels, and then a real response through AxiOwl MCP.

For VS Code native, the best proof is stronger than "a window changed." The expected recovery proof is:

AxiOwl receipt shows provider=vscode_native
bridge result shows accepted native delivery
prompt appears in the exact target session file or transcript
target replies through AxiOwl
reply sender is vscode_native:session:<same uuid>

For Cursor, the preferred path is:

AxiOwl provider edge
-> command JSON file
-> Cursor bridge command watcher
-> glass.axiowlSubmitToAgent
-> Cursor agent/composer
-> reply through AxiOwl MCP

If the URI wake-up path was involved, treat it as fallback evidence and keep checking the watcher and patched command path. The bridge is not truly healthy if the normal watcher path is still unavailable.

What not to do

Do not use a remote provider as a silent fallback for a broken local provider bridge. Remote features are out of scope for local-provider remediation builds and should remain unchecked by default unless intentionally selected.

Do not manually edit provider chat JSONL files to simulate delivery. For VS Code native, the documented working method opens the exact Agent Session resource and submits through VS Code commands; manual file edits can corrupt evidence and still fail to reach the provider.

Do not trust a visible chat title as stable identity. Use the provider session id, registry row, bridge result, and reply identity.

Do not assume a successful reinstall fixed every selected provider. The installer writes logs and runs discovery, but provider support still requires message delivery and response-backed validation.

A practical recovery checklist

Use this sequence when a bridge fails:

  1. Identify the provider surface: VS Code native, VS Code Copilot, Cursor, Codex, Antigravity, or a CLI target.
  2. Collect %LOCALAPPDATA%\AxiOwl\logs, %LOCALAPPDATA%\AxiOwl\registry, and %LOCALAPPDATA%\AxiOwl\runtime.
  3. Check provider output channels, CLI output, or session evidence for the selected provider.
  4. Run axiowl status, axiowl list agents, and targeted axiowl discover.
  5. Confirm the target row's provider, session id, node id, sendable state, and last error.
  6. Repair only the selected provider feature: extension, MCP config, patch, watcher, bridge registry, or app restart.
  7. Remove stale registry rows only with tight provider/session/node filters.
  8. Send a small strict test message.
  9. Verify provider-side delivery evidence.
  10. Require a reply through AxiOwl MCP before calling the bridge recovered.

The operating principle

AxiOwl recovery is evidence-led. The product is designed to fail loudly when a provider edge is incomplete, to keep provider-specific behavior at the edge, and to preserve the distinction between local acceptance and real provider delivery. That makes bridge recovery slower than a blind reinstall, but it gives operators a cleaner answer: which layer failed, which selected feature was repaired, and which proof shows the provider bridge is actually healthy again.

Tagged , , , , , , ,