Scope the PID lock to mutating commands (closes #150)

RunWithApp took the process-wide PID lock for every fx-backed command, so read-only commands (info, snapshot list, snapshot verify, remote info) failed with "already running" while a backup held it.

AppOptions now carries a lockMode declared at each call site: only mutating commands (snapshot create, snapshot purge, snapshot remove, prune, remote nuke) acquire the lock; read-only ones run without it. snapshot restore is classified read-only -- it writes only to its target directory, not the local index or remote store. The decision moves to a small acquireLockIfMutating helper, with a test that a read-only command runs while the lock is held and two mutators still exclude. The README locking section is rewritten to match.

Model: opus-4-8

internal/cli/app.go

@@ -33,14 +33,33 @@ import (
 // may take before we give up.
 const shutdownTimeout = 30 * time.Second
 
-// AppOptions contains common options for creating the fx application.
-// It includes the configuration file path, logging options, and additional
-// fx modules and invocations that should be included in the application.
+// lockMode says whether a command mutates persistent state — the local
+// index database or the remote store — and so must hold the process-wide
+// PID lock, or only reads that state and may run alongside a mutator.
+type lockMode int
+
+const (
+	// mutating commands (snapshot create, snapshot purge, snapshot remove,
+	// prune, remote nuke) write the local index or the remote store. They
+	// hold the PID lock so that at most one runs at a time.
+	mutating lockMode = iota
+	// readOnly commands (info, snapshot list, snapshot verify, remote info,
+	// snapshot restore) do not write the local index or the remote store,
+	// so they run without the lock and are never blocked by a running
+	// mutator. restore writes only to the target directory it is given.
+	readOnly
+)
+
+// AppOptions contains common options for creating and running the fx
+// application: the configuration file path, logging options, additional fx
+// modules and invocations, and whether the command mutates persistent
+// state (which decides whether it takes the PID lock).
 type AppOptions struct {
 	ConfigPath string
 	LogOptions log.Options
 	Modules    []fx.Option
 	Invokes    []fx.Option
+	Mode       lockMode
 }
 
 // setupGlobals records the startup time and, when an output-suppression
@@ -281,14 +300,15 @@ func RunOperation(
 }
 
 // runVaultikApp runs the standard single-operation command lifecycle
-// shared by the list/purge/verify/remove/remote-info subcommands:
+// shared by the snapshot list/purge/remove and remote nuke subcommands:
 // resolve the config, then run op against the Vaultik instance through
 // RunOperation, reporting a failure prefixed with failMsg (suppressed
-// while suppressErrors is true, e.g. under --json). jsonOutput marks a
-// command whose stdout is a JSON document: it quiets the UI but, unlike
-// Quiet, leaves the stderr log level alone.
+// while suppressErrors is true, e.g. under --json). mode says whether the
+// command takes the PID lock. jsonOutput marks a command whose stdout is a
+// JSON document: it quiets the UI but, unlike Quiet, leaves the stderr log
+// level alone.
 func runVaultikApp(
-	cmd *cobra.Command, jsonOutput, suppressErrors bool,
+	cmd *cobra.Command, mode lockMode, jsonOutput, suppressErrors bool,
 	failMsg string, op func(v *vaultik.Vaultik) error,
 ) error {
 	configPath, err := ResolveConfigPath()
@@ -306,6 +326,7 @@ func runVaultikApp(
 			Quiet:   rootFlags.Quiet,
 			JSON:    jsonOutput,
 		},
+		Mode: mode,
 	}, op, func(err error) {
 		if suppressErrors {
 			return
@@ -319,28 +340,46 @@ func runVaultikApp(
 // RunWithApp is a helper that creates and runs an fx app with the given options.
 // It combines NewApp and RunApp into a single convenient function. This is the
 // preferred way to run CLI commands that need the full application context.
-// It acquires a PID lock before starting to prevent concurrent instances.
+// A mutating command takes the process-wide PID lock before starting so that
+// only one runs at a time; a read-only command runs without it and is not
+// blocked while a mutator holds the lock (opts.Mode).
 func RunWithApp(ctx context.Context, opts AppOptions) error {
-	// Acquire PID lock to prevent concurrent instances
-	lockDir := filepath.Join(xdg.DataHome, "vaultik")
-
-	lock, err := pidlock.Acquire(lockDir)
+	release, err := acquireLockIfMutating(opts.Mode,
+		filepath.Join(xdg.DataHome, "vaultik"))
 	if err != nil {
-		if errors.Is(err, pidlock.ErrAlreadyRunning) {
-			return fmt.Errorf("cannot start: %w", err)
-		}
-
-		return fmt.Errorf("failed to acquire lock: %w", err)
+		return err
 	}
 
-	defer func() {
-		err := lock.Release()
-		if err != nil {
-			log.Warn("Failed to release PID lock", "error", err)
-		}
-	}()
+	defer release()
 
 	app := NewApp(opts)
 
 	return RunApp(ctx, app)
 }
+
+// acquireLockIfMutating takes the process-wide PID lock in lockDir for a
+// mutating command and returns a function that releases it. A read-only
+// command takes no lock, so it returns a no-op release and is never blocked
+// while a mutator holds the lock. ErrAlreadyRunning (another mutator holds
+// the lock) is surfaced as a "cannot start" error.
+func acquireLockIfMutating(mode lockMode, lockDir string) (func(), error) {
+	if mode != mutating {
+		return func() {}, nil
+	}
+
+	lock, err := pidlock.Acquire(lockDir)
+	if err != nil {
+		if errors.Is(err, pidlock.ErrAlreadyRunning) {
+			return nil, fmt.Errorf("cannot start: %w", err)
+		}
+
+		return nil, fmt.Errorf("failed to acquire lock: %w", err)
+	}
+
+	return func() {
+		err := lock.Release()
+		if err != nil {
+			log.Warn("Failed to release PID lock", "error", err)
+		}
+	}, nil
+}