TaskTime Pro local agent bridge
Debugging TaskTime Pro Agent Access
Troubleshooting guide for TaskTime Pro local MCP bridge pairing, unavailable app-session recovery, smoke tests, DebugBundle usage, and production-safe agent debugging.
Common Recovery Hints
| Signal | Agent response |
|---|---|
UNAVAILABLE with launch_tasktime | Call get_pairing_status, open the active bridge launchUrl, pair Account > Agent Access, then retry the tool call. |
| Expired or used pairing code | Call refresh_pairing on the active MCP bridge and use the returned launch URL. Do not start a second terminal bridge for a managed install. |
| Missing scope | Explain the required scope and ask the user whether to relaunch or reconnect with that scope. Do not tell users to select scopes in the app unless a scope picker is visible. |
| Approval gated | Use a valid exact-input approval token from a trusted local grant or wait for visible browser approval. |
| Pairing failure | Check that the endpoint is from the active bridge, the dynamic port is listening, the path matches, the code is fresh, and browser local-network policy allows loopback WebSockets. |
| Paired, then disconnected after refresh | Update TaskTime Pro and the bridge/plugin together. Current builds restore the same tab automatically; do not start another bridge. |
| Disconnected after closing and reopening TaskTime | Use the same browser profile and allow IndexedDB/Web Crypto. Restricted/private storage falls back truthfully to explicit pairing. |
legacy_mcp_conflict | Back up the OpenClaw config, inspect the reported legacy path, preview openclaw config unset <path> --dry-run, then unset, validate, and restart. Do not run both owners. |
| Bridge PID, instance ID, or port changed | The Gateway/bridge restarted. Old browser authorization is intentionally invalid; use the new get_pairing_status launch URL once. |
| OpenClaw CLI/Gateway versions differ | Run openclaw --version, which openclaw, and openclaw gateway status --deep; align versions before changing TaskTime setup. |
Local Verification
After changing the bridge, tool definitions, docs generation, or Agent Access UI, run the focused bridge checks through Docker.
make npm CMD="run build:agent-bridge"
make npm CMD="run build:openclaw-plugin"
make npm CMD="run smoke:agent-bridge"
make npm CMD="run smoke:agent-bundles"
make npm CMD="run smoke:agent-live"
make npm CMD="run test:run -- src/agent/bridge/mcpServer.test.ts src/agent/bridge/bridge.test.ts src/agent/commands/commands.test.ts"
Use make build before release to verify the merged React app and Astro public docs artifact.
DebugBundle Usage
Use DebugBundle when the problem is a runtime or customer-facing incident: endpoint downtime, production failures, health-check failures, webhook or notification delivery issues, noisy captured incidents, or symptoms likely to have generated captured events.
For deterministic local source issues, UI layout issues, copy changes, refactors, and test-only failures, inspect source and tests first. Do not check DebugBundle incidents unless runtime evidence is needed.
Production Data Rules
- Do not tell users to clear browser data or cloud sync state as a normal fix.
- Do not auto-sync destructive resets across devices.
- Preserve existing IndexedDB, Yjs, cloud sync, invoice, billing, and backup contracts.
- Use preview commands before destructive delete, restore, billing, or account-data operations.