Make Each Coding Agent Preview Point to the Right Worktree

Before judging an agent's UI change, connect the task to the service that is presenting the page. Record the worktree, the process launched from it, the address that process actually reports, the page identity at that address, and the target used by any planned checks. A correct directory can still have a browser pointing at another service.

This guide applies when several development previews may be running at once. It uses one complete fictional example with main and two task worktrees. All startup records, page descriptions, and histories below are authored teaching material. No services were started, pages requested, or tests run. Ports 3000, 3001, and 3002 are example values, not ports reserved or checked on your machine.

Two historical discussions motivate the task: a VS Code issue about worktree development-server ports describes a changed port leaving the browser and checks pointed at an earlier service; a superpowers environment-isolation request asks about worktree-specific configuration and raises possible shared-data interference. They are separate reported situations, not reproductions of one incident. Neither establishes what a current version supports, nor that database damage occurred.

Keep the code task small enough to recognize

The fictional app displays two supplied note records in this order:

The main page has the heading Notes, the filter label All items, and an Open action on each record. Task A changes only that action label to Open preview. Task B changes the initial filter to Active only, so its initial page contains N11 and omits N12. Its action remains Open.

These are separate proposed changes from the same main baseline. The records are literal teaching fixtures, not database responses. The exercise does not supply a backend, test account, database configuration, or an implemented filtering function.

Give the three source states simple labels: M0, A1, and B1. Give their serving processes the labels S-M, S-A, and S-B. These are invented references for this case, not Git commit hashes, operating-system process IDs, or commands to execute.

Map the launch separately from the directory

All example services and the example browser use the same computer's loopback network. A remote environment or forwarded preview would need its own host and forwarding information; the example addresses cannot identify that environment for you.

The fictional S-A launch first asks for port 3000. With S-M already using it, this example's server selects 3001 and reports that address. This is a stipulated behavior of the example, not a promise that a framework will fall back rather than stop. S-B reports 3002.

The complete launch notes are:

AUTHORED LAUNCH NOTES — not captured terminal output

S-M
  source label: M0
  launch directory: /example/notes/main
  reported address: http://127.0.0.1:3000

S-A
  source label: A1
  launch directory: /example/notes/task-a
  requested port: 3000
  fictional startup decision: 3000 occupied; selected 3001
  reported address: http://127.0.0.1:3001

S-B
  source label: B1
  launch directory: /example/notes/task-b
  reported address: http://127.0.0.1:3002

In real work, keep the actual process reference and the launch information you can inspect. A terminal tab called “Task A” is a useful label, but it is not the launch directory. Likewise, a message saying “server ready” is incomplete if the address changed and nobody carries it into the next step.

Connect the address to a recognizable page

For this exercise, each authored page includes a sample identity marker. The three complete page descriptions are:

MAIN PAGE — authored fixture
Address: http://127.0.0.1:3000/notes
Page marker: PREVIEW-M0
Heading: Notes
Filter: All items
N11 | Sketch response | active | Open
N12 | Review brief    | archived | Open

TASK A PAGE — authored fixture
Address: http://127.0.0.1:3001/notes
Page marker: PREVIEW-A1
Heading: Notes
Filter: All items
N11 | Sketch response | active | Open preview
N12 | Review brief    | archived | Open preview

TASK B PAGE — authored fixture
Address: http://127.0.0.1:3002/notes
Page marker: PREVIEW-B1
Heading: Notes
Filter: Active only
N11 | Sketch response | active | Open

A page marker helps distinguish these fixtures. It is not an automatic attestation of a source revision. In an actual app, find out where the marker comes from and whether it can be stale or copied. Correlate it with the service's launch information and the task-specific content you intended to inspect.

Here is the intended preview and check map:

baseURL is a name for the check's effective starting address in this example. No framework configuration syntax is prescribed. A real runner may obtain its target from several places, so inspect the value that will actually be used rather than relying on a familiar filename or profile label.

History 1: A is ready, but the browser still shows main

The following history introduces a wrong target. Its page contents and startup notes come from the fictional materials above; they are not captured observations.

Refreshing the unchanged address in W5 cannot select S-A in this case. There is also no reason here to rewrite A's label again: the inspected page belongs to M0. In a real case with incomplete identity information, keep the cause unresolved until you establish the service mapping rather than guessing about caching, rebuilding, or a failed code edit.

A check that only looks for the shared heading Notes would be a weak discriminator: all three fixture pages contain it. An Open preview check aimed at 3000 would examine the wrong source page. These are deductions from the authored pages, not test results. The actual-result field remains empty.

The wrong target explains why a correct checkout and a correct task conversation can still lead to an irrelevant preview. It can happen even with a dedicated browser window and no competing keyboard input.

History 2: carry A's service address through the review

Continue from W8, preserving A1 and the same three service records. The correction below is an authored plan and history; it does not change a real runner or start an automated suite.

The complete before-and-after check record is small:

AUTHORED CHECK TARGET RECORD — no runner invoked

Profile: A-check
Before: baseURL http://127.0.0.1:3000; path /notes
After:  baseURL http://127.0.0.1:3001; path /notes
Expected page identity: PREVIEW-A1
Expected heading/filter: Notes / All items
Expected records, in order: N11, N12
Expected actions: Open preview on both records
Actual run result:

For your own runner, carry the actual startup address into the effective target and the returned review record. If an override, proxy, forwarding rule, stale process, or stale page identity prevents that chain from being established, leave the mismatch open. Repeating the check against an unexplained address does not resolve it.

Give each resource its own boundary

Different port numbers distinguish the addresses written in the map. They do not establish how processes, data, or sessions are separated. A preview may still use a shared backend or an account associated with other work.

Keep these unknowns visible while making useful progress on the address mapping. The sample pages do not justify claims about a database or login that the example never configured. In real work, do not assume that loading a preview has no downstream effects; establish the relevant project behavior before treating it as a harmless inspection surface.

Correct only the identified target. Preserve unrelated services, ongoing work, and data. If the service owner or resource relationship cannot be established, keep the next step to inspection and planning. This guide provides no process-termination, database-clearing, migration, or environment-replacement commands.

Copy a blank read-only preview card

Use a separate card for each intended service. Fill observed fields from information you can actually inspect; leave unknown values unknown. Do not paste credentials or a complete environment file into the card.

Task and intended UI change:

Code
Intended worktree / branch or detached state:
Observed source revision and existing changes:

Service
Process reference and who owns it:
Launch directory and basis for that mapping:
Actual startup address:
Host/container/forwarding context, if applicable:

Page
Final address being inspected, including path:
Expected page identity and where it comes from:
Presented page identity and task-specific content:
What supports its connection to the intended source:
What remains uncertain about freshness or assets:

Checks
Check profile / target definition:
Effective baseURL and path:
Overrides or forwarding that affect the destination:
Planned identity check before behavior checks:
Checks actually performed and results, if any:

Resources
Database/test-data relationship:
Queue/background-work relationship:
Storage relationship:
Browser/account/session relationship:
Any operation already in progress and its known status:

Next read-only inspection or unresolved mismatch:

The card is deliberately blank. The completed main/A/B map is a teaching example, not a set of values to paste into another project. Reinspect the relevant links in the chain when the service restarts, its reported address changes, or the source/page identity no longer matches.

Ask the agent to establish the preview target before judging the change

Help me map the preview for the intended task before assessing its UI change.
This step is read-only inspection and a written mapping, not service startup,
configuration edits, HTTP requests, browser actions, or test execution.

Using the task and launch records I supply, identify:
- intended task, worktree, source revision, and specific expected change;
- serving process reference, launch directory, and reported address;
- page address/identity information already supplied and what it establishes;
- the check runner's effective baseURL/path, including any visible overrides;
- database, queue, storage, and browser/session relationships that remain unknown.

Distinguish the intended destination from what the records actually show.
If the browser or check target still points at main, name that mismatch.
Do not diagnose a missing source change from a page belonging to another service.
Do not treat a page label as proof of every source, asset, or backend relationship.

Return a task-to-service-to-page-to-check map, unresolved links, and the
smallest proposed target correction. Separate any later proposed page/check
inspection from work already performed. Leave unrun results unrun.

Do not launch or stop processes, change ports or configuration, clear storage,
seed data, run migrations, execute checks, or modify the application in this step.
Do not assume a new port isolates data or sessions. If a relationship is missing,
state it and identify the information needed to continue.

A worktree-to-conversation check answers which code and instructions a task should use. A shared-browser handover answers who may send the next UI input. This additional map answers which running service presents the page and which address the checks will reach. Keep all three questions separate, and use the preview as evidence for a change only to the extent that its connection to the intended source is established.