Add additional subprocess diagnostics for the audita interface

internal/adapters/audita/subprocess.go

@@ -189,11 +189,16 @@ func (r *SubprocessRunner) Run(ctx context.Context, req PolishRequest) (PolishRe
 		StderrLogPath: req.StderrLogPath,
 	})
 	if err != nil {
-		return r.failureResult(req, reqModules, runRes, credentialPresent, primaryConcurrencyViaEnv), fmt.Errorf(
-			"run audita process (binary=%q, stdout_log=%q, stderr_log=%q): %w",
+		wrappedMessage := fmt.Sprintf(
+			"run audita process (binary=%q, stdout_log=%q, stderr_log=%q)",
 			r.binary,
 			req.StdoutLogPath,
 			req.StderrLogPath,
+		)
+		wrappedMessage = addSubprocessStreamHint(wrappedMessage, err)
+		return r.failureResult(req, reqModules, runRes, credentialPresent, primaryConcurrencyViaEnv), fmt.Errorf(
+			"%s: %w",
+			wrappedMessage,
 			err,
 		)
 	}
@@ -328,6 +333,17 @@ func validateProcessedOutput(path string) error {
 	return nil
 }
 
+func addSubprocessStreamHint(message string, runErr error) string {
+	if runErr == nil {
+		return message
+	}
+	lower := strings.ToLower(runErr.Error())
+	if strings.Contains(lower, "bad file descriptor") || strings.Contains(lower, "exit code 120") {
+		return message + "; hint=audita child process may have started with invalid stderr/stdout descriptors"
+	}
+	return message
+}
+
 func validateJSONFile(path string) error {
 	data, err := os.ReadFile(path)
 	if err != nil {

internal/adapters/audita/subprocess_test.go

@@ -247,6 +247,36 @@ func TestSubprocessRunnerSubprocessFailure(t *testing.T) {
 	}
 }
 
+func TestSubprocessRunnerSubprocessFailureAddsStderrDescriptorHint(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("helper wrapper script uses /bin/sh")
+	}
+	t.Setenv("GO_WANT_AUDITA_HELPER", "1")
+	t.Setenv("AUDITA_HELPER_MODE", "fail_bad_fd")
+	t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
+	t.Setenv("AUDITA_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))
+
+	llmConcurrency := 1
+	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
+		Binary:         writeAuditaHelperWrapper(t),
+		Timeout:        mustParseAuditaDuration(t, "2s"),
+		LLMAPIKeyEnv:   "OPENAI_KEY_SOURCE",
+		Modules:        []string{"glossary"},
+		BaseURL:        "https://openrouter.ai/api/v1",
+		Model:          "openrouter/google/gemma-4-31b-it",
+		LLMConcurrency: &llmConcurrency,
+		Report:         true,
+	})
+	req := auditaReqForTest(t, true)
+	_, err := runner.Run(context.Background(), req)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "hint=audita child process may have started with invalid stderr/stdout descriptors") {
+		t.Fatalf("error = %q, want stderr descriptor hint", err.Error())
+	}
+}
+
 func TestSubprocessRunnerMissingOutputFails(t *testing.T) {
 	if runtime.GOOS == "windows" {
 		t.Skip("helper wrapper script uses /bin/sh")
@@ -442,6 +472,9 @@ func TestAuditaSubprocessHelper(t *testing.T) {
 	case "fail":
 		_, _ = os.Stderr.WriteString("audita helper failure\n")
 		os.Exit(8)
+	case "fail_bad_fd":
+		_, _ = os.Stderr.WriteString("OSError: [Errno 9] Bad file descriptor\n")
+		os.Exit(120)
 	case "missing_output":
 		if reportPath != "" {
 			writeAuditaHelperFile(reportPath, `{"schema":"audita.report.v1","steps":[]}`)