retention: explicit run-history and artifact retention

Add `pipelines retention report` (strictly read-only) and
`pipelines retention apply` (explicit, approval-gated removal) with an age
and/or count policy, protected-run rules, atomic single-transaction removal
and honest database space reclaim. Nothing prunes automatically.
This commit is contained in:
2026-10-17 15:45:46 +01:00
parent b2e920a150
commit 14175eba70
15 changed files with 2127 additions and 12 deletions
+19
View File
@@ -40,6 +40,9 @@ type options struct {
output string
conflict string
kind string
db, artifacts, olderThan string
keep int
keepSet bool
all bool
json, source, noOpen, yes, allow, createOnly, force, wait bool
version, expected, limit int
@@ -151,6 +154,19 @@ func (a App) flags(command string) (*flag.FlagSet, *options) {
f.DurationVar(&o.waitTimeout, "wait-timeout", 0, "Client limit for --wait (0 waits until the run ends); independent of --timeout")
case "cancel", "draft-delete":
f.BoolVar(&o.yes, "yes", false, "Confirm this action without an interactive prompt")
case "retention":
f.StringVar(&o.db, "db", "", "Existing database path (default: standard data directory)")
f.StringVar(&o.artifacts, "artifacts", "", "Artifacts root (default: artifacts/ beside --db)")
f.StringVar(&o.olderThan, "older-than", "", "Select runs created before this rolling UTC duration ago (e.g. 720h, 30d, 12w)")
f.Func("keep", "Keep the newest N runs; older runs are selected (0 selects every eligible run)", func(value string) error {
n, err := strconv.Atoi(strings.TrimSpace(value))
if err != nil {
return fmt.Errorf("--keep requires an integer count")
}
o.keep, o.keepSet = n, true
return nil
})
f.BoolVar(&o.yes, "yes", false, "Approve removal without an interactive prompt (apply only)")
case "decide":
f.StringVar(&o.option, "option", "", "Option key to choose among the waiting stage's edges (required)")
f.StringVar(&o.feedback, "feedback", "", "Optional free-text feedback recorded with the decision")
@@ -389,6 +405,9 @@ func (a App) Run(ctx context.Context, args []string) error {
_, err := fmt.Fprintln(a.Out, "Deleted draft:", pos[0])
return err
}
if command == "retention" {
return a.retention(ctx, o, pos)
}
if command != "drafts" && os.Getenv("PIPELINES_URL") == "" {
explicit := false
f.Visit(func(value *flag.Flag) {
+2
View File
@@ -31,6 +31,7 @@ var usage = map[string]string{
"status": "status [--json]",
"stats": "stats [--json]",
"rpc": "rpc <request.json|->",
"retention": "retention report|apply [--older-than DURATION] [--keep N] [--db FILE] [--artifacts DIR] [--json] [--yes]",
"tui": "tui",
}
@@ -51,6 +52,7 @@ var notes = map[string]string{
"decide": "Choose an option for a run waiting on a human stage. The run must be `waiting`; the option must be one of that stage's non-error edges. The stage is inferred from the run's current stage unless named. The choice and optional --feedback are recorded as the step's evidence (visible in inspect and the TUI) and the run resumes along the chosen edge. An unknown option is refused with the valid list; a repeated decision for an already-decided visit does not double-apply. Works across a server restart because the wait is persisted.",
"debug": "Open a fresh configured harness conversation to investigate a run using inspect/show/runs CLI queries. --harness opencode|pi|nvim chooses another configured harness or read-only nvim packet. Does not resume implementation or retry. --json returns the prompt without launching anything.",
"rpc": "Accepts a JSON protocol envelope; '-' reads stdin. Every TUI server operation is available here too. Mutating commands are not dry runs. The omni-search command is `search` (fields query, optional kind and limit) and answers with ranked `search_results`.",
"retention": "Local, explicit run-history retention; never automatic and never a side effect of another command. `report` is strictly read-only and prints what a policy would remove; `apply` removes it after approval (--yes for scripted use). Policy: --older-than DURATION selects runs created before now minus that rolling UTC duration (Go durations plus d/w; not a calendar boundary), --keep N keeps the newest N runs by run id and selects older ranks (--keep 0 keeps none). Both together are the conservative intersection; at least one is required. Protected and never removed: queued/running runs, runs waiting on a person (waiting run or step), runs with an active cleanup agent, and any run referenced by a retained run's retry provenance (transitively). A run that becomes protected before deletion aborts the whole apply. Artifacts at <root>/<run> are removed with their run and kept with protected/retained runs; the database is VACUUMed and its WAL checkpointed, with measured reclaimed bytes. Definitions and versions are immutable and never touched. --db must name an existing database (default: the standard data directory); --artifacts defaults to artifacts/ beside --db. Works without a running server.",
"search": "One read-only query over pipelines, versions, runs, steps, field text and artifacts. QUERY is free text, a bare status word (queued, running, succeeded, failed, canceled, interrupted) selecting those runs, or a lone date expression (today, yesterday, this week [Monday 00:00 local], or YYYY-MM-DD) selecting the runs created in that window. --type is the only narrowing mechanism and takes one kind: pipeline, version, run, step, field or artifact; an unknown kind is an error. Ranking: an exact name match (3) beats a name substring (2) beats a body-text match (1); equal tiers break by recency, then a stable kind/target tie-break, and every hit reports score, matched_field and recency so a client can re-rank. Bounds: the result cap defaults to 50 and clamps to 200 (0 = default); every kind scans at most 2000 rows and field-text scanning is additionally capped at 2000 steps / 1 MiB; Truncated plus scanned_steps, scanned_bytes and scan_bound_bytes report when a bound applied. Targets are stable: pipeline:<id>, pipeline:<id>:v<version>, run:<id>, run:<id>:<sequence>, run:<id>:<sequence>:<field>, or an artifact URL.",
}
+8
View File
@@ -39,6 +39,10 @@ EXECUTE
version Identify this CLI build without connecting (--version)
rpc <request.json|-> Send any protocol command (automation escape hatch)
MAINTAIN
retention report Show what a run-history policy would remove (read-only)
retention apply Remove it after approval; artifacts go with their run
SERVER / INTERFACE
harness [opencode|pi] Launch the configured default harness in this directory
harness setup opencode|pi Login/select separate harness and new-pipeline defaults
@@ -71,6 +75,10 @@ Examples:
pipelines run "bug fix" "Fix the layout" --json
pipelines run "bug fix" "Fix the layout" --model openai/gpt-5 --stage-model review=openai/o4 --json
Run retention (local, explicit, never automatic):
pipelines retention report --db ~/.local/share/pipelines/data/pipelines.db --keep 200 --json
pipelines retention apply --db ~/.local/share/pipelines/data/pipelines.db --keep 200 --yes
Launch-time model overrides: 'pipelines run --model P/M' covers every model stage;
'--stage-model STAGE=P/M' (repeatable; a repeated key is last-wins) overrides one
stage and wins over --model, which wins over the model pinned in the pipeline
+218
View File
@@ -0,0 +1,218 @@
package cli
import (
"context"
"fmt"
"os"
"path/filepath"
"strconv"
"strings"
"time"
"git.a-wan.net/alan/pipelines/internal/paths"
"git.a-wan.net/alan/pipelines/internal/pipeline"
"git.a-wan.net/alan/pipelines/internal/tui"
)
// retention implements the local maintenance command: `report` describes what a
// policy would remove without touching anything, and `apply` removes it after
// explicit approval. It is dispatched before server URL resolution, so it works
// against a local database without a running server and never mutates the
// deployed server's configuration or definitions.
func (a App) retention(ctx context.Context, o *options, pos []string) error {
if len(pos) != 1 {
return fmt.Errorf("retention requires a subcommand: report or apply; use pipelines help retention")
}
sub := pos[0]
if sub != "report" && sub != "apply" {
return fmt.Errorf("unknown retention subcommand %q; use report or apply", sub)
}
policy, err := o.retentionPolicy()
if err != nil {
return err
}
db := strings.TrimSpace(o.db)
if db == "" {
db, err = paths.Database()
if err != nil {
return err
}
}
if _, err := os.Stat(db); err != nil {
return fmt.Errorf("retention database %s is unavailable: %w", db, err)
}
artifacts := strings.TrimSpace(o.artifacts)
if artifacts == "" {
artifacts = filepath.Join(filepath.Dir(db), "artifacts")
}
now := time.Now().UTC()
if sub == "report" {
store, err := pipeline.OpenReadOnly(db)
if err != nil {
return err
}
defer store.Close()
report, err := store.RetentionReport(ctx, policy, artifacts, now)
if err != nil {
return err
}
return a.printRetentionReport(report, o.json)
}
store, err := pipeline.OpenMaintenance(db)
if err != nil {
return err
}
defer store.Close()
if !o.yes {
preview, err := store.RetentionReport(ctx, policy, artifacts, now)
if err != nil {
return err
}
question := fmt.Sprintf("Permanently remove %d run(s) and %s of artifacts? Definitions and versions are never touched.",
len(preview.WouldRemove), tui.HumanBytes(preview.ArtifactBytes))
if err := a.confirmAction(question, false); err != nil {
if printErr := a.printRetentionReport(preview, o.json); printErr != nil {
return printErr
}
return err
}
}
result, err := store.ApplyRetention(ctx, policy, artifacts, now)
if result != nil {
// Print the report even on a refusal, cleanup or vacuum error so the
// selection and reasons stay visible.
if printErr := a.printRetentionResult(result, o.json); printErr != nil {
return printErr
}
}
return err
}
// retentionPolicy converts the parsed flags into a validated policy. An unset
// --keep is -1 (no count bound) so it is distinguishable from --keep 0.
func (o *options) retentionPolicy() (pipeline.RetentionPolicy, error) {
policy := pipeline.RetentionPolicy{Keep: -1}
if raw := strings.TrimSpace(o.olderThan); raw != "" {
duration, err := parseRetentionDuration(raw)
if err != nil {
return policy, err
}
if duration <= 0 {
return policy, fmt.Errorf("--older-than must be a positive duration")
}
policy.OlderThan = duration
}
if o.keepSet {
if o.keep < 0 {
return policy, fmt.Errorf("--keep must be nonnegative")
}
policy.Keep = o.keep
}
if err := policy.Validate(); err != nil {
return policy, err
}
return policy, nil
}
// parseRetentionDuration accepts Go durations plus a count of days or weeks,
// so an operator can write 720h, 30d or 12w. The result is a rolling duration,
// never a calendar-day boundary.
func parseRetentionDuration(value string) (time.Duration, error) {
value = strings.TrimSpace(value)
if value == "" {
return 0, fmt.Errorf("duration is empty")
}
unit, number := time.Duration(0), value
switch {
case strings.HasSuffix(value, "d"):
unit, number = 24*time.Hour, strings.TrimSuffix(value, "d")
case strings.HasSuffix(value, "w"):
unit, number = 7*24*time.Hour, strings.TrimSuffix(value, "w")
}
if unit != 0 {
count, err := strconv.ParseFloat(number, 64)
if err != nil {
return 0, fmt.Errorf("invalid duration %q: use Go durations or a count of d/w", value)
}
return time.Duration(count * float64(unit)), nil
}
duration, err := time.ParseDuration(value)
if err != nil {
return 0, fmt.Errorf("invalid duration %q: %w", value, err)
}
return duration, nil
}
func (a App) printRetentionReport(report *pipeline.RetentionReport, jsonOutput bool) error {
if jsonOutput {
return a.output(report)
}
writeRetention(a.Out, report)
fmt.Fprintln(a.Out, "\nNo changes made.")
return nil
}
func (a App) printRetentionResult(result *pipeline.RetentionApplyResult, jsonOutput bool) error {
if jsonOutput {
return a.output(result)
}
writeRetention(a.Out, &result.RetentionReport)
fmt.Fprintf(a.Out, "\nRemoved %d run(s) · %d files · %s\n", result.RemovedRunCount, result.RemovedArtifactFiles, tui.HumanBytes(result.RemovedArtifactBytes))
if result.Vacuumed {
fmt.Fprintf(a.Out, "Database reclaimed: %s · now %s · free %s\n", tui.HumanBytes(result.DatabaseBytesReclaimed), tui.HumanBytes(result.DatabaseBytesAfter), tui.HumanBytes(result.DatabaseFreeBytesAfter))
}
if result.VacuumError != "" {
fmt.Fprintf(a.Out, "Database reclaim failed: %s\n", result.VacuumError)
}
fmt.Fprintf(a.Out, "Total space reclaimed: %s\n", tui.HumanBytes(result.SpaceReclaimedBytes))
if result.StagingPath != "" {
fmt.Fprintf(a.Out, "Staging cleanup incomplete: %s · %d files · %s remain and are not reclaimed\n", result.StagingPath, result.StagingRemainingFiles, tui.HumanBytes(result.StagingRemainingBytes))
}
return nil
}
// writeRetention renders the shared report body used by both report and apply
// output, so the selection, sizes and reasons are presented identically.
func writeRetention(w interface{ Write([]byte) (int, error) }, report *pipeline.RetentionReport) {
fmt.Fprintf(w, "Retention · %s\n", report.Database)
fmt.Fprintf(w, "Artifacts root: %s\n", report.ArtifactsRoot)
fmt.Fprintf(w, "Policy: older-than %s · keep newest %s\n", retentionAge(report.Policy), retentionKeep(report.Policy))
fmt.Fprintf(w, "Runs: %d total · %d would remove · %d protected · %d retained\n", report.TotalRuns, len(report.WouldRemove), len(report.Protected), report.RetainedRuns)
fmt.Fprintf(w, "Artifacts: %d files · %s\n", report.ArtifactFiles, tui.HumanBytes(report.ArtifactBytes))
fmt.Fprintf(w, "Database: %s · free %s\n", tui.HumanBytes(report.DatabaseBytes), tui.HumanBytes(report.DatabaseFreeBytes))
fmt.Fprintf(w, "Reclaimable: %s\n", tui.HumanBytes(report.ReclaimableBytes))
if len(report.WouldRemove) > 0 {
fmt.Fprintln(w, "\nWould remove:")
for _, run := range report.WouldRemove {
fmt.Fprintf(w, " #%d %s %s %d files %s\n", run.ID, run.Status, run.CreatedAt, run.Artifacts.Files, tui.HumanBytes(run.Artifacts.Bytes))
}
}
if len(report.Protected) > 0 {
fmt.Fprintln(w, "\nProtected:")
for _, run := range report.Protected {
fmt.Fprintf(w, " #%d %s\n", run.ID, run.Reason)
}
}
if report.ArtifactsPartial {
fmt.Fprintln(w, "\nArtifact sizes are partial; some directories could not be fully walked:")
for _, err := range report.ArtifactWalkErrors {
fmt.Fprintf(w, " %s\n", err)
}
}
}
func retentionAge(policy pipeline.RetentionPolicy) string {
if policy.OlderThan <= 0 {
return "unset"
}
return policy.OlderThan.String()
}
func retentionKeep(policy pipeline.RetentionPolicy) string {
if policy.Keep < 0 {
return "unset"
}
return strconv.Itoa(policy.Keep)
}
+179
View File
@@ -0,0 +1,179 @@
package cli
import (
"bytes"
"context"
"encoding/json"
"fmt"
"os"
"path/filepath"
"strings"
"testing"
"git.a-wan.net/alan/pipelines/internal/pipeline"
)
// seedRetentionStore creates a scratch database with a definition and the given
// number of runs, plus one artifact under the first run. It returns the database
// path and the directory that holds the default artifacts root.
func seedRetentionStore(t *testing.T, runs int) (db, dir string) {
t.Helper()
dir = t.TempDir()
db = filepath.Join(dir, "pipelines.db")
ctx := context.Background()
store, err := pipeline.Open(db)
if err != nil {
t.Fatal(err)
}
if _, err := store.Submit(ctx, "cli-retention", pipeline.Template([]string{"one"}, true)); err != nil {
t.Fatal(err)
}
items, err := store.List(ctx)
if err != nil {
t.Fatal(err)
}
definition, err := store.Get(ctx, items[0].ID, 1)
if err != nil {
t.Fatal(err)
}
for i := 0; i < runs; i++ {
id, _, err := store.CreateRun(ctx, definition, fmt.Sprintf("run-%d", i), "ws", false, nil, map[string]any{"prompt": "task"})
if err != nil {
t.Fatal(err)
}
if err := store.FinishRun(ctx, id, "succeeded", "success", "", map[string]any{}); err != nil {
t.Fatal(err)
}
}
if err := store.Close(); err != nil {
t.Fatal(err)
}
artifact := filepath.Join(dir, "artifacts", "1", "1", "report.bin")
if err := os.MkdirAll(filepath.Dir(artifact), 0700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(artifact, []byte("artifact bytes"), 0600); err != nil {
t.Fatal(err)
}
return db, dir
}
func runCount(t *testing.T, db string) int {
t.Helper()
store, err := pipeline.OpenReadOnly(db)
if err != nil {
t.Fatal(err)
}
defer store.Close()
runs, err := store.ListRuns(context.Background())
if err != nil {
t.Fatal(err)
}
return len(runs)
}
func newRetentionApp() (App, *bytes.Buffer) {
var out bytes.Buffer
return App{Out: &out, Err: &out, In: strings.NewReader("")}, &out
}
func TestRetentionReportIsReadOnlyAndLocal(t *testing.T) {
ctx := context.Background()
db, dir := seedRetentionStore(t, 3)
app, out := newRetentionApp()
// --url not-a-server proves the command never dials a server.
if err := app.Run(ctx, []string{"retention", "report", "--db", db, "--keep", "1", "--json", "--url", "not-a-server"}); err != nil {
t.Fatal(err)
}
var report pipeline.RetentionReport
if err := json.Unmarshal(out.Bytes(), &report); err != nil {
t.Fatalf("report is not valid JSON: %v\n%s", err, out.String())
}
if report.Applied {
t.Fatal("a report must never be applied")
}
if len(report.WouldRemove) != 2 || report.TotalRuns != 3 {
t.Fatalf("report selection wrong: %+v", report)
}
if report.ArtifactsRoot != filepath.Join(dir, "artifacts") {
t.Fatalf("default artifacts root = %q, want artifacts/ beside the db", report.ArtifactsRoot)
}
if report.ReclaimableBytes < int64(len("artifact bytes")) {
t.Fatalf("reclaimable bytes must include the run artifacts: %d", report.ReclaimableBytes)
}
if runCount(t, db) != 3 {
t.Fatal("report must not change the run history")
}
if _, err := os.Stat(filepath.Join(dir, "artifacts", "1", "1", "report.bin")); err != nil {
t.Fatalf("report must not touch artifacts: %v", err)
}
}
func TestRetentionApplyRequiresApprovalAndRemovesRuns(t *testing.T) {
ctx := context.Background()
db, dir := seedRetentionStore(t, 3)
app, out := newRetentionApp()
// Without --yes and with no interactive input, apply refuses and changes nothing.
if err := app.Run(ctx, []string{"retention", "apply", "--db", db, "--keep", "1", "--url", "not-a-server"}); err == nil {
t.Fatal("apply must refuse without --yes or interactive approval")
}
if runCount(t, db) != 3 {
t.Fatal("refused apply changed the run history")
}
if _, err := os.Stat(filepath.Join(dir, "artifacts", "1", "1", "report.bin")); err != nil {
t.Fatalf("refused apply touched artifacts: %v", err)
}
out.Reset()
if err := app.Run(ctx, []string{"retention", "apply", "--db", db, "--keep", "1", "--yes", "--json", "--url", "not-a-server"}); err != nil {
t.Fatal(err)
}
var result pipeline.RetentionApplyResult
if err := json.Unmarshal(out.Bytes(), &result); err != nil {
t.Fatalf("apply is not valid JSON: %v\n%s", err, out.String())
}
if !result.Applied || result.RemovedRunCount != 2 || !result.Vacuumed {
t.Fatalf("apply did not remove and reclaim: %+v", result)
}
if runCount(t, db) != 1 {
t.Fatalf("apply removed the wrong number of runs: %d", runCount(t, db))
}
if _, err := os.Stat(filepath.Join(dir, "artifacts", "1")); !os.IsNotExist(err) {
t.Fatalf("removed run's artifacts must be gone: %v", err)
}
}
func TestRetentionValidationAndMissingDatabase(t *testing.T) {
ctx := context.Background()
db, dir := seedRetentionStore(t, 1)
app, _ := newRetentionApp()
for _, args := range [][]string{
{"retention", "report", "--db", db, "--url", "not-a-server"}, // no policy
{"retention", "report", "--db", db, "--keep=-1", "--url", "not-a-server"}, // negative count
{"retention", "report", "--db", db, "--older-than", "0h", "--url", "not-a-server"},
{"retention", "frobnicate", "--db", db, "--keep", "1", "--url", "not-a-server"}, // unknown subcommand
} {
if err := app.Run(ctx, args); err == nil {
t.Fatalf("%v was accepted", args)
}
}
missing := filepath.Join(dir, "missing.db")
if err := app.Run(ctx, []string{"retention", "report", "--db", missing, "--keep", "1", "--url", "not-a-server"}); err == nil {
t.Fatal("a missing database must be an error")
}
if _, err := os.Stat(missing); !os.IsNotExist(err) {
t.Fatal("retention must not create a database")
}
}
func TestRetentionHelp(t *testing.T) {
app, out := newRetentionApp()
if err := app.Run(context.Background(), []string{"help", "retention"}); err != nil {
t.Fatal(err)
}
for _, want := range []string{"retention report|apply", "--older-than", "--keep", "--artifacts"} {
if !strings.Contains(out.String(), want) {
t.Fatalf("help retention missing %q:\n%s", want, out.String())
}
}
}