Windows worker first-run onboarding: packaged setup dialog + working `scarcity-worker.exe pair` (v0.1.0 release blocker) #113

New issue

Closed

opened 2026-09-22 20:58:08 +00:00 by kilo · 0 comments

kilo commented

2026-09-22 20:58:08 +00:00

Member

Problem (observed on Windows 11, v0.1.0 candidate from `main @ a7ea86d`)

The Windows ZIP (scarcity-worker-0.1.0-windows-x64.zip, GitHub candidate run 35780744775) contains only scarcity-worker.exe. First launch prints:

the worker is not paired yet.
Run:
  scarcity-router-worker pair --server srws://SERVER:8790 --code CODE

scarcity-router-worker is the Python console script and is NOT in the ZIP — the standalone product dead-ends (download → launch → told to pair → instructed command does not exist). docs/m10-acceptance.md already claims the Windows package "asks for pairing information in its first-run dialog"; that statement must become true.

A second boundary: the worker-local adapter allowlist is intentionally worker-host authority (D-044); the server must never remotely grant itself access to local services, so enabling e.g. Ollama needs a small local configuration experience.

Product decision (owner)

Implement a compact first-run setup dialog — not a wizard, not a second application, no Electron/Qt/web stack. Smallest professional Windows UI compatible with the packaged tray app (stdlib/native preferred). Covers:

Pairing: server origin (srws://SERVER:8790) + one-time code (from the server web UI Workers page; dialog offers an action to open that UI). Pairing code never persisted or logged. Reuse WorkerRuntime.pair() / WorkerLocalStore / WorkerOrigin — no second pairing implementation.
Local resources: optional "Enable local Ollama" (resource id required; loopback host/port defaults 127.0.0.1:11434) reusing build_local_adapter_registry / LoopbackOllamaAdapter semantics — the GUI can never produce a non-loopback Ollama config. Windows-native Codex stays platform_not_evidenced: not offered in the UI, docs state the Linux/WSL requirement.
Pair-only mode is valid (paired worker with no local resource; configurable later via a new tray "Worker settings…" action reopening the same UI).
Persistence: small typed, versioned, non-secret local settings in the existing worker state directory (%LOCALAPPDATA%\scarcity-router) via the existing platform-state resolution; bounded, atomic, schema-validated, fail-closed on malformed config; extending WorkerLocalStore acceptable, no heavy migration.
Packaged CLI: scarcity-worker.exe pair --server … --code … must work from PowerShell/cmd without Python, sharing the same pairing path; run flags stay compatible; one executable (no second console-script-named exe).
Entrypoint: no-arg launch → first-run setup when unpaired, tray when paired; explicit argv keeps CLI semantics; user cancel before pairing mutates nothing; deterministic partial-failure semantics (pairing failure persists no identity; settings-save failure after successful pairing stays recoverable without a second code).
Security: verified TLS only (no verify=false/self-signed); no tracebacks to users but bounded safe diagnostics in the existing log location; server-side setup stays server-side (the GUI never mutates admin server configuration or holds admin credentials).

Deliverables

Library first-run/settings core (GUI-independent, unit-tested everywhere) + packaging-owned small dialog adapter, following the existing tray-view seam precedent.
PyInstaller spec updated only as required; ZIP stays self-contained; no MSIX, no code signing in this task.
Docs reconciled: README, docs/m10-acceptance.md, packaging comments; standalone instructions use scarcity-worker.exe, never the Python console script.
Discriminating tests failing on current main (entry routing, cancel semantics, real pairing path, code non-persistence, error mapping, CLI pair, instruction names, settings restart persistence, adapter registry reuse, pair-only validity, malformed-config fail-safe, CLI compatibility, tray regression, no secrets, no non-loopback exposure, no Windows-Codex advertisement).
GitHub manual release-candidate run against the PR HEAD producing a new ZIP (run 35780744775 is not acceptable evidence after packaging changes).
Fresh independent GLM-5.3-Flash (thinking MAX) review; up to two remediation rounds; PR left open, unmerged, targeting develop.

Non-goals

No Electron/Qt/web UI, no new long-running process, no generic plugin configuration, no routing settings or provider credentials in the tray, no remote allowlist expansion, no MSIX/signing, no Windows-native Codex claim.

## Problem (observed on Windows 11, v0.1.0 candidate from `main @ a7ea86d`) The Windows ZIP (`scarcity-worker-0.1.0-windows-x64.zip`, GitHub candidate run `35780744775`) contains only `scarcity-worker.exe`. First launch prints: ``` the worker is not paired yet. Run: scarcity-router-worker pair --server srws://SERVER:8790 --code CODE ``` `scarcity-router-worker` is the Python console script and is NOT in the ZIP — the standalone product dead-ends (`download → launch → told to pair → instructed command does not exist`). `docs/m10-acceptance.md` already claims the Windows package "asks for pairing information in its first-run dialog"; that statement must become true. A second boundary: the worker-local adapter allowlist is intentionally worker-host authority (D-044); the server must never remotely grant itself access to local services, so enabling e.g. Ollama needs a small **local** configuration experience. ## Product decision (owner) Implement a **compact first-run setup dialog** — not a wizard, not a second application, no Electron/Qt/web stack. Smallest professional Windows UI compatible with the packaged tray app (stdlib/native preferred). Covers: - **Pairing**: server origin (`srws://SERVER:8790`) + one-time code (from the server web UI Workers page; dialog offers an action to open that UI). Pairing code never persisted or logged. Reuse `WorkerRuntime.pair()` / `WorkerLocalStore` / `WorkerOrigin` — no second pairing implementation. - **Local resources**: optional "Enable local Ollama" (resource id required; loopback host/port defaults 127.0.0.1:11434) reusing `build_local_adapter_registry` / `LoopbackOllamaAdapter` semantics — the GUI can never produce a non-loopback Ollama config. Windows-native Codex stays `platform_not_evidenced`: not offered in the UI, docs state the Linux/WSL requirement. - **Pair-only mode is valid** (paired worker with no local resource; configurable later via a new tray "Worker settings…" action reopening the same UI). - **Persistence**: small typed, versioned, non-secret local settings in the existing worker state directory (`%LOCALAPPDATA%\scarcity-router`) via the existing platform-state resolution; bounded, atomic, schema-validated, fail-closed on malformed config; extending `WorkerLocalStore` acceptable, no heavy migration. - **Packaged CLI**: `scarcity-worker.exe pair --server … --code …` must work from PowerShell/cmd without Python, sharing the same pairing path; `run` flags stay compatible; one executable (no second console-script-named exe). - **Entrypoint**: no-arg launch → first-run setup when unpaired, tray when paired; explicit argv keeps CLI semantics; user cancel before pairing mutates nothing; deterministic partial-failure semantics (pairing failure persists no identity; settings-save failure after successful pairing stays recoverable without a second code). - **Security**: verified TLS only (no verify=false/self-signed); no tracebacks to users but bounded safe diagnostics in the existing log location; server-side setup stays server-side (the GUI never mutates admin server configuration or holds admin credentials). ## Deliverables - Library first-run/settings core (GUI-independent, unit-tested everywhere) + packaging-owned small dialog adapter, following the existing tray-view seam precedent. - PyInstaller spec updated only as required; ZIP stays self-contained; no MSIX, no code signing in this task. - Docs reconciled: README, `docs/m10-acceptance.md`, packaging comments; standalone instructions use `scarcity-worker.exe`, never the Python console script. - Discriminating tests failing on current `main` (entry routing, cancel semantics, real pairing path, code non-persistence, error mapping, CLI pair, instruction names, settings restart persistence, adapter registry reuse, pair-only validity, malformed-config fail-safe, CLI compatibility, tray regression, no secrets, no non-loopback exposure, no Windows-Codex advertisement). - GitHub manual release-candidate run against the PR HEAD producing a new ZIP (run `35780744775` is not acceptable evidence after packaging changes). - Fresh independent GLM-5.3-Flash (thinking MAX) review; up to two remediation rounds; PR left open, unmerged, targeting `develop`. ## Non-goals No Electron/Qt/web UI, no new long-running process, no generic plugin configuration, no routing settings or provider credentials in the tray, no remote allowlist expansion, no MSIX/signing, no Windows-native Codex claim.