Proposal: flexible budget and limit control across session continuation

Status

Proposal only — this issue requests design and implementation planning; it does not authorize an implementation yet.

Why

Today, a run can terminate when its iteration or runtime budget is exhausted, but the user experience for restoring and continuing is poor: the continuation path can be unclear, and restarting or forking can make accounting look reset or incomplete. That creates trust concerns about whether a resumed session is still honoring the original limits, especially for unattended, shared, or security-sensitive workloads. A session should be able to continue deliberately without silently creating a fresh allowance or bypassing a prior stop reason.

This builds on the budget discussion in #3701, but focuses on durable accounting and truthful continuation semantics rather than only declaring limits.

What

Design a persisted, root-owned budget ledger for each session tree:

• Persist cumulative usage and limit decisions at the session root; child sessions and forks must have explicit, auditable ownership and accounting semantics.
• Make restore and fork behavior truthful and deterministic. Restoring continues the same ledger; forking must clearly define whether it shares, snapshots, or starts a separately authorized ledger, with no accidental reset or double counting.
• Support policy-governed additive extensions (for example, an explicit user/API/CLI approval to add budget), recording who/what authorized the extension, when, the amount, and the resulting limit. Extensions must not be an implicit consequence of restore, retry, or fork.
• Keep distinct concepts distinct: hard safety limits, spend/time/token budgets, and iteration limits should have separate configuration, enforcement, stop reasons, and user-facing accounting.
• Provide deliberate continuation from the TUI, API, and CLI, including inspection of remaining/exhausted budget, the stop reason, ledger identity, and any extension history. Headless/API behavior must be deterministic and machine-readable.
• Treat the ledger as security-sensitive state: validate persisted data, use atomic/concurrency-safe updates, prevent unauthorized extension or path-based substitution, and fail closed or visibly degraded when accounting integrity cannot be established.

How / proposed phased rollout

1. Semantics and threat model: define the ledger schema, root/session/fork identity, accounting units, hard-limit vs budget vs iteration-limit precedence, authorization model, crash/concurrency behavior, and compatibility contract. Use the shared detailed plan flexible-budget-limit-control as the authoritative source for full PR sequencing and design decisions.
2. Ledger foundation: add versioned persistence, migration handling, integrity/atomicity safeguards, and runtime accounting with focused tests. Preserve current behavior for configurations that do not opt into the new model.
3. Enforcement and continuation: implement truthful restore/fork semantics and policy-checked additive extensions, with explicit stop reasons and audit records. Add API/CLI commands and TUI flows only after the core state machine is stable.
4. Compatibility and rollout gate: document migration and backward-compatibility behavior, validate old sessions/configurations, add failure-injection/concurrency/security tests, and gate release behind opt-in/feature rollout until ledger correctness and continuation UX are verified against the detailed plan.

Acceptance criteria

• A resumed session cannot silently reset or exceed its root-owned accounting.
• Fork behavior and accounting ownership are visible and covered by tests.
• Budget extensions require the configured policy/authorization and leave an auditable record.
• Hard limits, budgets, and iteration limits remain independently inspectable and enforceable.
• TUI, API, and CLI expose consistent continuation and machine-readable outcomes.
• Existing sessions and configurations have a documented, tested migration/backward-compatibility path.

The detailed implementation plan, including full PR sequencing, migration, safety, backwards compatibility, validation, and rollout gate, is shared under slug flexible-budget-limit-control.