fix(web): a planning launch waits for the picker's options before judging the agent

startPlanning() navigated to the Study Session console, then startSession()
returned before any fetch with "Select an agent to continue." whenever
`this.agent` was still unset — and it is only set once init()'s
/api/session/options has resolved. On a cold server a "Plan with architect"
click can beat that fetch: the learner lands on the console with no session
and a refusal for a choice they were never offered. In CI this was the first
e2e test of test_web_plan_architect_journey.py failing on both PR #20 runs
(F......... — a navigated page and no POST, then a 20 s timeout) while the
nine warm-server tests passed; locally the cold start answered in 60 ms, so
it never showed.

init() now records the options settlement as _optionsReady (resolved in a
finally, never rejecting), and a planning start with no agent awaits it
before the check. No agent after the options resolve is still the same
named refusal. A focus start is untouched: its Start button is disabled
until an agent exists.

Proved in a real browser by holding /api/session/options (no continue),
clicking, and asserting no POST and no refusal, then releasing and requiring
exactly one 201: fails on the old code with "Could not start the architect:
Select an agent to continue.", passes with the fix. That scenario is now a
permanent journey test; the JS unit suite gains the same race and the
no-agent-after-options case (135/135). Journey module 11 passed on ten
consecutive runs; one earlier run of the module had a single failure whose
identity was not captured before it passed again — recorded, not explained.

Author: NetDevAutomate

packages/studyloop/src/studyloop/web/static/js/components/session-timer.js

@@ -178,6 +178,13 @@ export function sessionTimer() {
         const statePromise = fetch('/api/session/state')
           .then((res) => res.ok ? res.json() : {})
           .catch(() => ({}));
+        /* A launch that arrives before the options have resolved (a Plans-view
+           "Plan with architect" click on a cold server) awaits this before it
+           judges whether an agent exists -- otherwise it refuses with "Select an
+           agent" against a picker that simply has not learned its agents yet.
+           Resolves either way; the fetch's own catch above makes it never reject. */
+        let markOptionsSettled;
+        this._optionsReady = new Promise((resolve) => { markOptionsSettled = resolve; });
 
         try {
           const options = await optionsPromise;
@@ -197,7 +204,9 @@ export function sessionTimer() {
             const firstAvailable = (this.studyOptions.agents || []).find((a) => a.available);
             if (firstAvailable) this.agent = firstAvailable.value;
           }
-        } catch { /* enhanced picker unavailable — free-text still works */ }
+        } catch { /* enhanced picker unavailable — free-text still works */ } finally {
+          markOptionsSettled();
+        }
 
         try {
           const state = await statePromise;
@@ -275,6 +284,14 @@ export function sessionTimer() {
            architect interviews for one, and the server names the session
            "Study plan" when none was given — so '' is a valid topic here. */
         if (!topic && purpose !== 'planning') return false;
+        /* A planning launch can arrive from the Plans view before init()'s
+           options fetch has resolved; the agent is not missing, it is not yet
+           known. Wait for the picker's own settlement before deciding.
+           (init() sets _optionsReady on every run; a timer whose init never
+           ran has nothing to wait for and falls through to the check.) */
+        if (purpose === 'planning' && !this.agent && this._optionsReady) {
+          await this._optionsReady;
+        }
         if (!this.agent) {
           /* The Start button is disabled without an agent; a Plans-view launch
              has no such guard, so refuse here with the picker's own hint. */

packages/studyloop/tests/js/plan-architect-launch.test.js

@@ -436,3 +436,67 @@ test('liveAgentConsole adopts purpose from /api/session/state on reload', async
   assert.equal(con.lastDetail.reattached, true);
   assert.match(con.purposeLabel, /planning/i);
 });
+
+/* ---------------------------------------------------------------- *
+ * The cold-server race (CI e2e, PR #20 runs 35214968238 / 35216220593):
+ * startPlanning() navigated to the console, then startSession() returned
+ * false before any fetch because `this.agent` was still unset -- init()'s
+ * /api/session/options had not resolved yet. The learner saw the console
+ * with "Select an agent to continue." and no session; the journey saw a
+ * navigated page and no POST. A planning launch must wait for the picker's
+ * own options before deciding there is no agent.
+ * ---------------------------------------------------------------- */
+
+test('startPlanning made before the options resolve waits for the agent and still POSTs once', async () => {
+  let releaseOptions;
+  const optionsGate = new Promise((resolve) => { releaseOptions = resolve; });
+  const baseFetch = globalThis.fetch;
+  globalThis.fetch = async (url, opts) => {
+    if (String(url).endsWith('/api/session/options')) {
+      await optionsGate;
+      return jsonResponse(200, {
+        agents: [{ value: 'claude', label: 'Claude', available: true }],
+        topics: [], terminal_engine: {},
+      });
+    }
+    return baseFetch(url, opts);
+  };
+  const timer = sessionTimer();
+  timers.push(timer);
+  timer.$nextTick = (cb) => cb();
+  const initDone = timer.init(); // options still in flight: no agent yet
+  const seen = startEvents();
+
+  const launch = timer.startPlanning({ topic: 'SQL window functions' });
+  await settle();
+  assert.equal(posts.length, 0, 'nothing to POST until the picker knows its agent');
+  assert.equal(timer.startError, '', 'must not refuse while the options are still loading');
+
+  releaseOptions();
+  await initDone;
+  const ok = await launch;
+
+  assert.equal(ok, true);
+  assert.equal(posts.length, 1, 'exactly one POST once the agent is known');
+  assert.equal(posts[0].purpose, 'planning');
+  assert.equal(posts[0].agent, 'claude');
+  assert.equal(seen.length, 1);
+  assert.deepEqual(navCalls, ['study-session']);
+});
+
+test('startPlanning with no agent available after the options resolve still refuses by name', async () => {
+  const baseFetch = globalThis.fetch;
+  globalThis.fetch = async (url, opts) => (String(url).endsWith('/api/session/options')
+    ? jsonResponse(200, { agents: [{ value: 'claude', label: 'Claude', available: false }], topics: [] })
+    : baseFetch(url, opts));
+  const timer = sessionTimer();
+  timers.push(timer);
+  timer.$nextTick = (cb) => cb();
+  await timer.init();
+
+  const ok = await timer.startPlanning({ topic: 'SQL window functions' });
+
+  assert.equal(ok, false);
+  assert.equal(posts.length, 0);
+  assert.match(timer.startError, /select an agent/i);
+});

packages/studyloop/tests/test_web_plan_architect_journey.py

@@ -595,3 +595,58 @@ def test_abandoning_a_launch_mid_flight_leaves_no_session_and_no_plan(
     assert _visible_purpose_labels(page) == []
     # The slot is free: the abandoned session's id is not what a reconnect would find.
     assert state.get("last_release", {}).get("study_session_id", study_id) == study_id
+
+
+# ---------------------------------------------------------------------------
+# The cold-server race (PR #20 CI runs 35214968238 / 35216220593, e2e job)
+# ---------------------------------------------------------------------------
+
+
+def test_click_that_beats_the_options_fetch_still_starts_exactly_once(page: Page) -> None:
+    """On a cold server the first "Plan with architect" click arrived before the
+    picker's ``/api/session/options`` had resolved. ``startPlanning()`` had
+    already navigated to the console, then ``startSession()`` returned before
+    any fetch with "Select an agent to continue." — the agent was not missing,
+    it was not yet known. The learner saw the console and no session; the
+    journey saw a navigated page and no POST, and the first test of this
+    module failed on both CI runs while the nine warm ones passed.
+
+    The options request is HELD here (no ``continue_``) so the click provably
+    beats it, then released: the launch must wait, not refuse, and then make
+    exactly one POST that the server answers 201."""
+    held: list = []
+    page.route("**/api/session/options", lambda route: held.append(route))
+    posts: list[dict] = []
+
+    def _on_response(response) -> None:  # type: ignore[no-untyped-def]
+        request = response.request
+        if request.method == "POST" and request.url.endswith("/api/session/start"):
+            posts.append({"status": response.status, "body": json.loads(request.post_data or "{}")})
+
+    page.on("response", _on_response)
+    _goto_plans(page)
+    _instrument_starts(page)
+    assert held, "the options request was never issued, so nothing is being raced"
+    page.locator('[data-testid="plan-architect-subject"]').fill("SQL window functions")
+
+    page.get_by_role("button", name="Plan with architect").click()
+    page.wait_for_timeout(800)
+    assert posts == [], "no agent is known yet, so no POST may have been made"
+    status = page.locator('[data-testid="plan-architect-status"]').inner_text()
+    assert "select an agent" not in status.lower(), (
+        f"refused before the options resolved: {status!r}"
+    )
+
+    def _is_start(response) -> bool:  # type: ignore[no-untyped-def]
+        return response.request.method == "POST" and response.url.endswith("/api/session/start")
+
+    with page.expect_response(_is_start, timeout=20000):
+        for route in held:
+            route.continue_()
+
+    page.wait_for_timeout(600)
+    page.remove_listener("response", _on_response)
+    assert [p["status"] for p in posts] == [201], posts
+    assert posts[0]["body"]["purpose"] == "planning"
+    assert posts[0]["body"]["topic"] == "SQL window functions"
+    _wait_for_console(page)