P2.2-P2.9, P3.2-P3.10, P4.1-P4.3: Complete Phases 2, 3, and 4

11 work units built in parallel and merged:

Agent handlers (Phase 2):
- P2.2 Deploy: pull images, stop/remove/run containers, update registry
- P2.3 Lifecycle: stop/start/restart with desired_state tracking
- P2.4 Status: list (registry), live check (runtime), get status (drift+events)
- P2.5 Sync: receive desired state, reconcile unmanaged containers
- P2.6 File transfer: push/pull scoped to /srv/<service>/, path validation
- P2.7 Adopt: match <service>-* containers, derive component names
- P2.8 Monitor: continuous watch loop, drift/flap alerting, event pruning
- P2.9 Snapshot: VACUUM INTO database backup command

CLI commands (Phase 3):
- P3.2 Login, P3.3 Deploy, P3.4 Stop/Start/Restart
- P3.5 List/Ps/Status, P3.6 Sync, P3.7 Adopt
- P3.8 Service show/edit/export, P3.9 Push/Pull, P3.10 Node list/add/remove

Deployment artifacts (Phase 4):
- Systemd units (agent service + backup timer)
- Example configs (CLI + agent)
- Install script (idempotent)

All packages: build, vet, lint (0 issues), test (all pass).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

internal/agent/files.go

@@ -0,0 +1,152 @@
+package agent
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	mcpv1 "git.wntrmute.dev/kyle/mcp/gen/mcp/v1"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+// validatePath validates and resolves a relative path within a service's
+// /srv/<service>/ directory. It rejects path traversal, absolute paths,
+// and symlink escapes.
+func validatePath(service, relPath string) (string, error) {
+	if service == "" {
+		return "", fmt.Errorf("empty service name")
+	}
+	if relPath == "" {
+		return "", fmt.Errorf("empty path")
+	}
+	if filepath.IsAbs(relPath) {
+		return "", fmt.Errorf("absolute path not allowed: %s", relPath)
+	}
+
+	cleaned := filepath.Clean(relPath)
+	if strings.Contains(cleaned, "..") {
+		return "", fmt.Errorf("path traversal not allowed: %s", relPath)
+	}
+
+	serviceDir := filepath.Join("/srv", service)
+	fullPath := filepath.Join(serviceDir, cleaned)
+
+	if !strings.HasPrefix(fullPath, serviceDir+"/") {
+		return "", fmt.Errorf("path escapes service directory: %s", relPath)
+	}
+
+	parentDir := filepath.Dir(fullPath)
+	if _, err := os.Stat(parentDir); err == nil {
+		resolved, err := filepath.EvalSymlinks(parentDir)
+		if err != nil {
+			return "", fmt.Errorf("resolve symlinks: %w", err)
+		}
+		if !strings.HasPrefix(resolved, serviceDir) {
+			return "", fmt.Errorf("symlink escapes service directory: %s", relPath)
+		}
+	}
+
+	return fullPath, nil
+}
+
+// PushFile writes a file to the node's filesystem under /srv/<service>/.
+func (a *Agent) PushFile(ctx context.Context, req *mcpv1.PushFileRequest) (*mcpv1.PushFileResponse, error) {
+	if req.Service == "" {
+		return nil, status.Errorf(codes.InvalidArgument, "service name required")
+	}
+	if req.Path == "" {
+		return nil, status.Errorf(codes.InvalidArgument, "path required")
+	}
+
+	fullPath, err := validatePath(req.Service, req.Path)
+	if err != nil {
+		return nil, status.Errorf(codes.InvalidArgument, "invalid path: %v", err)
+	}
+
+	a.Logger.Info("push file", "service", req.Service, "path", req.Path)
+
+	dir := filepath.Dir(fullPath)
+	if err := os.MkdirAll(dir, 0750); err != nil {
+		return nil, status.Errorf(codes.Internal, "create directories: %v", err)
+	}
+
+	// Atomic write: temp file in the same directory, then rename.
+	tmp, err := os.CreateTemp(dir, ".mcp-push-*")
+	if err != nil {
+		return nil, status.Errorf(codes.Internal, "create temp file: %v", err)
+	}
+	tmpName := tmp.Name()
+
+	cleanup := func() { _ = os.Remove(tmpName) }
+
+	if _, err := tmp.Write(req.Content); err != nil {
+		_ = tmp.Close()
+		cleanup()
+		return nil, status.Errorf(codes.Internal, "write temp file: %v", err)
+	}
+	if err := tmp.Close(); err != nil {
+		cleanup()
+		return nil, status.Errorf(codes.Internal, "close temp file: %v", err)
+	}
+
+	mode := os.FileMode(req.Mode)
+	if mode == 0 {
+		mode = 0600
+	}
+	if err := os.Chmod(tmpName, mode); err != nil {
+		cleanup()
+		return nil, status.Errorf(codes.Internal, "set permissions: %v", err)
+	}
+
+	if err := os.Rename(tmpName, fullPath); err != nil {
+		cleanup()
+		return nil, status.Errorf(codes.Internal, "rename to target: %v", err)
+	}
+
+	return &mcpv1.PushFileResponse{Success: true}, nil
+}
+
+// PullFile reads a file from the node's filesystem under /srv/<service>/.
+func (a *Agent) PullFile(ctx context.Context, req *mcpv1.PullFileRequest) (*mcpv1.PullFileResponse, error) {
+	if req.Service == "" {
+		return nil, status.Errorf(codes.InvalidArgument, "service name required")
+	}
+	if req.Path == "" {
+		return nil, status.Errorf(codes.InvalidArgument, "path required")
+	}
+
+	fullPath, err := validatePath(req.Service, req.Path)
+	if err != nil {
+		return nil, status.Errorf(codes.InvalidArgument, "invalid path: %v", err)
+	}
+
+	a.Logger.Info("pull file", "service", req.Service, "path", req.Path)
+
+	f, err := os.Open(fullPath) //nolint:gosec // path validated by validatePath
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, status.Errorf(codes.NotFound, "file not found: %s", req.Path)
+		}
+		return nil, status.Errorf(codes.Internal, "open file: %v", err)
+	}
+	defer f.Close() //nolint:errcheck
+
+	info, err := f.Stat()
+	if err != nil {
+		return nil, status.Errorf(codes.Internal, "stat file: %v", err)
+	}
+
+	content, err := io.ReadAll(f)
+	if err != nil {
+		return nil, status.Errorf(codes.Internal, "read file: %v", err)
+	}
+
+	return &mcpv1.PullFileResponse{
+		Content: content,
+		Mode:    uint32(info.Mode().Perm()),
+	}, nil
+}