feat(simulate): expose run ID for CI baseline handoff

Author: u9g

README.md

@@ -455,6 +455,20 @@ The above simulates 5 concurrent rooms, where each room has:
 
 Once the specified duration is over (or if the load test is manually stopped), the load test statistics will be displayed in the form of a table.
 
+## Agent simulations in CI
+
+Use a finished simulation run as a baseline so known failures are reported without failing CI, while regressions still return a nonzero exit code:
+
+```shell
+lk agent simulate \
+  --scenarios scenarios.yaml \
+  --baseline "$SIMULATION_BASELINE_RUN_ID" \
+  --run-id-file "$RUNNER_TEMP/simulation-run-id"
+```
+
+The CLI writes the new run ID to `--run-id-file` as soon as the run is created, even if the simulation later fails. Store the ID in your CI provider's variable or artifact store. Only a successful run on the main branch should replace the stored baseline; pull requests and failed main runs should leave it unchanged.
+
+For the first run, omit `--baseline`, inspect and accept its results, then store the ID written to the file. A missing, unfinished, or inaccessible baseline fails CI rather than silently using strict comparison.
 
 ## Browsing documentation
 

cmd/lk/simulate.go

@@ -105,6 +105,10 @@ var simulateCommand = &cli.Command{
 			Name:  "baseline",
 			Usage: "Compare failures against the finished run with run `ID`: only scenarios that pass there and fail here fail the exit code. Non-interactive (CI) runs only",
 		},
+		&cli.StringFlag{
+			Name:  "run-id-file",
+			Usage: "Write the simulation run ID to `FILE` as soon as it is available. Non-interactive (CI) runs only",
+		},
 		&cli.StringFlag{
 			Name:  "agent-name",
 			Usage: "Run against an already-running agent instead of spawning one locally. Pass the registered `NAME`, or \"\" to target the project's default agent (the one that auto-joins every room). Requires --scenarios.",
@@ -219,6 +223,7 @@ type simulateConfig struct {
 	scenariosPath  string   // path to the --scenarios file (empty when generating from source)
 	viewModeRunID  string   // non-empty when --view opens a pre-existing run
 	baselineRunID  string   // --baseline: failures this run also has don't fail CI
+	runIDFile      string   // --run-id-file: machine-readable handoff to CI
 	liveAgent      bool     // --agent-name: run against an already-running agent, don't spawn one
 	warnings       []string // config-level warnings surfaced at setup (e.g. ignored flags)
 
@@ -422,6 +427,7 @@ func runSimulate(ctx context.Context, cmd *cli.Command, simulationMode livekit.S
 		scenariosPath:  scenariosPath,
 		viewModeRunID:  runID,
 		baselineRunID:  cmd.String("baseline"),
+		runIDFile:      cmd.String("run-id-file"),
 		liveAgent:      liveAgent,
 		warnings:       simulateConfigWarnings(mode, numSimulations),
 	}
@@ -438,6 +444,9 @@ func runSimulate(ctx context.Context, cmd *cli.Command, simulationMode livekit.S
 	if simCfg.baselineRunID != "" {
 		return fmt.Errorf("--baseline only applies to non-interactive (CI) runs; the TUI already shows every failure")
 	}
+	if simCfg.runIDFile != "" {
+		return fmt.Errorf("--run-id-file only applies to non-interactive (CI) runs; the TUI already shows the run ID")
+	}
 	return runSimulateTUI(simCfg)
 }
 

cmd/lk/simulate_ci.go

@@ -120,6 +120,11 @@ func runSimulateCI(ctx context.Context, config *simulateConfig) error {
 		report.EndSetup()
 		return err
 	}
+	if err := writeSimulationRunID(config.runIDFile, runID); err != nil {
+		report.SetupFailed(err)
+		report.EndSetup()
+		return err
+	}
 	report.SimulationCreated(time.Since(start))
 
 	if config.mode == modeGenerateFromSource {
@@ -221,6 +226,16 @@ func runSimulateCI(ctx context.Context, config *simulateConfig) error {
 	return baselineFailureError(ctx, config, run)
 }
 
+func writeSimulationRunID(path, runID string) error {
+	if path == "" {
+		return nil
+	}
+	if err := os.WriteFile(path, []byte(runID+"\n"), 0o644); err != nil {
+		return fmt.Errorf("write simulation run ID to %s: %w", path, err)
+	}
+	return nil
+}
+
 // baselineFailureError fetches the --baseline run when one was given and
 // reports which failures it already had before deciding the exit error. A
 // baseline that can't be fetched fails CI loudly rather than silently
@@ -332,6 +347,9 @@ func runSimulateCIView(ctx context.Context, config *simulateConfig) error {
 
 	report := newSimLog(out.ResultWriter(), out.StatusWriter())
 	runID := config.viewModeRunID
+	if err := writeSimulationRunID(config.runIDFile, runID); err != nil {
+		return err
+	}
 
 	ticker := time.NewTicker(simulationPollInterval)
 	defer ticker.Stop()

cmd/lk/simulate_ci_test.go

@@ -15,12 +15,29 @@
 package main
 
 import (
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
 	"github.com/livekit/protocol/livekit"
 )
 
+func TestWriteSimulationRunID(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "run-id")
+
+	if err := writeSimulationRunID(path, "SR_test123"); err != nil {
+		t.Fatalf("writeSimulationRunID: %v", err)
+	}
+	got, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read run ID file: %v", err)
+	}
+	if string(got) != "SR_test123\n" {
+		t.Errorf("run ID file = %q, want %q", got, "SR_test123\\n")
+	}
+}
+
 func simJob(label string, failed bool) *livekit.SimulationRun_Job {
 	status := livekit.SimulationRun_Job_STATUS_COMPLETED
 	if failed {