runtime: lane exhaustion raises a consented fallback card (P4)

When a subscription/key lane hits its usage window, the turn pauses on a
card: stop (default) or continue on memcode credits — the same never-
silently-move-spend doctrine as the BYOK consent. The choice is sticky per
vendor for the session (a one-line notice on auto-apply), the retry reissues
the same call with a turn-scoped gateway bypass honored by lane dispatch,
and headless/sub-agent sessions fail with the reason and reset time.

Author: timothyerwin

internal/agent/runtime/lanefallback_test.go

@@ -0,0 +1,72 @@
+package runtime
+
+import (
+	"context"
+	"testing"
+
+	"github.com/memcode-ai/memcode/internal/llm"
+	"github.com/memcode-ai/memcode/internal/provider"
+)
+
+func exhErr(canFallback bool) *provider.ErrLaneExhausted {
+	return &provider.ErrLaneExhausted{
+		Lane:        provider.LaneInfo{Vendor: "anthropic", Name: "claude-sub", Kind: "sub"},
+		Status:      429,
+		CanFallback: canFallback,
+	}
+}
+
+// The exhaustion card: stop is the default, "continue" flips the turn onto
+// the gateway bypass and sticks for the vendor, headless fails closed.
+func TestConsentLaneFallback(t *testing.T) {
+	s := &Session{purpose: llm.MainLoop}
+
+	// No gateway → nothing to offer.
+	if s.consentLaneFallback(context.Background(), exhErr(false)) {
+		t.Fatal("consented with no fallback path")
+	}
+
+	// Headless (no asker) → fail closed.
+	if s.consentLaneFallback(context.Background(), exhErr(true)) {
+		t.Fatal("headless session consented")
+	}
+
+	// Explicit continue → bypass set + sticky.
+	s.ask = func(ctx context.Context, r AskRequest) AskResponse {
+		if r.Options[0].Label != "Stop the turn" {
+			t.Fatalf("stop must be the FIRST (default) option, got %q", r.Options[0].Label)
+		}
+		return AskResponse{Answer: "Continue on memcode credits"}
+	}
+	s.turn = newTurnState()
+	if !s.consentLaneFallback(context.Background(), exhErr(true)) {
+		t.Fatal("explicit continue refused")
+	}
+	if s.turn.laneBypass != "gateway" {
+		t.Fatalf("laneBypass = %q", s.turn.laneBypass)
+	}
+
+	// Sticky: a second exhaustion for the vendor never re-asks.
+	s.ask = func(ctx context.Context, r AskRequest) AskResponse {
+		t.Fatal("sticky choice re-asked")
+		return AskResponse{}
+	}
+	s.turn = newTurnState()
+	if !s.consentLaneFallback(context.Background(), exhErr(true)) {
+		t.Fatal("sticky continue not applied")
+	}
+
+	// Empty answer (Esc) → stop, and THAT sticks too.
+	s2 := &Session{purpose: llm.MainLoop, turn: newTurnState()}
+	s2.ask = func(ctx context.Context, r AskRequest) AskResponse { return AskResponse{} }
+	if s2.consentLaneFallback(context.Background(), exhErr(true)) {
+		t.Fatal("empty answer consented")
+	}
+	s2.ask = func(ctx context.Context, r AskRequest) AskResponse {
+		t.Fatal("sticky stop re-asked")
+		return AskResponse{}
+	}
+	if s2.consentLaneFallback(context.Background(), exhErr(true)) {
+		t.Fatal("sticky stop consented")
+	}
+}

internal/agent/runtime/loop.go

@@ -234,6 +234,7 @@ func (s *Session) runLoop(ctx context.Context, sys promptSpec, messages *[]wire.
 			Effort: eff, MaxTokens: maxTok,
 			Difficulty:  s.turnDifficulty,    // the judge's tier verdict → the ladder's difficulty input
 			BillingLane: s.turnBillingLane(), // "" normally; "credits" after an explicit BYOK-failure consent
+			LaneBypass:  s.turn.laneBypass,   // "" normally; "gateway" after a consented lane-exhaustion fallback
 			// Escalation signals only the CLI can see (self-heal, room friction,
 			// high-risk surfaces) — inputs to the CLI's own semantic ladder.
 			RoutingHint: s.turnRoutingHint(),
@@ -307,6 +308,19 @@ func (s *Session) runLoop(ctx context.Context, sys promptSpec, messages *[]wire.
 				s.printf("\n■ %s\n", metaStyle.Render("Your API key was rejected — fix or remove it with /apikeys"))
 				return iterations, false, nil
 			}
+			// A subscription/own-key lane hit its usage window. Same doctrine as
+			// BYOK: never SILENTLY move spend — the only path onto credits is an
+			// explicit per-vendor choice, sticky for this session. Headless
+			// sessions fail with the reason (and the reset time when known).
+			var laneExh *provider.ErrLaneExhausted
+			if errors.As(err, &laneExh) {
+				if s.consentLaneFallback(ctx, laneExh) {
+					s.printf("\n%s\n", metaStyle.Render("⊙ "+laneExh.Error()+" — continuing on memcode credits (session choice; /status to review)"))
+					continue
+				}
+				s.printf("\n■ %s\n", metaStyle.Render(laneExh.Error()+" — turn stopped. Pick another family with /model, or wait for the window."))
+				return iterations, false, nil
+			}
 			// Token rejected (401): the SESSION is signed out (expired or revoked
 			// key). Disconnect the provider so the front-end's signed-out gate
 			// takes over (no more doomed dispatches), and say what fixes it.
@@ -1316,6 +1330,43 @@ func estimateTokens(chars int) int {
 	return chars / 4
 }
 
+// consentLaneFallback asks (once per vendor per session) how to continue when
+// a lane's subscription/key hits its usage window. True = serve this and
+// future exhausted turns for that vendor on memcode credits via the gateway.
+func (s *Session) consentLaneFallback(ctx context.Context, exh *provider.ErrLaneExhausted) bool {
+	if !exh.CanFallback {
+		return false // no gateway base — nothing to fall back to
+	}
+	if s.laneFallback == nil {
+		s.laneFallback = map[string]string{}
+	}
+	if choice, ok := s.laneFallback[exh.Lane.Vendor]; ok {
+		if choice == "gateway" {
+			s.turn.laneBypass = "gateway"
+			return true
+		}
+		return false
+	}
+	if s.ask == nil || s.purpose != llm.MainLoop {
+		return false // headless / sub-agent: fail with the reason
+	}
+	resp := s.ask(ctx, AskRequest{
+		Question: exh.Error() + ". How should this session continue when it's exhausted?",
+		Options: []AskOption{
+			{Label: "Stop the turn", Description: "Wait for the window, or /model another family"},
+			{Label: "Continue on memcode credits", Description: "This and future exhausted turns — billed to your credit balance"},
+		},
+	})
+	ans := strings.ToLower(strings.TrimSpace(resp.Answer))
+	if strings.HasPrefix(ans, "continue") {
+		s.laneFallback[exh.Lane.Vendor] = "gateway"
+		s.turn.laneBypass = "gateway"
+		return true
+	}
+	s.laneFallback[exh.Lane.Vendor] = "stop"
+	return false
+}
+
 // turnBillingLane returns the billing-lane extension for this turn's model
 // calls: "credits" only after the user explicitly consented to serve this
 // turn on memcode credits (a BYOK key failure); "" otherwise (byok-preferred,

internal/agent/runtime/runtime.go

@@ -76,11 +76,12 @@ type Session struct {
 	purpose           llm.Purpose            // ledger purpose for THIS session's main loop (main_loop, or explore for scout sub-agents)
 	root              string
 	model             string
-	scoutModel        string // model for read-only explore sub-agents (cheap; Luna by default)
-	vendor            string // per-session strong-tier vendor ("" = configured default; set by /model)
-	pin               string // pinned model label ("" = Automatic; set by /model — every real request serves this model)
-	lastServedModel   string // last turn's serving model — cross-family thinking-block hygiene (loop.go)
-	pinWindow         int    // the pin's context window from the picker list (0 = unknown; sizes the meter before the first serve)
+	scoutModel        string            // model for read-only explore sub-agents (cheap; Luna by default)
+	vendor            string            // per-session strong-tier vendor ("" = configured default; set by /model)
+	pin               string            // pinned model label ("" = Automatic; set by /model — every real request serves this model)
+	lastServedModel   string            // last turn's serving model — cross-family thinking-block hygiene (loop.go)
+	laneFallback      map[string]string // vendor → sticky exhaustion choice for this session ("gateway" | "stop")
+	pinWindow         int               // the pin's context window from the picker list (0 = unknown; sizes the meter before the first serve)
 	mode              permissions.Mode
 	modeMu            sync.RWMutex // guards mode: the TUI goroutine cycles it (Shift+Tab // /mode) while the engine reads it at the permission gate
 	personality       string       // chosen voice (built-in key or custom text); travels as a fact, tone-only

internal/agent/runtime/turnstate.go

@@ -21,6 +21,7 @@ type turnState struct {
 	firstBreak     string          // the FIRST broken-edit nudge this turn — the failure evidence for lesson distillation
 	lessonDone     bool            // a lesson was already distilled this turn (fire once)
 	billingCredits bool            // user consented to serve THIS turn on memcode credits after a BYOK key failure
+	laneBypass     string          // "gateway" after a consented lane-exhaustion fallback — this turn serves off-lane
 }
 
 // newTurnState returns a fresh per-turn state (with an initialized gather tracker).

internal/provider/dispatch.go

@@ -16,6 +16,13 @@ import (
 func (l *Lazy) route(r wire.Request) (wire.Request, *conn, *lane, error) {
 	base := l.c.Load()
 	lanes := l.laneSet()
+	// A consented exhaustion choice bypasses lane dispatch for this turn.
+	if r.LaneBypass == "gateway" {
+		if base == nil {
+			return r, nil, nil, ErrNotLoggedIn
+		}
+		return r, base, nil, nil
+	}
 	if len(lanes) == 0 {
 		if base == nil {
 			return r, nil, nil, ErrNotLoggedIn

internal/wire/wire.go

@@ -239,6 +239,10 @@ type Request struct {
 	// from that extension and the gateway ENFORCES it — it never silently
 	// reroutes between the user's keys and credits. NOT marshaled on this type.
 	BillingLane string `json:"-"`
+	// LaneBypass forces a turn OFF its family lane after an explicit,
+	// consented exhaustion choice: "gateway" serves it on the hosted base.
+	// Client-side routing state only — never serialized to any wire.
+	LaneBypass string `json:"-"`
 }
 
 // Response is a model completion result, plus the serving telemetry the footer/