fix(tui): one-shot run hangs forever when a precondition is unmet

[kovtcharov]

Why this matters

gaia tui run <id> --query "..." is the scriptable, CI-friendly path — the one that exists so automation doesn't need a human at a terminal. With the local model server down it hangs indefinitely and prints nothing at all. No stdout, no stderr, no exit. A CI job wedges until its own timeout kills it, with nothing in the log to say why.

This is the exact failure the readiness gate was built to prevent, and the one-shot is the path that needs it most: an interactive user sees a blank screen and presses ctrl-C, but a script just stops.

Before: silent hang, forever, no diagnostic.
After: fails in seconds naming the unmet precondition and the command to fix it.

Repro

Verified with the local model server confirmed down:

$ curl -s -m 3 http://localhost:13305/api/v1/health   # no response — server is down
$ gaia tui run email --query "triage my inbox"
  …200+ seconds, no output on stdout or stderr, no exit

Cause

RunAgent goes straight to RunOneShot with context.Background() — no readiness check and no deadline, so an unreachable backend has nothing to fail against.

The interactive path does not have this problem: launching from the hub now runs the preflight gate, which reports the same condition as a checkable row with a remedy.

Fix direction

Two things, and the second matters even if the first lands:

1. Run the readiness check on the one-shot path. It should not render the interactive gate — a script has nobody to press a key — but it should fail with the same actionable message the gate would have shown, and a non-zero exit.
2. Give the one-shot a deadline regardless. context.Background() means any unreachable dependency hangs forever; a bounded context turns that into a reportable error. The headless preflight.Check(ctx, …) already exists and is usable without the UI.

This was flagged during review as "presumably deliberate for the scripting path" — it is reasonable not to show a gate, but the current behaviour isn't a skipped gate, it's an unbounded wait.

Test plan

• With the model server stopped, gaia tui run email --query "hi" exits non-zero within seconds and names the remedy
• The message matches what the interactive gate reports for the same condition
• With everything healthy, the one-shot still answers on stdout and exits 0
• A dependency that hangs rather than refuses also hits the deadline

[github-actions]

Confirmed — the diagnosis is exactly right. The non-interactive run path drives a single turn with an unbounded context, so an unreachable model server has nothing to fail against and the process just waits. Both parts of your fix are the right call, and the bounded-context part is worth landing on its own even if the readiness check slips.

One thing to flag for whoever picks this up: the run command, RunAgent/RunOneShot, and the readiness gate aren't on main yet — they live in the in-flight daemon-transport TUI work (PRs #2476 / #2478). So this is a follow-up on that path, and the fix should land there (or as a fast follow) rather than against main as it stands today.

Small correction on the "already exists" note: the sidecar's structured readiness report exists as an HTTP endpoint, but a Go-side preflight.Check helper for the TUI doesn't exist yet — the readiness gate is still the Phase-1 exit test in the TUI plan. So the one-shot check and the interactive gate would share whatever that helper becomes; the deadline is the piece that's landable immediately with no new plumbing.

🔍 Technical details

In PR #2478 the one-shot branch of RunAgent (tui/internal/ui/app.go) is:

if query != "" {
    res := RunOneShot(context.Background(), c, query, os.Stdout, os.Stderr)
    return res.ExitCode, nil
}

context.Background() is the unbounded wait you described — no deadline, no cancellation on an unreachable backend. RunOneShot in the same PR takes the ctx through to c.Send(ctx, query), so a context.WithTimeout(...) here is enough to convert the hang into a reportable, non-zero-exit error (Test-plan item 4 — the hangs rather than refuses case — is precisely what the deadline covers).

On main today none of this exists: tui/internal/cli/ only registers hub, chat, and version (root.go, chat.go), there's no run command and no preflight package. Even the interactive chat path uses context.WithCancel(context.Background()) (tui/internal/ui/chat/model.go:345) with no deadline — fine there because a human can ctrl-C, which is the asymmetry the issue calls out.

For the readiness message parity (Test-plan items 1–2): the structured report the interactive gate would show comes from the email sidecar's GET /v1/email/init (added in #1813), which the TUI plan (#2476/#2478 plan docs) scopes as the Phase-1 readiness gate. The headless one-shot check should reuse that same source so the message matches by construction rather than by duplication.

[kovtcharov-amd]

Fixed — closing.

A one-shot gaia tui run no longer hangs when a precondition isn't met. It runs the readiness check first, prints every row (not just the blocker) so a wrong-reason pass is visible, exits 1 when blocked, and bounds the turn itself with a deadline so it can't stall indefinitely either.

This shipped in PR #2488, which merged into a feature branch rather than main — that's why GitHub never closed this automatically.

🔍 Technical details

• tui/internal/ui/app.go:235 — ReportReadiness(...) over the daemon transport
• tui/internal/ui/app.go:242 — if rep.Blocked() { return 1, nil }
• tui/internal/ui/app.go:247 — context.WithTimeout wrapping RunOneShot
• Deadline covered by tui/internal/ui/oneshot_test.go