feat: add --timeout flag to override the startup readiness deadline

[gtsiolis]

Motivation

lstk start could wait indefinitely when the emulator never became healthy, hanging CI and other non-interactive jobs until an external timeout killed them (reported by harsh.mishra). The startup wait itself was later bounded in #390 (per-mode defaults + LSTK_STARTUP_TIMEOUT); this PR adds the command-line --timeout flag PRO-357 asked for, so the deadline is controllable per run without an env var.

Changes

• Add a --timeout <duration> flag to start (and the bare root, which starts the emulator when invoked with no subcommand).
• When set explicitly, the flag overrides the env/config-derived cfg.StartupTimeout for that run (applyTimeoutFlag in cmd/root.go). An unset flag preserves LSTK_STARTUP_TIMEOUT, which in turn falls back to the per-mode default in resolveStartupTimeout (20s interactive / 60s non-interactive).
• --timeout 0 uses the per-mode default rather than disabling the timeout — there is intentionally no indefinite wait (that was the hang Fix lstk start waits forever when the container fails during startup #390 fixed). This differs from the flag behavior originally suggested on the ticket (5m default, 0 disables), which predates Fix lstk start waits forever when the container fails during startup #390's mechanism.
• restart and the snapshot auto-start path deliberately do not expose the flag; they keep using the env/config value.
• Document the flag on the LSTK_STARTUP_TIMEOUT entry in CLAUDE.md.

Scope note: the timeout mechanism itself — startupMonitor, per-mode defaults, the interactive keep-waiting/stop prompt, startupTimeoutError, and the start_timeout telemetry code — landed in #390. After rebasing onto main this PR is scoped to exposing that mechanism as a CLI flag plus a non-interactive integration test.

Review

Human review advised — adds new user-facing behavior (a --timeout flag), which the review-scope checklist routes to human review regardless of diff size.

Tests

• New integration test TestStartTimesOutWhenEmulatorNeverBecomesHealthy: starts a local image that stays running but never serves /_localstack/health, runs start --timeout 3s non-interactively, and asserts the fast failure (clear error + exit 1).
• Unit coverage of the mechanism (TestStartupMonitorAwait_*, TestResolveStartupTimeout, TestStartContainers_TimeoutEmitsErrorAndTelemetry) is retained from Fix lstk start waits forever when the container fails during startup #390.
• Manual: go build ./...; lstk start --help and lstk --help both list --timeout; an invalid value (--timeout bogus) is rejected with a usage error.

Closes PRO-357

[skyrpex]

Not much to say, it looks good to me and the functionality is very welcomed.

[skyrpex]

BTW love the difference in behavior between interactive and non-interactive.

Interactive:

$ ./bin/lstk start --timeout 1s

   ▟████▖   lstk (dev)
  ▟██▙█▙█▟  LocalStack Enterprise
    ▀▛▀▛▀   ~/.config/lstk/config.toml

✔︎ Pulled localstack/localstack-pro:latest
✔︎ Valid license (Enterprise)
? LocalStack is taking longer than expected to start. Check logs with 'lstk logs' [Keep waiting [W]/Stop LocalStack and exit [S]]

Non-interactive:

$ ./bin/lstk start --timeout 1s | cat
Pulling localstack/localstack-pro:latest...
Preparing LocalStack...
✔︎ Pulled localstack/localstack-pro:latest
Checking license...
✔︎ Valid license (Enterprise)
Starting LocalStack...
Error: LocalStack did not become ready within 1s
  LocalStack is still running so you can inspect it, or stop it.
Last container output:

LocalStack version: 2026.7.0
LocalStack build date: 2026-07-22
LocalStack build git hash: 983eb90ac

2026-07-23T11:03:12.601  INFO --- [  MainThread] l.licensing.licensingv2    : Successfully activated cached license 970b3ec2-1299-4ead-8597-84ab74a5d3f0:enterprise from /var/lib/localstack/cache/license.json 🔑✅
2026-07-23T11:03:13.290  INFO --- [  MainThread] localstack.utils.bootstrap : Execution of "_resolve_api_provider_specs" took 623.13ms
  ==> View the logs: lstk logs
  ==> Stop LocalStack: lstk stop
  ==> Allow more time on a slow machine: LSTK_STARTUP_TIMEOUT=5m lstk start