An agent's diff and a browser page can both be real while showing different versions of an app. Imagine the agent changed a task board's button label, yet the local preview still has the old label. First identify which file changed and which process is serving the page. Only then investigate hot reload or cache. This order avoids another speculative edit that makes the branch harder to review.
Prove the change exists in the checkout you meant to run
Ask the agent for the exact file, branch, worktree path, and changed line. In that checkout, inspect Git status, the diff, and the most recent commit. An empty diff may mean the change was committed; it may also mean you are standing in another worktree. Search for the expected new label in the file the app imports. If another agent edited the same feature in a different checkout, compare the two paths before trying to restart anything. A terminal tab, an agent conversation, and a Git worktree identify different things.
- Write down the new text or behavior you expect to see.
- Record the repository root and branch for both the agent and the service process.
- Check committed and uncommitted changes; do not reset an unexplained checkout.
Match the browser URL to one live server
Read the running service's command, working directory, process output, and printed URL in Canopy Servers or the original terminal. Open that exact URL, including its port and path. When two worktrees run the same framework, one may move to another free port or fail to start; an old browser tab can still point at the first worktree. Restart the intended service only after you know its directory and command. If the process log shows a build error, fix that first. A green process badge is weaker evidence than a successful page request from the intended server.
| What changed | What serves | What opens | What you observed |
|---|---|---|---|
| File, branch, worktree | Command, directory, printed port | Full local URL and browser tab | Expected marker versus actual marker |
Separate hot reload failure from a stale browser response
Make a harmless, visible test edit in the intended checkout and watch the service log. If the server never reports the file change, investigate its watcher, imported path, or container and filesystem setup. Vite documents both undetected file changes and cases where a detected change fails to hot reload; a case mismatch in an import is one documented cause. If the server did react, reload the exact URL once. In Chrome DevTools, the Network panel can disable the browser HTTP cache while DevTools is open. Compare the document and changed asset requests before clearing data. A hard reload is a diagnostic step, not proof that the deployed app or another user's browser is fixed.
- If this is a Next.js App Router page with stale fetched data, check whether the view changes after full navigation or reload; its development Server Components HMR cache can retain fetch responses across hot updates.
- If the app registers a service worker, inspect its active and waiting versions and Cache Storage in the browser Application panel. Service-worker caches are a separate layer from ordinary HTTP cache.
- Do not clear all site storage before checking whether the problem is an old server or port; that can erase useful local state without addressing the cause.
Check whether the old value comes from data, not the UI bundle
If the new button label appears but the list, count, or profile is still old, use the browser Network panel to find the request that supplies that value. Record its URL, response status, and a safe excerpt of the returned data. Compare the frontend's environment or API target with the server and database you intended to run. A page can load fresh JavaScript while requesting an older backend or a different test account. A service worker may also intercept a request, so inspect the request's source before blaming the API. For a deployed Preview, compare the deployment commit and environment separately; local refresh steps cannot update a hosted build.
- Distinguish old HTML or JavaScript from an old API response or persisted client state.
- Use one test record with a recognizable, non-sensitive marker to identify the data source.
- Never copy production credentials into a local or preview environment just to make the values match.
Give the agent a diagnosis and retest the exact symptom
Tell the agent which boundary failed: wrong checkout, wrong port, server did not see the edit, browser cache, service worker, or data source. Ask for one scoped correction and a short explanation tied to the evidence. Then reopen the service's printed URL, repeat the original action, and inspect the latest diff. If the fix required a configuration change, record who changed it and restart or redeploy the affected environment. The final handoff should name the checkout, URL, expected marker, and observed result so the next reviewer can reproduce it.
- A browser refresh that shows the new label closes only that symptom; test the changed interaction too.
- Verify the final state after the agent's last edit, not from an earlier screenshot.
- Keep the old and new URLs in the report if a server moved ports.
Copyable resources
Stale preview diagnosis card
Use a harmless visible marker; redact private URLs, tokens, and response bodies before sharing.
Expected visible change: [ ]
Agent file / branch / worktree: [ ]
Git status, diff, or commit showing the change: [ ]
Service command / working directory / printed URL: [ ]
Browser URL actually opened: [ ]
Did server log report the file edit? [yes / no / unknown]
Did full reload change the page? [yes / no]
Was HTTP cache or a service worker involved? [evidence]
If data is stale, request URL / status / target: [ ]
First differing boundary and smallest correction: [ ]
Retest result after last edit: [ ]Frequently asked questions
Why does the code change appear in Git but not in my local browser?
First compare the changed checkout with the service's working directory and the browser's full URL. A different worktree or port is often distinguishable without changing code. Then inspect server reload and browser requests.
Should I clear the browser cache immediately?
First confirm the right server and port. Then use the Network panel to compare responses with cache disabled. If the app uses a service worker, inspect its separate cache and lifecycle before clearing site data.
Can hot reload update code while the page still shows old data?
Yes. A data request can target another backend, and some development frameworks cache fetched responses across hot updates. Inspect the specific request and perform a full reload to separate those cases.
Will restarting the agent fix the preview?
Restart the service that serves the page only when its process or watcher is the issue. An agent restart does not change which URL the browser opens or which backend it calls.