feat(run): Measure guest boot time and report it as a ready event

[ananos]

Summary

We quote boot times in the README and nothing in the repo produces them: the telemetry start event's boot: ok means the VMM process spawned, and the harnesses wait on console markers without reading a clock. This adds the measurement.

run now reports a ready telemetry event carrying ready_ms: the time from the VMM spawn (InstanceState.StartTime) to the guest agent's first answer to /bin/true, on all three backends. It is a separate event rather than a delayed start, so start keeps its timing and a guest that never answers sends nothing instead of a bogus value. The probe runs on its own goroutine next to the console attach, bounded by a two minute budget, so it never delays the user. Foreground runs only: a detached run returns to its caller at once, and a restore resumes memory rather than booting.

The pty and hvi harnesses now print the elapsed time to their markers (boot: kernel-to-init 0.46s (backend vz), kernel-to-shell, kernel-to-entrypoint, hull-spawn-to-*), print only, no assertion. Neither harness runs --net shared, so there is no DHCP milestone to print. The README rows stay hand-typed until someone regenerates them from this output on a real machine; the CI gate is a follow-up.

The unit tests drive the probe against a fake agent speaking the real protocol. No live VM was booted for this PR.

Changes

• exec_compose.go: agent error replies are wrapped in an errGuestAgent sentinel so callers can tell "agent refused" from "instance gone"
• telemetry.go, run.go: probeGuestReady, readyEventFields, sendReadyEvent; the run path starts the probe after the instance is recorded as running
• docs/telemetry.md: the ready event, and start no longer implies the guest booted
• test/pty-terminal-test.py, test/hvi-boot-test.py: print boot timings; the hvi harness streams output instead of buffering it and cleans up on overrun

Checklist

• make test passes
• make macos builds hull, vz-runner and hvi, if Go, Swift or Rust code changed (CI build lane)
• I have added or updated tests covering the change
• I have run the e2e harnesses (test/*.py) for changes touching boot, console, or the run path (CI unit + e2e lane)
• I have updated the affected docs (README, docs/)

[ananos]

@claude-fleet review

[claude-fleet]

Review task queued.

Task: 70a74d74-2bfd-46e2-9692-2c2b782c7401
Commit: c2bf880
Model: executor default (effort high)
Executor: ci-16gb-fsn1-1
Status: done. Review posted.

[claude-fleet]

Verdict: approve. This is a well-constructed, well-tested change. I read the probe path end to end, verified the error-sentinel semantics the probe relies on, checked every new test bites against the code it exercises, and confirmed the harness edits compile and are print-only. Findings are two nits, neither blocking.

What I verified holds

• Sentinel semantics are correct. execCapture (exec_compose.go:186) now wraps agent error replies in errGuestAgent; transport failures wrap errAgentTransport. probeGuestReady returns true on nil || errors.Is(err, errGuestAgent) — so an agent that refuses /bin/true counts as up, matching the doc and TestProbeGuestReadyCountsARefusalAsUp. A stopped/missing instance returns a plain error (exec_compose.go:126,129) that wraps neither sentinel, so execCaptureRetry returns at once and the probe reports unready without retrying — matching TestProbeGuestReadyStopsWhenTheInstanceIsGone. Confirmed execCaptureRetry retries only on errAgentTransport.
• Measurement endpoints are right. state.StartTime is set at run.go:2360, immediately before vmmCmd.Start(), so ready_ms is spawn→first-answer and excludes image pull, as the docs claim. The goroutine passes state.ID, vmmType, state.StartTime by value (run.go:2433), so no race on later state mutation.
• The --restore and detach guards are real. checkpoint.go:240-241 appends --restore to cmdArgs, so slices.Contains(cmdArgs, "--restore") in run.go:2428 correctly suppresses the event on restore. Detached runs are excluded.
• No panic / nil risk from the new goroutine. Client.Enabled() and Send are nil-safe, so sendReadyEvent on an uninitialized client is a no-op, not a crash on a non-main goroutine.
• Store access is concurrency-safe. GetInstance/SaveInstance take s.mu (RWMutex), and background goroutines already share s (metrics sampler, lease discovery), so the probe adds nothing new.
• Tests are not tautologies. Each TestProbeGuestReady* targets a distinct branch: startup-window EOFs (fakeAgent(...,2,0)), refusal-as-up (fakeRefusingAgent), budget bound (2s budget, asserts <6s), instance-gone short-circuit. TestReadyEventFieldsAreWholeMilliseconds pins truncation, the negative-clamp, and the exact two-field shape.
• Harness edits. Both read via os.read(fileno) after select, bypassing Python buffering correctly; VMM_MARKER/b"VMM started (PID" matches hull's actual line (run.go:2384). The hvi harness kills the process and dies on overrun. Both py_compile clean.

Gates

• GOOS=darwin GOARCH=arm64 go build ./cmd/hull/ — clean.
• GOOS=darwin GOARCH=arm64 go vet ./cmd/hull/ — clean.
• GOOS=darwin GOARCH=arm64 go test -c ./cmd/hull/ — test binary compiles.
• python3 -m py_compile on both harnesses — clean.
• Not run: the Go test suite. This is a macOS/vz/hvi target; the package does not build for linux (compose/gateway files are darwin-tagged) and the tests need a darwin runtime, so I could not execute make test here. ruff unavailable in this environment. The PR checkbox claims make test passes; I did not independently confirm it.

Findings (both nits)

1. The kernel-to-* labels are measured from hull's VMM started line, not from kernel start — so they overstate the kernel-to-init/shell/entrypoint intervals by the firmware/VMM-init time. Since these numbers are what feeds the README, the label is misleading.
2. A new ready event is added but schema_version stays 1, while the page states it is "bumped on any schema change." Additive, so defensible, but worth a deliberate call.

Not checked:

• Execution of the Go test suite (make test): package builds only for darwin and tests need a darwin/vz/hvi runtime; verified via cross-compile + test-binary compile + vet only.
• Live boot: no VM was booted, so real ready_ms values and the harness boot-timing output were not observed end to end.
• ruff/shellcheck on the Python harnesses (ruff unavailable here); only py_compile was run.
• Whether concurrent probe exec of /bin/true perturbs the guest workload or console on a real backend.

Task 70a74d74-2bfd-46e2-9692-2c2b782c7401 on ci-16gb-fsn1-1, model executor default, effort high.

[claude-fleet]

nit: print_boot_time computes origin from t_vmm, the timestamp of hull's VMM started (PID line, then labels the interval kernel-to-init/kernel-to-shell. That host line is printed right after spawn, before guest firmware and kernel, so the printed number includes VMM/firmware startup and overstates the true kernel-to-X time. These values feed the README boot-time rows, so the mislabel propagates. Consider vmm-start-to-init or subtracting to a kernel marker.

[claude-fleet]

nit: Same as the pty harness: origin is the VMM started (PID timestamp but the label reads kernel-to-init/kernel-to-entrypoint. Measured from the host spawn line, not kernel start, so the printed interval is larger than a true kernel-to-X and the README rows it feeds would inherit the inflation.

[claude-fleet]

nit: A new ready event type is added but schema_version stays 1, while this same row says it is bumped on any schema change, with this page updated. Additive events keep existing consumers working, so 1 is defensible, but confirm this is intentional rather than an omission.