How the no-mistakes Background Daemon Works: Architecture and Implementation

TLDR: The no-mistakes background daemon is a singleton Go process that coordinates CI pipelines by acquiring an OS-level file lock, serving RPC via Unix domain sockets, and managing run lifecycles through a SQLite database.

The kunchenguid/no-mistakes repository implements a background daemon that acts as the central nervous system for local CI-like workflows. Written in Go, this long-running process coordinates pipeline executions, enforces security gates, and manages agent interactions through a combination of OS-level primitives and database transactions.

Singleton Lock and Process Coordination

The daemon guarantees single-instance operation through an exclusive OS file lock implemented in internal/daemon/lock.go. Before initializing any network resources, the daemon acquires a lock on <NM_HOME>/daemon.lock using the lockfile package.

// Acquiring the singleton lock (internal/daemon/lock.go)
lock, err := lockfile.New(filepath.Join(nmHome, "daemon.lock"))
if err != nil { return err }
if err := lock.Lock(); err != nil { return err }
defer lock.Unlock()

This lock prevents race conditions where a second daemon process might steal the IPC socket or corrupt shared state. If the lock file is already held, the daemon exits immediately with an appropriate error code.

Inter-Process Communication Architecture

After securing the lock, the daemon initializes its IPC channel in internal/ipc/server.go. The implementation uses Unix-domain sockets on Linux and macOS, falling back to Windows named pipes on Windows systems.

The socket is created only after the lock acquisition succeeds, ensuring no other process can bind to the address. Client commands communicate with the daemon through this socket using a simple RPC protocol defined in internal/ipc/client.go:

// Client-side RPC to submit a run (internal/ipc/client.go)
client := ipc.NewClient(socketPath)
resp, err := client.StartRun(ctx, request)

Run Lifecycle and Database Safety

The daemon manages pipeline runs through a strict ordering guarantee implemented in internal/daemon/manager.go. When a new run starts, the daemon first inserts a row into the SQLite runs table defined in internal/db/run.go before creating the associated worktree.

// Creating a new run (internal/daemon/manager.go)
runID, err := db.InsertRun(ctx, runMeta) // inserts row first
if err != nil { return err }
if err := worktree.Create(runID); err != nil { /* cleanup if needed */ }

This transaction ordering ensures the daemon never removes a worktree for a run that is still pending or active, preventing data loss and orphaned processes.

Trusted Configuration Loading

Security-critical operations rely on trusted configuration loaded from the repository's default branch. Unlike the CLI which might read local uncommitted changes, the daemon fetches the .no-mistakes.yaml file at a pinned SHA from the upstream default branch through internal/daemon/manager.go.

Only this trusted configuration can enable privileged commands via the allow_repo_commands field. This prevents malicious local configuration changes from executing arbitrary code through the daemon.

Command Execution and Resource Management

All configurable steps (commands.test, commands.lint, etc.) execute through helpers in internal/shellenv/shellenv.go. The implementation attaches a cancellable context to each subprocess and enforces a 5-second wait-delay backstop to prevent resource leaks.

On Windows, the daemon passes processes through winproc.Harden to ensure proper process tree cleanup, preventing orphaned grandchildren from consuming system resources after pipeline completion.

Lifecycle Guards and Graceful Shutdown

The internal/lifecycle/guard.go module implements safety checks for lifecycle commands like daemon stop and daemon restart. Before terminating, the daemon queries for active runs and refuses shutdown unless the --force flag is supplied.

This guard protects in-flight pipelines from accidental interruption, ensuring that long-running tests or deployments complete normally unless explicitly overridden.

Observability and Telemetry

Runtime metrics and execution statistics persist to <NM_HOME>/telemetry-gate.json and log files under <NM_HOME>/logs. The internal/db/stats.go package handles aggregation of run durations, success rates, and resource utilization, enabling commands like no-mistakes stats to report historical performance without recalculating from scratch.

CLI Entrypoint and Core Daemon Loop

The no-mistakes daemon run subcommand is implemented in internal/cli/daemon_cmd.go. This entrypoint parses command-line options and delegates to internal/daemon/daemon.go, which contains the core event loop coordinating lock acquisition, IPC server startup, and run dispatching.

// Starting the daemon (internal/cli/daemon_cmd.go)
if err := daemon.RunWithOptions(ctx, opts); err != nil {
    log.Fatalf("daemon failed: %v", err)
}

Summary

• The no-mistakes background daemon uses an OS-level file lock in internal/daemon/lock.go to enforce singleton operation across the workspace.
• IPC communication proceeds through Unix-domain sockets or Windows named pipes after lock acquisition, ensuring exclusive access to the socket address.
• Run safety is guaranteed by inserting database records before creating worktrees, preventing cleanup of active runs.
• Security relies on trusted configuration loaded from the default branch SHA, blocking unprivileged local configuration changes.
• Resource management uses cancellable contexts and platform-specific process hardening to prevent orphaned subprocesses.
• Lifecycle guards in internal/lifecycle/guard.go protect active pipelines from accidental shutdown.

Frequently Asked Questions

How does the daemon prevent multiple instances from running?

The daemon acquires an exclusive OS file lock on <NM_HOME>/daemon.lock using the implementation in internal/daemon/lock.go. If another daemon process holds this lock, the new instance exits immediately, preventing socket binding conflicts and state corruption.

What happens if I try to stop the daemon while pipelines are running?

The internal/lifecycle/guard.go module checks for active runs before allowing shutdown. If any runs are in progress, the daemon stop command fails unless you provide the --force flag, protecting in-flight CI pipelines from accidental interruption.

How does the daemon ensure configuration security?

Unlike the CLI which reads local working directory files, the daemon loads .no-mistakes.yaml from the default branch at a pinned SHA through internal/daemon/manager.go. Only this trusted configuration can enable privileged operations like allow_repo_commands, preventing execution of malicious local configuration changes.

Where does the daemon store run metadata and logs?

Run metadata persists to a SQLite database with schema definitions in internal/db/run.go, while logs and telemetry write to <NM_HOME>/logs and <NM_HOME>/telemetry-gate.json respectively. The internal/db/stats.go package manages aggregation of historical execution data for status reporting.

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