dagger-check-cloud-design-briefing.md

Handoff: dagger check + Cloud Results

Context

Yves (eunomie) has an open PR — dagger/dagger#13130 — adding dagger module-checks, a new experimental command that fetches check/trace results from Dagger Cloud and renders them in the CLI. It works, but it's a separate command with its own rendering pipeline, disconnected from the existing dagger check.

The design direction we landed on

Don't add a new command. Make dagger check smarter.

dagger check already owns the developer's core question: "can I ship this?" Today it only answers from local execution. It should answer from all available sources — local runs and cloud results — merged into a single view.

How it should work

Deciding what to do based on context:

• In a module dir, no ref arg → run locally (today's behavior, unchanged)
• Explicit ref arg like @sha or @branch → cloud-only mode, no local execution
• Authenticated with cloud results for HEAD → show them alongside local results

Unified output: One list of checks. No "local section" / "cloud section." Cloud-only checks get a subtle (cloud) annotation. If the same check ran both locally and in cloud, local wins. User sees checks being "executed" — some resolve instantly (cloud already has the answer), some take minutes (actually running). Same UX as cache hit vs miss.

The ideal end state is that cloud results become check-spans fed into the same TUI rendering pipeline as local checks. The rendering layer doesn't know or care where the result came from. This is effectively a high-level caching layer: "do I already have a result for this check at this commit?"

The "bridge moment" is the highest-leverage design detail: after dagger check finishes locally, show a one-liner if cloud has additional results:

Cloud: 4/6 checks running — dagger check --watch

This is how users discover the feature without documentation.

Clean tree optimization: If cloud has complete results for the exact HEAD commit and the tree is clean, show them instantly instead of re-running locally. With local checks taking 5-25 minutes, this goes from "nice" to "life-changing."

What exists today (raw material from the PR)

• internal/cloud/checks.go — GraphQL client with two queries: OrgChecks (scan recent commits) and ModuleChecks (targeted fetch for polling)
• Data model: CheckCommit → []Check (name, status, duration, traceId, etc.)
• Dedup logic: latestChecksByName — groups by check name, latest StartedAt wins
• Rendering: its own progress bar + grouped table, completely separate from dagger check's telemetry/span-based rendering

The gap

Nothing connects the cloud data to the engine's span/telemetry pipeline. These are two parallel stacks. The bridge — turning a cloud.Check into a span the TUI can render — doesn't exist yet. Open question whether that translation happens CLI-side or engine-side. Instinct: engine-side ("engine smart, CLI dumb"), since the engine already manages caching and execution decisions.

Suggested rollout

1. Bridge line — after local dagger check finishes, append cloud status one-liner. ~50 lines, zero risk. Validates whether users follow the breadcrumb.
2. Cloud-only mode — dagger check @sha queries cloud instead of running locally. Absorbs module-checks into the main command.
3. Merged table — local + cloud results as unified check-spans in one TUI render. Biggest change, can defer.