fix(cleanup): resolve every cleanup entry point through one retention policy (#10562)

Cleanup is reachable through an aggregate planner and a set of category
specialists. Every one of them is a delete path, and every one of them
used to carry its own `default_value_t` retention literal.

Those literals happened to equal the shipped configuration defaults,
which made the drift invisible: the moment an operator widened
`retention.runtime_tmp_days` to 30, `homeboy self cleanup-runtime-tmp
--apply` still deleted at 7 days while `homeboy cleanup --include
runtime-tmp` honored the configuration. Same shape for `runs retention`
and `runs artifact cleanup-persisted` against `retention.terminal_run_days`
and `retention.limit`. A configured retention window being silently
ignored by a delete path is fail-open.

Add `homeboy_core::cleanup::resolve_cleanup_policy`, following the
precedent `controller_runtime::resolve_cleanup_options` set in #10288.
`None` on a command flag now means "use the configured value" and is the
only way a specialist can answer. The resolved policy is the manifest
reported in output, so a report cannot describe a window the deletion
did not apply.

Fail-closed rules the resolver enforces:

- A negative window or non-positive limit is rejected on every entry
  point, including when it arrives from configuration rather than from
  an argument.
- `scan_limit()` converts the record budget with `unwrap_or(0)`. The CLI
  aggregate used `unwrap_or(usize::MAX)` in four places, which widens a
  delete budget when a conversion fails.
- The two runner age floors become one named constant instead of a
  literal `24` in the aggregate beside `default_value_t = 24` in each
  specialist. They stay per-invocation arguments rather than becoming
  configuration keys: both live on a remote host whose clock and
  in-flight uploads the controller cannot fully observe, so lowering
  them should not persist into every future sweep.
- `terminal_only` on persisted-artifact cleanup is documented as
  non-overridable. Releasing evidence for a run that is still executing,
  or whose state cannot be read, is data loss, not a preference.

Delete `homeboy runs retention`. It was the one specialist with no
narrowing argument left — its `--apply`, `--older-than-days`, and
`--limit` were exactly the aggregate's. Every other specialist survives
because it accepts a narrowing argument the aggregate cannot express
(`--run-id`, `--kind`, `--component`, `--prefix`, `--runner`,
`--passes`, `--cursor`) or is an explicit destructive escape hatch
(`runtime controller-prune --ignore-retention`). Folding those into
`--include`-scoped flags would put a dozen single-category flags on a
surface that sweeps thirteen categories.

Also account for the artifact root in `cleanup retained-storage`. It
accumulated from five sources and never called `artifacts::root()`, so
the one command whose purpose is "where did my disk go" was blind to the
product's primary output store. Persisted run artifacts, runner
downloads, and orphaned artifact bytes now contribute read-only plans,
and `safe_next_commands` names a reclaim command for each. Bytes a
planner would reclaim report `liveness: reclaimable` and are totalled
separately: "cleanup cannot free this" and "cleanup has not freed this
yet" are different answers and are never summed together. Unmeasured
sizes are reported as zero and never inferred.

Refs #10316

Co-authored-by: chubes-bot <266378653+homeboy-ci[bot]@users.noreply.github.com>

Author: chubes4

crates/homeboy-cli/src/commands/cleanup.rs

@@ -358,8 +358,10 @@ pub(super) enum RunnerCommand {
         apply: bool,
 
         /// Minimum slot age before an unselected slot is eligible.
-        #[arg(long, default_value_t = 24)]
-        min_age_hours: u64,
+        /// Defaults to the shared runner age floor
+        /// (`cleanup::RUNNER_MIN_AGE_HOURS`).
+        #[arg(long)]
+        min_age_hours: Option<u64>,
     },
     /// Execute a command on a configured runner. Use `homeboy runner exec [HOMEBOY_OPTIONS] <RUNNER> -- <COMMAND>...`.
     #[command(

crates/homeboy-cli/src/commands/runner/cli.rs

@@ -220,7 +220,10 @@ pub fn run(args: RunnerArgs) -> CmdResult<RunnerCommandOutput> {
             &runner_id,
             runner::RunnerBinaryCachePruneOptions {
                 apply,
-                min_age_hours,
+                // One named age floor shared with `homeboy cleanup --include
+                // runner-binary-caches` (#10316).
+                min_age_hours: min_age_hours
+                    .unwrap_or(homeboy::core::cleanup::RUNNER_MIN_AGE_HOURS),
             },
         )),
         RunnerCommand::Exec {

crates/homeboy-cli/src/commands/runner/dispatch.rs

@@ -1,6 +1,7 @@
 use clap::{Subcommand, ValueEnum};
 use serde::Serialize;
 
+use homeboy::core::cleanup;
 use homeboy::runner::runners::{
     self as runner, RunnerWorkspaceApplyOutput, RunnerWorkspaceListOutput,
     RunnerWorkspacePruneOutput, RunnerWorkspacePullOutput, RunnerWorkspaceSnapshotFilters,
@@ -128,12 +129,16 @@ pub(super) enum RunnerWorkspaceCommand {
         apply: bool,
 
         /// Minimum workspace age before it can be considered orphaned.
-        #[arg(long, default_value_t = 24)]
-        min_age_hours: u64,
+        /// Defaults to the shared runner age floor
+        /// (`cleanup::RUNNER_MIN_AGE_HOURS`).
+        #[arg(long)]
+        min_age_hours: Option<u64>,
 
-        /// Maximum number of orphan candidates to report or remove.
-        #[arg(long, default_value_t = 25)]
-        limit: usize,
+        /// Maximum number of orphan candidates to report or remove per pass.
+        /// Defaults to the shared page size
+        /// (`cleanup::RUNNER_WORKSPACE_PAGE_LIMIT`).
+        #[arg(long)]
+        limit: Option<usize>,
 
         /// Maximum apply passes to run. Each pass re-scans and removes at most --limit candidates.
         #[arg(long, default_value_t = 1)]
@@ -221,8 +226,11 @@ pub(super) fn run(command: RunnerWorkspaceCommand) -> CmdResult<RunnerWorkspaceO
             &runner_id,
             runner::RunnerWorkspacePruneOptions {
                 apply,
-                min_age_hours,
-                limit,
+                // One named age floor shared with `homeboy cleanup --include
+                // remote-lab-workspaces`, which used to carry its own literal
+                // `24` beside this command's `default_value_t = 24` (#10316).
+                min_age_hours: min_age_hours.unwrap_or(cleanup::RUNNER_MIN_AGE_HOURS),
+                limit: limit.unwrap_or(cleanup::RUNNER_WORKSPACE_PAGE_LIMIT),
                 passes,
                 cursor,
             },

crates/homeboy-cli/src/commands/runner/workspace/mod.rs

@@ -9,7 +9,7 @@ use super::types::{RunsArgs, RunsArtifactArgs, RunsArtifactCommand, RunsCommand,
 use super::CmdResult;
 use super::{
     bench, compare, distribution, dossier, drift, evidence, findings, fuzz_compare, handlers,
-    hotspots, latest, loop_sync, proof, query, reconcile, refs, resources, retention, watch,
+    hotspots, latest, loop_sync, proof, query, reconcile, refs, resources, watch,
 };
 
 impl RunsArgs {
@@ -172,7 +172,6 @@ pub fn run(args: RunsArgs) -> CmdResult<RunsOutput> {
         RunsCommand::FuzzCompare(args) => fuzz_compare::fuzz_compare_from_args(args),
         RunsCommand::Hotspots(args) => hotspots::runs_hotspots(args),
         RunsCommand::Reconcile(args) => reconcile::reconcile_runs(args),
-        RunsCommand::Retention(args) => retention::retain_terminal_runs(args),
         RunsCommand::Watch(args) => watch::watch_run(args),
         RunsCommand::Cancel { run_id } => handlers::cancel_run(&run_id),
         RunsCommand::Show {

crates/homeboy-cli/src/commands/runs/dispatch.rs

@@ -35,7 +35,6 @@ mod refs;
 mod remote;
 mod remote_artifact;
 mod resources;
-mod retention;
 #[cfg(test)]
 mod tests;
 mod types;
@@ -46,9 +45,7 @@ use super::CmdResult;
 // Public command-layer API consumed by routing, raw/json output, rig, and bench.
 pub use dispatch::{global_runner_error, run, run_markdown};
 pub use handlers::list_runs;
-pub use types::{
-    RunsArgs, RunsOutput, RunsRetentionArgs, RunsRetentionOutput, HOSTED_BLUEPRINT_VIEWER,
-};
+pub use types::{RunsArgs, RunsOutput, HOSTED_BLUEPRINT_VIEWER};
 
 // Intra-module re-exports so sibling submodules (and the test modules) can
 // reference shared items via `super::` without depending on each other's

crates/homeboy-cli/src/commands/runs/mod.rs

@@ -1,6 +1,7 @@
 use std::fs;
 use std::path::{Path, PathBuf};
 
+use homeboy::core::cleanup::{resolve_cleanup_policy, CleanupPolicyOverrides};
 use homeboy::core::observation::artifact_preview;
 use homeboy::core::observation::runs_service::{
     self, PersistedArtifactCleanupOptions, RunnerDownloadCleanupOptions,
@@ -445,22 +446,35 @@ pub fn cleanup_downloads(args: RunsArtifactCleanupDownloadsArgs) -> CmdResult<Ru
 }
 
 pub fn cleanup_persisted(args: RunsArtifactCleanupPersistedArgs) -> CmdResult<RunsOutput> {
+    // Same resolver as `homeboy cleanup --include persisted-run-artifacts`.
+    // The narrowing filters below (`--run-id`, `--kind`, `--type`,
+    // `--run-kind`, `--component`) are what keep this specialist alive; the
+    // retention window is not one of them (#10316).
+    let policy = resolve_cleanup_policy(CleanupPolicyOverrides {
+        terminal_run_days: args.older_than_days,
+        limit: args.limit,
+        ..CleanupPolicyOverrides::default()
+    })?;
     let outcome = runs_service::cleanup_persisted_artifacts(PersistedArtifactCleanupOptions {
         apply: args.apply,
-        older_than_days: args.older_than_days,
+        older_than_days: policy.terminal_run_days,
         run_id: args.run_id,
         kind: args.kind,
         artifact_type: args.artifact_type,
         run_kind: args.run_kind,
         component_id: args.component_id,
-        limit: args.limit,
+        limit: policy.limit,
+        // Never widened by an operator flag: releasing evidence for a run that
+        // is still executing, or whose state cannot be read, is a data-loss
+        // path, not a retention preference.
         terminal_only: true,
     })?;
 
     Ok((
         RunsOutput::ArtifactCleanupPersisted(RunsArtifactCleanupPersistedOutput {
             command: "runs.artifact.cleanup-persisted",
             dry_run: outcome.dry_run,
+            retention: policy,
             artifact_root: outcome.artifact_root.display().to_string(),
             older_than_days: outcome.older_than_days,
             inspected_count: outcome.totals.inspected_count,
@@ -1057,13 +1071,13 @@ mod tests {
             // active lease, even when the age threshold is zero.
             let active = cleanup_persisted(RunsArtifactCleanupPersistedArgs {
                 apply: true,
-                older_than_days: 0,
+                older_than_days: Some(0),
                 run_id: Some(run.id.clone()),
                 kind: None,
                 artifact_type: None,
                 run_kind: None,
                 component_id: None,
-                limit: 100,
+                limit: Some(100),
             })
             .expect("active cleanup")
             .0;
@@ -1081,13 +1095,13 @@ mod tests {
 
             let dry = cleanup_persisted(RunsArtifactCleanupPersistedArgs {
                 apply: false,
-                older_than_days: 0,
+                older_than_days: Some(0),
                 run_id: Some(run.id.clone()),
                 kind: None,
                 artifact_type: None,
                 run_kind: None,
                 component_id: None,
-                limit: 100,
+                limit: Some(100),
             })
             .expect("dry-run")
             .0;
@@ -1103,13 +1117,13 @@ mod tests {
 
             let applied = cleanup_persisted(RunsArtifactCleanupPersistedArgs {
                 apply: true,
-                older_than_days: 0,
+                older_than_days: Some(0),
                 run_id: Some(run.id.clone()),
                 kind: None,
                 artifact_type: None,
                 run_kind: None,
                 component_id: None,
-                limit: 100,
+                limit: Some(100),
             })
             .expect("apply")
             .0;

crates/homeboy-cli/src/commands/runs/remote_artifact.rs

@@ -11,6 +11,7 @@ use serde_json::Value;
 
 use homeboy::core::artifact_links::ArtifactViewerDescriptor;
 use homeboy::core::artifacts::{ArtifactPreviewEntrypoint, MatrixArtifactSummary};
+use homeboy::core::cleanup::CleanupPolicy;
 use homeboy::core::observation::evidence_report::DirectoryArtifactPublicationGuidance;
 use homeboy::core::observation::runs_service;
 use homeboy::core::observation::ArtifactRecord;
@@ -85,8 +86,6 @@ pub(super) enum RunsCommand {
     Hotspots(RunsHotspotsArgs),
     /// Mark orphaned running observation records stale
     Reconcile(RunsReconcileArgs),
-    /// Plan or apply bounded retention of terminal observation rows and dependent records
-    Retention(RunsRetentionArgs),
     /// Block and stream a run's status until it reaches a terminal state,
     /// exiting with a code that reflects pass/fail. Works for attached and
     /// detached/offloaded runs.
@@ -214,31 +213,6 @@ pub struct RunsListArgs {
     pub include_active_runner_jobs: bool,
 }
 
-#[derive(Args, Clone)]
-pub struct RunsRetentionArgs {
-    /// Delete the planned terminal rows. Without this flag, only reports the plan.
-    #[arg(long)]
-    pub apply: bool,
-    /// Only include terminal runs finished more than this many days ago.
-    #[arg(long, default_value_t = 30)]
-    pub older_than_days: i64,
-    /// Maximum terminal run rows to inspect and remove in one invocation.
-    #[arg(long, default_value_t = 1000)]
-    pub limit: i64,
-}
-
-#[derive(Serialize)]
-pub struct RunsRetentionOutput {
-    pub command: &'static str,
-    pub dry_run: bool,
-    pub older_than_days: i64,
-    pub candidate_run_ids: Vec<String>,
-    pub artifact_cleanup: Vec<runs_service::PersistedArtifactCleanupOutcome>,
-    pub lifecycle_directories: Vec<runs_service::TerminalRunLifecycleDirectory>,
-    pub skipped_run_ids: Vec<String>,
-    pub removed_run_count: usize,
-}
-
 #[derive(Serialize)]
 #[serde(tag = "variant", content = "payload", rename_all = "snake_case")]
 pub enum RunsOutput {
@@ -269,7 +243,6 @@ pub enum RunsOutput {
     FuzzCompare(FuzzCompareOutput),
     Hotspots(RunsHotspotsOutput),
     Reconcile(RunsReconcileOutput),
-    Retention(RunsRetentionOutput),
     Watch(RunsWatchOutput),
     Cancel(RunsCancelOutput),
     Export(RunsExportOutput),
@@ -767,8 +740,9 @@ pub struct RunsArtifactCleanupPersistedArgs {
     #[arg(long)]
     pub apply: bool,
     /// Only include artifacts older than this many days.
-    #[arg(long, default_value_t = 30)]
-    pub older_than_days: i64,
+    /// Defaults to the configured `retention.terminal_run_days`.
+    #[arg(long)]
+    pub older_than_days: Option<i64>,
     /// Limit cleanup to one run id.
     #[arg(long)]
     pub run_id: Option<String>,
@@ -785,14 +759,17 @@ pub struct RunsArtifactCleanupPersistedArgs {
     #[arg(long = "component")]
     pub component_id: Option<String>,
     /// Maximum artifact rows to inspect in one invocation.
-    #[arg(long, default_value_t = 1000)]
-    pub limit: i64,
+    /// Defaults to the configured `retention.limit`.
+    #[arg(long)]
+    pub limit: Option<i64>,
 }
 
 #[derive(Serialize)]
 pub struct RunsArtifactCleanupPersistedOutput {
     pub command: &'static str,
     pub dry_run: bool,
+    /// The resolved policy this invocation applied.
+    pub retention: CleanupPolicy,
     pub artifact_root: String,
     pub older_than_days: i64,
     pub inspected_count: usize,