feat(observe): autostart the observe web UI + lifecycle controls (restart, config opt-out, stable port) (#403)

* docs(specs): observe UI overhaul + autostart design spec

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(plans): TDD implementation plans for observe autostart (PR 1) + UI overhaul (PR 2)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(observe): config resolvers for autostart + port (env > .rn-agent/config.json > default 7333)

Implements parsePort, DEFAULT_OBSERVE_PORT, resolveObserveAutostart, and
resolveObservePort with env > config > default precedence matching existing
resolveAutoConnect pattern.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(observe): restart action + config-resolved port in observe tool

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(observe): pin unique port in observe-tool test so the suite never binds the real default 7333

* feat(observe): per-project state file records the live UI url (GH #383 state-file pattern)

* feat(observe): autostart web UI at MCP boot in RN projects (non-fatal, env/config gated)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(observe): SessionStart URL notice + /observe command covers stop/restart and autostart opt-out

* fix(observe): route /observe sub-arguments via $ARGUMENTS + tolerate null config in hook notice

* build(cdp-bridge): rebuild dist for observe autostart + lifecycle (PR1 tasks 1-5)

dist/ is the shipped artifact for the plugin (not gitignored, per 86e54ac).
Tasks 1-5 of the observe-autostart-lifecycle spec landed src/test changes but
left the compiled output stale; this brings dist back in sync via `tsc` so
the shipped plugin actually carries the autostart, port-resolution, restart
action, and state-file behaviors.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore: changeset for observe autostart + lifecycle

Also applies the oxfmt fix on observe-state-file.test.js caught by the
repo-wide `npx oxfmt --check` gate.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(observe): prove stop closes the port while the worker process stays alive

* fix(observe): make autostart fire-and-forget so a throwing logger can never reject main()

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(observe): serialize start/stop so a stop racing a pending start cannot orphan the server (PR #403 review)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: Lykhoyda

.changeset/observe-autostart-lifecycle.md

@@ -0,0 +1,11 @@
+---
+"rn-dev-agent-cdp": minor
+"rn-dev-agent-plugin": minor
+---
+
+The observe web UI now autostarts when the MCP worker boots in an RN project, listening on a
+stable default port (7333, `http://127.0.0.1:7333`) with an ephemeral fallback on collision.
+New `.rn-agent/config.json` block `{ "observe": { "autoStart": boolean, "port": number } }`
+plus `RN_AGENT_OBSERVE_AUTOSTART` env override (precedence env > config > default, matching
+`cdp.autoConnect`). The `observe` tool gains a `restart` action; `stop` is session-scoped.
+The live URL is recorded in a per-project state file and announced at SessionStart.

commands/observe.md

@@ -1,6 +1,21 @@
 ---
 command: observe
-description: Start the read-only observability web UI and print the URL to watch the agent live.
+description: Show the observability web UI URL (it autostarts with the session); stop or restart it.
+argument-hint: [stop|restart]
 ---
 
-Call the `observe` MCP tool with `action: "start"`. Print the returned `url` prominently and tell the user to open it in a browser to watch the live tool-call timeline, device screenshot, and app state. If it's already running, `observe status` returns the existing URL; to stop, call `observe` with `action: "stop"`.
+The observe web UI autostarts when the session begins in an RN project. Permanent opt-out:
+`.rn-agent/config.json` → `{ "observe": { "autoStart": false } }` (port via `observe.port`,
+default 7333; env `RN_AGENT_OBSERVE_AUTOSTART` / `RN_AGENT_OBSERVE_PORT` override config).
+
+The user's argument: "$ARGUMENTS"
+
+- If the argument is empty: call the `observe` MCP tool with `action: "status"`. If running,
+  print the returned `url` prominently and tell the user to open it in a browser to watch the
+  live tool-call timeline, device screenshot, and app state. If NOT running (autostart disabled
+  or previously stopped), call `action: "start"` — an explicit /observe is an explicit request
+  to see the UI — and print the URL.
+- If the argument is `stop`: call with `action: "stop"`. The UI stays down for the rest of the
+  session; mention the config opt-out if the user wants it permanent.
+- If the argument is `restart`: call with `action: "restart"` and print the (possibly new) URL.
+  The event timeline is preserved across restarts.