backnotprop / backnotprop/plannotator
Session reachability: always surface the review URL, and keep the port stable across plan resubmissions
- Dominant language
- TypeScript
- Stars
- 8.7k
- Forks
- 649
- Avg merge
- 11h 12m
- Merged PRs (30d)
- 109
Description
Two small gaps make a running Plannotator session hard to reach. Both were reported separately (#601, #589) and both are still current on main. This issue supersedes both.
**1. The URL is only printed when the browser fails.** `handleServerReady` (packages/server/shared-handlers.ts:209-228) writes the session URL to stderr only when the session is remote, when the Codex desktop host is detected, or when `openBrowser()` fails. On the common local path where the browser opens fine, nothing is printed, so there is no way to recover the URL if the tab is closed, if you are on a second machine, or if you want to hand it to another tool.
**2. The port changes on every resubmission.** `getServerPortConfiguration` (packages/server/remote.ts) returns port 0 for local sessions, so each deny, revise, resubmit cycle spawns a new process on a new random port. Anyone pointing a secondary tool or a bookmark at the session has to be re-told the port every round. `PLANNOTATOR_PORT` is the only workaround today, and #1042's bounded ranges do not address it (a range still picks a different free port each start).
**Acceptance criteria**
- The session URL is written to stderr on every session start, including local sessions where the browser opened successfully.
- Within one plan review cycle (same project and plan slug), a resubmitted plan reuses the previous session's port when it is still free, without requiring `PLANNOTATOR_PORT`.
- `plannotator sessions` continues to list and reopen these sessions unchanged.
Out of scope: the portless / stable-hostname idea from #601. That is a much larger proxy story; open it separately if wanted.
Related: #899 (big-picture session tracker), #1042 (bounded port ranges, merged).
Contributor guide
Research direction
Start by reading handleServerReady in packages/server/shared-handlers.ts:209-228 and getServerPortConfiguration in packages/server/remote.ts, then inspect the plannotator sessions behavior. Done means every session start prints its URL to stderr, resubmissions reuse the prior free port for the same project and plan slug without PLANNOTATOR_PORT, and sessions listing and reopening remain unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend, cli, networking
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 65/100