The control surface

[claude]

Question

Where does the user configure the app, pick the target window, and enter the API key — now that there is no Electron window to put those in?

The output window put history and settings behind titlebar icons on a desktop window that no longer exists. Configuration and API key storage specified an in-app masked input for the key and a picker for the target window, both assuming that window. Cost control assumed a status pill and a pause the user can reach. All three need a new home.

Blocked on The host runtime (which decides whether any local UI exists at all) and Reach and trust (which decides whether a networked client is trusted with the key).

Decide:

• Where settings live. In the web client, on a separate local-only admin page, in a config file edited by hand, or via CLI flags. Configuration and API key storage #8's requirement that all settings apply live with no restart survives and constrains this.
• The window picker. Choosing a capture target means enumerating windows on the host and showing them. Whether that's reachable from a phone across the room, or deliberately host-only. Configuration and API key storage #8 identified the target by process name + title with a fallback to reopening the picker — decide where that picker opens now, especially at startup with no client connected.
• The API key. Whether a masked input in the web client is acceptable, given what Reach and trust decided about who can reach it, or whether key entry is host-only by construction. The key never leaving the host process is settled; this decides how it gets in.
• Control from a client. Whether a connected browser can pause the loop, resume it, change the interval, or force a solve — or whether clients are strictly read-only mirrors and control is host-side. This also settles whether The stream contract's transport needs a client-to-server direction at all. Cost control #9's pause is the sharp case: hitting a budget limit stops the loop, and someone has to be able to resume it.
• Multiple clients disagreeing. If clients can control the loop, what happens when two do at once. If they can't, this is moot — which is an argument for read-only.
• First-run. With no key and no target window, what the very first visitor to the client sees, and whether the app can be configured entirely from a browser or needs a host-side step.

Deliverable: the control surface — what lives where, what a client may and may not do — expressed in #7's and #9's existing vocabulary wherever it already covers the case.

---

Generated by Claude Code

[jpka]

Update — The host runtime resolved, and it deletes this ticket's hardest bullet rather than answering it.

• The API key. Gone as a question. The host runtime #16 reversed Configuration and API key storage #8's safeStorage outright: the key is an ANTHROPIC_API_KEY env var read once in main and deleted from process.env before any renderer exists, and a missing key means the app refuses to start. So key entry is host-only by construction — there is no masked input anywhere, and the web client can never accept, echo, or hold a key. Nothing left to decide here.
• What local UI exists. Electron stays, but the only window is a hidden BrowserWindow that owns the capture stream — no chrome, nothing to hang settings on. There is no desktop surface to fall back to, so whatever this ticket picks is the only control surface there is.
• The pause control got easier. Cost control #9's sticky runaway breaker is in-memory and clears on restart (with no auto-start, a restart is the human acknowledgment), so no "clear the breaker" affordance is needed. That was the sharp case for client-side control; it's off the table.
• The window picker at startup is now unambiguously host-side-or-nothing, since the app has already refused to start if unconfigured on the key axis. Worth deciding whether the target window follows the same "refuse to start" rule or the softer "start and wait" one.
• New, from The host runtime #16: the capture session is held per run, torn down on pause and rebuilt on resume. So a pause has a real, visible consequence on the host (the yellow border goes dark) and none at all on a phone — which sharpens this ticket's half of the map's remaining "what watching looks like" fog.

---

Generated by Claude Code

[jpka]

Map update — two changes to this ticket's inputs. (1) Reach and trust closed as out of scope rather than resolved — it will not hand this ticket a decided trust/auth posture for the server. This ticket is no longer blocked waiting on it (GitHub will reflect that once the dependency's blocker closes), but "The API key" bullet now has to be decided without that input; lean toward the conservative default (host-only key entry) unless there's a specific reason to trust a networked client. (2) The trigger is now manual — the user clicks a "solve now" button in the web client — which settles that a client can send at least one command upstream, partially answering "Control from a client": yes, at minimum, for triggering a solve. What's still open is whether pause/resume/interval/settings follow the same path or stay host-side (note the map's "interval" concept itself is gone — there's no interval to control). See Screen Solver's updated Notes table and Out of scope section.

[jpka]

Resolved — grilled live with the user.

Where settings live: the web client itself — no separate admin page, no host-only restriction, no auth. Decided directly: v1 is personal-use-only, so the map's earlier "lean host-only absent a specific reason to trust a networked client" default doesn't apply here — only the API key stays host-only by construction, unchanged from #16.

Startup with no target window configured: start and wait, not refuse-to-start. Unlike the key, the target window can't gate startup — the only place to pick it is the web client itself, so refusing to start would make the picker unreachable. The server starts normally; if no target is configured (first run, or #8's re-resolve-by-title fallback fails), the client shows the window picker in place of the normal focus-pane view. POST /solve without a configured target returns 400.

The picker is persistent, not one-time. Reachable at any time post-setup, not locked after first run — matches #8's "all settings apply live, no restart" rule. Retargeting mid-session needs no restart.

Multiple clients / conflicting changes: last-write-wins. A target-window change overwrites config (in-memory + config.json) and broadcasts to every connected client via a new config{target} event on The stream contract's existing SSE channel — the same "one shared broadcast, no per-client filtering" rule #18 already established, no new transport. No locking, no conflict UI. An in-flight solve is unaffected by a retarget, since capture happens before the LLM call starts; only the next solve uses the new target.

First-run: the API key is the one unavoidable host-side step (env var, refuse-to-start, per #16 — unchanged, not revisited here). Everything else, target window included, is fully configurable from the browser starting on the first visit. No config-file editing, no CLI flags, no separate admin step.

Control from a client, now fully settled: a client can trigger solve (settled earlier by the manual-trigger scope change) and can view/change the target window (settled here). There is no interval to control (the concept doesn't exist) and no pause/resume affordance is needed (#9's breaker is in-memory and clears on restart).

Deliverable, in #7's/#9's vocabulary: the focus pane is the only view when a target is configured; it's replaced by the window picker when it isn't. There's no titlebar, no admin panel, no host-only gate — the web client is the control surface, wide open, by design, for a personal-use v1.

[jpka]

Closing — resolved above.