# External Beta Troubleshooting

Status: BETA3 tester support guide.

## Helper Health States

| State | Meaning | First Remediation |
| --- | --- | --- |
| `healthy` | Helper, extension, and MCP-visible state respond | Continue with Set Target Tab |
| `starting` | Helper is still responding | Wait briefly, then Run Doctor |
| `disconnected` | No live native helper response | Click Fix Now, then run native doctor |
| `stale_version` | Installed helper/runtime identity drift | Update, restart MCP/helper, reload extension |
| `auth_failed` | MCP endpoint rejected session | Refresh token and restart adapter/session |
| `token_expired` | Session token expired | Generate a fresh token file |
| `queue_stalled` | Live navigation did not reach terminal result | Click Fix Now, then Set Target Tab and retry |
| `native_host_unavailable` | Chrome cannot reach native host | Reinstall/verify native manifest |
| `mcp_unreachable` | MCP listener not reachable | Start MCP on configured host/port |
| `extension_inactive` | Runtime snapshot is not extension-backed | Reload extension and open popup on target tab |

## Common Failures

| Symptom | Likely Cause | Fix |
| --- | --- | --- |
| No target tab | Popup opened from the wrong window or no HTTP/HTTPS page focused | Focus the intended tab and click Set Target Tab |
| Origin grant required | Live actions are enabled but current origin is not granted | Click Grant current origin |
| Tab mismatch | Active tab changed after approval was requested | Return to target tab or create a new target lease |
| Action limit exceeded | Policy session/origin/agent limit hit | Review policy, extend session, or wait for limit reset |
| Panic mode active | Panic was triggered | Reset intentionally after reviewing audit state |
| Disabled unverified BrowserBridge extension | Chrome retained a stale CRX/external-install artifact | Remove the disabled entry from `chrome://extensions`, keep only the current Load unpacked BrowserBridge entry, then rerun installer doctor with the active extension id |
| Native manifest extension id mismatch | Native host manifest is pinned to an older extension id | Copy the current unpacked extension id, then run `scripts/install-or-update.sh update --from-latest --extension-id <id> --confirm --skip-start` and rerun doctor |
| Unpacked path mismatch | Chrome is loading an older BrowserBridge dist directory | Remove the old entry, Load unpacked from the current `packages/extension/dist`, and rerun doctor until it reports `path-ok` |

## Diagnostics

Use **Export Diagnostics** from Control Tower. The bundle is redacted and safe
for issue reports, but review it before sharing externally.

## Manual Browser Smoke

Automated smoke cannot visually inspect Chrome without screenshots or broad tab
enumeration. For visual verification:

1. Open `https://example.com`.
2. Open Control Tower from that tab.
3. Click Set Target Tab.
4. Request navigation to `https://www.google.com`.
5. Approve.
6. Confirm Chrome visibly changes to Google.
7. Trigger Panic and verify future actions are denied.