feat(derun): enrich error messages with deterministic details (#301)

## Summary
- add a shared `internal/errmsg` formatter for deterministic single-line
error details
- enrich derun runtime/usage/parse/required errors across CLI, MCP,
state, transport, retention, logging, capture, and session ID generation
- preserve compatibility-critical tokens (`session not found`, `parse
<field>`, `<field> is required`) while adding safe diagnostics
- keep sentinel compatibility by wrapping `ErrSessionNotFound` and
`ErrInvalidSessionID` with `%w`-compatible chains
- update derun docs contracts for the new `details` segment and
safe-data policy

## Testing
- `go test ./cmds/derun/...`

Author: kdy1

cmds/derun/internal/capture/writer.go

@@ -1,11 +1,11 @@
 package capture
 
 import (
-	"fmt"
 	"sync"
 	"time"
 
 	"github.com/delinoio/oss/cmds/derun/internal/contracts"
+	"github.com/delinoio/oss/cmds/derun/internal/errmsg"
 	"github.com/delinoio/oss/cmds/derun/internal/logging"
 	"github.com/delinoio/oss/cmds/derun/internal/state"
 )
@@ -35,7 +35,11 @@ func (w *Writer) Write(p []byte) (int, error) {
 	defer w.mu.Unlock()
 	offset, err := w.store.AppendOutput(w.sessionID, w.channel, p, time.Now().UTC())
 	if err != nil {
-		return 0, fmt.Errorf("append output: %w", err)
+		return 0, errmsg.Error(errmsg.Runtime("append output", err, map[string]any{
+			"session_id": w.sessionID,
+			"channel":    w.channel,
+			"chunk_size": len(p),
+		}), nil)
 	}
 	w.logger.Event("chunk_written", map[string]any{
 		"session_id":   w.sessionID,

cmds/derun/internal/cli/errors.go

@@ -1,17 +1,19 @@
 package cli
 
-import "fmt"
+import "github.com/delinoio/oss/cmds/derun/internal/errmsg"
 
 func formatUsageError(reason, hint string) string {
-	if hint == "" {
-		return fmt.Sprintf("invalid arguments: %s", reason)
-	}
-	return fmt.Sprintf("invalid arguments: %s; hint: %s", reason, hint)
+	return formatUsageErrorWithDetails(reason, hint, nil)
+}
+
+func formatUsageErrorWithDetails(reason, hint string, details map[string]any) string {
+	return errmsg.Usage(reason, hint, details)
 }
 
 func formatRuntimeError(action string, err error) string {
-	if err == nil {
-		return fmt.Sprintf("failed to %s", action)
-	}
-	return fmt.Sprintf("failed to %s: %v", action, err)
+	return formatRuntimeErrorWithDetails(action, err, nil)
+}
+
+func formatRuntimeErrorWithDetails(action string, err error, details map[string]any) string {
+	return errmsg.Runtime(action, err, details)
 }

cmds/derun/internal/cli/mcp.go

@@ -26,26 +26,43 @@ func ExecuteMCP(args []string) int {
 		return 2
 	}
 	if len(fs.Args()) != 0 {
+		firstArg := ""
+		if len(fs.Args()) > 0 {
+			firstArg = fs.Args()[0]
+		}
 		fmt.Fprintln(
 			os.Stderr,
-			formatUsageError("mcp command does not accept positional arguments", "use `derun mcp` without extra arguments"),
+			formatUsageErrorWithDetails(
+				"mcp command does not accept positional arguments",
+				"use `derun mcp` without extra arguments",
+				map[string]any{
+					"arg_count": len(fs.Args()),
+					"first_arg": firstArg,
+				},
+			),
 		)
 		return 2
 	}
 
 	stateRoot, err := resolveStateRootForMCP()
 	if err != nil {
-		fmt.Fprintln(os.Stderr, formatRuntimeError("resolve state root", err))
+		fmt.Fprintln(os.Stderr, formatRuntimeErrorWithDetails("resolve state root", err, map[string]any{
+			"has_derun_state_root": os.Getenv("DERUN_STATE_ROOT") != "",
+		}))
 		return 1
 	}
 	store, err := state.New(stateRoot)
 	if err != nil {
-		fmt.Fprintln(os.Stderr, formatRuntimeError("initialize state store", err))
+		fmt.Fprintln(os.Stderr, formatRuntimeErrorWithDetails("initialize state store", err, map[string]any{
+			"state_root": stateRoot,
+		}))
 		return 1
 	}
 	logger, err := logging.New(stateRoot)
 	if err != nil {
-		fmt.Fprintln(os.Stderr, formatRuntimeError("initialize logger", err))
+		fmt.Fprintln(os.Stderr, formatRuntimeErrorWithDetails("initialize logger", err, map[string]any{
+			"state_root": stateRoot,
+		}))
 		return 1
 	}
 	defer logger.Close()
@@ -54,7 +71,11 @@ func ExecuteMCP(args []string) int {
 
 	server := mcp.NewServer(store, logger, 10*time.Minute, defaultRetention)
 	if err := server.Serve(context.Background(), os.Stdin, os.Stdout); err != nil {
-		fmt.Fprintln(os.Stderr, formatRuntimeError("run mcp server", err))
+		fmt.Fprintln(os.Stderr, formatRuntimeErrorWithDetails("run mcp server", err, map[string]any{
+			"state_root":     stateRoot,
+			"gc_interval_ms": (10 * time.Minute).Milliseconds(),
+			"retention_ms":   defaultRetention.Milliseconds(),
+		}))
 		return 1
 	}
 	return 0

cmds/derun/internal/cli/root.go

@@ -30,7 +30,14 @@ func Execute(args []string) int {
 	default:
 		fmt.Fprintln(
 			os.Stderr,
-			formatUsageError(fmt.Sprintf("unknown command %q", args[0]), "run `derun help` to see available commands"),
+			formatUsageErrorWithDetails(
+				fmt.Sprintf("unknown command %q", args[0]),
+				"run `derun help` to see available commands",
+				map[string]any{
+					"command":   args[0],
+					"arg_count": len(args),
+				},
+			),
 		)
 		printUsage()
 		return 2
@@ -45,7 +52,11 @@ func executeHelp(args []string) int {
 	if len(args) > 1 {
 		fmt.Fprintln(
 			os.Stderr,
-			formatUsageError("help command accepts at most one topic", "use `derun help` or `derun help <run|mcp>`"),
+			formatUsageErrorWithDetails(
+				"help command accepts at most one topic",
+				"use `derun help` or `derun help <run|mcp>`",
+				map[string]any{"topic_count": len(args)},
+			),
 		)
 		return 2
 	}
@@ -60,7 +71,11 @@ func executeHelp(args []string) int {
 	default:
 		fmt.Fprintln(
 			os.Stderr,
-			formatUsageError(fmt.Sprintf("unknown help topic %q", args[0]), "use `derun help` to list supported topics"),
+			formatUsageErrorWithDetails(
+				fmt.Sprintf("unknown help topic %q", args[0]),
+				"use `derun help` to list supported topics",
+				map[string]any{"topic": args[0]},
+			),
 		)
 		printUsage()
 		return 2

cmds/derun/internal/cli/run.go

@@ -2,13 +2,13 @@ package cli
 
 import (
 	"errors"
-	"fmt"
 	"os"
 	"runtime"
 	"strings"
 	"time"
 
 	"github.com/delinoio/oss/cmds/derun/internal/contracts"
+	"github.com/delinoio/oss/cmds/derun/internal/errmsg"
 	"github.com/delinoio/oss/cmds/derun/internal/logging"
 	"github.com/delinoio/oss/cmds/derun/internal/session"
 	"github.com/delinoio/oss/cmds/derun/internal/state"
@@ -83,10 +83,24 @@ func selectTransportMode(ttyAttached bool, goos string) contracts.DerunTransport
 
 func validateRetentionDuration(retentionDuration time.Duration) error {
 	if retentionDuration <= 0 {
-		return errors.New(formatUsageError("retention must be positive", "use values like 1s, 5m, or 24h"))
+		return errors.New(formatUsageErrorWithDetails(
+			"retention must be positive",
+			"use values like 1s, 5m, or 24h",
+			map[string]any{
+				"retention":    retentionDuration.String(),
+				"retention_ms": retentionDuration.Milliseconds(),
+			},
+		))
 	}
 	if retentionDuration%time.Second != 0 {
-		return errors.New(formatUsageError("retention must use whole-second precision", "use values like 1s, 30s, or 5m"))
+		return errors.New(formatUsageErrorWithDetails(
+			"retention must use whole-second precision",
+			"use values like 1s, 30s, or 5m",
+			map[string]any{
+				"retention":    retentionDuration.String(),
+				"retention_ms": retentionDuration.Milliseconds(),
+			},
+		))
 	}
 	return nil
 }
@@ -99,14 +113,20 @@ func resolveStateRootForRun() (string, error) {
 }
 
 func generateUniqueSessionID(store *state.Store, logger *logging.Logger) (string, error) {
-	for attempt := 1; attempt <= 5; attempt++ {
+	const maxAttempts = 5
+	for attempt := 1; attempt <= maxAttempts; attempt++ {
 		sessionID, err := session.NewULID(time.Now().UTC())
 		if err != nil {
-			return "", err
+			return "", errors.New(formatRuntimeErrorWithDetails("generate candidate session id", err, map[string]any{
+				"attempt": attempt,
+			}))
 		}
 		hasMetadata, err := store.HasSessionMetadata(sessionID)
 		if err != nil {
-			return "", err
+			return "", errors.New(formatRuntimeErrorWithDetails("check candidate session metadata", err, map[string]any{
+				"attempt":    attempt,
+				"session_id": sessionID,
+			}))
 		}
 		if !hasMetadata {
 			return sessionID, nil
@@ -116,7 +136,9 @@ func generateUniqueSessionID(store *state.Store, logger *logging.Logger) (string
 			"attempt":    attempt,
 		})
 	}
-	return "", fmt.Errorf("too many session id collisions")
+	return "", errmsg.Error("too many session id collisions", map[string]any{
+		"attempt_limit": maxAttempts,
+	})
 }
 
 func derefInt(v *int) int {