P2-05: forget command with retention policy

End-to-end forget plumbing — operator can create a forget schedule
with keep-* values, agent runs restic forget --keep-* … on the
schedule's cron (or via per-row Run-now), snapshot list shrinks,
UI updates.

* api.CommandRunPayload gains retention_policy json.RawMessage so
  the agent doesn't need a typed copy of the server-side struct.
* restic.ForgetPolicy mirrors restic's --keep-* flags. Empty()
  reports zero dimensions; restic wrapper RunForget refuses to
  run an empty policy (would delete every snapshot). Does NOT
  pass --prune — pruning lives behind a separate admin-only
  credential (P2-06); forget just rewrites the snapshot index.
* runner.RunForget mirrors RunBackup's envelope shape so the
  live log viewer works without special-casing. On success
  triggers reportSnapshots (forget shrinks the index, the host's
  snapshot count almost certainly changed).
* cmd/agent dispatcher handles MsgCommandRun with kind=forget,
  decodes RetentionPolicy from the wire, builds restic.ForgetPolicy.
* Server dispatchScheduleNow marshals the schedule's
  RetentionPolicy into the wire payload for kind=forget jobs.
  Refuses to dispatch a forget schedule with empty retention.
* validateSchedule rejects kind=forget without at least one keep-*
  dimension (new error code: missing_retention).
* UI schedule edit form gains a Kind dropdown (backup or forget;
  immutable on edit). Paths block toggles by kind via inline
  data-kind attributes. Form help-text explains the prune
  separation.

Other kinds (prune, check, unlock) deferred to P2-06..08; the
Kind dropdown only offers backup and forget today.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

internal/agent/runner/runner.go

@@ -205,6 +205,75 @@ func (r *Runner) RunInit(ctx context.Context, jobID string) error {
 	return nil
 }
 
+// RunForget executes a forget job against the configured repo with
+// the given retention policy. Same envelope shape as RunBackup so
+// the live log viewer + job lifecycle work without special-casing.
+// On success refreshes the snapshot projection (forget rewrites the
+// snapshot index — the host's snapshot list shrinks).
+func (r *Runner) RunForget(ctx context.Context, jobID string, policy restic.ForgetPolicy) error {
+	startedAt := time.Now().UTC()
+	startEnv, _ := api.Marshal(api.MsgJobStarted, jobID, api.JobStartedPayload{
+		JobID: jobID, Kind: api.JobForget, StartedAt: startedAt,
+	})
+	if err := r.tx.Send(startEnv); err != nil {
+		slog.Warn("runner: send job.started (forget)", "err", err)
+	}
+
+	env := restic.Env{
+		Bin:          r.cfg.ResticBin,
+		RepoURL:      r.cfg.RepoURL,
+		RepoUsername: r.cfg.RepoUsername,
+		RepoPassword: r.cfg.RepoPassword,
+	}
+
+	var seq atomic.Int64
+	handle := func(stream string, line string, _ any) {
+		now := time.Now().UTC()
+		logEnv, _ := api.Marshal(api.MsgLogStream, "", api.LogStreamLine{
+			JobID:   jobID,
+			Seq:     seq.Add(1),
+			TS:      now,
+			Stream:  api.LogStream(stream),
+			Payload: line,
+		})
+		_ = r.tx.Send(logEnv)
+	}
+
+	err := env.RunForget(ctx, policy, handle)
+	finishedAt := time.Now().UTC()
+
+	status := api.JobSucceeded
+	exit := 0
+	errMsg := ""
+	if err != nil {
+		status = api.JobFailed
+		exit = -1
+		errMsg = err.Error()
+	}
+	finEnv, _ := api.Marshal(api.MsgJobFinished, jobID, api.JobFinishedPayload{
+		JobID:      jobID,
+		Status:     status,
+		ExitCode:   exit,
+		FinishedAt: finishedAt,
+		Error:      errMsg,
+	})
+	_ = r.tx.Send(finEnv)
+
+	// Refresh the server's snapshot projection — forget rewrites the
+	// index so the host's snapshot list almost certainly shrunk.
+	if err == nil {
+		if rerr := r.reportSnapshots(ctx, env); rerr != nil {
+			slog.Warn("runner: snapshots.report after forget failed",
+				"job_id", jobID, "err", rerr)
+		}
+	}
+
+	if err != nil {
+		return fmt.Errorf("runner forget: %w", err)
+	}
+	return nil
+}
+
 // reportSnapshots calls `restic snapshots --json`, translates the
 // payload into the wire shape, and ships it as a snapshots.report
 // envelope. Bounded by a separate timeout so a sluggish repo doesn't

internal/api/messages.go

@@ -66,10 +66,14 @@ const (
 )
 
 // CommandRunPayload is the server → agent dispatch for a run-now job.
+// RetentionPolicy is populated for kind=forget jobs (raw JSON so the
+// agent doesn't need to share the typed struct definition with the
+// server's store package).
 type CommandRunPayload struct {
-	JobID string   `json:"job_id"`
-	Kind  JobKind  `json:"kind"`
-	Args  []string `json:"args,omitempty"`
+	JobID           string          `json:"job_id"`
+	Kind            JobKind         `json:"kind"`
+	Args            []string        `json:"args,omitempty"`
+	RetentionPolicy json.RawMessage `json:"retention_policy,omitempty"`
 }
 
 // CommandCancelPayload is the server → agent cancel signal.

internal/restic/runner.go

@@ -148,6 +148,88 @@ func (e Env) RunBackup(ctx context.Context, paths, excludes, tags []string, hand
 	return summary, nil
 }
 
+// ForgetPolicy mirrors restic forget's --keep-* flags. All optional;
+// nil/zero means "don't pass that flag." Caller passes whatever the
+// schedule's RetentionPolicy carries.
+type ForgetPolicy struct {
+	KeepLast    *int
+	KeepHourly  *int
+	KeepDaily   *int
+	KeepWeekly  *int
+	KeepMonthly *int
+	KeepYearly  *int
+}
+
+// args returns the --keep-* CLI flags this policy translates into.
+// Empty slice if the policy is empty (caller should reject before
+// calling RunForget — restic refuses to forget without any keep-*).
+func (p ForgetPolicy) args() []string {
+	out := []string{}
+	add := func(flag string, v *int) {
+		if v != nil {
+			out = append(out, flag, fmt.Sprintf("%d", *v))
+		}
+	}
+	add("--keep-last", p.KeepLast)
+	add("--keep-hourly", p.KeepHourly)
+	add("--keep-daily", p.KeepDaily)
+	add("--keep-weekly", p.KeepWeekly)
+	add("--keep-monthly", p.KeepMonthly)
+	add("--keep-yearly", p.KeepYearly)
+	return out
+}
+
+// Empty reports whether no retention dimensions are set. restic
+// forget refuses to run without at least one keep-* flag (it would
+// delete every snapshot), so the agent rejects empty policies before
+// invoking restic.
+func (p ForgetPolicy) Empty() bool {
+	return p.KeepLast == nil && p.KeepHourly == nil &&
+		p.KeepDaily == nil && p.KeepWeekly == nil &&
+		p.KeepMonthly == nil && p.KeepYearly == nil
+}
+
+// RunForget executes `restic forget --keep-* … --json` against the
+// configured repo. Does NOT pass --prune — pruning lives behind a
+// separate, admin-only credential (see spec §4.3 / P2-06). Restic
+// just rewrites the snapshot index; the actual data deletion waits
+// for the next prune. Returns nil on a clean exit.
+func (e Env) RunForget(ctx context.Context, policy ForgetPolicy, handle LineHandler) error {
+	if policy.Empty() {
+		return fmt.Errorf("restic forget: refusing to run with empty retention policy (would delete every snapshot)")
+	}
+	args := append([]string{"forget", "--json"}, policy.args()...)
+	cmd := exec.CommandContext(ctx, e.Bin, args...)
+	cmd.Env = e.envSlice()
+	cmd.Dir = e.WorkDir
+
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		return fmt.Errorf("restic forget: stdout pipe: %w", err)
+	}
+	stderr, err := cmd.StderrPipe()
+	if err != nil {
+		return fmt.Errorf("restic forget: stderr pipe: %w", err)
+	}
+
+	if err := cmd.Start(); err != nil {
+		return fmt.Errorf("restic forget: start: %w", err)
+	}
+
+	done := make(chan error, 2)
+	go func() { done <- pumpPlain(stdout, "stdout", handle) }()
+	go func() { done <- pumpPlain(stderr, "stderr", handle) }()
+	for i := 0; i < 2; i++ {
+		if err := <-done; err != nil && handle != nil {
+			handle("event", fmt.Sprintf("pump error: %v", err), nil)
+		}
+	}
+	if werr := cmd.Wait(); werr != nil {
+		return fmt.Errorf("restic forget: %w", werr)
+	}
+	return nil
+}
+
 // RunInit executes `restic init` against the configured repo. Returns
 // nil on success. Restic init's output is small and not JSON-rich;
 // we tee stdout/stderr verbatim through handle so the operator sees

internal/server/http/schedule_push.go

@@ -187,6 +187,21 @@ func (s *Server) dispatchScheduleNow(ctx context.Context, hostID, scheduleID str
 		args = append(args, sched.Paths...)
 	}
 
+	// forget jobs need the retention policy on the wire — restic
+	// refuses to run without keep-* flags, and the agent doesn't
+	// hold a copy of the schedule (server is the source of truth).
+	var retentionJSON json.RawMessage
+	if sched.Kind == string(api.JobForget) {
+		if sched.RetentionPolicy == (store.RetentionPolicy{}) {
+			return "", errFmtf("schedule has no retention policy — refusing to forget (would delete every snapshot)")
+		}
+		b, err := json.Marshal(sched.RetentionPolicy)
+		if err != nil {
+			return "", errFmtf("marshal retention policy: %s", err)
+		}
+		retentionJSON = b
+	}
+
 	jobID := ulid.Make().String()
 	now := time.Now().UTC()
 	if err := s.deps.Store.CreateJob(ctx, store.Job{
@@ -202,9 +217,10 @@ func (s *Server) dispatchScheduleNow(ctx context.Context, hostID, scheduleID str
 	}
 
 	env, err := api.Marshal(api.MsgCommandRun, jobID, api.CommandRunPayload{
-		JobID: jobID,
-		Kind:  api.JobKind(sched.Kind),
-		Args:  args,
+		JobID:           jobID,
+		Kind:            api.JobKind(sched.Kind),
+		Args:            args,
+		RetentionPolicy: retentionJSON,
 	})
 	if err != nil {
 		return "", errFmtf("marshal command.run: %s", err)

internal/server/http/schedules.go

@@ -268,6 +268,11 @@ func validateSchedule(s *scheduleAPI) (code, msg string) {
 	if s.Kind == api.JobBackup && len(s.Paths) == 0 {
 		return "missing_paths", "backup schedules require at least one path"
 	}
+	// forget needs at least one keep-* dimension; otherwise restic
+	// would happily delete every snapshot.
+	if s.Kind == api.JobForget && (s.RetentionPolicy == store.RetentionPolicy{}) {
+		return "missing_retention", "forget schedules require at least one Keep-* value"
+	}
 	// Hooks are only meaningful on backup schedules (spec §14.3).
 	if s.Kind != api.JobBackup && (s.PreHook != "" || s.PostHook != "") {
 		return "hooks_not_allowed", "pre_hook / post_hook only apply to backup schedules"

internal/server/http/ui_schedules.go

@@ -34,6 +34,9 @@ type scheduleEditPage struct {
 	IsNew         bool
 	ScheduleID    string
 	Error         string
+	// Kind is settable on create, immutable on edit. The form's
+	// kind picker is hidden when !IsNew.
+	Kind          string
 	// Form values — strings so partial input survives validation
 	// errors (e.g. operator typed "abc" into keep_last).
 	CronExpr      string
@@ -110,6 +113,7 @@ func (s *Server) handleUIScheduleNewGet(w stdhttp.ResponseWriter, r *stdhttp.Req
 	view.Page = scheduleEditPage{
 		Host:     *host,
 		IsNew:    true,
+		Kind:     string(api.JobBackup),
 		CronExpr: "0 3 * * *",
 		Enabled:  true,
 	}
@@ -147,6 +151,7 @@ func (s *Server) handleUIScheduleEditGet(w stdhttp.ResponseWriter, r *stdhttp.Re
 		Host:        *host,
 		IsNew:       false,
 		ScheduleID:  sched.ID,
+		Kind:        sched.Kind,
 		CronExpr:    sched.CronExpr,
 		PathsRaw:    strings.Join(sched.Paths, "\n"),
 		ExcludesRaw: strings.Join(sched.Excludes, "\n"),
@@ -202,6 +207,7 @@ func (s *Server) handleUIScheduleSave(w stdhttp.ResponseWriter, r *stdhttp.Reque
 		Host:          *host,
 		IsNew:         scheduleID == "",
 		ScheduleID:    scheduleID,
+		Kind:          strings.TrimSpace(r.PostForm.Get("kind")),
 		CronExpr:      strings.TrimSpace(r.PostForm.Get("cron_expr")),
 		PathsRaw:      r.PostForm.Get("paths"),
 		ExcludesRaw:   r.PostForm.Get("excludes"),
@@ -217,6 +223,16 @@ func (s *Server) handleUIScheduleSave(w stdhttp.ResponseWriter, r *stdhttp.Reque
 		Enabled:       r.PostForm.Get("enabled") == "on",
 		Manual:        r.PostForm.Get("manual") == "on",
 	}
+	// Kind is immutable on edit — use the existing schedule's kind
+	// regardless of what the form submitted.
+	if !page.IsNew {
+		if existing, err := s.deps.Store.GetSchedule(r.Context(), hostID, scheduleID); err == nil {
+			page.Kind = existing.Kind
+		}
+	}
+	if page.Kind == "" {
+		page.Kind = string(api.JobBackup)
+	}
 
 	// Convert the raw form values into store-shape data, surfacing
 	// the first parse error as a banner.
@@ -238,13 +254,16 @@ func (s *Server) handleUIScheduleSave(w stdhttp.ResponseWriter, r *stdhttp.Reque
 	}
 
 	// Validate against the same rules the JSON API uses. Manual
-	// schedules skip the cron-expr requirement; everything else
-	// applies the same.
+	// schedules skip the cron-expr requirement; forget schedules
+	// require a non-empty retention policy. Other validation
+	// (kind in allowed set, paths required for backup, hooks
+	// rejected on non-backup) lives in validateSchedule.
 	apiShape := scheduleAPI{
-		Kind:     api.JobBackup,
-		CronExpr: page.CronExpr,
-		Paths:    paths,
-		Manual:   page.Manual,
+		Kind:            api.JobKind(page.Kind),
+		CronExpr:        page.CronExpr,
+		Paths:           paths,
+		Manual:          page.Manual,
+		RetentionPolicy: retention,
 	}
 	if code, msg := validateSchedule(&apiShape); code != "" {
 		page.Error = uiErrorMessage(code, msg)
@@ -256,7 +275,7 @@ func (s *Server) handleUIScheduleSave(w stdhttp.ResponseWriter, r *stdhttp.Reque
 		row := store.Schedule{
 			ID:              ulid.Make().String(),
 			HostID:          hostID,
-			Kind:            string(api.JobBackup),
+			Kind:            page.Kind,
 			CronExpr:        page.CronExpr,
 			Paths:           paths,
 			Excludes:        excludes,
@@ -500,6 +519,8 @@ func uiErrorMessage(code, msg string) string {
 		return "Cron expression doesn't parse: " + msg
 	case "missing_paths":
 		return "At least one backup path is required (one per line)."
+	case "missing_retention":
+		return "Forget schedules need at least one Keep-* value, otherwise restic would delete every snapshot."
 	case "invalid_kind":
 		return "Unsupported schedule kind."
 	default: