hostagent: unify requirement progress logging with (N/total) counter

Pre-compute the total number of requirement steps (essential + optional
+ guest-agent wait + final) and thread a shared counter through
waitForRequirements so each progress line is prefixed with (N/total).

Progress is emitted as a structured RequirementProgress event so the
limactl-side event watcher can render it two ways:

* TTY: each step occupies a single line that flips from 🕐 to
  ✅ in place when it completes.
* Non-TTY (piped output, log files, CI): two regular log lines per
  step, matching the previous behaviour.

Built-in requirement descriptions are reworded so they read naturally
in the new form (e.g. systemd must be available -> systemd is
available). capitalizeFirst is kept so user-supplied probe descriptions
render uniformly with the built-in ones, and is rune-safe.

Fix replaying of RequirementProgress events: the progress field was kept
on currentStatus after emit, so every subsequent unrelated event
(port-forward, vsock, cloud-init) carried the previous RequirementProgress
along and the limactl-side renderer re-emitted the pending line
for each one. Clear the transient field from the cached status inside
emitEvent so only the event that explicitly carries it renders. Add a
defensive dedup in renderRequirementProgress keyed on step/total:done
so any future re-emit path cannot reintroduce the spam.

Reword the built-in descriptions back to the to be form
so the pending line reads as a goal, not a premature completion claim.

Closes: #4553

Signed-off-by: mn-ram <235066282+mn-ram@users.noreply.github.com>

Author: mn-ram

pkg/hostagent/events/events.go

@@ -26,6 +26,32 @@ type Status struct {
 
 	// Vsock forwarder event
 	Vsock *VsockEvent `json:"vsock,omitempty"`
+
+	// Requirement progress update — one event per state transition, see
+	// RequirementProgress for fields.
+	RequirementProgress *RequirementProgress `json:"requirementProgress,omitempty"`
+}
+
+// RequirementProgress is emitted by the hostagent on every state transition
+// of a startup-requirement check, so the limactl-side watcher can render
+// progress with a TTY-aware in-place flip (🕐 -> ✅) when stdout is a
+// terminal, and fall back to two log lines otherwise.
+type RequirementProgress struct {
+	// Step is the 1-based index of this requirement across the unified
+	// essential / optional / guest-agent / final groups.
+	Step int `json:"step"`
+	// Total is the total number of steps across all groups for this boot.
+	Total int `json:"total"`
+	// Description is the human-readable name of the requirement, already
+	// capitalized for display.
+	Description string `json:"description"`
+	// Suffix is an optional trailing annotation shown only while the step
+	// is pending (e.g. " (essential)").
+	Suffix string `json:"suffix,omitempty"`
+	// Done is true when the requirement has been satisfied. The first
+	// event for each step is emitted with Done=false; the second with
+	// Done=true.
+	Done bool `json:"done,omitempty"`
 }
 
 type CloudInitProgress struct {

pkg/hostagent/hostagent.go

@@ -330,6 +330,11 @@ func (a *HostAgent) emitEvent(_ context.Context, ev events.Event) {
 
 	a.statusMu.Lock()
 	a.currentStatus = ev.Status
+	// RequirementProgress is a one-shot transition signal: it must not be
+	// replayed on subsequent unrelated events (port forwards, vsock, etc.),
+	// otherwise the limactl-side renderer would re-emit the pending "🕐 …"
+	// line every time some other event fires while a check is in progress.
+	a.currentStatus.RequirementProgress = nil
 	a.statusMu.Unlock()
 
 	if ev.Time.IsZero() {
@@ -362,6 +367,17 @@ func (a *HostAgent) emitPortForwardEvent(ctx context.Context, pfEvent *events.Po
 	a.emitEvent(ctx, ev)
 }
 
+func (a *HostAgent) emitRequirementProgress(ctx context.Context, prog *events.RequirementProgress) {
+	a.statusMu.RLock()
+	currentStatus := a.currentStatus
+	a.statusMu.RUnlock()
+
+	currentStatus.RequirementProgress = prog
+
+	ev := events.Event{Status: currentStatus}
+	a.emitEvent(ctx, ev)
+}
+
 func (a *HostAgent) emitVsockEvent(ctx context.Context, vsockEvent *events.VsockEvent) {
 	a.statusMu.RLock()
 	currentStatus := a.currentStatus
@@ -556,7 +572,16 @@ func (a *HostAgent) startHostAgentRoutines(ctx context.Context) error {
 		return nil
 	})
 	var errs []error
-	if err := a.waitForRequirements("essential", a.essentialRequirements()); err != nil {
+	hasGuestAgentDaemon := !*a.instConfig.Plain && *a.instConfig.OS == limatype.LINUX
+	essentialReqs := a.essentialRequirements()
+	optionalReqs := a.optionalRequirements()
+	finalReqs := a.finalRequirements()
+	totalSteps := len(essentialReqs) + len(optionalReqs) + len(finalReqs)
+	if hasGuestAgentDaemon {
+		totalSteps++ // for the explicit "guest agent is running" wait
+	}
+	step := 0
+	if err := a.waitForRequirements(ctx, "essential", essentialReqs, &step, totalSteps); err != nil {
 		errs = append(errs, err)
 	}
 	if *a.instConfig.SSH.ForwardAgent {
@@ -608,7 +633,6 @@ sudo chown -R "${USER}" /run/host-services`
 	staticPortForwards := a.separateStaticPortForwards()
 	a.addStaticPortForwardsFromList(ctx, staticPortForwards)
 
-	hasGuestAgentDaemon := !*a.instConfig.Plain && *a.instConfig.OS == limatype.LINUX
 	if hasGuestAgentDaemon {
 		go a.watchGuestAgentEvents(ctx)
 		go a.startTimeSync(ctx)
@@ -628,19 +652,29 @@ sudo chown -R "${USER}" /run/host-services`
 			}()
 		}
 	}
-	if err := a.waitForRequirements("optional", a.optionalRequirements()); err != nil {
+	if err := a.waitForRequirements(ctx, "optional", optionalReqs, &step, totalSteps); err != nil {
 		errs = append(errs, err)
 	}
 	if hasGuestAgentDaemon {
-		logrus.Info("Waiting for the guest agent to be running")
+		step++
+		a.emitRequirementProgress(ctx, &events.RequirementProgress{
+			Step:        step,
+			Total:       totalSteps,
+			Description: "Guest agent to be running",
+		})
 		select {
 		case <-a.guestAgentAliveCh:
-			// NOP
+			a.emitRequirementProgress(ctx, &events.RequirementProgress{
+				Step:        step,
+				Total:       totalSteps,
+				Description: "Guest agent to be running",
+				Done:        true,
+			})
 		case <-time.After(time.Minute):
 			errs = append(errs, errors.New("guest agent does not seem to be running; port forwards will not work"))
 		}
 	}
-	if err := a.waitForRequirements("final", a.finalRequirements()); err != nil {
+	if err := a.waitForRequirements(ctx, "final", finalReqs, &step, totalSteps); err != nil {
 		errs = append(errs, err)
 	}
 	// Copy all config files _after_ the requirements are done

pkg/hostagent/requirements.go

@@ -4,42 +4,81 @@
 package hostagent
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"runtime"
 	"strings"
 	"time"
+	"unicode"
+	"unicode/utf8"
 
 	"github.com/lima-vm/sshocker/pkg/ssh"
 	"github.com/sirupsen/logrus"
 
+	"github.com/lima-vm/lima/v2/pkg/hostagent/events"
 	"github.com/lima-vm/lima/v2/pkg/limatype"
 	"github.com/lima-vm/lima/v2/pkg/sshutil"
 )
 
-func (a *HostAgent) waitForRequirements(label string, requirements []requirement) error {
+// capitalizeFirst returns s with its first letter upper-cased, using rune
+// semantics so non-ASCII inputs are handled correctly.
+func capitalizeFirst(s string) string {
+	if s == "" {
+		return s
+	}
+	r, size := utf8.DecodeRuneInString(s)
+	return string(unicode.ToUpper(r)) + s[size:]
+}
+
+// waitForRequirements iterates through requirements, advancing *step (a unified
+// counter shared across the essential / optional / final groups, plus the
+// guest-agent step) and emits a RequirementProgress event for each state
+// transition. The limactl-side event watcher renders these as either an
+// in-place 🕐 -> ✅ flip (when stdout is a TTY) or two log lines (otherwise).
+func (a *HostAgent) waitForRequirements(ctx context.Context, label string, requirements []requirement, step *int, total int) error {
 	const (
 		retries       = 200
 		sleepDuration = 3 * time.Second
 	)
 	var errs []error
 
-	for i, req := range requirements {
-		logrus.Infof("Waiting for the %s requirement %d of %d: %q", label, i+1, len(requirements), req.description)
+	for _, req := range requirements {
+		*step++
+		stepNum := *step
+		suffix := ""
+		if label == "essential" {
+			suffix = " (essential)"
+		}
+		// capitalizeFirst is applied so user-supplied probe descriptions render
+		// uniformly with the built-in ones; built-in descriptions are already in
+		// sentence case so it is a no-op for them.
+		desc := capitalizeFirst(req.description)
+		a.emitRequirementProgress(ctx, &events.RequirementProgress{
+			Step:        stepNum,
+			Total:       total,
+			Description: desc,
+			Suffix:      suffix,
+		})
 	retryLoop:
 		for j := range retries {
 			err := a.waitForRequirement(req)
 			if err == nil {
-				logrus.Infof("The %s requirement %d of %d is satisfied", label, i+1, len(requirements))
+				a.emitRequirementProgress(ctx, &events.RequirementProgress{
+					Step:        stepNum,
+					Total:       total,
+					Description: desc,
+					Done:        true,
+				})
 				break retryLoop
 			}
 			if req.fatal {
 				logrus.Infof("No further %s requirements will be checked", label)
-				errs = append(errs, fmt.Errorf("failed to satisfy the %s requirement %d of %d %q: %s; skipping further checks: %w", label, i+1, len(requirements), req.description, req.debugHint, err))
+				errs = append(errs, fmt.Errorf("failed to satisfy the %s requirement (%d/%d) %q: %s; skipping further checks: %w", label, stepNum, total, req.description, req.debugHint, err))
 				return errors.Join(errs...)
 			}
 			if j == retries-1 {
-				errs = append(errs, fmt.Errorf("failed to satisfy the %s requirement %d of %d %q: %s: %w", label, i+1, len(requirements), req.description, req.debugHint, err))
+				errs = append(errs, fmt.Errorf("failed to satisfy the %s requirement (%d/%d) %q: %s: %w", label, stepNum, total, req.description, req.debugHint, err))
 				break retryLoop
 			}
 			time.Sleep(sleepDuration)
@@ -159,7 +198,7 @@ func (a *HostAgent) essentialRequirements() []requirement {
 	req := make([]requirement, 0)
 	req = append(req,
 		requirement{
-			description: "ssh",
+			description: "SSH connection",
 			script: `#!/bin/sh
 true
 `,
@@ -170,7 +209,7 @@ If any private key under ~/.ssh is protected with a passphrase, you need to have
 			noMaster: true,
 		})
 	startControlMasterReq := requirement{
-		description: "Explicitly start ssh ControlMaster",
+		description: "Persistent SSH ControlMaster",
 		script: `#!/bin/sh
 true
 `,
@@ -182,7 +221,7 @@ true
 	}
 	req = append(req,
 		requirement{
-			description: "user session is ready for ssh",
+			description: "user session to be ready for SSH",
 			script: fmt.Sprintf(`#!/bin/sh
 set -eux
 [ "$(cat /run/lima-ssh-ready 2>/dev/null)" = "%s" ]
@@ -209,7 +248,7 @@ A possible workaround is to run "apt-get install sshfs" in the guest.
 `,
 		})
 		req = append(req, requirement{
-			description: "fuse to \"allow_other\" as user",
+			description: "fuse \"allow_other\" to be enabled for the user",
 			script: `#!/bin/sh
 set -eux
 sudo grep -q ^user_allow_other /etc/fuse*.conf
@@ -228,7 +267,7 @@ func (a *HostAgent) optionalRequirements() []requirement {
 	if isLinuxGuest && (*a.instConfig.Containerd.System || *a.instConfig.Containerd.User) && !*a.instConfig.Plain {
 		req = append(req,
 			requirement{
-				description: "systemd must be available",
+				description: "systemd to be available",
 				fatal:       true,
 				script: `#!/bin/bash
 set -eux -o pipefail
@@ -275,7 +314,7 @@ func (a *HostAgent) finalRequirements() []requirement {
 	}
 	req = append(req,
 		requirement{
-			description: "boot scripts must have finished",
+			description: "boot scripts to be finished",
 			script: fmt.Sprintf(`#!/bin/sh
 set -eux
 BOOT_DONE=/run/lima-boot-done

pkg/instance/start.go

@@ -17,6 +17,7 @@ import (
 
 	"github.com/docker/go-units"
 	"github.com/lima-vm/go-qcow2reader"
+	"github.com/mattn/go-isatty"
 	"github.com/sirupsen/logrus"
 
 	"github.com/lima-vm/lima/v2/pkg/autostart"
@@ -312,7 +313,20 @@ func watchHostAgentEvents(ctx context.Context, inst *limatype.Instance, haStdout
 		err                  error
 	)
 
+	// progressTTY is true when stderr is a real terminal, so we can render
+	// requirement progress with an in-place 🕐 -> ✅ flip; otherwise we
+	// fall back to two log lines per step.
+	progressTTY := isatty.IsTerminal(os.Stderr.Fd()) || isatty.IsCygwinTerminal(os.Stderr.Fd())
+	// lastProgressKey is the "step/total:done" of the most recently
+	// rendered RequirementProgress, used to suppress duplicate renders
+	// when the same event is observed more than once.
+	var lastProgressKey string
+
 	onEvent := func(ev hostagentevents.Event) bool {
+		if p := ev.Status.RequirementProgress; p != nil {
+			renderRequirementProgress(p, progressTTY, &lastProgressKey)
+			return false
+		}
 		if !printedSSHLocalPort && ev.Status.SSHLocalPort != 0 {
 			logrus.Infof("SSH Local Port: %d", ev.Status.SSHLocalPort)
 			printedSSHLocalPort = true
@@ -388,6 +402,43 @@ func watchHostAgentEvents(ctx context.Context, inst *limatype.Instance, haStdout
 	return nil
 }
 
+// renderRequirementProgress prints a RequirementProgress event. On a TTY it
+// keeps the pending "🕐" line on the current row and overwrites it in place
+// with "✅" when the step completes, so each step occupies a single line that
+// flips from waiting to satisfied. On a non-TTY (piped output, log file)
+// each transition becomes a regular log line via logrus.
+//
+// `pending` carries the text of the currently-displayed pending line across
+// calls so the completion event can clear it with `\r` + clear-EOL.
+func renderRequirementProgress(p *hostagentevents.RequirementProgress, tty bool, pending *string) {
+	// Dedup identical consecutive renders. The hostagent should only emit
+	// one event per state transition, but if the same RequirementProgress
+	// gets replayed (e.g. carried along on an unrelated status event) we
+	// must not redraw, otherwise the pending line would be reprinted on
+	// every unrelated event and either spam the log (non-TTY) or fight
+	// with interleaved logrus output (TTY).
+	key := fmt.Sprintf("%d/%d:%t", p.Step, p.Total, p.Done)
+	if key == *pending {
+		return
+	}
+	*pending = key
+
+	if !tty {
+		if p.Done {
+			logrus.Infof("(%2d/%d) ✅ %s", p.Step, p.Total, p.Description)
+		} else {
+			logrus.Infof("(%2d/%d) 🕐 %s%s", p.Step, p.Total, p.Description, p.Suffix)
+		}
+		return
+	}
+	const clearEOL = "\033[K"
+	if p.Done {
+		fmt.Fprintf(os.Stderr, "\r%s(%2d/%d) ✅ %s\n", clearEOL, p.Step, p.Total, p.Description)
+		return
+	}
+	fmt.Fprintf(os.Stderr, "\r%s(%2d/%d) 🕐 %s%s", clearEOL, p.Step, p.Total, p.Description, p.Suffix)
+}
+
 type watchHostAgentEventsTimeoutKey = struct{}
 
 // WithWatchHostAgentTimeout sets the value of the timeout to use for