feat: nan run / nan runs (agent automations phase 1)

[sre-helmcode]

⚠️ Do not merge until the runs backend is live

Merging this PR publishes a release: tag.yml tags and releases any merge to main that changes internal/tui.Version (bumped here to 0.1.24). The /v1/runs API this talks to does not exist yet (cloud-api T1–T4 of Agent Automations Phase 1), so this must wait until https://cloud-api.nan.builders/v1/runs is deployed and the feature gate is on. No tags or releases were created.

What

NaN Agent Automations Phase 1, task T5 (NaN community tenant). Spec: helmcode/nan-devops AGENT-AUTOMATIONS-PHASE1.md §2.1.3 (HTTP API + SSE frames), §2.4 (CLI), §5 "nan-cli (T5)". Issue: helmcode/nan#162.

nan run [--ws NAME] [--agent pi|hermes] [--model M] [--cwd PATH] [--worktree|--no-worktree]
        [--timeout 30m] [--detach] [--json] [--idempotency-key K] ( "prompt" | -f prompt.md | - )
nan runs ls [--ws NAME] [--state S] [--limit 20] [--json]
nan runs show <id> [--json]
nan runs logs <id> [-f] [--after N] [--json]
nan runs cancel <id> [--json]

• internal/api/runs.go — RunsBaseURL = https://cloud-api.nan.builders (not api.nan.builders: the edge Worker rewrites bodies, spec §0.3). Types mirror §2.1.3. Session cookie nan_session first; member API key as Authorization: Bearer when there is no session; 401 → ErrSessionExpired. Both error envelopes parsed (OpenAI on /v1, bare on /api).
• SSE reader: LF framing (tolerates CRLF, multi-line data:), Last-Event-ID reconnect up to 5 failures in a row with exponential backoff (1s→16s; the budget resets after any byte, so the 30-min server close never exhausts it), replayed events de-duplicated by seq, 45 s idle timeout (the server heartbeats every 15 s), no client timeout on the stream (the 30 s timeout stays on every other request). 401/404 are not retried. Lines over 1 MiB are fatal.
• internal/runs/render.go — event → terminal lines. All guest text is sanitised: CSI/OSC/DCS/SOS/PM/APC and two-byte escapes, C0 (except \n/\t), DEL, C1, CR, bidi overrides; invalid UTF-8 → U+FFFD. --json output also escapes C1/bidi controls (encoding/json already escapes C0).
• cmd/run.go, cmd/runs.go, cmd/exit.go — exit-code table of §2.4 (0/1/2/3/4 run outcome; 64 usage; 65 auth; 69 unavailable / stream lost, naming the run; 75 detached). Ctrl-C detaches and prints nan runs logs <id> -f / nan runs cancel <id>; a second Ctrl-C within 2 s cancels. Ctrl-C is only captured once the run is being followed. --ws defaults to the member's only workspace (GET /api/workspaces), else exit 64 listing the names. Run ids are validated as UUIDs before they go into a path. Client-side checks mirror the server limits (prompt 1..32768 bytes, UTF-8, no NUL; timeout 1m..2h; model and idempotency-key regexes) so mistakes exit 64 without a round trip. Unset optional flags are omitted from the body so the platform defaults apply.
• cmd/root.go — Execute honours ExitError; on run/runs a cobra refusal (unknown flag, missing id, mutually exclusive flags) exits 64. Other commands keep exiting 1.
• README: usage, flags, Ctrl-C behaviour, exit codes. CONTRIBUTING: project structure.
• Version 0.1.23 → 0.1.24 (patch).

User-facing strings are English, like the rest of the CLI.

Assumptions to confirm against the backend (T1/T4)

• message events are incremental chunks (coalesced deltas), with final: true on the last; the renderer concatenates them. If final carries the full text instead, the renderer needs a one-line change.
• GET /v1/runs?workspace= accepts the workspace name.
• GET /api/workspaces accepts the same credentials (session; with API-key-only auth, a refusal tells the member to pass --ws).

Tests

Spec-driven, httptest mocks of §2.1.3 for every item in §5 "nan-cli (T5)":

• run streams and exits 0/1/2/3/4 (incl. 4 for config_error/agent_not_installed/no_inference_key)
• SSE reconnect with Last-Event-ID, duplicate drop, 5-retry give-up (exit 69 naming the run), idle timeout reconnect, no stream timeout, no retry on 401/404, context cancel
• Ctrl-C detach (exit 75, hints, no cancel) / double Ctrl-C cancel (exit 3, one cancel POST)
• --ws default, ambiguity (exit 64, names sanitised), none, explicit --ws
• 401 → exit 65 with nan auth login on run/ls/show/cancel; no session → 65; API-key fallback
• control chars stripped from stream, logs, tables, error messages; JSON escapes
• runs ls/show/logs/cancel JSON output; logs -f exit codes and --after
• admission refusals → exit codes; usage errors exit 64 before anything is sent; cobra refusals → 64

gofmt -l .          # clean
go vet ./...        # clean
go test -race -count=5 ./...   # ok
cross-compile linux/darwin/windows × amd64/arm64   # ok
govulncheck@v1.8.0  # No vulnerabilities found.

Deploy notes

None beyond the merge gate above. No env vars, no secrets.

🤖 Generated with Claude Code

[sre-helmcode]

Blocking reviews (Claude Code, Opus), three separate lenses, all on head fc39159964c8bf74a4f5560552a365fc5affe693:

• QA: APPROVED (round 3). Round 1 blockers: idle timeout didn't cover the header wait; a 200 that is not SSE reconnected forever; logs -f 401/404 untested. Round 2 blockers: doRun only reachable from the tests; logs pagination untested. All fixed.
• UX: APPROVED (every round).
• Security: APPROVED (round 3). Round 2 blocker: a lone C1 byte carried through json.RawMessage into --json output. Fixed.

Reminder: do not merge until /v1/runs is live — merging publishes v0.1.24 via tag.yml.

🤖 Generated with Claude Code