fix(runner): an inapplicable cap is not an unsafe one (#185)

* fix(runner): an inapplicable cap is not an unsafe one

Codex preflight refused `agent:` and `budget_usd` with the same sentence,
and they are not the same kind of thing. `agent:` names a Claude Code
subagent — without it the node runs without that agent's system prompt,
so it is a different node, and refusing stays correct. `budget_usd` is a
USD ceiling over a runtime that reports no USD: there is no quantity to
bound, which makes it inapplicable rather than unsafe.

ValidateGraphForRuntime now returns warnings alongside its error. A
budgeted node under codex loads and warns that the cap cannot apply,
naming the guard still in force — its own `timeout:` or the runner's
default — quoted from the constant the CLIRunner applies. The runaway
guard was never the budget: graphs/fragments/e2e-verify.yaml says so
beside its own `budget_usd: 10.00` ("The hang guard is `timeout:`, not
the budget").

Measured, `--runtime codex lint graphs/*.yaml`: five of eight graphs
refused before, one after — adr-driven-dev, for `agent:`.

`auto --max-goal-budget-usd` stays refused, deliberately: a goal ceiling
is the ONLY bound on an iterating loop, so an unmeasurable one would stop
at its first cycle boundary with StopBudgetUnmeasurable having bought a
cycle to learn what preflight says for free.

All five call sites surface the warnings through one helper; `run` alone
discards executeGraph's second copy, having already printed the list in
its pre-run disclosure. A nil writer there means stderr, never silence.

shipped_graphs_runtime_test.go lints every embedded graph under both
runtimes and asserts the verdict per named graph, with its reason, so a
graph that becomes unloadable under Codex fails `make test` by name.

The Claude path does not move: ValidateGraphForRuntime still returns on
its first line for RuntimeClaude. --help, version, lint and --dry-run
over all eight shipped graphs are byte-identical to HEAD's binary.

Refs: ADR 0026, amending ADR 0025.

Co-Authored-By: oh-my-graph <graphs@oh-my-graph.dev>

Signed-off-by: jitokim <pigberger70@gmail.com>

* fix(runner): the goal ceiling is not the only bound, and say so

ADR 0026 justified refusing `auto --max-goal-budget-usd` on a premise the
code denies: that a goal ceiling is the ONLY bound on an iterating loop.
flags.go refuses the flag unless --max-cycles >= 2, and its own comment
says the cycle flag IS the bound with no unbounded spelling (ADR 0011 §1).
Drop the ceiling and the loop is still hard-bounded — the exact parallel
to a node keeping its `timeout:` that the record spends a section denying.

The sound argument was already there and is verifiable: goal.go checks the
ceiling only inside its `cycle > 1` block, so accepting an unmeasurable one
buys a whole cycle before StopBudgetUnmeasurable says what preflight says
for free, while an inapplicable node cap costs nothing extra. That is now
the reason in all six places the claim appears — preflight.go's doc,
noteCodexRuntimePolicy, ADR 0026 §2, CHANGELOG, LIMITATIONS, EXAMPLES —
with "only bound" demoted to "only spend-shaped bound".

README.ko.md still said all three declarations are refused before
execution; the English paragraph was rewritten in 773ba51 and its mirror
was not. Ported. This mirror has drifted twice before (CHANGELOG:487,
:1336).

Three new tests in cmd/oh-my-graph/runtime_test.go pin the claim that made
the split worth making — that every call site PRINTS. `lint` and
`--dry-run` are pinned at their spawn-free sites, and `run` is pinned to
print the list EXACTLY once counted across stdout and stderr together, so
the fix for a double print cannot be to move one copy where the test is
not looking. Mutation-checked: `_ = runtimeWarnings` at either spawn-free
site, or dropping `run`'s io.Discard, turns each red; before this they
stayed green.

shipped_graphs_runtime_test.go counts a graph's warnings instead of
asserting presence, because ADR 0026 §1's table records counts: stripping
one of review-loop's two caps was green under the bool and now fails by
name with both numbers.

`run` also passes flags.graphPath rather than "", so its warning carries
the same `<path>: ` prefix as the other four sites, and warnRuntimePreflight
now documents why `run` alone routes to stdout — the disclosure block below
refers back to those lines, and a reference split from its referent across
two streams reads worse than the inconsistency. The 2026-08-14 plan record
gets a banner for the one item ADR 0026 reversed.

The Claude path still does not move: lint and --dry-run over all eight
shipped graphs, --help, bare `run` and bare `auto` are byte-identical in
stdout, stderr and exit to 773ba51's binary.

Refs: ADR 0026.

Co-Authored-By: oh-my-graph <graphs@oh-my-graph.dev>

Signed-off-by: jitokim <pigberger70@gmail.com>

---------

Signed-off-by: jitokim <pigberger70@gmail.com>

Author: jitokim

CHANGELOG.md

@@ -10,6 +10,28 @@ oh-my-graph is **alpha software**. The graph YAML schema, the CLI, and the
 
 ## [Unreleased]
 
+### Changed
+
+- **A node's `budget_usd` no longer refuses a Codex graph
+  ([ADR 0026](docs/adr/0026-an-inapplicable-cap-is-not-an-unsafe-one.md)).**
+  Preflight had one sentence for two different facts: `agent:` names a subagent
+  whose system prompt the node would otherwise lose (a different node — still
+  refused), while `budget_usd` is a USD ceiling a runtime that reports no USD
+  has nothing to bound. Inapplicable is not unsafe, so the graph now loads and
+  warns per node, naming the guard still in force — that node's `timeout:`, or
+  the runner's 20m default. Measured on `graphs/*.yaml`: **five refused under
+  `--runtime codex` before, one after** (`adr-driven-dev`, for its `agent:`).
+  `auto --max-goal-budget-usd` stays refused and that is not an inconsistency:
+  it is checked only at a cycle boundary, so an unmeasurable ceiling would buy a
+  whole cycle before stopping to say it cannot be checked, where an inapplicable
+  node cap costs nothing extra. The loop stays bounded either way —
+  `--max-cycles` is what bounds iterations.
+  `internal/runner/shipped_graphs_runtime_test.go` now lints every shipped
+  graph under both runtimes and asserts the verdict by name, so a graph that
+  becomes unloadable under Codex fails `make test` instead of a user's run.
+  **The Claude path is unchanged**: `ValidateGraphForRuntime` still returns on
+  its first line for `RuntimeClaude`, warning nothing and refusing nothing.
+
 ## [v0.8.0] - 2026-08-15
 
 **Minor because the CLI grew a token you may type.** Compared by name rather

DESIGN.md

@@ -33,8 +33,10 @@ the selected protocol reports and uses it for `handoff: session`.
 
 Codex reports token usage but no USD total. `CostUnknown` is durable through
 the ledger, `state.json`, `events.jsonl`, CLI history views and web UI; it must
-never render as `$0`. Positive `budget_usd`, `agent:`, and the goal-level USD
-budget are refused at preflight for Codex.
+never render as `$0`. `agent:` and the goal-level USD budget are refused at
+preflight for Codex; a node's `budget_usd` is not (ADR 0026) — it loads with a
+warning saying the cap cannot apply and naming the guard that still holds, that
+node's own `timeout:` or the runner's default.
 
 ## Node runtime mechanics (ground truth — use exactly)
 

README.ko.md

@@ -76,8 +76,11 @@ Codex는 `permission_mode: plan`을 read-only sandbox로, 일반 모드를
 `workspace-write`로, `bypassPermissions`를 `danger-full-access`로 매핑합니다.
 이 sandbox는 네트워크 경계이기도 해서, Codex 그래프는 push하거나 `gh`를
 호출하는 첫 번째 노드에서 멈춥니다.
-Codex에는 Claude의 호출별 `budget_usd`와 `agent:` 선택자가 없고 USD도 보고하지
-않으므로, 이 두 graph field와 `--max-goal-budget-usd`는 실행 전에 거부합니다.
+Codex는 USD를 보고하지 않고 Claude의 `agent:` 선택자도 구현하지 않으므로,
+`agent:`와 `--max-goal-budget-usd`는 Codex run이 무언가를 쓰기 전에 거부합니다.
+노드의 `budget_usd`는 거부하지 않습니다. 묶을 USD가 없어 그저 적용될 수 없을
+뿐이므로, 그래프는 로드되고 노드마다 경고 한 줄이 그 사실과 함께 여전히 그
+노드를 지키는 `timeout:`을 알려줍니다.
 Claude Code agent mapping과 skill activation은 Claude 전용이며, Codex `auto`는
 Codex sandbox isolation을 사용합니다.
 

README.md

@@ -72,9 +72,11 @@ Codex maps `permission_mode: plan` to its read-only sandbox, ordinary modes to
 `workspace-write`, and `bypassPermissions` to `danger-full-access`. That sandbox
 is also a network boundary, so a Codex graph halts at its first node that
 pushes or calls `gh`. Codex does
-not report USD or implement Claude's per-call `budget_usd` and `agent:`
-selector, so those two graph fields and `--max-goal-budget-usd` are rejected
-before a Codex run spends anything. Claude Code agent mapping and skill
+not report USD or implement Claude's `agent:` selector, so `agent:` and
+`--max-goal-budget-usd` are rejected before a Codex run spends anything. A
+node's `budget_usd` is not rejected: with no USD to bound it simply cannot
+apply, so the graph loads and one warning per node says so and names the
+`timeout:` that still guards it. Claude Code agent mapping and skill
 activation are Claude-only; Codex `auto` runs use Codex sandbox isolation
 instead.
 

SECURITY.md

@@ -151,8 +151,10 @@ assessor do not. A hand-written graph also keeps the user's normal config,
 matching the existing reviewed-artifact boundary.
 
 This is a filesystem sandbox stance, not granular enforcement of
-`allowed_tools`. Positive `budget_usd`, `agent:`, and the goal-level USD budget
-flag are rejected for Codex rather than silently ignored. Claude agent mapping
+`allowed_tools`. `agent:` and the goal-level USD budget flag are rejected for
+Codex rather than silently ignored. A node's `budget_usd` is neither rejected
+nor silently ignored: it is accepted with a warning that the cap cannot apply
+and that the node's `timeout:` is the guard still in force (ADR 0026). Claude agent mapping
 and skill activation are not attempted. Codex USD cost is recorded as unknown;
 its provider-reported token counts are the accounting surface.
 

cmd/oh-my-graph/dryrun.go

@@ -40,7 +40,9 @@ func dryRunGraphForRuntime(w, warnW io.Writer, path string, inputs map[string]st
 	}
 
 	g := loaded.Graph
-	if err := runner.ValidateGraphForRuntime(runtime, g); err != nil {
+	runtimeWarnings, err := runner.ValidateGraphForRuntime(runtime, g)
+	warnRuntimePreflight(warnW, path, runtimeWarnings)
+	if err != nil {
 		return err
 	}
 	warnAdvisories(warnW, path, g)

cmd/oh-my-graph/flags.go

@@ -23,6 +23,14 @@ type commonRunFlags struct {
 	noWeb               bool
 	planningCostUnknown bool
 	planningUsage       runner.TokenUsage
+	// runtimeWarnW receives the runtime-preflight warnings executeGraph's own
+	// runner.ValidateGraphForRuntime call produces (ADR 0026). Not a flag: the
+	// caller's answer to "have these already been shown?". `run` sets it to
+	// io.Discard because it surfaced the identical list at load, as part of the
+	// pre-run Codex disclosure; every other entry to executeGraph leaves it nil,
+	// which means os.Stderr — nil must never mean silence, or the one path that
+	// forgets to set it drops the warning.
+	runtimeWarnW io.Writer
 }
 
 func (c *commonRunFlags) register(set *flag.FlagSet) {

cmd/oh-my-graph/lint.go

@@ -76,7 +76,9 @@ func lintGraphForRuntime(w, warnW io.Writer, path string, runtime runner.Runtime
 		return err
 	}
 	if len(issues) == 0 {
-		if err := runner.ValidateGraphForRuntime(runtime, loaded.Graph); err != nil {
+		runtimeWarnings, err := runner.ValidateGraphForRuntime(runtime, loaded.Graph)
+		warnRuntimePreflight(warnW, path, runtimeWarnings)
+		if err != nil {
 			return err
 		}
 		printFragmentResolutions(w, loaded.Resolutions)
@@ -118,6 +120,33 @@ func warnAdvisories(warnW io.Writer, path string, g *graph.Graph) {
 	}
 }
 
+// warnRuntimePreflight prints one `warning:` line per runtime-preflight
+// warning — today, a `budget_usd` the selected runtime cannot evaluate
+// (ADR 0026). It is called at EVERY runner.ValidateGraphForRuntime call site,
+// including the ones whose call also returns an error: the two verdicts are
+// independent (a graph refused for `agent:` may also carry an inapplicable
+// cap), and a warning nobody prints is exactly the silent drop the split
+// exists to avoid. path may be empty, for the callers that judge a graph in
+// memory rather than a file on disk. Advice only: never an exit code.
+//
+// The writer is the caller's, and the callers do not all pick the same stream:
+// `lint`, `--dry-run`, `resume` and executeGraph's default put these on stderr
+// with every other `warning:` line, while `run` deliberately routes them to the
+// stdout its pre-run Codex DISCLOSURE prints on. That is not drift. The
+// disclosure block immediately below them (noteCodexRuntimePolicy) refers back
+// to these very lines — "each such node is warned by name" — and a reference
+// that lands on a different stream than its referent is a worse read than a
+// warning that is not on the advisory channel.
+func warnRuntimePreflight(warnW io.Writer, path string, warnings []string) {
+	for _, warning := range warnings {
+		if path == "" {
+			fmt.Fprintf(warnW, "warning: %s\n", warning)
+			continue
+		}
+		fmt.Fprintf(warnW, "warning: %s: %s\n", path, warning)
+	}
+}
+
 // warnFragmentAdvisories prints one `warning:` line per fragment-file
 // advisory (ADR 0013 — e.g. a declared substitution point the fragment body
 // never references). Same standing as warnAdvisories: advice only, never an

cmd/oh-my-graph/main.go

@@ -298,11 +298,19 @@ func runGraphWithRuntime(runtime runner.Runtime, args []string, nodeRunner runne
 		return err
 	}
 	g := loaded.Graph
-	if err := runner.ValidateGraphForRuntime(runtime, g); err != nil {
+	runtimeWarnings, err := runner.ValidateGraphForRuntime(runtime, g)
+	// Part of the pre-run disclosure, so it prints where the rest of the Codex
+	// policy prints and not on a stream the reader may not be watching. The
+	// identical list is produced again inside executeGraph, which is the gate
+	// `auto` and a chat-started graph reach WITHOUT passing here; runtimeWarnW
+	// below tells that call not to print this run's copy twice.
+	warnRuntimePreflight(stdout, flags.graphPath, runtimeWarnings)
+	if err != nil {
 		return err
 	}
 	noteCodexRuntimePolicy(stdout, runtime, g, false)
 	flags.runtime = runtime
+	flags.runtimeWarnW = io.Discard
 	printFragmentResolutions(os.Stdout, loaded.Resolutions)
 	// The advisory half of the same disclosure, through the same helper `lint`
 	// and `--dry-run` use: a run that announces which fragments it spliced must
@@ -739,7 +747,17 @@ func executeGraph(ctx context.Context, runID string, g *graph.Graph, nodeRunner
 		runtime = runner.RuntimeClaude
 	}
 	flags.runtime = runtime
-	if err := runner.ValidateGraphForRuntime(runtime, g); err != nil {
+	runtimeWarnings, err := runner.ValidateGraphForRuntime(runtime, g)
+	// The last gate before anything spends, and the ONLY one an `auto` or
+	// chat-started graph passes through, so it surfaces its own copy (ADR 0026).
+	// A nil writer means stderr; `run` alone passes io.Discard, having already
+	// printed this list beside the rest of its Codex disclosure.
+	runtimeWarnW := flags.runtimeWarnW
+	if runtimeWarnW == nil {
+		runtimeWarnW = os.Stderr
+	}
+	warnRuntimePreflight(runtimeWarnW, graphSourcePath, runtimeWarnings)
+	if err != nil {
 		return err
 	}
 	// The leg holds the run's resume.lock for its whole duration — the same
@@ -1085,6 +1103,7 @@ func noteCodexRuntimePolicy(w io.Writer, runtime runner.Runtime, g *graph.Graph,
 	fmt.Fprintln(w, "    Last node: adr-driven-dev (finalize), and every user of graphs/fragments/pr-publish.yaml (self-dev, dev-review-pr, backlog-batch). First node: apply-flags (dev pushes before verify reads). Every node: merge-shepherd, which is `gh` end to end and fails at node 1 having done nothing.")
 	fmt.Fprintln(w, "    Two remedies, both per node: permission_mode: bypassPermissions maps to danger-full-access, which is no sandbox — that node keeps network AND keyring. Or Codex's sandbox_workspace_write.network_access=true, which lifts the block for `git push`/`git ls-remote` but not for `gh` on a machine where gh's token is in an OS keyring the sandbox denies (measured 2026-08-14, macOS: \"no oauth token found for github.com\"; where no keyring exists gh reads ~/.config/gh/hosts.yml, which the sandbox can read).")
 	fmt.Fprintln(w, "  Cost is unknown for every Codex node: tokens are counted, USD never is, so this run reports no dollar figure per node or in total.")
+	fmt.Fprintln(w, "  A node's budget_usd therefore loads but cannot apply — there is no spend to compare it against, and that node's runaway guard is its timeout: (each such node is warned by name). `auto --max-goal-budget-usd` is refused instead, because it is checked only at a cycle boundary: an unmeasurable ceiling would buy a whole cycle before stopping to say it cannot be checked, where an inapplicable node cap costs nothing extra. The loop stays bounded either way — --max-cycles is what bounds iterations (ADR 0026).")
 	fmt.Fprintln(w, "  approval_policy=\"never\" is passed on every node: a non-interactive run cannot answer a prompt, so nothing is escalated for approval.")
 	fmt.Fprintln(w, "  No session-limit pause: ADR 0009's resumable pause is Claude-only, so a Codex session limit is an ordinary node failure (ADR 0009 scopes it to the Claude runtime).")
 	if isolated {

cmd/oh-my-graph/resume.go

@@ -355,7 +355,13 @@ func continueRun(flags *resumeFlags, snap runstate.Snapshot, records map[string]
 	if err != nil {
 		return fmt.Errorf("resume run %q: %w", runID, err)
 	}
-	if err := runner.ValidateGraphForRuntime(runtime, g); err != nil {
+	runtimeWarnings, err := runner.ValidateGraphForRuntime(runtime, g)
+	// A resumed leg re-surfaces these for the same reason it re-warns about
+	// bypassPermissions below: the terminal that saw the first leg's copy may
+	// be long gone, and a cap that cannot apply is a fact about the nodes this
+	// leg is about to spend on (ADR 0026).
+	warnRuntimePreflight(os.Stderr, snap.GraphSourcePath, runtimeWarnings)
+	if err != nil {
 		return fmt.Errorf("resume run %q: %w", runID, err)
 	}
 	// A resumed leg re-warns exactly as `run` did at load: the warning is