Fix stuck model switches from false end-failure in session takeover

The model_locked takeover only released rows that were active on the
locked model, so ended-within-grace rows (the stale rows the branch
exists for) and already-released rows produced an explanation claiming
the end had failed when no DELETE was ever attempted, locking the user
out of their pick for the session hour (#1298).

Route the follow-up GET through a pure planner that separates release
(live row attributable to the lock) from retry (row already gone,
re-POST the consumed pick once) from explain (real read/delete failure
or an unattributable row). Grace-window DELETE replays the refund
receipt idempotently via the instance id.

Author: nordicnode

cli/src/hooks/use-freebuff-session.ts

@@ -42,6 +42,7 @@ import {
   holdsLiveFreebuffSlot,
   isFreebuffSessionTimeoutError,
   mergeCompactActiveSession,
+  planModelLockedSwitch,
 } from '../utils/freebuff-session-api'
 import {
   failedPollDelayMs,
@@ -589,25 +590,30 @@ export function useFreebuffSession(): UseFreebuffSessionResult {
             const current = getFreebuffModel(next.currentModel).displayName
             const requested = getFreebuffModel(explicitPickModel).displayName
             let released = false
+            let lockRaced = false
             try {
               const held = await callFreebuffSession('GET', token, {
                 signal: fetchController.signal,
               })
               if (
                 !cancelled &&
                 !fetchController.signal.aborted &&
-                generation === restartGeneration &&
-                held.status === 'active' &&
-                held.model === next.currentModel
+                generation === restartGeneration
               ) {
-                await useFreebuffSessionStore
-                  .getState()
-                  .releaseSlot(held, fetchController.signal)
-                released = true
+                const action = planModelLockedSwitch(held, next.currentModel)
+                if (action === 'release') {
+                  await useFreebuffSessionStore
+                    .getState()
+                    .releaseSlot(held, fetchController.signal)
+                  released = true
+                } else if (action === 'retry') {
+                  lockRaced = true
+                }
               }
             } catch {
-              // DELETE failed — fall through to the revert-with-explanation
-              // path below rather than stranding the user mid-switch.
+              // Reading or deleting the held row failed — fall through to the
+              // revert-with-explanation path below rather than stranding the
+              // user mid-switch.
             }
             if (
               cancelled ||
@@ -629,6 +635,16 @@ export function useFreebuffSession(): UseFreebuffSessionResult {
               schedule(0)
               return
             }
+            if (lockRaced) {
+              // The GET found no row left to release: the lock raced and
+              // released itself. Re-POST rather than reporting an end that
+              // was never needed (#1298). The marker is consumed, so a
+              // second model_locked takes the revert branch — one retry,
+              // no loop.
+              nextMethod = 'POST'
+              schedule(0)
+              return
+            }
             useChatStore
               .getState()
               .setMessages((prev) => [

cli/src/utils/__tests__/freebuff-session-api.test.ts

@@ -10,8 +10,11 @@ import {
   classifyFreebuffSessionRequestFailure,
   FreebuffSessionRequestError,
   mergeCompactActiveSession,
+  planModelLockedSwitch,
 } from '../freebuff-session-api'
 
+import type { FreebuffSessionServerResponse } from '@codebuff/common/types/freebuff-session'
+
 let fetchSpy: ReturnType<typeof spyOn> | undefined
 
 afterEach(() => {
@@ -230,3 +233,45 @@ test('DELETE sends the held instance and preserves the server refund receipt', a
     'held-cli',
   )
 })
+
+const heldActive = (model: string): FreebuffSessionServerResponse => ({
+  status: 'active',
+  accessTier: 'full',
+  instanceId: 'inst-held',
+  model,
+  admittedAt: '2026-09-09T00:00:00.000Z',
+  expiresAt: '2026-09-09T01:00:00.000Z',
+  remainingMs: 60_000,
+})
+
+test('a deliberate pick releases the row that holds the lock', () => {
+  expect(planModelLockedSwitch(heldActive('x/mimo'), 'x/mimo')).toBe('release')
+})
+
+test('an ended row still inside the grace window is released (#1298)', () => {
+  expect(
+    planModelLockedSwitch(
+      { status: 'ended', instanceId: 'inst-held' },
+      'x/mimo',
+    ),
+  ).toBe('release')
+})
+
+test('an ended row past grace means nothing to end: retry the pick', () => {
+  expect(planModelLockedSwitch({ status: 'ended' }, 'x/mimo')).toBe('retry')
+})
+
+test('a swept row means nothing to end: retry the pick', () => {
+  expect(planModelLockedSwitch({ status: 'none' }, 'x/mimo')).toBe('retry')
+})
+
+test('a different model than the lock named is never deleted', () => {
+  expect(planModelLockedSwitch(heldActive('x/other'), 'x/mimo')).toBe('explain')
+})
+
+test('no readable row explains instead of claiming a failed end', () => {
+  expect(planModelLockedSwitch(undefined, 'x/mimo')).toBe('explain')
+  expect(planModelLockedSwitch({ status: 'superseded' }, 'x/mimo')).toBe(
+    'explain',
+  )
+})

cli/src/utils/freebuff-session-api.ts

@@ -227,3 +227,29 @@ export function holdsLiveFreebuffSlot(
     (current.status === 'ended' && Boolean(current.instanceId))
   )
 }
+
+/** What the `model_locked` takeover should do with the row a follow-up GET
+ *  returned. One function asks this so "we tried to end it and failed" stays
+ *  distinguishable from "there was nothing to end":
+ *   - 'release': the row still holds a slot — active on the locked model, or
+ *     `ended` inside the grace window (the stale row from a crashed CLI; its
+ *     DELETE replays the refund receipt idempotently via the instance id).
+ *   - 'retry': no row is left to release (#1298: the lock raced and released
+ *     itself) — re-POST instead of reporting a failed end.
+ *   - 'explain': anything we cannot attribute to this lock, including a row
+ *     that arrived under an unexpected status — never delete it blindly.
+ */
+export type ModelLockedSwitchAction = 'release' | 'retry' | 'explain'
+
+export function planModelLockedSwitch(
+  held: FreebuffSessionServerResponse | undefined,
+  lockedModel: string,
+): ModelLockedSwitchAction {
+  if (!held) return 'explain'
+  if (held.status === 'none') return 'retry'
+  if (held.status === 'ended') {
+    return held.instanceId ? 'release' : 'retry'
+  }
+  if (held.status === 'active' && held.model === lockedModel) return 'release'
+  return 'explain'
+}