Connect: 'Waiting for bridge…' hangs at 15% — only manual install works

[latentloop07]

Repro

1. Fresh 0.5.5 install (npx skillnote@latest start or docker compose up, version v0.5.5)
2. Open the web UI → Connect → Connect Claude Code
3. Modal opens with progress bar at 15% — Setting up Claude Code, Waiting for bridge…

Expected

The automatic flow runs to completion: bridge picks up the dispatched job, executes the install on the host, modal advances through the heuristic step list, finishes at 100%.

Actual

Modal stays at 15% indefinitely with the "Waiting for bridge…" spinner. The 25s client-side timeout (src/components/integrations/connect-modal.tsx:146-165) was supposed to surface a helpful error message in this situation but does not fire on at least some setups — observed sitting well past 25s with no error shown.

The Manual install command (curl pipe) under the "Advanced" disclosure works fine — proving the API + script paths are healthy; the problem is purely the bridge auto-dispatch path.

Screenshot

(See attached — modal stuck at 15%, manual command shown below.)

Likely root cause

The web modal dispatches a job to /v1/setup/agent and then waits for a local skillnote bridge daemon to claim and execute it. The bridge is auto-started by skillnote start (cli/src/commands/start.ts:266-279 spawns runBridgeLoop in-process), but it does not run when the user starts SkillNote via:

• docker compose up -d directly (no CLI wrapper)
• A fresh npx skillnote@latest start where the bridge silently crashes on first launch
• Any case where the host machine doesn't have the bridge process running

The UI currently can't distinguish "no bridge present" from "bridge present but slow" — it just spins.

Suggested fixes (in priority order)

1. Surface 'no bridge detected' faster. The 25s client timeout exists but isn't showing up on every code path. Audit connect-modal.tsx state transitions to ensure the timeout consistently advances the UI into an error state with the manual fallback promoted.
2. Add a server-side liveness signal for the bridge. Expose e.g. GET /v1/bridge/health that returns the last-poll timestamp from any connected bridge. The modal can read this on open and, if no bridge has polled in the last ~5s, skip straight to a "Bridge not running — see manual install" state with the curl command surfaced (no expand needed).
3. Auto-promote manual install in non-CLI deploys. When the user reached SkillNote via plain Docker (detect via a build-arg or runtime flag the CLI sets when it boots the stack), default to showing the manual install pre-expanded — bridge automation is a CLI-only feature, and the docker-only path shouldn't pretend otherwise.
4. Better doctor coverage. skillnote doctor should warn loudly if the bridge isn't polling, and link to remediation.

Workaround for users hitting this today

Click "Advanced" → "Manual install" → copy the curl command → run it in a terminal on the host. Works end-to-end.

Environment

• SkillNote v0.5.5 (ghcr.io/luna-prompts/skillnote-{web,api}:0.5.5)
• Started via docker compose up -d directly (not skillnote start) — which is the most common cause but the modal should still degrade gracefully
• macOS / Chrome