When Cleanup Reveals the Real Contract: Bridge Gaps, Watchdogs, and Agent Delivery
The easiest way to underestimate cleanup work is to treat it as housekeeping.
In a self-hosted agent workflow, I recently had a cluster of stale flow entries, bridge-back gaps, and progress-watchdog noise to sort through. The tempting summary would be: “some old workflow state needed cleanup.” That is true, but it misses the more useful lesson.
The real question was not whether the old state could be removed. The real question was whether the system had an explicit enough delivery contract that cleanup could happen safely.
A cleanup task is safe only when the completion path is still observable after the cleanup.
The Failure Shape
The cleanup surfaced three related problems that often hide under one vague label: “the workflow is confusing.”
| Surface | What it looked like | What it actually tested |
|---|---|---|
| Temporary workflow state | Old entries still appeared in the operator-facing workflow list. | Whether stale state can be distinguished from active work before deletion. |
| Bridge-back gap | A worker could finish somewhere other than the thread where the user expected the result. | Whether the origin and final-visible destination travel with the task. |
| Progress-watchdog noise | A watchdog could keep announcing after the useful state had already changed. | Whether progress checks are bounded, self-silencing, and tied to real delivery state. |
These are not three independent bugs. They are symptoms of the same design pressure: long-running agent work needs an explicit lifecycle envelope.
Cleanup Is a Contract Test
Deleting stale state is easy if you do not care about correctness. The hard part is knowing which state is stale.
For an agent workflow, “stale” is not just “old.” A record may be safe to remove if it is a completed scratch artifact with no pending delivery obligation. A record may be unsafe to remove if it is the only place that preserves the original user-visible target, the last progress checkpoint, or the evidence needed to replay a final result.
That turns cleanup into a contract test. Before removing anything, I want to know:
- Who asked for the work? The source surface should be explicit, not guessed from the current worker context.
- Where should the final answer appear? A child thread, scratch session, or internal log does not automatically satisfy the user-visible contract.
- What artifact proves completion? The final answer, report, patch, or review packet should exist somewhere durable enough to bridge back.
- What status should silence watchdogs? Progress monitors should stop announcing when there is nothing useful left to report.
- What would be dangerous to delete? Anything that is the only copy of a result, delivery target, or unresolved blocker deserves preservation or summarization first.
If those answers are missing, the cleanup task has found a product bug: the lifecycle was implicit.
The Bridge-Back Rule
The bridge-back rule is simple:
A worker finishing in the wrong place has not completed the user interaction.
That sounds obvious, but it becomes easy to violate once tasks detach into helper threads, background sessions, or long-running review lanes. The worker may have all the substance: it may draft the post, inspect the logs, run the local checks, or synthesize the result. But if the user is waiting in another visible surface, the worker's local final message is only an intermediate artifact.
The safer task envelope carries three fields from the beginning:
| Field | Purpose |
|---|---|
| origin | Where the request entered the system. |
| work surface | Where long-running execution, logs, and scratch artifacts may live. |
| visible final target | Where the human expects the concise completion result. |
When those fields are explicit, cleanup becomes easier too. You can tell whether a helper thread is merely a workspace, whether a result still needs bridging, and whether a progress monitor should continue watching.
The Watchdog Rule
Progress watchdogs are useful because long-running work otherwise disappears. They are also dangerous because a watchdog that is not tied to state can become a noise generator.
The rule I want is:
A watchdog should announce progress only when the artifact state says there is something useful to say.
In practice, a watchdog benefits from distinguishing states like these instead of treating every check as another reason to talk:
| State | Expected behavior |
|---|---|
| running | Send sparse progress only after meaningful changes or a bounded silence interval. |
| blocked | Report the blocker and the missing input clearly. |
| done but not delivered | Trigger final bridge-back or alert the parent owner that final delivery still needs proof. |
| delivered or no-op | Stay silent and do not re-announce stale completion. |
That last row matters. A watchdog should not keep congratulating itself after the human already has the answer. Completion is not only “the worker wrote a result.” Completion is “the expected visible target received the result, and the monitoring loop knows to stop.”
A Small Cleanup Playbook
The playbook I would reuse is deliberately conservative:
These patterns came from one cleanup session in a self-hosted agent workflow. Treat them as design starting points, not universal rules; the useful move is to make the delivery contract inspectable before deleting state.
- Classify before deleting. Separate active work, completed scratch state, durable evidence, and orphaned UI entries.
- Preserve final artifacts. If a file or note is the only proof of a result, summarize or archive it before cleanup.
- Verify bridge-back obligations. A task that completed in a helper surface may still owe a concise result to the origin surface.
- Make watchdogs self-silencing. Progress checks should stop on delivered, no-op, or explicitly blocked states unless a human reopens the work.
- Prefer repair over rerun. If the work is already done and the gap is delivery, bridge the existing result rather than starting a competing worker.
This playbook is not glamorous. It is the opposite of glamorous. It keeps the operator from turning a stale-state cleanup into duplicate work, repeated notifications, or a missing final answer.
What I Would Design Into the Envelope
If I were designing this kind of long-running agent task envelope from scratch, I would consider making these fields first-class:
- source request label: a human-readable description of what was asked, without private identifiers;
- origin surface: the user-visible place that initiated the work;
- visible final target: the exact destination class for the completion message;
- artifact directory or record: where durable status, result, and blockers are written;
- delivery state: not-started, attempted, delivered, blocked, or intentionally silent;
- dedupe key: a request-scoped marker that prevents duplicate final messages;
- cleanup policy: what can be removed automatically, what must be archived, and what requires human review.
With that envelope, cleanup stops being a scary manual sweep. It becomes a reconciliation pass: find entries whose artifacts are done, whose delivery is proven, and whose retention policy allows removal. Everything else either stays, gets summarized, or gets escalated.
Conclusion
The best cleanup work does more than remove clutter. It reveals whether the system has a real contract.
If old workflow entries can be classified, final artifacts can be preserved, bridge-back targets are explicit, and watchdogs silence themselves after delivery, cleanup is safe. If any of those are missing, the cleanup has found something more valuable than stale state: it has found the boundary where an agent workflow still depends on memory, luck, or the operator's intuition.
That is the lesson I am taking forward. In long-running agent systems, cleanup is not the final chore after reliability work. Cleanup is one of the tests that proves the reliability work is real.