feat(server): always surface the session URL on every start

[technicalpickles]

Part of #1134, criterion 1 only. Leaving the stable-port half for a separate PR as you suggested, since the abandoned-session cleanup looked like its own conversation.

Summary

• The session URL now goes to stderr on every start, one line, URL last. It previously appeared only for remote sessions, the Codex desktop host, or a failed browser launch, so a local session whose browser opened fine printed nothing and a closed tab left no way back.
• Pi gets the same unconditional announce via ctx.ui.notify, and the OpenCode stderr filter learned the new phrasing while still forwarding the older two-line shape from older binaries.
• isCodexDesktopHost() is gone. It existed only to special-case printing the URL, which is now unconditional.
• PLANNOTATOR_READY_FILE stays exactly what it was, an opt-in side channel that hosts point at their own temp file. No default, per your review. Discovery for everyone else is the stderr line plus the existing plannotator sessions registry, which is what the docs now say.

The format is deliberately boring and stable, since the point is that agents grep it:

  Plannotator session ready: http://localhost:PORT

Two leading spaces, no trailing slash. Remote adds a port-forwarding line after it, and a failed browser launch adds a "could not open" line. The URL itself appears exactly once either way.

Test plan

bun run typecheck is clean.

bun test has four failures that predate this branch, and none of them are in code it touches. Three are in apps/pi-extension/server.test.ts, where a global gpg.format=ssh config leaks into the test's temp HOME and git can't write a commit object; that file imports only ./server.ts plus the generated modules. The fourth is the git-timeout case in packages/shared/workspace-status.test.ts, which lines up with the parallel-timing flakes you mentioned: this branch doesn't touch packages/shared/ at all, and that file passes 6/6 in isolation across three consecutive runs.

New coverage in packages/server/shared-handlers.test.ts pins the URL appearing exactly once on the local, remote, and browser-failed paths, and pins the line's literal bytes including the two-space indent. apps/opencode-plugin/cli-bridge.test.ts imports SESSION_READY_LINE_PREFIX and runs a line built from it through the real filter, so drifting the constant now breaks a test instead of silently costing OpenCode users the URL.

[backnotprop]

Review (at 7ae3d3cf)

Verdict: needs changes, and the core of the PR is genuinely good. The unconditional stderr line is correct, protocol-safe, and well executed: the reviewer ran the real PermissionRequest hook path end to end with streams captured separately and stdout carried only the decision JSON, every new write goes to stderr, and the URL prints only after a successful bind with the final port (the retry path cannot double-print or print a stale port). All four Bun server types share one handleServerReady implementation, so exactly-once holds by construction there. The isCodexDesktopHost removal is safe: exactly one production caller on main, and the new line is a strict superset of what it printed. No conflict with in-flight #1183, textually or semantically. Full suite green (the four failures are the documented parallel-timing flakes; all pass in isolation).

Two things to resolve before merge.

1. The grep-stable format contract is unenforced, and drifting it silently breaks OpenCode. The new test asserts against SESSION_READY_LINE_PREFIX itself, which is self-referential: mutating the constant to different text leaves all 24 related tests green while cli-bridge.ts matches a hardcoded /^Plannotator session ready\b/, so OpenCode users would lose the URL entirely with zero test failures. The two leading spaces everything depends on are also never asserted. Cheap fix: pin the literal bytes once (expect(SESSION_READY_LINE_PREFIX).toBe("Plannotator session ready: ") plus an exact-line assertion including the indent), and add a cross-component test in cli-bridge.test.ts importing the constant, which works today since @plannotator/server is already a linked devDependency there.

2. The ready-file default needs a design decision, and this one is on us, not you. Our #1134 reply pointed you at PLANNOTATOR_READY_FILE, but the repo already has a session registry that solves the discovery problem better: ~/.plannotator/sessions/<pid>.json with dead-PID pruning, surfaced by plannotator sessions and documented in the troubleshooting page one paragraph above the one this PR edits. The new ready.jsonl default duplicates it without pid, timestamp, or liveness, grows unboundedly (confirmed: pure append, nothing trims, only uninstall clears it), and the documented tail -n 1 returns the last session started rather than the last one alive, which reintroduces the exact stale-server confusion from your transcript data. Suggestion: keep the stderr line exactly as you built it, keep PLANNOTATOR_READY_FILE as the opt-in side channel amp already uses (host-supplied value respected, which your wiring does correctly), drop the always-on default file, and have the docs point agents at the stderr line and the existing sessions registry instead. If a default file is still wanted, single-line overwrite with pid and startedAt so staleness is detectable.

Smaller items, none blocking:

• The docs present the ready-file default as global, but only the Claude Code hook calls ensureReadyFileEnv(); Pi never publishes one and OpenCode's in-process paths bypass it. Resolves itself if the default is dropped.
• OpenCode: the browser-failure line ("Could not open a browser automatically") matches none of the filter regexes and is dropped, where the old shape was forwarded; users get the URL but not the reason the tab never appeared. Also the poller and the stderr forwarder now race for which text wins the toast (deduped, so cosmetic).
• Pi announces twice on remote (the new unconditional notify plus the existing sessionOpenedMessage URL embed), so the exactly-once claim does not hold there; pre-existing shape, worth one line.
• PR body nit: it advertises http://127.0.0.1:PORT/ but the emitted URL is http://localhost:PORT, no trailing slash. The docs page is right; the body should match since byte stability is the selling point.
• CLAUDE.md's data-dir row does not mention the new file; moot if the default goes.

On process: this is a first code contribution to the repo and it is a strong one: scoped exactly as discussed on the issue, both runtimes touched, docs and tests included, and the OpenCode compat matrix (old binary/new plugin and the reverse) was validated by the reviewer against the real filter in all six scenarios. Happy to re-review as soon as the two items above are addressed.

[technicalpickles]

This is a better review than I gave you a PR for. Both items are fixed, and you were right on the design call.

1, the format contract. Yeah, that one stings. Asserting against SESSION_READY_LINE_PREFIX meant the test checked the constant against itself, so the one thing OpenCode actually depends on was the one thing nothing verified.

Pinned three ways now: the literal bytes, the emitted line asserted exactly with its two-space indent and newlines, and a cross-component test in cli-bridge.test.ts that imports the constant and pushes a line built from it through the real filter. That import just worked, like you said it would.

Then I mutated the constant to see what happened. Five tests go red, the cross-component one included. Reverted.

2, the ready-file default is gone. You talked me out of it. sessions.ts already carries pid and startedAt and prunes dead PIDs with process.kill(pid, 0), so ready.jsonl was a second session-state mechanism holding strictly less. Your tail -n 1 point is the one that got me, though: last session started instead of last one alive is the exact stale-server confusion I set out to kill. Single-line overwrite with pid and startedAt fixes the staleness, sure. Then it's just a worse copy of the registry. No version of it was worth keeping.

So ensureReadyFileEnv(), getDefaultReadyFilePath(), the purge entry, the apps/hook/ call site, and the docs paragraph all came out. PLANNOTATOR_READY_FILE goes back to opt-in and host-supplied, respected verbatim, which is the part amp leans on and the part that already worked. Troubleshooting now sends people to the stderr line and plannotator sessions. That covers your docs-say-global note too, since the hook was the only thing ever publishing one.

Now the part I didn't fix, before you find it yourself on re-review: the contract is pinned for the Bun runtime and OpenCode, and not for Pi. plannotator-browser.ts hardcodes Plannotator session ready: ${serverUrl} as a bare literal instead of importing the constant, because the Pi extension is a separate Node build that vendors from packages/shared/ rather than packages/server/. So Pi's copy can still drift. Moving the constant into packages/shared/ with a vendor entry would close it, but that's a real change to two runtimes and I didn't want to decide it inside this PR. Your double-announce catch is the same shape: remote does fire twice now, and which of the two should win reads like your call, not mine. Happy to take either as a follow-up.

The dropped browser-failure line was ours, and it's fixed. "Could not open a browser automatically" matched none of the filter regexes, so OpenCode users got a URL and nothing about why no tab showed up, where the old shape forwarded it. Matched and covered.

Body's fixed too. It advertised http://127.0.0.1:PORT/ while the code emits http://localhost:PORT, no trailing slash. Fair hit on a PR whose whole pitch is byte stability.

Marking it ready for review.

[backnotprop]

Delta re-review (at d4b006bd)

Verdict from review: merge as-is. Both findings are properly fixed, and the fix came out smaller and better-reasoned than what the review asked for: the delta is net negative against the base, with the hook wiring, the uninstall entry, and the env-docs paragraph all fully reverted rather than patched around.

Verified independently rather than taken on faith:

• The constant mutation was re-run and fails exactly the five tests you named, the cross-component one included. The exact-line assertion pins the two-space indent and surrounding newlines, and the docstring explaining why the old assertion was self-referential is the part that will stop a future refactor from quietly undoing this. Also checked something you did not claim: the barrel import in cli-bridge.test.ts stays out of the production bundle (devDependency only, and the only available route since the package exports no subpath). Correct call.
• The ready-file removal sweep is clean: zero orphaned references repo-wide, amp's opt-in path byte-identical to main semantics, and a live server run confirms stderr is unchanged and no file is created. The replacement docs accurately describe the sessions registry's liveness behavior.
• The six-scenario compat matrix is fully green including the newly forwarded browser-failure line, and the noise control still drops what it should. Anchoring that regex before the tail of the copy was a good instinct.
• Full suite 2669 pass / 0 fail locally, typecheck clean, merges onto current main with no conflicts (the fix(annotate): resolve natural-language arguments or hand off to the agent #1183 overlap vanished when the hook file reverted). The pre-disclosed Pi items are untouched by this delta, as stated.

CI had not run on the branch (fork PRs need workflow approval); approved now so the merge decision has real signal. The maintainer makes the merge call from here.

The pre-disclosed Pi constant-sharing question and the remote double-announce are logged as follow-up candidates for the maintainer to prioritize.

[backnotprop]

TLDR: This is the right design for the session URL line and the first real attempt at the core of #1134, but the delivery currently breaks both TUI hosts: OpenCode's default embedded runtime leaks the raw stderr print into its renderer, and Pi's two back-to-back notifies coalesce so the URL disappears exactly on the browser-failure path. Per-host prescription below. AI-assisted review.

What's good, and should survive as-is: the single stable line with an exported SESSION_READY_LINE_PREFIX, URL last so agents can grep it; the cross-component drift test with its written rationale for hardcoding the literal; the docs pin; explicitly scoping to criterion 1 of #1134 and leaving the port half for a separate PR; and the stdout contract holds (we verified nothing lands on stdout in hook or json modes). Your CLI-bridge filter update for OpenCode is also correct. For the Bun CLI hosts (Claude Code, Codex, Gemini and friends) the unconditional un-TTY-gated stderr line is exactly right and should not change.

The two host blockers, verified against both hosts' source:

1. OpenCode's default runtime is embedded, not the CLI bridge. handleServerReady runs in-process inside OpenCode's worker-thread server, which shares stderr with the opentui renderer running in passthrough mode, so the new unconditional print writes raw lines into the TUI on every local session. Our own comment at apps/opencode-plugin/server.ts:322-327 documents this hazard, and its premise (that handleServerReady prints nothing locally) is what this PR removes. Fix: add an announce (or quiet) option to ServerReadyOptions, suppress the raw print on the embedded path (embedded.ts and commands.ts call sites), and deliver through the existing logPlannotatorReady channel (client.app.log plus tui.showToast), then update that stale comment.

2. Pi: the two adjacent ctx.ui.notify(..., "info") calls coalesce (Pi's showStatus overwrites back-to-back status lines), so on a headless box the user sees "open the URL above" with no URL above. Collapse to one notify that carries the URL, call it through the safeNotify wrapper, and prefer the in-turn sessionOpenedMessage channel, which our code documents as the one that reliably renders (the after-turn notify fires too late).

Merge-forward items (not your fault, the branch is ~112 commits behind): shared-handlers now contains the QR, urlHost, and tailscale work inside the code this PR restructures, and post-merge the tailscale path would print the ready line twice. Whoever rebases should resolve the QR placement and add a single-print test across the tailscale path; the hook and json modes deserve a stdout-stays-clean test too.

The core is sound and this closes a gap people have been asking about since #601. Rebase plus the two host fixes and it is mergeable. If you want, we can push the mechanical parts (the rebase and the OpenCode announce seam) to your branch and leave the Pi channel choice to you.