feat(#353): cost_exceeded_action:fail — make per-node cost caps safe

A per-node max_cost_usd breach always routed OutcomeRetry, which re-runs (and
multiplies the cost of) an expensive, uncached node — so capping the runaway
review lane from the case study would burn up to 3× the cap before giving up,
often worse than uncapped. That retry-multiplier is why capping the reviewers
couldn't be done safely.

New `cost_exceeded_action: fail` node attr routes the node's fail edges
immediately on a cost breach (no retry), so a cap is safe to place on a lane that
should escalate rather than re-run. In build_product the reviewers' fail path
already routes to EscalateReview (a human gate), so a capped-then-failed reviewer
escalates cleanly. Default stays "retry" (unchanged behavior).

This ships the enabling primitive; the cap *value* on build_product's reviewers
needs real-run cost data to calibrate (too low → false escalations), so that .dip
edit is deliberately left for a run rather than guessed blind. Combined with the
already-shipped `tracker diagnose` cost-asymmetry detector, #353 now has both the
"make it visible" and the "make a cap safe" halves.

Tests: cost_exceeded_action=fail routes OutcomeFail (not Retry) while still
setting node_cost_exceeded for fail-edge conditions.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01GVTTPqhd6w2tzmgwEqJpL3

Author: clintecker

CHANGELOG.md

@@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`cost_exceeded_action: fail` — safe per-node cost caps (#353).** A per-node
+  cost ceiling (`max_cost_usd`) previously always routed `retry` on breach, which
+  re-runs (and multiplies the cost of) an expensive, uncached node — so capping a
+  runaway review lane could make it *worse*. The new `cost_exceeded_action: fail`
+  attr routes the node's fail edges immediately on breach (no retry), so a cap is
+  safe to place on a lane that should escalate rather than re-run. Default stays
+  `retry` (unchanged). This is the primitive #353's reviewer-cap fix needs;
+  choosing the cap value + wiring it into `build_product`'s reviewers is left to a
+  real run to calibrate.
+
 - **Test-fidelity check: `tracker verify-tests [dir]` (#489, core).** Flags Go
   test functions that share a body — byte-for-byte duplicates and near-duplicates
   that differ only in literal values — the exact "a required test is a copy of

pipeline/handlers/codergen.go

@@ -527,8 +527,14 @@ func (h *CodergenHandler) buildNodeCostExceededOutcome(node *pipeline.Node, prom
 			Timestamp: time.Now(),
 		})
 	}
+	// Default retries within budget; cost_exceeded_action: fail routes fail edges
+	// immediately so a cap doesn't re-run (and multiply) an expensive node (#353).
+	status := pipeline.OutcomeRetry
+	if node.AgentConfig(h.graphAttrs).CostExceededAction == "fail" {
+		status = pipeline.OutcomeFail
+	}
 	outcome := pipeline.Outcome{
-		Status: pipeline.OutcomeRetry,
+		Status: status,
 		ContextUpdates: map[string]string{
 			pipeline.ContextKeyLastResponse:             msg,
 			pipeline.ContextKeyResponsePrefix + node.ID: msg,

pipeline/handlers/codergen_guards_test.go

@@ -50,6 +50,35 @@ func TestCodergenNodeCostExceededRoutesToRetry(t *testing.T) {
 	}
 }
 
+func TestCodergenCostExceededActionFailRoutesToFail(t *testing.T) {
+	// cost_exceeded_action: fail → the cap routes fail edges immediately (no
+	// retry), so an expensive node can't be re-run and multiply the cost (#353).
+	client := &scriptedCompleter{responses: []*llm.Response{
+		truncatedCostResponse(0.006),
+		truncatedCostResponse(0.006),
+	}}
+	h := NewCodergenHandler(client, t.TempDir())
+	node := &pipeline.Node{
+		ID: "review", Shape: "box", Handler: "codergen",
+		Attrs: map[string]string{
+			"prompt":               "review something expensive",
+			"max_cost_usd":         "0.01",
+			"cost_exceeded_action": "fail",
+		},
+	}
+	outcome, err := h.Execute(context.Background(), node, pipeline.NewPipelineContext())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if outcome.Status != pipeline.OutcomeFail {
+		t.Errorf("want %q with cost_exceeded_action=fail, got %q", pipeline.OutcomeFail, outcome.Status)
+	}
+	// The guard flag is still set so fail-edge routing can condition on it.
+	if outcome.ContextUpdates[pipeline.ContextKeyNodeCostExceeded] != "true" {
+		t.Errorf("node_cost_exceeded should still be set, got %q", outcome.ContextUpdates[pipeline.ContextKeyNodeCostExceeded])
+	}
+}
+
 func TestCodergenNoProgressDetectedRoutesToRetry(t *testing.T) {
 	// no_progress_turns=2: two consecutive truncated turns without tool calls → no-progress fires.
 	client := &scriptedCompleter{responses: []*llm.Response{

pipeline/node_config.go

@@ -33,8 +33,14 @@ type AgentNodeConfig struct {
 	MaxBudgetUSD    float64
 	MaxCostUSD      float64 // #304: per-node cost ceiling in USD; 0 = unlimited
 	NoProgressTurns int     // #304: halt after K consecutive tool-call-free turns; 0 = disabled
-	PermissionMode  string
-	ACPAgent        string
+	// CostExceededAction controls what happens when MaxCostUSD is breached:
+	// "retry" (default — re-run within retry budget) or "fail" (route fail edges
+	// immediately, no retry). "fail" makes a cap safe on an expensive, uncached
+	// node whose retries would multiply the cost (#353) — e.g. a review lane that
+	// should escalate rather than re-run.
+	CostExceededAction string
+	PermissionMode     string
+	ACPAgent           string
 
 	// ToolAccess restricts the agent's tool surface. When non-empty (any
 	// value), the runtime registers zero tools, sets ToolChoice=none on
@@ -138,6 +144,7 @@ func (n *Node) AgentConfig(graphAttrs map[string]string) AgentNodeConfig {
 	cfg.PermissionMode = n.Attrs["permission_mode"]
 	cfg.ToolAccess = n.Attrs["tool_access"]
 	cfg.ACPAgent = n.Attrs["acp_agent"]
+	cfg.CostExceededAction = n.Attrs["cost_exceeded_action"]
 	cfg.SystemPrompt = n.Attrs["system_prompt"]
 	cfg.ResponseFormat = n.Attrs["response_format"]
 	cfg.ResponseSchema = n.Attrs["response_schema"]