How no-mistakes Handles Worktree Cleanup with Pending or Running Runs

The no-mistakes daemon guarantees that git worktrees are never deleted while their associated runs are in pending or running status by querying the SQLite database before removing any filesystem artifacts during startup.

The kunchenguid/no-mistakes orchestration tool defends against data loss through a defensive cleanup strategy implemented in internal/daemon/daemon.go. When the daemon initializes, it executes a targeted scan of the worktree directory while cross-referencing run states to ensure active pipelines remain intact. This article examines the cleanupOrphanWorktrees function and explains how the system distinguishes between abandoned directories and those belonging to active executions.

The Cleanup Safety Mechanism

The safety mechanism centers on the cleanupOrphanWorktrees function invoked during every daemon startup. This routine targets the <NM_HOME>/worktrees directory, where each run maintains an isolated git checkout.

For every subdirectory present, the daemon retrieves the corresponding run record from the database using db.GetRunByID. If the run's Status field indicates pending or running, the worktree is preserved regardless of age or previous daemon crashes. Only worktrees associated with terminal states—such as succeeded, failed, or cancelled—or those with missing database entries are considered orphaned and eligible for deletion.

Implementation in internal/daemon/daemon.go

The core logic resides in internal/daemon/daemon.go, where the cleanup routine runs immediately after database and path initialization.

Startup Invocation

The daemon calls cleanupOrphanWorktrees before accepting new work to ensure the filesystem is in a known state:

// Called during daemon start-up
cleanupOrphanWorktrees(d, p)               // https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/daemon.go#L288

This early execution prevents accumulation of stale directories from previous crashes while safeguarding any runs that were interrupted mid-execution.

The Safety Guard

The explicit safety guarantee is documented directly in the source code alongside the status check logic:

// worktree is never removed while its run is still pending or running
// – this protects active runs from accidental cleanup.               // https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/daemon.go#L346

This comment precedes the conditional logic that filters the worktree list based on the run's current state in the database.

Database-Driven Decisions

The daemon relies on internal/db/run.go to provide the Run model and its Status field. The cleanup logic evaluates this field to categorize worktrees:

• Kept: pending, running
• Removed: succeeded, failed, cancelled, or missing records

This database-centric approach ensures that filesystem operations are always grounded in the authoritative state of the run scheduler.

Directory Structure and Path Resolution

The internal/paths/paths.go module provides the WorktreeDir helper function that constructs the absolute path to each run's working directory. The cleanup routine uses these paths to correlate filesystem entries with database records, ensuring that the correct directories are targeted for removal based on their associated run IDs.

Testing the Cleanup Behavior

The safety guarantee is enforced by integration tests in internal/daemon/startup_recovery_test.go. These tests verify that:

1. Worktrees for pending runs survive daemon restarts.
2. Worktrees for running runs are preserved even if the process crashes.
3. Only orphaned worktrees with terminal or missing states are actually deleted from disk.

Summary

• No-mistakes defers worktree deletion until runs reach a terminal state, preventing accidental loss of active code.
• The cleanupOrphanWorktrees function in internal/daemon/daemon.go implements this safety check during every daemon startup at line 288.
• Database lookups via db.GetRunByID determine whether a worktree is active or orphaned before any filesystem removal occurs.
• Worktrees in pending or running status are explicitly protected by the safety guard at line 346.
• Integration tests in startup_recovery_test.go validate that active runs survive cleanup operations across restarts.

Frequently Asked Questions

What prevents no-mistakes from deleting a worktree while a job is running?

The daemon queries the SQLite database for each run's status before deleting its worktree directory. If the status is running or pending, the cleanup routine skips that directory entirely. This check occurs in cleanupOrphanWorktrees inside internal/daemon/daemon.go.

When does the cleanupOrphanWorktrees function run?

It executes during daemon initialization, immediately after the database and filesystem paths are established. This startup cleanup ensures that worktrees from previous crashes are reclaimed before new runs begin, without interfering with any runs that were mid-execution when the daemon stopped.

How does no-mistakes distinguish between an orphaned worktree and an active one?

The daemon uses the run ID encoded in the worktree directory name to query the Run table via internal/db/run.go. If the record shows a terminal status (succeeded, failed, or cancelled) or no record exists, the worktree is considered orphaned and deleted. Active states (pending, running) trigger a skip.

Where are the integration tests for this cleanup behavior?

The safety logic is tested in internal/daemon/startup_recovery_test.go, which verifies that worktrees for pending and running runs persist across daemon restarts while orphaned worktrees are properly removed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}