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

> Explore the no-mistakes background daemon architecture. Learn how this Go process coordinates CI pipelines using file locks RPC and a SQLite database.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: architecture
- Published: 2026-07-14

---

**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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/lock.go). Before initializing any network resources, the daemon acquires a lock on `<NM_HOME>/daemon.lock` using the `lockfile` package.

```go
// 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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/ipc/client.go):

```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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run.go) **before** creating the associated worktree.

```go
// 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`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) file at a pinned SHA from the upstream default branch through [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/daemon_cmd.go). This entrypoint parses command-line options and delegates to [`internal/daemon/daemon.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/daemon.go), which contains the core event loop coordinating lock acquisition, IPC server startup, and run dispatching.

```go
// 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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) from the default branch at a pinned SHA through [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/stats.go) package manages aggregation of historical execution data for status reporting.