Work Directories and Cleanup
Understand Agent task work directories, Worktree cleanup at task exit, and periodic garbage collection.
Work Directories and Cleanup
The daemon prepares Agent task directories under MOPHEUS_WORKDIR. A directory can contain provider state, skills, runtime configuration, durable event and usage queues, and Git worktrees created through mopheus repo checkout.
Two independent paths clean these directories: immediate cleanup when a task exits, and periodic TTL-based garbage collection.
Task-Exit Cleanup
| Phase | Applies to | Contents |
|---|---|---|
| Forced cleanup | Every exit | Protocol, process, configuration staging, provider home, skills, and injected runtime-config markers. |
| Success cleanup | Server confirms Completed=true | Optional Worktree removal. |
| Final release | Every exit | Environment and repository references. |
Failures, cancellation, interruption, and unconfirmed completion do not trigger Worktree removal. Pending=true continues the same-session interaction flow; responses that are neither Completed nor Pending retain the terminal record for later confirmation.
Worktree Cleanup After Success
Worktrees are not removed immediately by default. Enable the following variable to force removal only after server-confirmed completion:
MOPHEUS_AGENT_TASK_CLEANUP_WORKTREE=trueThe variable accepts true or 1. Removal uses explicit force authorization and can discard uncommitted, untracked, or unpushed changes. Enable it only when those local changes are disposable.
The daemon removes a Worktree path from task GC metadata only after the Worktree has actually disappeared. Failed removal retains the metadata.
Periodic GC
GC is enabled automatically when MOPHEUS_WORKDIR is configured. The first sweep starts 90 seconds after daemon start, then runs at the configured interval. Use mopheus daemon disk-usage to inspect current disk usage.
| Variable | Default | Description |
|---|---|---|
MOPHEUS_GC_INTERVAL | 4h | Sweep interval. |
MOPHEUS_GC_TTL | 7 days | When a Ticket remains done, cancelled, or archived for this period, GC force-removes its entire task directory. |
MOPHEUS_GC_ORPHAN_TTL | 72h | Retention period for directories without metadata or an available server record. |
MOPHEUS_GC_ARTIFACT_TTL | 12h | Delay before removing regenerable directories such as node_modules, .next, and .turbo; 0 disables it. |
MOPHEUS_GC_ARTIFACT_PATTERNS | node_modules,.next,.turbo | Comma-separated regenerable directory basenames. |
GC retains non-terminal tickets and tickets in failed status. It also protects task directories with pending terminal reports. The TTL cleanup is a destructive, whole-directory removal, including any remaining Worktree contents. It is a capacity-reclamation mechanism, not a replacement for task-exit cleanup. Enabling immediate Worktree cleanup does not change GC TTLs, intervals, or orphan handling.
Local worktree registry
The daemon records each managed worktree atomically in <bare>.git.metadata/worktrees/, alongside (and never inside) the existing <bare>.git.codegraph-cache/. Listing and pruning use these local records and Git state, so they continue to work after database records or task directories are removed.
Use mopheus repo worktree list --ticket <uuid>, --task <uuid>, or --untracked --repo <url>. Records reconcile to active, missing, drifted, and untracked states. Use mopheus repo worktree prune with a ticket/task selector for managed records; untracked pruning requires --repo and explicit --force. Dirty, unpushed, or drifted managed worktrees are protected unless forced. Use --workspace <uuid> to narrow untracked scans; without it, ambiguous multi-workspace prune is rejected without changes. -o table is human-readable and -o json is pure JSON. Missing records remain visible until pruned, and deleting a bare repository removes all three .git, .git.metadata, and .git.codegraph-cache siblings.