feat: vm logs --tail N

Adds the kubectl-style --tail flag to cocoon vm logs. Pairs with -f for
tail+follow. seekToLastNLines reads backwards in 4 KiB chunks counting
'\n' (skipping a trailing terminator), then Seek positions the fd so
the subsequent io.Copy emits exactly the last N lines. Tail-initiated
Seek does not interfere with the follow loop's truncate detection — the
head signature is sampled via ReadAt from offset 0 and is independent
of fd position.

README Logs Flags table and CLI tree updated.

Author: CMGS

README.md

@@ -139,7 +139,7 @@ cocoon
 │   ├── inspect VM                 Show detailed VM info (JSON)
 │   ├── console [flags] VM         Attach interactive console
 │   ├── exec [flags] VM -- CMD     Run a command in a running VM via cocoon-agent (vsock)
-│   ├── logs [-f] VM               Print the per-VM hypervisor log file
+│   ├── logs [-f] [--tail N] VM    Print the per-VM hypervisor log file
 │   ├── rm [flags] VM [VM...]      Delete VM(s) (--force to stop first)
 │   ├── restore [flags] VM SNAP   Restore a running VM to a snapshot
 │   ├── status [VM...]             Watch VM status in real time
@@ -335,15 +335,18 @@ Requires cocoon-agent to be running inside the guest (already baked into the off
 
 `cocoon vm logs` prints the per-VM hypervisor process log (`cloud-hypervisor.log` or `firecracker.log` under the configured `log_dir`). The log captures VMM-side activity — device init warnings, API errors, virtio messages, shutdown — but **not** guest console output (use `cocoon vm console` for that). The file lives under the VM's log dir for as long as the VM record exists (cleaned up on `vm rm`); each `vm run` / `vm start` truncates and rewrites it from scratch — `-f` detects the truncation and seeks back to the start of the file so you don't miss the new boot's lines.
 
-| Flag           | Default | Description                                        |
-| -------------- | ------- | -------------------------------------------------- |
-| `--follow`, `-f` | `false` | Stream new log lines as they are written (Ctrl-C to stop) |
+| Flag             | Default | Description                                                          |
+| ---------------- | ------- | -------------------------------------------------------------------- |
+| `--follow`, `-f` | `false` | Stream new log lines as they are written (Ctrl-C to stop)            |
+| `--tail`         | `0`     | Show only the last N lines (0 = all); pairs with `-f` for tail+follow |
 
 ```
 $ cocoon vm logs myvm
 cloud-hypervisor:   0.003732s: <vmm> WARN:virtio-devices/src/block.rs:793 -- sparse=on requested but backend does not support sparse operations
-$ cocoon vm logs -f myvm
-... live tail ...
+$ cocoon vm logs --tail 5 myvm
+... last 5 lines ...
+$ cocoon vm logs -f --tail 10 myvm
+... last 10 lines, then live tail ...
 ```
 
 ### List Flags

cmd/vm/commands.go

@@ -120,6 +120,7 @@ func Command(h Actions) *cobra.Command {
 		RunE:  h.Logs,
 	}
 	logsCmd.Flags().BoolP("follow", "f", false, "stream new log lines as they are written")
+	logsCmd.Flags().Int("tail", 0, "show only the last N lines (0 = all)")
 
 	rmCmd := &cobra.Command{
 		Use:   "rm [flags] VM [VM...]",

cmd/vm/lifecycle.go

@@ -190,10 +190,11 @@ func (h Handler) Logs(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("logs: %w", err)
 	}
 	follow, _ := cmd.Flags().GetBool("follow")
-	return streamLog(ctx, path, follow)
+	tail, _ := cmd.Flags().GetInt("tail")
+	return streamLog(ctx, path, follow, tail)
 }
 
-func streamLog(ctx context.Context, path string, follow bool) error {
+func streamLog(ctx context.Context, path string, follow bool, tail int) error {
 	f, err := os.Open(path) //nolint:gosec
 	if err != nil {
 		if os.IsNotExist(err) {
@@ -203,6 +204,12 @@ func streamLog(ctx context.Context, path string, follow bool) error {
 	}
 	defer f.Close() //nolint:errcheck
 
+	if tail > 0 {
+		if seekErr := seekToLastNLines(f, tail); seekErr != nil {
+			return fmt.Errorf("seek tail: %w", seekErr)
+		}
+	}
+
 	if !follow {
 		if _, copyErr := io.Copy(os.Stdout, f); copyErr != nil {
 			return fmt.Errorf("read log: %w", copyErr)
@@ -244,6 +251,41 @@ func streamLog(ctx context.Context, path string, follow bool) error {
 	}
 }
 
+// seekToLastNLines positions f so a subsequent read returns the last n lines.
+// A final trailing '\n' is not counted as a line separator.
+func seekToLastNLines(f *os.File, n int) error {
+	info, err := f.Stat()
+	if err != nil {
+		return err
+	}
+	size := info.Size()
+	if size == 0 {
+		return nil
+	}
+	const chunk = 4096
+	buf := make([]byte, chunk)
+	pos, found := size, 0
+	for pos > 0 {
+		readSize := min(int64(chunk), pos)
+		pos -= readSize
+		if _, readErr := f.ReadAt(buf[:readSize], pos); readErr != nil {
+			return readErr
+		}
+		for i := readSize - 1; i >= 0; i-- {
+			if buf[i] != '\n' || pos+i == size-1 {
+				continue
+			}
+			found++
+			if found == n {
+				_, seekErr := f.Seek(pos+i+1, io.SeekStart)
+				return seekErr
+			}
+		}
+	}
+	_, err = f.Seek(0, io.SeekStart)
+	return err
+}
+
 func (h Handler) RM(cmd *cobra.Command, args []string) error {
 	ctx, conf, err := h.Init(cmd)
 	if err != nil {

cmd/vm/lifecycle_tail_tmp_test.go

@@ -0,0 +1,44 @@
+package vm
+
+import (
+	"io"
+	"os"
+	"testing"
+)
+
+func TestSeekToLastNLinesTmp(t *testing.T) {
+	tests := []struct {
+		name string
+		body string
+		n    int
+		want string
+	}{
+		{name: "no trailing newline", body: "a\nb\nc", n: 2, want: "b\nc"},
+		{name: "trailing newline", body: "a\nb\nc\n", n: 2, want: "b\nc\n"},
+		{name: "more than available", body: "a\nb", n: 5, want: "a\nb"},
+		{name: "one line trailing", body: "a\nb\nc\n", n: 1, want: "c\n"},
+		{name: "empty", body: "", n: 3, want: ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f, err := os.CreateTemp(t.TempDir(), "log")
+			if err != nil {
+				t.Fatal(err)
+			}
+			defer f.Close()
+			if _, err := f.WriteString(tt.body); err != nil {
+				t.Fatal(err)
+			}
+			if err := seekToLastNLines(f, tt.n); err != nil {
+				t.Fatal(err)
+			}
+			got, err := io.ReadAll(f)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if string(got) != tt.want {
+				t.Fatalf("got %q, want %q", got, tt.want)
+			}
+		})
+	}
+}