fix(tasks): stabilize lifecycle logs and operational log.scan root scope

Author: goktugcy

CHANGELOG.md

@@ -15,6 +15,11 @@ Formatting rules:
 
 ## [Unreleased]
 
+### Fixed
+
+- Task lifecycle log shipping now truncates oversized log lines to the API-safe limit and retries queued-state conflicts before failing, reducing cases where tasks appear stuck in `queued` without visible progress.
+- Root `log.scan` execution now normalizes legacy `task` scope requests to `operational` scope and uses a dedicated operational helper path, so log scan operations no longer depend on task-root grants.
+
 ## [1.0.6] - 2026-04-05
 
 ### Added

internal/agentctl/commands.go

@@ -33,9 +33,11 @@ const (
 	linuxPrivilegedUpdateHelperPath  = "/usr/local/libexec/noderax-agent-self-update"
 	linuxRootProfileHelperPath       = "/usr/local/libexec/noderax-agent-root-profile"
 	linuxPackageMutationHelperPath   = "/usr/local/libexec/noderax-agent-package-mutation"
+	linuxOperationalLogScanHelperPath = "/usr/local/libexec/noderax-agent-operational-log-scan"
 	linuxTaskRootHelperPath          = "/usr/local/libexec/noderax-agent-task-root"
 	linuxPrivilegedUpdateRequestPath = linuxServiceHome + "/update-request.json"
 	linuxPackageMutationRequestPath  = linuxServiceHome + "/package-mutation-request.txt"
+	linuxOperationalLogScanRequestPath = linuxServiceHome + "/operational-log-scan-request.json"
 	linuxTaskRootRequestPath         = linuxServiceHome + "/task-root-request.txt"
 	linuxConfigPath                  = "/etc/noderax-agent/config.json"
 	linuxStatePath                   = "/var/lib/noderax-agent/agent_identity.json"
@@ -63,6 +65,7 @@ type platformSpec struct {
 	PrivilegedUpdateHelperPath string
 	RootProfileHelperPath      string
 	PackageMutationHelperPath  string
+	OperationalLogScanHelperPath string
 	TaskRootHelperPath         string
 	BaseSudoersPath            string
 	RootAccessSudoersPath      string
@@ -247,6 +250,9 @@ func (c CLI) Install(ctx context.Context, args []string) error {
 	if err := writePackageMutationHelper(spec); err != nil {
 		return fmt.Errorf("write package mutation helper: %w", err)
 	}
+	if err := writeOperationalLogScanHelper(spec); err != nil {
+		return fmt.Errorf("write operational log scan helper: %w", err)
+	}
 	if err := writeTaskRootHelper(spec); err != nil {
 		return fmt.Errorf("write task root helper: %w", err)
 	}
@@ -426,6 +432,18 @@ func (c CLI) Uninstall(ctx context.Context) error {
 		packageMutationHelperRemoved,
 	)
 
+	operationalLogScanHelperRemoved, err := removeFileIfExists(spec.OperationalLogScanHelperPath)
+	if err != nil {
+		return err
+	}
+	recordRemovalResult(
+		&removed,
+		&missing,
+		"operational log scan helper",
+		spec.OperationalLogScanHelperPath,
+		operationalLogScanHelperRemoved,
+	)
+
 	taskRootHelperRemoved, err := removeFileIfExists(spec.TaskRootHelperPath)
 	if err != nil {
 		return err
@@ -615,6 +633,7 @@ func currentPlatformSpec() (platformSpec, error) {
 			PrivilegedUpdateHelperPath: linuxPrivilegedUpdateHelperPath,
 			RootProfileHelperPath:      linuxRootProfileHelperPath,
 			PackageMutationHelperPath:  linuxPackageMutationHelperPath,
+			OperationalLogScanHelperPath: linuxOperationalLogScanHelperPath,
 			TaskRootHelperPath:         linuxTaskRootHelperPath,
 			BaseSudoersPath:            linuxBaseSudoersPath,
 			RootAccessSudoersPath:      linuxRootAccessSudoersPath,
@@ -638,6 +657,7 @@ func currentPlatformSpec() (platformSpec, error) {
 			PrivilegedUpdateHelperPath: "",
 			RootProfileHelperPath:      "",
 			PackageMutationHelperPath:  "",
+			OperationalLogScanHelperPath: "",
 			TaskRootHelperPath:         "",
 			BaseSudoersPath:            "",
 			RootAccessSudoersPath:      "",
@@ -1223,6 +1243,24 @@ func writePackageMutationHelper(spec platformSpec) error {
 	return nil
 }
 
+func writeOperationalLogScanHelper(spec platformSpec) error {
+	path := strings.TrimSpace(spec.OperationalLogScanHelperPath)
+	if path == "" {
+		return nil
+	}
+
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return fmt.Errorf("create helper directory for %s: %w", path, err)
+	}
+
+	content := renderOperationalLogScanHelper(spec)
+	if err := os.WriteFile(path, []byte(content), 0o755); err != nil {
+		return fmt.Errorf("write helper %s: %w", path, err)
+	}
+
+	return nil
+}
+
 func writeTaskRootHelper(spec platformSpec) error {
 	path := strings.TrimSpace(spec.TaskRootHelperPath)
 	if path == "" {
@@ -1414,6 +1452,28 @@ esac
 `, spec.PackageMutationHelperPath, linuxPackageMutationRequestPath)
 }
 
+func renderOperationalLogScanHelper(spec platformSpec) string {
+	return fmt.Sprintf(`#!/bin/sh
+set -eu
+
+HELPER_PATH=%q
+REQUEST_FILE=%q
+AGENT_BINARY=%q
+
+if [ "$#" -ne 0 ]; then
+	echo "usage: ${HELPER_PATH}" >&2
+	exit 64
+fi
+
+if [ ! -f "${REQUEST_FILE}" ]; then
+	echo "operational log scan request file is missing" >&2
+	exit 1
+fi
+
+exec "${AGENT_BINARY}" log-scan --request "${REQUEST_FILE}"
+`, spec.OperationalLogScanHelperPath, linuxOperationalLogScanRequestPath, spec.BinaryPath)
+}
+
 func renderTaskRootHelper(spec platformSpec) string {
 	return fmt.Sprintf(`#!/bin/sh
 set -eu
@@ -1483,6 +1543,7 @@ SERVICE_USER=%q
 SERVICE_NAME=%q
 SUDOERS_FILE=%q
 PACKAGE_MUTATION_HELPER=%q
+OPERATIONAL_LOG_SCAN_HELPER=%q
 TASK_ROOT_HELPER=%q
 
 if [ "$#" -ne 2 ] || [ "$1" != "apply" ]; then
@@ -1529,6 +1590,11 @@ append_operational_profile() {
     append_alias "NODERAX_AGENT_PACKAGE_MUTATIONS"
   fi
 
+	if [ -x "${OPERATIONAL_LOG_SCAN_HELPER}" ]; then
+		append_line "Cmnd_Alias NODERAX_AGENT_OPERATIONAL_LOG_SCAN = ${OPERATIONAL_LOG_SCAN_HELPER}"
+		append_alias "NODERAX_AGENT_OPERATIONAL_LOG_SCAN"
+	fi
+
   if [ -n "${SYSTEMCTL_PATH}" ]; then
     append_line "Cmnd_Alias NODERAX_AGENT_SERVICE_CONTROL = ${SYSTEMCTL_PATH} restart ${SERVICE_NAME}, ${SYSTEMCTL_PATH} restart ${SERVICE_NAME%%.service}"
     append_alias "NODERAX_AGENT_SERVICE_CONTROL"
@@ -1628,7 +1694,7 @@ if command -v visudo >/dev/null 2>&1; then
 fi
 
 install -o root -g root -m 0440 "${TMP_FILE}" "${SUDOERS_FILE}"
-`, spec.RootProfileHelperPath, spec.ServiceUser, spec.ServiceName, spec.RootAccessSudoersPath, spec.PackageMutationHelperPath, spec.TaskRootHelperPath)
+`, spec.RootProfileHelperPath, spec.ServiceUser, spec.ServiceName, spec.RootAccessSudoersPath, spec.PackageMutationHelperPath, spec.OperationalLogScanHelperPath, spec.TaskRootHelperPath)
 }
 
 func writeServiceUnit(path, content string) error {

internal/agentctl/commands_test.go

@@ -135,6 +135,7 @@ func TestRenderRootProfileHelperSupportsCombinedProfiles(t *testing.T) {
 		ServiceName:               "noderax-agent.service",
 		RootAccessSudoersPath:     "/etc/sudoers.d/noderax-agent-root-access",
 		PackageMutationHelperPath: "/usr/local/libexec/noderax-agent-package-mutation",
+		OperationalLogScanHelperPath: "/usr/local/libexec/noderax-agent-operational-log-scan",
 		TaskRootHelperPath:        "/usr/local/libexec/noderax-agent-task-root",
 	}
 
@@ -146,6 +147,8 @@ func TestRenderRootProfileHelperSupportsCombinedProfiles(t *testing.T) {
 		"operational_terminal)",
 		"task_terminal)",
 		"append_operational_profile",
+		"NODERAX_AGENT_OPERATIONAL_LOG_SCAN",
+		"/usr/local/libexec/noderax-agent-operational-log-scan",
 		"append_task_profile",
 		"append_terminal_profile",
 		"for shell_name in bash zsh sh; do",

internal/agentctl/update.go

@@ -322,6 +322,9 @@ func (c CLI) applyManagedUpdate(
 	if err := writePackageMutationHelper(spec); err != nil {
 		return fmt.Errorf("refresh package mutation helper: %w", err)
 	}
+	if err := writeOperationalLogScanHelper(spec); err != nil {
+		return fmt.Errorf("refresh operational log scan helper: %w", err)
+	}
 	if err := writeTaskRootHelper(spec); err != nil {
 		return fmt.Errorf("refresh task root helper: %w", err)
 	}

internal/tasks/executor.go

@@ -33,6 +33,8 @@ const (
 	linuxPrivilegedUpdateRequestPath = "/var/lib/noderax-agent/update-request.json"
 	linuxPackageMutationHelperPath   = "/usr/local/libexec/noderax-agent-package-mutation"
 	linuxPackageMutationRequestPath  = "/var/lib/noderax-agent/package-mutation-request.txt"
+	linuxOperationalLogScanHelperPath = "/usr/local/libexec/noderax-agent-operational-log-scan"
+	linuxOperationalLogScanRequestPath = "/var/lib/noderax-agent/operational-log-scan-request.json"
 	linuxTaskRootHelperPath          = "/usr/local/libexec/noderax-agent-task-root"
 	linuxTaskRootRequestPath         = "/var/lib/noderax-agent/task-root-request.txt"
 	linuxAgentServiceName            = "noderax-agent.service"
@@ -149,6 +151,7 @@ type ShellExecutor struct {
 	fileExists                  func(string) bool
 	privilegedUpdateRequestPath string
 	packageMutationRequestPath  string
+	operationalLogScanRequestPath string
 	taskRootRequestPath         string
 	newCommand                  func(context.Context, string, ...string) commandRunner
 	rootScopeChecker            func(string) bool
@@ -166,6 +169,7 @@ func NewShellExecutor(defaultTimeout time.Duration) *ShellExecutor {
 		},
 		privilegedUpdateRequestPath: linuxPrivilegedUpdateRequestPath,
 		packageMutationRequestPath:  linuxPackageMutationRequestPath,
+		operationalLogScanRequestPath: linuxOperationalLogScanRequestPath,
 		taskRootRequestPath:         linuxTaskRootRequestPath,
 		newCommand:                  newExecCommandRunner,
 	}
@@ -453,22 +457,22 @@ func (e *ShellExecutor) logScanCommand(payload json.RawMessage) (commandSpec, er
 	commandArgs := []string{"log-scan", "--request", requestPath}
 
 	if parsed.RunAsRoot {
-		if strings.TrimSpace(parsed.RootScope) == "" {
-			return commandSpec{}, fmt.Errorf("%w: log.scan root execution requires rootScope", ErrInvalidTaskPayload)
+		effectiveScope := strings.TrimSpace(parsed.RootScope)
+		if effectiveScope == "" || effectiveScope == "task" {
+			effectiveScope = "operational"
 		}
-		if parsed.RootScope != "task" {
-			return commandSpec{}, fmt.Errorf("%w: log.scan root execution requires task scope", ErrInvalidTaskPayload)
+		if effectiveScope != "operational" {
+			return commandSpec{}, fmt.Errorf("%w: log.scan root execution requires operational scope", ErrInvalidTaskPayload)
 		}
-		if e.rootScopeChecker != nil && !e.rootScopeChecker(parsed.RootScope) {
-			return commandSpec{}, fmt.Errorf("%w: current root access profile does not allow %s scope", ErrUnsupportedExecutionEnvironment, parsed.RootScope)
+		if e.rootScopeChecker != nil && !e.rootScopeChecker(effectiveScope) {
+			return commandSpec{}, fmt.Errorf("%w: current root access profile does not allow %s scope", ErrUnsupportedExecutionEnvironment, effectiveScope)
 		}
 
-		if e.goos == "linux" && e.fileExists(linuxTaskRootHelperPath) {
-			rootCommand := formatCommandForLog(commandName, commandArgs)
-			if err := writeTaskRootRequest(e.taskRootRequestPath, rootCommand); err != nil {
-				return commandSpec{}, fmt.Errorf("%w: write task root request: %v", ErrUnsupportedExecutionEnvironment, err)
+		if e.goos == "linux" && e.fileExists(linuxOperationalLogScanHelperPath) {
+			if err := writeOperationalLogScanRequest(e.operationalLogScanRequestPath, payload); err != nil {
+				return commandSpec{}, fmt.Errorf("%w: write operational log scan request: %v", ErrUnsupportedExecutionEnvironment, err)
 			}
-			commandName, commandArgs, err = e.wrapWithSudo(linuxTaskRootHelperPath, nil)
+			commandName, commandArgs, err = e.wrapWithSudo(linuxOperationalLogScanHelperPath, nil)
 		} else {
 			commandName, commandArgs, err = e.wrapWithSudo(commandName, commandArgs)
 		}
@@ -968,6 +972,45 @@ func writeTaskRootRequest(path string, command string) error {
 	return nil
 }
 
+func writeOperationalLogScanRequest(path string, payload json.RawMessage) error {
+	cleanPath := filepath.Clean(strings.TrimSpace(path))
+	if cleanPath == "" {
+		return fmt.Errorf("request path is empty")
+	}
+
+	if err := os.MkdirAll(filepath.Dir(cleanPath), 0o755); err != nil {
+		return fmt.Errorf("create operational log scan request directory: %w", err)
+	}
+
+	file, err := os.CreateTemp(filepath.Dir(cleanPath), ".noderax-agent-operational-log-scan-*.json")
+	if err != nil {
+		return fmt.Errorf("create operational log scan request file: %w", err)
+	}
+
+	tempPath := file.Name()
+	if _, err := file.Write(payload); err != nil {
+		file.Close()
+		_ = os.Remove(tempPath)
+		return fmt.Errorf("write operational log scan request file: %w", err)
+	}
+	if err := file.Chmod(0o600); err != nil {
+		file.Close()
+		_ = os.Remove(tempPath)
+		return fmt.Errorf("chmod operational log scan request file: %w", err)
+	}
+	if err := file.Close(); err != nil {
+		_ = os.Remove(tempPath)
+		return fmt.Errorf("close operational log scan request file: %w", err)
+	}
+
+	if err := os.Rename(tempPath, cleanPath); err != nil {
+		_ = os.Remove(tempPath)
+		return fmt.Errorf("replace operational log scan request file: %w", err)
+	}
+
+	return nil
+}
+
 func writeManagedUpdateRequest(path string, payload agentUpdatePayload) error {
 	cleanPath := filepath.Clean(strings.TrimSpace(path))
 	if cleanPath == "" {

internal/tasks/executor_test.go

@@ -8,6 +8,7 @@ import (
 	"io"
 	"os"
 	"os/exec"
+	"path/filepath"
 	"reflect"
 	"strconv"
 	"strings"
@@ -474,6 +475,99 @@ func TestShellExecutorExecutePropagatesExitCodeAndLogs(t *testing.T) {
 	}
 }
 
+func TestShellExecutorLogScanRootUsesOperationalScopeAndHelper(t *testing.T) {
+	t.Parallel()
+
+	executor := NewShellExecutor(5 * time.Minute)
+	executor.goos = "linux"
+	executor.lookPath = fakeLookPath(map[string]string{
+		"noderax-agent": "/usr/local/bin/noderax-agent",
+		"sudo":          "/usr/bin/sudo",
+	})
+
+	requestPath := filepath.Join(t.TempDir(), "operational-log-scan-request.json")
+	executor.operationalLogScanRequestPath = requestPath
+	executor.fileExists = func(path string) bool {
+		return path == linuxOperationalLogScanHelperPath
+	}
+
+	checkedScope := ""
+	executor.SetRootScopeChecker(func(scope string) bool {
+		checkedScope = scope
+		return scope == "operational"
+	})
+
+	recorder := &recordingCommandFactory{
+		runner: &fakeCommandRunner{stdoutText: "{}\n"},
+	}
+	executor.newCommand = recorder.factory
+
+	_, err := executor.Execute(context.Background(), api.Task{
+		Type: TaskTypeLogScan,
+		Payload: mustJSON(t, map[string]any{
+			"mode":           "preview",
+			"sourcePresetId": "auth.log",
+			"runAsRoot":      true,
+			"rootScope":      "task",
+		}),
+	}, nil)
+	if err != nil {
+		t.Fatalf("Execute returned error: %v", err)
+	}
+
+	if checkedScope != "operational" {
+		t.Fatalf("expected root scope checker to receive operational, got %q", checkedScope)
+	}
+
+	if recorder.name != "/usr/bin/sudo" {
+		t.Fatalf("command name mismatch: got %q want %q", recorder.name, "/usr/bin/sudo")
+	}
+
+	wantArgs := []string{"-n", linuxOperationalLogScanHelperPath}
+	if !reflect.DeepEqual(recorder.args, wantArgs) {
+		t.Fatalf("command args mismatch: got %v want %v", recorder.args, wantArgs)
+	}
+
+	requestBytes, err := os.ReadFile(requestPath)
+	if err != nil {
+		t.Fatalf("read operational request file: %v", err)
+	}
+	if !strings.Contains(string(requestBytes), `"sourcePresetId":"auth.log"`) {
+		t.Fatalf("unexpected request payload: %s", string(requestBytes))
+	}
+}
+
+func TestShellExecutorLogScanRootRejectsNonOperationalScope(t *testing.T) {
+	t.Parallel()
+
+	executor := NewShellExecutor(5 * time.Minute)
+	executor.goos = "linux"
+	executor.lookPath = fakeLookPath(map[string]string{
+		"noderax-agent": "/usr/local/bin/noderax-agent",
+		"sudo":          "/usr/bin/sudo",
+	})
+
+	recorder := &recordingCommandFactory{runner: &fakeCommandRunner{}}
+	executor.newCommand = recorder.factory
+
+	_, err := executor.Execute(context.Background(), api.Task{
+		Type: TaskTypeLogScan,
+		Payload: mustJSON(t, map[string]any{
+			"mode":           "preview",
+			"sourcePresetId": "auth.log",
+			"runAsRoot":      true,
+			"rootScope":      "terminal",
+		}),
+	}, nil)
+
+	if !errors.Is(err, ErrInvalidTaskPayload) {
+		t.Fatalf("expected ErrInvalidTaskPayload, got %v", err)
+	}
+	if recorder.calls != 0 {
+		t.Fatalf("expected no command execution, got %d calls", recorder.calls)
+	}
+}
+
 func TestCommandHelperProcess(t *testing.T) {
 	if os.Getenv("GO_WANT_HELPER_PROCESS") != "1" {
 		return