refactor: route live session commands through ApiGateway

[riglar]

Summary

Final item from the #3 code review: the five live subcommands (start/install/exec/stop/status) each built their own raw fetch() with hand-spread auth.headers and a per-call handleApiError — the one architecture violation flagged in the review (CLAUDE.md mandates commands orchestrate services with no I/O logic; HTTP belongs in ApiGateway).

More than a tidiness issue: because they bypassed the gateway, they also bypassed its network-error enhancement. A DNS/connection failure surfaced as a bare fetch failed TypeError instead of the friendly "Network request failed... Possible causes" diagnostic every other command gives.

This adds five methods to ApiGateway — startLiveSession, installLiveBinary, execLiveYaml, stopLiveSession, getLiveSession — each following the established try / fetch / handleApiError / catch → enhanceFetchError skeleton, plus typed LiveSession / LiveSessionSummary / LiveExecResult interfaces (the swagger has no /live schema, so these are hand-defined). live.ts keeps all its presentation logic and just calls the gateway: −66 lines in the command.

Verification

Smoke-tested against the mock API:

• network-error path (live status → unreachable URL): now the enhanced "Network request failed" message — previously a bare fetch failed ← the actual fix
• auth-error path (live stop → invalid key): auth-mode-neutral message with operation context
• happy path and 415s flow through handleApiError unchanged

pnpm test 122/122 · pnpm typecheck clean (strict) · pnpm lint 0 errors · pnpm build clean

🤖 Generated with Claude Code

[claude]

The three JSDoc comments describe only what each type is — information already fully conveyed by the interface names. Per CLAUDE.md: "Default to writing no comments. Only add one when the WHY is non-obvious… Don't explain WHAT the code does, since well-named identifiers already do that."

The one genuinely non-obvious WHY — that these are hand-defined because the swagger schema has no /live routes and openapi-typescript can't generate them — is currently absent from the code. That belongs as a single comment.

Suggested change

	/** Summary returned when a live session is created. */
	export interface LiveSessionSummary {
	id: number;
	platform: string;
	session_name: string;
	status: string;
	}
	/** Full live session record returned by the status endpoint. */
	export interface LiveSession extends LiveSessionSummary {
	binary_upload_id: null | string;
	created_at: string;
	}
	/** Result of executing Maestro YAML against a live session. */
	export interface LiveExecResult {
	error?: string;
	output?: string;
	success: boolean;
	}
	// Hand-defined: swagger has no /live routes so openapi-typescript cannot generate these.
	export interface LiveSessionSummary {
	id: number;
	platform: string;
	session_name: string;
	status: string;
	}
	export interface LiveSession extends LiveSessionSummary {
	binary_upload_id: null | string;
	created_at: string;
	}
	export interface LiveExecResult {
	error?: string;
	output?: string;
	success: boolean;
	}

[riglar]

Partially applied. The non-obvious WHY (swagger has no /live routes for openapi-typescript to generate) is now a header comment on the new domain file. I kept the brief per-interface comments: they note which endpoint returns each type, which clarifies the otherwise-confusing Summary-vs-full distinction, and that's consistent with the contextual doc comments in the existing auth.types.ts. Note: the quoted "Default to writing no comments…" text isn't actually in this repo's CLAUDE.md — the verifiable rule (domain types location) drove the change.

[claude]

LiveSessionSummary, LiveSession, and LiveExecResult are exported from this file and consumed in src/commands/live.ts, making them cross-layer types. Per CLAUDE.md: "Domain types live in src/types/domain/."

The existing src/types/domain/auth.types.ts and device.types.ts follow this pattern for types that cross layer boundaries. Consider moving these three interfaces to a new src/types/domain/live.types.ts and importing them back into api-gateway.ts.

[riglar]

Done in f0082fa — moved all three interfaces to a new src/types/domain/live.types.ts and imported them back into api-gateway.ts, matching the auth.types.ts/device.types.ts pattern. Verified the CLAUDE.md:31 citation, good catch.

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.