feat(goals): opt-in token budget for /goal (input/output caps)

[HermesZum]

Summary

Adds an opt-in input/output token budget to the existing durable /goal machinery (hermes_cli/goals.py), enforced alongside the existing max_turns backstop. A long-running goal currently has only a turn cap; this adds a token cap so a goal cannot burn unbounded tokens. Ports prime-agent's "durable /goal with token budget" by extending the existing goals.py primitive — no architecture fork, no prompt-cache or message-role invariant break.

Closes #90286.

Changes

• hermes_cli/goals.py: GoalState gains max_input_tokens / max_output_tokens (JSON round-trip via existing state_meta) + per-session baselines captured in set() / resume(); set_budget() / clear_budget(); evaluate_after_turn enforces the delta since goal start read from the existing session_model_usage table (not aux_accounting, which would double-count main-loop usage); status_line surfaces the budget.
• hermes_cli/cli_commands_mixin.py: /goal budget in:<n> out:<n> and /goal budget off.
• tests/hermes_cli/test_goals_token_budget.py (new, 8 tests): round-trip, enforcement pause, set/clear, resume re-baseline, status line.

Design notes

• Opt-in / off by default: existing goals with no max_input_tokens/max_output_tokens are unchanged.
• Token source is the existing session_model_usage rows (main-loop, per-session) — reused, not a new table, consistent with how goals.py already persists via state_meta.
• Enforcement reuses the existing goal-pause path (same as max_turns), so behavior on exhaustion is consistent.
• v1 delta is raw input_tokens + output_tokens (reasoning/cache token nuance excluded).

Relationship to existing work (Step-0 duplicate search, see #90286)

• Turn budgets are well-covered (feat(goals): /goal budget <N> — update turn budget on active goal in place #37263 merged /goal budget <N> for turns; feat(goals): unbounded turn-budget sentinel + judge kill-switch #69308 unbounded turn sentinel). No existing effort adds a token budget — this is complementary, not overlapping.

Test plan

• New tests/hermes_cli/test_goals_token_budget.py: 8 tests (round-trip, enforcement, set/clear, resume re-baseline, status line).
• Regression: test_goals.py (36) green — no regressions in touched modules.
• py_compile clean on goals.py + cli_commands_mixin.py.

Invariants preserved

• No conversation/system-prompt mutation → prompt-cache + message-role invariants hold.
• Pure additive state on GoalState; no schema migration.

Notes / asks

• F2 only, split out from a larger prime-agent port to keep review surface small. F1 is PR feat(refine): reversible /refine undo (snapshot-before-write rollback) #90284; F3 (peer steer) follows separately.
• Open question (in feat(goals): opt-in token budget for /goal (input/output caps) #90286): unified /goal budget surface covering turns + tokens vs. separate token flags.

[HermesZum]

Clarification: how this relates to the turn-budget work (#37263)

This PR is not a re-do or conflict with #37263 — it adds a different axis of the same surface:

Command	Controls	Source PR
/goal budget <N>	turn ceiling (existing)	#37263 (merged)
/goal budget in:<n> out:<n>	token ceiling (this PR)	#90285
/goal budget off	clears the token ceiling (this PR)	#90285

The two are distinguished by argument shape, not by a separate keyword, so there is no CLI-parser collision:

• An integer arg → turn budget (delegated to the existing GoalManager.set_budget(n) path from feat(goals): /goal budget <N> — update turn budget on active goal in place #37263).
• in:/out: keyed tokens → token budget (new set_budget()/clear on GoalState).

Both are opt-in and additive; a goal with neither set behaves exactly as today. The token budget is enforced off the existing session_model_usage rows (delta since goal start), fully separate from the turn counter.

If maintainers would prefer a single unified syntax (e.g. /goal budget turns:<N> tokens:<M>) instead of two shapes under one prefix, that's a reasonable follow-up — but it's a UX choice, not a correctness conflict, and this PR keeps the existing /goal budget <N> turns behavior byte-for-byte unchanged.

Related: F1 #90284, F3 #90340 (supersedes partial #90288).

[HermesZum]

Status update (2026-08-20): rebased onto current upstream/main, MERGEABLE

This branch was rebased onto the current upstream/main (which had advanced since the branch was opened and merged its own run_budget_seconds wall-clock feature). The rebase was clean — GitHub now reports this PR as MERGEABLE with no conflicts.

Validation note for reviewers: this sandbox does not have the project's uv/pytest venv, so the full tests/ regression suite has not been executed here. Verification done locally: py_compile clean on all touched modules + hermetic stub smoke tests of the new logic. The real regression gate is GitHub CI on this PR — please check the CI run before merging.

No behavior change from the prior revision; only the base moved forward.

[HermesZum]

Closing: features moved to a private plugin (HermesZum/prime-agent-features). This PR is withdrawn.