Safe cleanup wall-clock budget is discarded on the dry-run path (10s budget produces a 104s run)

[chubes4]

Problem

workspace cleanup safe --dry-run ignores its wall-clock budget. An explicit
10-second budget produces a ~104-second run:

$ time studio wp datamachine-code workspace cleanup safe --dry-run --until-budget=10s
safe dry-run with 10s budget: 103866 ms

WP-CLI/Studio bootstrap is not the cause — a trivial wp option get siteurl
on the same install costs 4.4s.

WorkspaceSafeCleanupOrchestrator::DEFAULT_BUDGET is 45s, so even the
unspecified default is overrun by ~2.7x.

Root cause

The budget is computed and plumbed, then dropped on the only stage the safe
dry-run actually runs.

WorkspaceCleanupPlan::workspace_cleanup_plan() resolves until_budget
(WorkspaceCleanupPlan.php:48) and forwards it to the worktree branch
only:

// WorkspaceCleanupPlan.php:96 — worktree branch receives the budget
$worktree_args['until_budget'] = $inputs['until_budget'];

The artifact branch never receives it (WorkspaceCleanupPlan.php:61-73):

$artifact_plan = $this->worktree_cleanup_artifacts( array(
    'dry_run'        => true,
    'force'          => $inputs['force_artifact_cleanup'],
    'full_workspace' => $inputs['full_workspace'],
    'limit'          => $inputs['limit'],
    'offset'         => $inputs['offset'],
    'sort'           => $inputs['artifact_sort'],
    'older_than'     => $inputs['worktree_older_than'],
    // no 'until_budget'
) );

WorkspaceArtifactCleanup::worktree_cleanup_artifacts() has no wall-clock
budget parameter at all — its documented $opts are dry_run, force, allow_active_artifact_cleanup, allow_unavailable_process_probe, apply_plan, limit, offset, exhaustive, safety_probes, older_than, only_handles. It is
bounded only by limit.

The safe dry-run then disables the one branch that honors the budget.
WorkspaceSafeCleanupOrchestrator.php:167-173:

$artifact_input = $dry_run ? array(
    'mode'              => 'artifacts',
    'include_artifacts' => true,
    'include_worktrees' => false,   // the budgeted branch is off
    'limit'             => $limit,
) : ...

So on the safe dry-run path, 100% of the resolved budget is discarded. The
orchestrator's own pre-stage checks (budget_partial_result()) still work, but
they only gate between stages — they cannot bound a stage that runs long.

Impact

• --until-budget is inert on the documented safe-cleanup preview path.
• The operation cannot be used as a bounded, resumable preview as designed.
• Callers that budget around it are terminated mid-inventory. Homeboy's
  worktree-provider cleanup delegates here and reports
  inventory_completeness: partial with 0 reclaimable bytes on every run,
  while a direct DMC cleanup on the same workspace reclaimed ~147 GiB across
  93 worktrees.

Measured stage costs

Timed individually against this workspace (~300 worktrees):

stage	budget	wall clock
worktree locks --prune-stale --dry-run	n/a	2.9s
bounded-cleanup-eligible-apply --dry-run	5s	3.2s (honored)
cleanup-artifacts --dry-run --limit=25	n/a	3.5s
cleanup safe --dry-run	10s	103.9s

The individually-timed stages are all cheap, so the ~104s is not yet
attributed to a single stage. Note the low-level cleanup plan --mode=artifacts
CLI defaults (limit=100, include_worktrees=true) differ from the
orchestrator's inputs (limit=25, include_worktrees=false), so that command
is not a faithful proxy — per-stage timing evidence from the orchestrator
itself is still needed to attribute the remaining time.

Acceptance criteria

• worktree_cleanup_artifacts() accepts and enforces a wall-clock budget.
• workspace_cleanup_plan() forwards until_budget to the artifact branch.
• cleanup safe --dry-run --until-budget=<d> returns within <d> plus a
  bounded reporting margin, emitting a resumable continuation instead of
  overrunning.
• Regression coverage asserts a short budget produces a short run and a
  continuation, rather than only asserting the option is accepted.
• Per-stage elapsed timing is reported in the run evidence so a future overrun
  is attributable without external timing.

---

AI assistance disclosure: investigated and written with Claude Sonnet 4.5 (Anthropic) driving OpenCode via the Kimaki Discord bridge. The model ran the timings above and traced the budget plumbing through the source; a human directed the work. An earlier hypothesis that sort=size forced a full-workspace scan was tested and disproven (3.5s), and is recorded here so it is not retried.

[chubes4]

Root cause for the remaining overrun is now attributed, and it is the same class as the artifact-scan bug fixed in #1281.

active_no_signal overruns its budget by ~1.5x

Measured against v0.72.8 with an explicit 10s budget:

stage	budget	elapsed	honors budget
artifact_plan	10s	10.85s	yes (fixed by #1281)
eligible_drain	10s	7.7s	yes
active_no_signal	10s	15.0s	no

Cause

WorkspaceActiveNoSignalCleanup::worktree_active_no_signal_report() stamps $started_at at entry, then runs a full-workspace inventory before the budgeted loop:

// limit 0 => entire workspace, unbudgeted
$inventory = $this->worktree_cleanup_inventory_only('', '', false, null, 0, ...);
$active    = array_filter( $inventory['skipped'], ... );
$page      = array_slice($active, $offset, $limit);   // only now bounded to 25

The row loop is budgeted via build_worktree_loop_budget_context() / is_worktree_loop_budget_exhausted(), but that gate sits after the expensive setup. By the time the first row is considered, the budget is already spent, so the loop breaks at $index === 0 and the call still returns having burned ~15s.

This is exactly the shape fixed in #1281: the budget gates the iteration, while the unbounded work happens before the loop.

Dead code

Lines 40-45 parse until_budget into $budget_seconds and never read it:

if ( isset($opts['until_budget']) && '' !== trim( (string) $opts['until_budget']) ) {
    $budget_seconds = $this->parse_worktree_metadata_reconciliation_budget(trim( (string) $opts['until_budget']));
    if ( is_wp_error($budget_seconds) ) { return $budget_seconds; }
}

$budget_seconds appears nowhere else in the file. build_worktree_loop_budget_context() re-reads $opts['until_budget'] itself, so this block only validates. It reads as enforcement and is not.

Suggested fix

• Budget the inventory step, or derive the candidate page without a full-workspace scan.
• Check the budget immediately after inventory and return a bounded partial with a continuation rather than proceeding.
• Delete $budget_seconds, keeping the early validation only if it returns a distinct error.

Correction to earlier evidence

An earlier note in this issue implied active_no_signal cost ~45s. That measurement invoked the ability without until_budget, so no budget context was built. With a budget it is 15s. The 45s figure describes the unbudgeted path only and should not be used for sizing.

---

AI assistance disclosure: measured and written with Claude Sonnet 4.5 (Anthropic) driving OpenCode via the Kimaki Discord bridge. The model produced, then caught and corrected, the 45s measurement error noted above; a human directed the work.

[chubes4]

Status: the original defect is fixed; what remains is a bounded constant

Measured on origin/main (includes #1281 and #1283) against this ~300-worktree workspace, active-no-signal-drain:

budget	elapsed	overrun
3s	6.37s	+3.37s
10s	14.32s	+4.32s
20s	21.90s	+1.90s

The overrun is roughly constant, not proportional. Relative overrun falls from 112% at 3s to 9.5% at 20s. This is a fixed setup cost sitting outside the budget window, not an unbounded scan.

For contrast, the defect as originally filed:

	10s budget
originally reported	~104s (budget had no effect at all)
now	14.3s

Where the remaining cost is

The per-entry filesystem loop in build_workspace_inventory_snapshot() is budget-aware — it checks $budget->expired() before each entry and again every 25 entries, recording partial, next_entry, and budget_exhaustion_reason.

What is not inside that window:

• worktree_inventory()->list() (WorkspaceHygieneReport.php:547) runs in full unless the budget is already expired when it is reached. It is a single DB read, so it is bounded, but it is not interruptible.
• scandir() plus sort($entries, SORT_NATURAL) over the workspace directory.
• Post-snapshot classification in worktree_cleanup_inventory_only(), which walks the returned rows after the budgeted loop has stopped.

Together these form the constant tail. Each is bounded work; none of them can currently observe the budget.

Recommendation

I am not shipping a change for this on the current evidence, because the remaining behaviour is a design question rather than a bug:

• Making the DB snapshot and post-snapshot classification budget-aware is genuine surgery on shared inventory code used well beyond this path.
• The payoff is capping a ~2-4s constant, on an operation whose default budget is 45s. At realistic budgets the overrun is already under 10%.
• A caller that needs a hard ceiling can set its budget below the target and absorb the constant, which is the same arithmetic Homeboy now applies for provider timeouts.

Suggested disposition: downscope this issue to "inventory setup cost is outside the budget window", keep it open as a known bound rather than a defect, and revisit only if a caller needs sub-5s determinism from this path.

The original symptom that motivated the issue — the safe cleanup preview being effectively unbounded and starving Homeboy's provider — is resolved by #1281 and #1283.

---

AI assistance disclosure: measured and written with Claude Sonnet 4.5 (Anthropic) driving OpenCode via the Kimaki Discord bridge. The model ran the budget sweep above against a temporarily patched copy of the deployed plugin and restored it byte-identical afterward. The recommendation not to change code here is the model's, offered for a human decision rather than acted on.

[chubes4]

Corrected measurement: budgets made these stages bounded, not fast

Deployed v0.72.12 (contains #1281, #1283, #1284, #1287) and re-measured. My prediction that this would cut the preview from ~75s to ~35s was wrong — the provider run went 75.9s to 82.5s.

Per-stage on v0.72.12, each handed a 45s budget:

stage	elapsed
artifact_plan	48.6s
active_no_signal	47.7s
eligible_drain	6.2s
inventory_prune_missing	0.001s

Both expensive stages now run to their budget rather than ignoring it. Earlier readings of ~45s and ~30s that I attributed to "unbudgeted" behaviour were close to the budgeted cost all along: the work was always there, and the budget only decides where it stops. The signal was already visible in the 10s→14s and 20s→22s sweep, where the stage tracked the budget instead of finishing early, and I read it as overrun instead of saturation.

So the budget fixes delivered boundedness, which is what they were for. None of them reduced work, and none of them could.

The binding constraint

Both expensive stages independently rebuild the entire workspace inventory:

• WorkspaceArtifactCleanup.php:464 → build_workspace_inventory_rows()
• WorkspaceWorktreeInventoryCleanup.php:56 → build_workspace_inventory_rows($budget)

One preview therefore performs scandir, sort, lifecycle-metadata read, and per-entry classification across ~300 worktrees more than once. worktree_cleanup_inventory_only() already declares $inventory_rows_override — "Optional pre-read inventory rows" — and no call site passes it.

Attempted and rejected: transparent request-local memoization

I implemented a request-local snapshot cache mirroring the existing artifact_process_path_snapshot pattern, caching only non-partial snapshots with a $fresh bypass.

It regressed two tests and the reason is worth recording:

tests/workspace-hygiene-bounded-inventory.php
RuntimeException: A slow inventory must return bounded partial rows.

A cached complete snapshot is strictly more data than a bounded partial one, so serving it looks harmless — but it silently voids the bounded-partial contract a budgeted caller depends on. tests/workspace-command-startup-bounds.php additionally passed standalone while failing in-suite, because the cache leaked across tests sharing one process.

Both are correct objections. Re-baselining them would have traded a measurable speedup for a quietly weakened guarantee, so the change was reverted rather than landed.

Correct direction

Share the snapshot explicitly, not transparently: read the inventory once in the orchestrator and thread it through $inventory_rows_override. Each stage then receives rows it can see and reason about, the bounded-partial contract stays a property of the read that actually performed the work, and no caller silently receives evidence produced under a different budget.

That is what the existing unused parameter was designed for. It requires touching the orchestrator and both stage entry points, so it wants its own change rather than being appended to a session of small fixes.

---

AI assistance disclosure: measured and written with Claude Sonnet 4.5 (Anthropic) driving OpenCode via the Kimaki Discord bridge. The model made the wrong prediction recorded above, deployed and re-measured to disprove it, attempted the memoization approach, and reverted it when it regressed two bounded-inventory tests. A human directed the work.