JuliusBrussee/caveman · error

unsafe recovery failure result

Error message

unsafe recovery failure result: %w

What it means

emitCompressResult wraps the original compression error with "unsafe recovery failure result" when the engine is configured to pass through on CCR (compression) failure but the returned Result does not look like a genuine pass-through: the output differs from the input, PassedThrough() is false, or token counts changed. The engine refuses to emit a contradictory result (claiming recovery while altering bytes) rather than guessing what to print. The wrapped original compressErr is preserved for diagnosis.

Solutions

1. Inspect the wrapped compressErr to see why CCR failed, then check the compressor that produced res — it must return the untouched input bytes when failing.
2. Ensure the compressor sets PassedThrough() and leaves TokensAfter == TokensBefore on any error-path result.
3. If input legitimately changed, fix the compressor to fail closed (return input unchanged) rather than expecting the emitter to accept it.

Example fix

// before: compressor transforms then errors
out := transform(input) // mutated
return Result{Output: out}, err
// after: fail closed with original bytes
return Result{Output: input, PassedThrough: true, TokensAfter: n, TokensBefore: n}, err

if compressErr != nil && (!bytes.Equal(res.Output, input) || !res.PassedThrough() || res.TokensAfter != res.TokensBefore) {
    // refuse to emit; log both compressErr and the offending Result
}

if err := emitCompressResult(input, res, compressErr, stdout, stderr); err != nil {
    var unsafe *emitError
    if errors.As(err, &unsafe) { log.Fatalf("compressor violated pass-through invariant: %v", err) }
}

When it happens

Trigger: runCompress received a non-nil compressErr (e.g. ccr.ErrBudgetExceeded or other CCR failure) but the compress pipeline returned a res whose Output != input, res.PassedThrough() == false, or res.TokensAfter != res.TokensBefore — i.e. a bug or misbehaving compressor produced transformed bytes alongside a failure.

Common situations: A new compressor stage mutates output before failing; a change to Result accounting (TokensAfter/TokensBefore) breaks the pass-through invariant; a caller wires a compressor that returns partially-transformed data on error instead of the original input.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• bedrock request path
• cave_claude_terminal_missing
• cave_harness_model_identity_missing
• cave_sandbox_child_process_containment_unavailable
• cave_sandbox_network_egress_unbounded

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/af6350a38d26eb9f. Report an issue: GitHub.

Appendix: source

Thrown at engine/cmd/caveman-engine/main.go:125

	if err := emitCompressResult(input, res, err, os.Stdout, os.Stderr); err != nil {
		fatal("compress: %v", err)
	}
}

type compressReport struct {
	engine.Result
	Error string `json:"error,omitempty"`
}

// emitCompressResult preserves the engine's byte-safety contract at the CLI
// boundary. CCR failures are expected operational conditions: the engine has
// already returned an accounted pass-through result, so stdout must still get
// the original bytes. Any contradictory result fails rather than guessing.
func emitCompressResult(input []byte, res engine.Result, compressErr error, stdout, stderr io.Writer) error {
	code := ""
	if compressErr != nil {
		if !bytes.Equal(res.Output, input) || !res.PassedThrough() || res.TokensAfter != res.TokensBefore {
			return fmt.Errorf("unsafe recovery failure result: %w", compressErr)
		}
		code = "cave_ccr_unavailable"
		if errors.Is(compressErr, ccr.ErrBudgetExceeded) {
			code = "cave_ccr_budget_exceeded"
		}
	}
	if _, err := stdout.Write(res.Output); err != nil {
		return fmt.Errorf("write stdout: %w", err)
	}
	// Report stays on stderr so stdout remains clean payload bytes.
	report, err := json.Marshal(compressReport{Result: res, Error: code})
	if err != nil {
		return fmt.Errorf("encode report: %w", err)
	}
	if _, err := fmt.Fprintln(stderr, string(report)); err != nil {
		return fmt.Errorf("write report: %w", err)
	}
	return nil

View on GitHub (pinned to 3ee70a1026)