fix: transport escalation exempts log reads, get_entity accepts slug alias, add restart_service + push_file tools

P0: Transport escalation in classifyAndGate (server.go:745) now exempts
    log-inspection commands (tail/head/cat/journalctl on *.log or /logs/)
    from the /opt//etc//var/lib/ gating on LXC targets. Fixes the
    'tail -3 /opt/seanime/data/logs/seanime.log queued for approval' bug.

P1: queryEntity returns actionable error when slug_or_id param is empty
    ('slug_or_id is required') instead of silent 'entity not found: '.

P2: Added slugArg() helper (server.go) so get_entity, get_relations,
    get_blast_radius, and explain accept 'slug' as an alias for their
    declared param name. Solves the discoverability inconsistency where
    every tool used a different param name for the same concept.

P3: Two new MCP tools:
    - restart_service(target, service) — systemctl restart wrapper,
      correctly classified config_mutation (requires approval)
    - push_file(target, source_path, dest_path, backup=true) — pct push
      from Proxmox host into LXC, with optional backup. Classified
      config_mutation. LXC-only for now.

P4: Updated homelab-lxc-ops skill with MCP tools preference table.

Plus: Wails desktop build now uses build-tag approach for frontend embed
      (assets_embed.go + assets_stub.go), so go build ./... works on
      clean checkout without the frontend built first.

Version: 0.31.0 → 0.32.0

internal/mcp/entity_tools.go

@@ -24,7 +24,7 @@ func EntityTools(pool *db.Pool, agentID uuid.UUID, sec secretBackend) []toolReg
 					InputSchema: objSchema(prop{"slug_or_id", "string", "Entity slug (e.g. host:hubris) or UUID"}),
 				}, handler: func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 					args := argsMap(req)
-					idOrSlug, _ := args["slug_or_id"].(string)
+					idOrSlug := slugArg(args, "slug_or_id", "slug", "id")
 					return queryEntity(ctx, pool, idOrSlug), nil
 				}},
 				{tool: &mcp.Tool{Name: "list_entities", Description: "List entities filtered by type, state, or search",
@@ -52,7 +52,7 @@ func EntityTools(pool *db.Pool, agentID uuid.UUID, sec secretBackend) []toolReg
 					),
 				}, handler: func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 					args := argsMap(req)
-					slug, _ := args["entity_id"].(string)
+					slug := slugArg(args, "entity_id", "slug")
 					typesStr, _ := args["types"].(string)
 					if slug == "" {
 						return textResult("entity_id is required"), nil
@@ -76,7 +76,7 @@ func EntityTools(pool *db.Pool, agentID uuid.UUID, sec secretBackend) []toolReg
 						prop{"depth", "integer", "Traversal depth (default 3)"}),
 				}, handler: func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 					args := argsMap(req)
-					slug, _ := args["entity_id"].(string)
+					slug := slugArg(args, "entity_id", "slug")
 					depth := int(getFloat(args, "depth", 3))
 					return queryRows(ctx, pool,
 						"SELECT e.slug, CAST(b.depth AS int) FROM blast_radius((SELECT id FROM entities WHERE slug = $1), $2) b JOIN entities e ON e.id = b.entity_id",

internal/mcp/ops_tools.go

@@ -595,5 +595,82 @@ func OpsTools(pool *db.Pool, agentID uuid.UUID, sec secretBackend) []toolReg {
 					}
 					return textResult(fmt.Sprintf("secret %s stored", key)), nil
 				}},
+				{tool: &mcp.Tool{Name: "restart_service", Description: "Restart a systemd service on a host or LXC. Wraps `systemctl restart <service>` with correct risk classification (config_mutation — requires operator approval). Prefer this over raw `run` for restarts: it resolves the target, sets the risk class, and records a clean execution row.",
+					InputSchema: objSchema(
+						prop{"target", "string", "Target entity slug (e.g. lxc:seanime, host:hubris)"},
+						prop{"service", "string", "systemd unit name (e.g. seanime, caddy)"}),
+				}, handler: func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+					args := argsMap(req)
+					targetSlug := slugArg(args, "target", "service_slug", "slug")
+					service := slugArg(args, "service", "unit")
+					if targetSlug == "" || service == "" {
+						return textResult("error: target and service are required"), nil
+					}
+					sessionID, _ := args["_session_id"].(string)
+					var targetID uuid.UUID
+					if err := pool.QueryRow(ctx, "SELECT id FROM entities WHERE slug = $1", targetSlug).Scan(&targetID); err != nil {
+						return textResult(fmt.Sprintf("target not found: %s", targetSlug)), nil
+					}
+					command := fmt.Sprintf("systemctl restart %s", service)
+					purpose := fmt.Sprintf("restart %s on %s", service, targetSlug)
+					return classifyAndGate(ctx, pool, agentID, targetID, targetSlug, command, purpose, "config_mutation", sessionID), nil
+				}},
+				{tool: &mcp.Tool{Name: "push_file", Description: "Copy a file from a Proxmox host into an LXC container via `pct push`. The source path must already exist on the Proxmox host that owns the LXC (stage it there first via `run` on the host, e.g. with scp/curl/wget). Classified config_mutation — requires operator approval. Prefer this over manual 3-hop SSH piping (`cat | ssh | pct exec tee`), which repeatedly drops into partial-write/text-file-busy states.",
+					InputSchema: objSchema(
+						prop{"target", "string", "LXC entity slug (e.g. lxc:seanime)"},
+						prop{"source_path", "string", "Path on the Proxmox host (e.g. /tmp/seanime)"},
+						prop{"dest_path", "string", "Destination path inside the container (e.g. /opt/seanime/bin/seanime)"},
+						prop{"backup", "boolean", "If true, copy the existing dest to dest.bak inside the container first (default true)"}),
+				}, handler: func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+					args := argsMap(req)
+					targetSlug := slugArg(args, "target", "slug")
+					sourcePath := slugArg(args, "source_path")
+					destPath := slugArg(args, "dest_path")
+					backup := true
+					if b, ok := args["backup"].(bool); ok {
+						backup = b
+					}
+					if targetSlug == "" || sourcePath == "" || destPath == "" {
+						return textResult("error: target, source_path, and dest_path are required"), nil
+					}
+					if !strings.HasPrefix(targetSlug, "lxc:") {
+						return textResult(fmt.Sprintf("error: push_file only supports lxc: targets for now (got %s) — host/vm push needs scp, not yet wired", targetSlug)), nil
+					}
+					// Resolve pve_id and the owning Proxmox host (same chain as get_lxc_state).
+					var pveID string
+					if err := pool.QueryRow(ctx, "SELECT attributes->>'pve_id' FROM entities WHERE slug = $1", targetSlug).Scan(&pveID); err != nil || pveID == "" {
+						return textResult(fmt.Sprintf("LXC not found or missing pve_id: %s", targetSlug)), nil
+					}
+					var hostID uuid.UUID
+					err := pool.QueryRow(ctx, `
+						SELECT t.id FROM entities t
+						JOIN relationships r ON r.source_id = t.id
+						JOIN entities s ON s.id = r.target_id
+						WHERE s.slug = $1 AND r.type = 'hosts' AND r.valid_to IS NULL
+						LIMIT 1`, targetSlug).Scan(&hostID)
+					var hostSlug string
+					if err == nil {
+						pool.QueryRow(ctx, "SELECT slug FROM entities WHERE id = $1", hostID).Scan(&hostSlug)
+					} else {
+						pool.QueryRow(ctx, "SELECT attributes->>'host' FROM entities WHERE slug = $1", targetSlug).Scan(&hostSlug)
+					}
+					if hostSlug == "" {
+						return textResult(fmt.Sprintf("cannot resolve Proxmox host for %s", targetSlug)), nil
+					}
+					cmd := fmt.Sprintf("pct push %s %s %s", pveID, sourcePath, destPath)
+					if backup {
+						cmd = fmt.Sprintf("pct exec %s -- cp -n %s %s.bak 2>/dev/null || true; %s", pveID, destPath, destPath, cmd)
+					}
+					sessionID, _ := args["_session_id"].(string)
+					var hostEntityID uuid.UUID
+					if err := pool.QueryRow(ctx, "SELECT id FROM entities WHERE slug = $1", "host:"+hostSlug).Scan(&hostEntityID); err != nil {
+						// hostSlug may already carry the host: prefix
+						if err2 := pool.QueryRow(ctx, "SELECT id FROM entities WHERE slug = $1", hostSlug).Scan(&hostEntityID); err2 != nil {
+							return textResult(fmt.Sprintf("host entity not found: %s", hostSlug)), nil
+						}
+					}
+					purpose := fmt.Sprintf("push %s into %s at %s", sourcePath, targetSlug, destPath)
+					return classifyAndGate(ctx, pool, agentID, hostEntityID, "host:"+hostSlug, cmd, purpose, "config_mutation", sessionID), nil
+				}},
 	}
 }

internal/mcp/server.go

@@ -300,6 +300,22 @@ func argsMap(req *mcp.CallToolRequest) map[string]any {
 	return m
 }
 
+// slugArg returns the first non-empty string value among the given keys.
+// Tools historically used inconsistent param names for "the entity slug"
+// (slug_or_id, entity_id, service_slug, lxc_slug, target). This lets a single
+// handler accept any of them, so an agent guessing "slug" still works.
+func slugArg(m map[string]any, keys ...string) string {
+	if m == nil {
+		return ""
+	}
+	for _, k := range keys {
+		if s, ok := m[k].(string); ok && strings.TrimSpace(s) != "" {
+			return strings.TrimSpace(s)
+		}
+	}
+	return ""
+}
+
 func getFloat(m map[string]any, key string, def float64) float64 {
 	if m == nil {
 		return def
@@ -353,6 +369,9 @@ func jsonErr(format string, args ...any) []byte {
 }
 
 func queryEntity(ctx context.Context, pool *db.Pool, idOrSlug string) *mcp.CallToolResult {
+	if strings.TrimSpace(idOrSlug) == "" {
+		return textResult("slug_or_id is required — expected an entity slug (e.g. lxc:seanime) or UUID")
+	}
 	var id uuid.UUID
 	if u, err := uuid.Parse(idOrSlug); err == nil {
 		id = u
@@ -742,9 +761,15 @@ func classifyAndGate(ctx context.Context, pool *db.Pool, agentID, targetID uuid.
 	// the same command locally on the Proxmox host via pct exec.
 	// Caught live: "cat /etc/hostname" on lxc:dns queued as config_mutation
 	// while "pct exec 107 -- cat /etc/hostname" on host:hubris auto-ran.
+	//
+	// EXEMPTION: tail/head/cat/less/journalctl on log files (*.log, */logs/*)
+	// are always read-only — caught live 2026-08-15 session f6a7d4e:
+	// "tail -3 /opt/seanime/data/logs/seanime.log" on lxc:seanime was gated.
 	if riskClass == policy.RiskReadOnly && strings.HasPrefix(targetSlug, "lxc:") {
-		if strings.Contains(command, "/opt/") || strings.Contains(command, "/etc/") || strings.Contains(command, "/var/lib/") {
-			riskClass = policy.RiskConfigMutation
+		if !isLogInspectionRead(command) {
+			if strings.Contains(command, "/opt/") || strings.Contains(command, "/etc/") || strings.Contains(command, "/var/lib/") {
+				riskClass = policy.RiskConfigMutation
+			}
 		}
 	}
 
@@ -1134,6 +1159,22 @@ func hostLxcCommand(cmd string) (string, bool) {
 	return first, hostLxcCommands[first]
 }
 
+// isLogInspectionRead returns true if the command is a safe read-only operation
+// on a log file — tail, head, cat, less, or journalctl with a .log or /logs/ path.
+// Used by the transport-aware escalation check to avoid gating the most common
+// debugging action (e.g. "tail -3 /opt/seanime/data/logs/seanime.log" on lxc:seanime).
+func isLogInspectionRead(cmd string) bool {
+	trimmed := strings.TrimSpace(cmd)
+	for _, prefix := range []string{"tail ", "head ", "cat ", "less ", "journalctl "} {
+		if strings.HasPrefix(trimmed, prefix) {
+			if strings.Contains(trimmed, ".log") || strings.Contains(trimmed, "/logs/") {
+				return true
+			}
+		}
+	}
+	return false
+}
+
 // validateCommandSyntax checks for common LLM-generated bash errors that always
 // fail at the shell. Returns an error message or "" if the command looks valid.
 func validateCommandSyntax(cmd string) string {