feat(setup): market data as a background job, so the last mechanical step can be a button

[eaitbrahim]

Refs #437 (D4). Milestone: Desktop distribution (#18).

The last step left in NOT_AUTOMATED_YET, with the reason recorded there:

a request that blocks that long is not a button, it is a background job with progress and cancellation — so it stays keel fetch until there is somewhere for such a job to live

This builds that somewhere. NOT_AUTOMATED_YET is now empty — and it stays, because the next step someone decides not to automate should have a place to say why.

Exactly one slot, deliberately

Not a queue, not a pool.

• Two concurrent fetches write candles to one SQLite database and race each other.
• A setup flow has no use for concurrency.
• "Is something running?" with one answer is a question a page can render honestly.

A second start is refused and says so, rather than silently dropped or silently queued — both of which look identical to a user watching a page that is not changing.

A failed job stays visible

Not cleared on read, not cleared by time. The entire point of running something in the background is that nobody was watching when it broke, so the failure has to still be there when they look. It is replaced only when the next job starts.

The recorded error is the exception's type and message, never a traceback — a traceback in a browser page is a stack of file paths from someone else's machine.

run_fetch needed no adapting

Its echo parameter is already documented as the progress stream and emits the same lines the CLI prints; its build_client is already a lazy factory, so nothing constructs a broker until the fetch needs one. The job module knows nothing about fetching.

Blank separator lines are dropped — in a bounded tail they would push real output out of view.

Refresh only while running

A finished page that kept reloading would fight a reader; a running one that did not would be a progress display that never progresses. The zero-JS meta refresh is still the only mechanism available to a page that ships no scripts.

The step's button also disappears while its job runs: offering it again would invite a second start that the slot refuses anyway, which reads as the page ignoring the click.

Verified end to end, on the realistic first-run mistake

Starting a fetch with no credentials configured:

POST /setup/market_data  →  303, immediately

job panel:
  market_data · failed · 0s elapsed
  AuthenticationError: Unauthenticated request to private endpoint. If you wish to access
  private endpoints, you must provide your API key and secret ...
  MISSING BTC-USD ONE_DAY

meta refresh: present while running, absent once finished

That is the venue's own error, in front of the operator, with the progress that preceded it — and the checklist directly above it already names the credential step.

mypy caught a bug no test would have

The fetch closure imported keel.strategy.freshness; the module is keel.data.freshness. Every import in that closure is lazy and runs only on the background thread, so the suite was green and the job would have died with a ModuleNotFoundError the first time anyone pressed the button.

Verification

4083 passed, 3 skipped (12 new). ruff check clean repo-wide, mypy clean over keel + packages.

Where D4 stands

Every mechanical step of a first run is now reachable from the browser, with no command typed: config, database, rule library, credential, market data. What remains outstanding is by design — the judgement steps (asset attestations, promoting a rule) and the off-venue ones, which #437 says a wizard must present rather than perform.

🤖 Generated with Claude Code