backnotprop / backnotprop/plannotator

Session reachability: always surface the review URL, and keep the port stable across plan resubmissions

Open
#1,134 2 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.