P10 — Scheduled Housekeeper

Problem

Dependencies, generated files, stale worktrees, and local resources need care even when no human is actively coding.

Context

A workspace needs repeated housekeeping without an immortal agent session. An external scheduler or orchestrator owns the trigger and loop state; it invokes a bounded ws run against a managed repository or selected Runtime Resources.

Pattern

Have the external owner schedule a Housekeeper Agent Profile that creates bounded Runs with a narrow objective, evidence, and checkpoint. ws executes the supplied Task; it does not own schedules or retries.

Diagram

schedule → inspect → bounded change → validate → Candidate / report

Example

Weekly Run: from the workspace root, inspect stale worktrees, report active resources, and propose cleanup. A separate policy decides whether deletion is allowed; the ignored repos/ checkouts are never treated as disposable control repository files.

Trade-offs

Repeated Runs are restartable and observable. Scheduling adds operational state and requires idempotent tasks.

Failure modes

The housekeeper changes too much, repeats work after a timeout, or assumes a resource is abandoned without checking ownership.

Extension points

Cron, an external scheduler, a daemon, or a queue can trigger Runs.

When not to use

Do not schedule maintenance that has no stable validation or safe rollback path.