feat(logs): fetch execution log output and fix background runs

[jahvon]

Summary

Three related changes to execution logs and background runs, driven by an agent's-eye view of the get_execution_logs MCP tool.

1. Fetch log output, not just metadata (+ truncation)

get_execution_logs / flow logs previously returned only run metadata (ref, status, exitCode, error) and a logFile path — never the captured output. Now:

• New tail, grep, content (and max_bytes) options slice a run's output, each keeping the end of the log where failures surface.
• Output is byte-capped; for MCP the cap is enforced server-side (default 50 KB, hard-capped 200 KB) so an under-specified request can't flood an agent's context window.
• Response reports contentTruncated / contentTotalLines / contentReturnedLines so the caller always knows it's seeing a slice.
• Reading is live, so it works on still-running executions — a running record now resolves its log file by archive ID (the resolved path is only written on completion), giving a snapshot of what's been written so far.

Default behavior is unchanged: with no content option, only metadata is returned, so listing stays cheap.

2. Fix flow exec --background

--background silently ran inline for --cmd and --spec (the ad-hoc/spec dispatch returned before the background check), and even on the named path launchBackground rebuilt the child from just verb + args, dropping every flag. Now the detached child is reconstructed from the full arg list with only the background flag stripped, so named / --cmd / --spec runs all background identically and every flag propagates. --spec - (stdin) + --background is rejected with a clear message (a detached child has no stdin to re-read).

3. Nameless --spec ref fallback

A --spec without a name: produced an empty ref (exec flow/). It now falls back to spec-<slugified-label> (or spec), mirroring --cmd's adhoc- naming, so history and the background-run line show a meaningful ref.

Testing

• flow validate passes locally: generate → lint → unit + e2e tests → schema validation.
• New unit tests: ExtractContent slicing (tail/grep/byte-cap/boundaries), in-progress join-by-ID, backgroundChildArgs, transientSpecName, plus MCP handler arg-forwarding/cap-clamping cases.
• Verified end-to-end: live tail of a running background run, --background detaching for --cmd/--spec, and the spec-name fallback.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 87.30159% with 16 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cmd/internal/exec.go	57.89%	15 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!