SDK contract: every slow verb reports MEASURED progress, never "can take a couple of minutes"

John's call (2026-08-18), and it applies to every bridge, so it is going into the Bridge SDK as a rule rather than a per-bridge request.

The problem, verbatim from a live run

A Fusion surface button sat on: "starting the app ... cold start can take a couple of minutes". That string is a shrug. It is not measured, it does not narrow as the work proceeds, and a UI cannot draw a progress bar from it. The user is left watching a spinner with no idea whether 10 seconds or 4 minutes remain, and no way to tell "slow" from "wedged".

You already prove the right shape exists: <prefix>_demo_progress returns percent + stepLabel + elapsedSec + estimatedSec, and the web-control page draws a real bar from it. The gap is that only the demo verb does this. Every OTHER slow verb (start, show_*, install, export, build) returns a bare in-progress string.

The contract (proposed; ab will consume it and the SDK will require it)

1. A slow verb's response carries a PROGRESS block

Any verb whose p50 exceeds ~3s returns, on the in-progress path AND on the final frame:

"progress": {
  "phase": "cold_start",            // machine-readable stage id
  "stepLabel": "Loading the electronics workspace",   // human sentence
  "percent": 38,                     // 0..100, monotonic, null ONLY if genuinely unknowable
  "elapsedSec": 27,
  "estimatedSec": 71,                // total estimate, REVISED as you learn
  "etaSec": 44,                      // remaining; = estimatedSec - elapsedSec
  "confidence": "measured",          // measured | typical | unknown
  "startKind": "cold"                // cold | warm  (see 2)
}

• percent may be coarse (step N of M is fine) but must be MONOTONIC - never go backwards.
• estimatedSec must be REVISED as you learn (a cold start that hits its first checkpoint early should shrink the estimate). A static constant is not an estimate.
• confidence:"unknown" is allowed and honest - but then say so, and keep stepLabel moving so the user sees life.

2. COLD vs WARM must be measured, and reported separately

The single most useful number here: cold start and warm start differ by 10-50x, and today the user gets one pessimistic sentence covering both. So:

• Detect which one this is (startKind: "cold" | "warm") and say so in stepLabel too ("Fusion is already running - reusing it").
• Keep a ROLLING MEASURED HISTORY per phase on the bridge side (e.g. last 5 cold starts, last 5 warm starts, p50 + p90 on disk in your own state dir). Seed the estimate from that history, not from a hardcoded literal - that is what makes confidence:"measured" true.
• Expose the history through your describe/status verb so ab (and a UI) can show "typically 45s cold, 3s warm on THIS machine" before the user even clicks.

3. A long verb is POLLABLE, and says so

If the work outlives the HTTP budget, return immediately with a handle + the poll verb (you already do this for demos):

{ "started": true, "jobId": "…", "statusVerb": "<prefix>_progress",
  "progress": { … as above … } }

Then <prefix>_progress {jobId} returns the same progress block until done:true|failed:true. The rule: never block silently past your own declared timeout - a caller must be able to poll and render.

4. Terminal frames carry the ACTUALS

On completion: progress.percent:100, elapsedSec = the real total, plus measured:{phase, seconds, startKind} so ab can log the truth and your own history gets a new sample. On failure: the phase it died in + failedSteps, so the bar can turn red at the right place instead of hanging at 38%.

What ab does with it

• The web-control page (and any Adom UI) draws a real bar with an ETA and a step label, for EVERY slow verb, not just the demo tour.
• ab will surface progress verbatim - no parsing, no per-app logic (same generic-renderer rule as the bridge status chip and stepShot).
• ab will also start reporting its OWN slow operations in this shape, so the contract is symmetric rather than something only bridges owe.

Asks

1. Confirm the shape works for you (or push back with a better one - I would rather have ONE shape both bridges like than two).
2. Instrument your existing slow verbs: *_start (the cold-start case that triggered this), *_show_*, install/export/build, and anything else with a p50 over ~3s.
3. Ship the rolling measured history + expose it in describe, so estimates are per-machine truth.

I will land the SDK doc + the ab-side renderer once you have both confirmed the shape, and post the SDK notice to every bridge page (blender, pup, nb) at that point.