switchroom 0.18.29 → 0.18.30

package/telegram-plugin/tests/litellm-proxy-auth-misconfig.test.ts

@@ -0,0 +1,278 @@
+/**
+ * litellm-proxy-auth-misconfig.test.ts — outcome-asserting tests for Ken's
+ * deterministic error-surfacing policy applied to the LiteLLM proxy-fallback
+ * 401 incident (2026-07-16).
+ *
+ * Root cause: LiteLLM's internal fallback chain re-dispatched WITHOUT the
+ * client's OAuth Authorization header onto a keyless `claude-sonnet-5`
+ * deployment, so Anthropic returned 401 authentication_error "x-api-key header
+ * is required". The gateway classifier mapped ANY authentication_error →
+ * credentials-invalid → an always-rendered "🔑 re-authenticate" card that was
+ * broadcast to EVERY allowlist chat — wrong audience (a non-operator user like
+ * Lisa cannot re-auth) and wrong diagnosis (the login is fine).
+ *
+ * These assert OUTCOMES:
+ *   1. the proxy 401 classifies as an operator-only infra fault, NEVER auth /
+ *      credentials-invalid, and NEVER renders a re-auth card;
+ *   2. a genuine credential expiry still classifies as credentials-expired and
+ *      still reaches the operator;
+ *   3. the audience router sends operator-actionable faults to the operator
+ *      ONLY, and hands non-operator users a diagnosis-free plain-language
+ *      notice — while the operator (allowlist head, incl. their own DM) always
+ *      keeps the full card.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  classifyClaudeError,
+  renderOperatorEvent,
+  decideOperatorEventAudience,
+  isOperatorActionableKind,
+  renderUserFacingFailureNotice,
+  type OperatorEvent,
+  type OperatorEventKind,
+} from '../operator-events.js'
+import { isLitellmProxyAuthMisconfig } from '../model-unavailable.js'
+import { parseLlmError, renderLlmError } from '../llm-error-present.js'
+import {
+  PendingUserNoticeGate,
+  PENDING_USER_NOTICE_TTL_MS,
+  type PendingUserNotice,
+} from '../pending-user-notice.js'
+
+// The verbatim shape Anthropic returns to the header-less proxy fallback.
+const PROXY_401_MESSAGE =
+  'litellm.AuthenticationError: AnthropicException - {"type":"error","error":{"type":"authentication_error","message":"x-api-key header is required"}} (fallback deployment claude-sonnet-5)'
+
+function makeEvent(kind: OperatorEventKind, overrides?: Partial<OperatorEvent>): OperatorEvent {
+  return {
+    kind,
+    agent: 'gymbro',
+    detail: '',
+    suggestedActions: [],
+    firstSeenAt: new Date('2026-07-16T20:00:00Z'),
+    ...overrides,
+  }
+}
+
+describe('isLitellmProxyAuthMisconfig', () => {
+  it('detects the definitive keyless-401 marker', () => {
+    expect(isLitellmProxyAuthMisconfig(PROXY_401_MESSAGE)).toBe(true)
+    expect(isLitellmProxyAuthMisconfig('x-api-key header is required')).toBe(true)
+  })
+
+  it('detects an authentication_error carrying the fallback + x-api-key structural pair', () => {
+    expect(
+      isLitellmProxyAuthMisconfig(
+        'litellm fallback re-dispatch: authentication_error — upstream demanded x-api-key on backup deployment',
+      ),
+    ).toBe(true)
+  })
+
+  it('does NOT down-classify a genuine Anthropic OAuth expiry', () => {
+    expect(
+      isLitellmProxyAuthMisconfig(
+        'authentication_error: OAuth token has expired. Please run /login to refresh.',
+      ),
+    ).toBe(false)
+    expect(isLitellmProxyAuthMisconfig('authentication_error: invalid bearer token')).toBe(false)
+  })
+
+  // #3293 review finding 2 — precision over recall: an AMBIGUOUS proxy
+  // envelope (mentions litellm/proxy/api_key but lacks the keyless-fallback
+  // signature) must KEEP the credentials diagnosis, not become misconfig.
+  it('does NOT claim a genuine expiry wrapped in a proxy envelope mentioning api_key', () => {
+    const wrappedExpiry =
+      'litellm.AuthenticationError: AnthropicException - authentication_error: OAuth token has expired (api_key slot proxy-default). Please refresh.'
+    expect(isLitellmProxyAuthMisconfig(wrappedExpiry)).toBe(false)
+    expect(
+      classifyClaudeError({ type: 'authentication_error', status: 401, message: wrappedExpiry }),
+    ).toBe('credentials-expired')
+  })
+
+  it('does NOT claim proxy+fallback wording without an explicit x-api-key signal', () => {
+    expect(
+      isLitellmProxyAuthMisconfig(
+        'litellm proxy fallback: authentication_error while routing to backup deployment',
+      ),
+    ).toBe(false)
+  })
+
+  it('never throws on junk input', () => {
+    expect(isLitellmProxyAuthMisconfig('')).toBe(false)
+    // @ts-expect-error — deliberate wrong type
+    expect(isLitellmProxyAuthMisconfig(null)).toBe(false)
+  })
+})
+
+describe('classifyClaudeError — proxy 401 vs genuine credential faults', () => {
+  it('classifies the proxy fallback 401 as proxy-misconfig, NOT credentials-invalid', () => {
+    const kind = classifyClaudeError({
+      type: 'authentication_error',
+      status: 401,
+      message: PROXY_401_MESSAGE,
+    })
+    expect(kind).toBe('proxy-misconfig')
+    expect(kind).not.toBe('credentials-invalid')
+    expect(kind).not.toBe('credentials-expired')
+  })
+
+  it('still classifies a genuine expired credential as credentials-expired', () => {
+    const kind = classifyClaudeError({
+      type: 'authentication_error',
+      message: 'authentication_error: your OAuth token has expired, please refresh',
+    })
+    expect(kind).toBe('credentials-expired')
+  })
+
+  it('still classifies a bare invalid credential as credentials-invalid', () => {
+    const kind = classifyClaudeError({
+      type: 'authentication_error',
+      message: 'authentication_error: credentials are not valid',
+    })
+    expect(kind).toBe('credentials-invalid')
+  })
+})
+
+describe('renderOperatorEvent — proxy-misconfig card', () => {
+  it('renders an operator infra card with NO re-auth button and NO login language', () => {
+    const { text, keyboard } = renderOperatorEvent(makeEvent('proxy-misconfig', { detail: 'x-api-key header is required' }))
+    // No re-auth instruction reaches the surface.
+    expect(text.toLowerCase()).not.toContain('re-authenticate')
+    expect(text.toLowerCase()).not.toContain('reauth')
+    expect(text).toContain('misconfig')
+    // Only a Dismiss button — never a Reauth callback.
+    const callbacks = keyboard.inline_keyboard.flat().map((b) => b.callback_data ?? '')
+    expect(callbacks.some((c) => c.startsWith('op:reauth:'))).toBe(false)
+  })
+})
+
+describe('parseLlmError — proxy 401 never becomes the user-facing auth kind', () => {
+  it('parses the proxy 401 as infra_misconfig (operator-only), source litellm-local', () => {
+    const parsed = parseLlmError(PROXY_401_MESSAGE)
+    expect(parsed.kind).toBe('infra_misconfig')
+    expect(parsed.kind).not.toBe('auth')
+    expect(parsed.source).toBe('litellm-local')
+  })
+
+  it('the rendered infra_misconfig line carries NO re-auth recommendation', () => {
+    const parsed = parseLlmError(PROXY_401_MESSAGE)
+    const { text } = renderLlmError(parsed, 'gymbro', 'UTC')
+    expect(text.toLowerCase()).not.toContain('re-authenticate this account')
+  })
+
+  it('a genuine OAuth expiry still parses as the actionable auth kind', () => {
+    const parsed = parseLlmError('authentication_error: OAuth token has expired, please refresh')
+    expect(parsed.kind).toBe('auth')
+  })
+})
+
+describe('decideOperatorEventAudience — Ken routing policy', () => {
+  const allow = ['5000000001' /* operator */, '5000000002' /* Lisa */, '5000000003']
+
+  it('routes the proxy misconfig to the operator ONLY; users get a plain notice', () => {
+    const { operatorChats, userNoticeChats } = decideOperatorEventAudience(
+      'proxy-misconfig',
+      allow,
+      allow[0],
+    )
+    expect(operatorChats).toEqual(['5000000001'])
+    expect(userNoticeChats).toEqual(['5000000002', '5000000003'])
+  })
+
+  it('routes credentials-invalid / -expired / credit-exhausted to the operator ONLY', () => {
+    for (const kind of ['credentials-invalid', 'credentials-expired', 'credit-exhausted'] as const) {
+      const a = decideOperatorEventAudience(kind, allow, allow[0])
+      expect(a.operatorChats).toEqual(['5000000001'])
+      expect(a.userNoticeChats).toEqual(['5000000002', '5000000003'])
+    }
+  })
+
+  it('preserves the operator DM: a lone-operator allowlist still gets the full card, no user notice', () => {
+    const a = decideOperatorEventAudience('proxy-misconfig', ['5000000001'], '5000000001')
+    expect(a.operatorChats).toEqual(['5000000001'])
+    expect(a.userNoticeChats).toEqual([])
+  })
+
+  it('leaves non-operator-actionable kinds broadcasting to every allowlist chat', () => {
+    for (const kind of ['rate-limited', 'unknown-5xx', 'agent-crashed', 'quota-exhausted'] as const) {
+      const a = decideOperatorEventAudience(kind, allow, allow[0])
+      expect(a.operatorChats).toEqual(allow)
+      expect(a.userNoticeChats).toEqual([])
+    }
+  })
+
+  it('isOperatorActionableKind gates exactly the credential/infra fault classes', () => {
+    expect(isOperatorActionableKind('proxy-misconfig')).toBe(true)
+    expect(isOperatorActionableKind('credentials-invalid')).toBe(true)
+    expect(isOperatorActionableKind('credentials-expired')).toBe(true)
+    expect(isOperatorActionableKind('credit-exhausted')).toBe(true)
+    expect(isOperatorActionableKind('rate-limited')).toBe(false)
+    expect(isOperatorActionableKind('quota-exhausted')).toBe(false)
+  })
+})
+
+// #3293 review finding 1 — the user notice is gated on the TURN OUTCOME, not
+// the error line: a turn that 401s on the proxy fallback but still delivers a
+// reply must produce NO user notice; only a reply-less turn end flushes it.
+describe('PendingUserNoticeGate — notice fires IFF the turn dies reply-less', () => {
+  function makeNotice(overrides?: Partial<PendingUserNotice>): PendingUserNotice {
+    return {
+      chatIds: ['5000000002', '5000000003'],
+      text: renderUserFacingFailureNotice(),
+      agent: 'gymbro',
+      kind: 'proxy-misconfig',
+      atMs: 1_000_000,
+      ...overrides,
+    }
+  }
+
+  it('DROPS the notice when the turn recovered (delivered a reply)', () => {
+    const gate = new PendingUserNoticeGate()
+    gate.schedule(makeNotice())
+    expect(gate.resolveTurnEnd(true, 1_001_000)).toEqual([])
+    // And it does not resurrect on a later failed turn end.
+    expect(gate.resolveTurnEnd(false, 1_002_000)).toEqual([])
+  })
+
+  it('SENDS the notice exactly once when the turn ends without a reply', () => {
+    const gate = new PendingUserNoticeGate()
+    const notice = makeNotice()
+    gate.schedule(notice)
+    const flushed = gate.resolveTurnEnd(false, 1_001_000)
+    expect(flushed).toHaveLength(1)
+    expect(flushed[0].chatIds).toEqual(['5000000002', '5000000003'])
+    // Exactly once — a second turn end flushes nothing.
+    expect(gate.resolveTurnEnd(false, 1_002_000)).toEqual([])
+  })
+
+  it('collapses an error burst within one turn to ONE pending notice per agent', () => {
+    const gate = new PendingUserNoticeGate()
+    gate.schedule(makeNotice({ atMs: 1_000_000 }))
+    gate.schedule(makeNotice({ atMs: 1_000_500 }))
+    gate.schedule(makeNotice({ atMs: 1_001_000 }))
+    expect(gate.resolveTurnEnd(false, 1_002_000)).toHaveLength(1)
+  })
+
+  it('expires an unresolved notice after the TTL (bias to silence over false failure)', () => {
+    const gate = new PendingUserNoticeGate()
+    gate.schedule(makeNotice({ atMs: 1_000_000 }))
+    const after = 1_000_000 + PENDING_USER_NOTICE_TTL_MS + 1
+    expect(gate.hasPending(after)).toBe(false)
+    expect(gate.resolveTurnEnd(false, after)).toEqual([])
+  })
+})
+
+describe('renderUserFacingFailureNotice', () => {
+  it('is a diagnosis-free, re-auth-free, byte-free plain-language notice', () => {
+    const notice = renderUserFacingFailureNotice()
+    const lower = notice.toLowerCase()
+    expect(lower).not.toContain('re-auth')
+    expect(lower).not.toContain('reauth')
+    expect(lower).not.toContain('x-api-key')
+    expect(lower).not.toContain('litellm')
+    expect(lower).not.toContain('authentication_error')
+    // Communicates "our side" honestly.
+    expect(lower).toContain('our side')
+  })
+})

package/telegram-plugin/tests/local-time.test.ts

@@ -10,7 +10,7 @@
  */
 
 import { describe, expect, it } from 'vitest'
-import { fmtLocalStamp, resolveEnvTimezone } from '../shared/local-time.js'
+import { fmtLocalStamp, resolveEnvTimezone, renderLogTimestampsLocal } from '../shared/local-time.js'
 
 // 2025-06-15T14:26:40Z — a fixed instant so the local rendering is deterministic.
 const MS = 1750000000 * 1000
@@ -66,3 +66,70 @@ describe('fmtLocalStamp', () => {
     }
   })
 })
+
+describe('renderLogTimestampsLocal', () => {
+  // #tz-fix audit (MEDIUM gap 2): /logs docker lines carry a leading UTC
+  // ISO-Z stamp; render it in local am/pm at display time.
+  it('rewrites a leading UTC ISO-Z timestamp into local am/pm', () => {
+    // 04:09Z in July → Melbourne AEST (UTC+10) → 02:09 PM.
+    const out = renderLogTimestampsLocal(
+      '2026-07-16T04:09:00.123456789Z gateway boot ok',
+      'Australia/Melbourne',
+    )
+    expect(out).toContain('2026-07-16 02:09 PM AEST')
+    expect(out).toContain('gateway boot ok')
+    expect(out).not.toContain('T04:09')
+    expect(out).not.toContain('Z gateway')
+  })
+
+  it('handles a fractionless ISO-Z timestamp', () => {
+    const out = renderLogTimestampsLocal('2026-07-16T04:09:00Z hello', 'Australia/Melbourne')
+    expect(out).toContain('2026-07-16 02:09 PM AEST hello')
+  })
+
+  it('converts every line and preserves non-timestamped lines verbatim', () => {
+    const input = [
+      '2026-07-16T04:09:00Z first',
+      '  continuation line with no timestamp',
+      '2026-07-16T05:10:00Z second',
+    ].join('\n')
+    const out = renderLogTimestampsLocal(input, 'Australia/Melbourne').split('\n')
+    expect(out[0]).toContain('02:09 PM AEST first')
+    expect(out[1]).toBe('  continuation line with no timestamp')
+    expect(out[2]).toContain('03:10 PM AEST second')
+  })
+
+  it('preserves a line whose leading token is not a valid ISO-Z stamp', () => {
+    const raw = 'not-a-timestamp still here'
+    expect(renderLogTimestampsLocal(raw, 'Australia/Melbourne')).toBe(raw)
+  })
+
+  it('does not touch a timestamp that is not at line start', () => {
+    const raw = 'prefix 2026-07-16T04:09:00Z trailing'
+    expect(renderLogTimestampsLocal(raw, 'Australia/Melbourne')).toBe(raw)
+  })
+
+  it('returns empty input unchanged', () => {
+    expect(renderLogTimestampsLocal('', 'Australia/Melbourne')).toBe('')
+  })
+
+  // End-to-end shape check against REAL `docker logs --timestamps` output —
+  // the /logs path requests --timestamps precisely so this prefix exists.
+  // (Captured verbatim from a live container; nanosecond precision.)
+  it('converts a verbatim docker --timestamps line (the real /logs input shape)', () => {
+    const real = '2026-07-16T20:17:58.433481596Z gateway-supervisor: heartbeat ok'
+    const out = renderLogTimestampsLocal(real, 'Australia/Melbourne')
+    // 20:17:58Z on 16 Jul → AEST (UTC+10) → 06:17 AM on 17 Jul local.
+    expect(out).toBe('Friday 2026-07-17 06:17 AM AEST gateway-supervisor: heartbeat ok')
+    expect(out).not.toContain('Z ')
+    expect(out).not.toContain('UTC')
+  })
+
+  it('does NOT touch an app-emitted local-zone stamp (no double shift)', () => {
+    // Post-#3275 containers run with local TZ baked, so Python-style
+    // `%H:%M:%S,mmm` stamps are already local wall clock — converting them
+    // as UTC would be wrong. They must pass through verbatim.
+    const appLine = '2026-07-16 20:14:14,725 - INFO - scheduler tick'
+    expect(renderLogTimestampsLocal(appLine, 'Australia/Melbourne')).toBe(appLine)
+  })
+})

package/telegram-plugin/tests/model-command.test.ts

@@ -28,6 +28,9 @@ import {
   isClaudeModel,
   isBusyRefusalText,
   isOfflineTrustedModelToken,
+  classifyModelSwitchConfirmation,
+  parseModelSwitchTarget,
+  modelFamilyToken,
   MODEL_ALIASES,
   type ModelCommandDeps,
 } from "../gateway/model-command.js";
@@ -528,3 +531,133 @@ describe("#3177 — routing decision helpers", () => {
     expect(line).toContain("arg=opus");
   });
 });
+
+describe("parseModelSwitchTarget", () => {
+  it("extracts the target from a menu relaunch reason", () => {
+    expect(
+      parseModelSwitchTarget("user: /model fable (session-only relaunch, menu)"),
+    ).toBe("fable");
+  });
+  it("extracts the target from a typed relaunch reason", () => {
+    expect(
+      parseModelSwitchTarget("user: /model sr-gemini-2.5-flash (session-only relaunch)"),
+    ).toBe("sr-gemini-2.5-flash");
+  });
+  it("extracts the default sentinel from a revert reason", () => {
+    expect(parseModelSwitchTarget("user: /model default (revert relaunch)")).toBe("default");
+  });
+  it("returns null for a non-/model reason", () => {
+    expect(parseModelSwitchTarget("cli: restart")).toBeNull();
+  });
+});
+
+describe("classifyModelSwitchConfirmation", () => {
+  // The regression this fix closes: a /model fable apply-boot that reverted to
+  // the configured default (opus) must be reported as NOT-applied (⚠️), not as a
+  // green "✅ Now running opus (the configured default)". Under the OLD inline
+  // logic (isApplyBoot ? applied : green-default) this exact case produced the
+  // misleading green card — this asserts the corrected outcome.
+  it("flags a non-default switch that reverted to the configured default as not-applied", () => {
+    const out = classifyModelSwitchConfirmation({
+      reason: "user: /model fable (session-only relaunch, menu)",
+      launched: "opus",
+      configured: "opus",
+    });
+    expect(out).toEqual({ kind: "not-applied", target: "fable", revertedTo: "opus" });
+  });
+
+  it("reports an applied switch when the launched model differs from the default", () => {
+    const out = classifyModelSwitchConfirmation({
+      reason: "user: /model fable (session-only relaunch, menu)",
+      launched: "fable",
+      configured: "opus",
+    });
+    expect(out).toEqual({ kind: "applied", launched: "fable" });
+  });
+
+  it("reports the default (green) for an intended /model default revert", () => {
+    const out = classifyModelSwitchConfirmation({
+      reason: "user: /model default (revert relaunch)",
+      launched: "opus",
+      configured: "opus",
+    });
+    expect(out).toEqual({ kind: "default", launched: "opus" });
+  });
+
+  it("reports the default (green) when the operator asked for the configured model itself", () => {
+    // /model opus while configured=opus is a SUCCESS, not a silent revert.
+    const out = classifyModelSwitchConfirmation({
+      reason: "user: /model opus (session-only relaunch)",
+      launched: "opus",
+      configured: "opus",
+    });
+    expect(out).toEqual({ kind: "default", launched: "opus" });
+  });
+
+  it("is case-insensitive on the target-vs-launched comparison", () => {
+    const out = classifyModelSwitchConfirmation({
+      reason: "user: /model OPUS (session-only relaunch)",
+      launched: "opus",
+      configured: "opus",
+    });
+    expect(out).toEqual({ kind: "default", launched: "opus" });
+  });
+
+  it("treats an empty launched value (unreadable .active-session-model) as a revert to the default", () => {
+    const out = classifyModelSwitchConfirmation({
+      reason: "user: /model fable (session-only relaunch, menu)",
+      launched: "",
+      configured: "opus",
+    });
+    expect(out).toEqual({ kind: "not-applied", target: "fable", revertedTo: "opus" });
+  });
+
+  // LOW-1: an ALIAS target must family-match its RESOLVED full-id revert, so a
+  // `/model sonnet` on a `claude-sonnet-5`-default agent (start.sh wrote the full
+  // id to .active-session-model on a config-changed / proxy-down revert path) is
+  // NOT falsely reported as "sonnet didn't apply". This is the exact case the
+  // reviewer flagged; a naive string compare returns not-applied here.
+  it("family-matches an alias target to its resolved full-id default (sonnet ≡ claude-sonnet-5)", () => {
+    const out = classifyModelSwitchConfirmation({
+      reason: "user: /model sonnet (session-only relaunch)",
+      launched: "claude-sonnet-5",
+      configured: "claude-sonnet-5",
+    });
+    expect(out).toEqual({ kind: "default", launched: "claude-sonnet-5" });
+  });
+
+  it("still flags a genuinely different-family switch that reverted to the full-id default", () => {
+    // /model opus reverting to a claude-sonnet-5 default is a REAL failed switch.
+    const out = classifyModelSwitchConfirmation({
+      reason: "user: /model opus (session-only relaunch)",
+      launched: "claude-sonnet-5",
+      configured: "claude-sonnet-5",
+    });
+    expect(out).toEqual({ kind: "not-applied", target: "opus", revertedTo: "claude-sonnet-5" });
+  });
+
+  it("family-matches a full-id target to the aliased default (claude-opus-4-8 ≡ opus)", () => {
+    const out = classifyModelSwitchConfirmation({
+      reason: "user: /model claude-opus-4-8 (session-only relaunch)",
+      launched: "opus",
+      configured: "opus",
+    });
+    expect(out).toEqual({ kind: "default", launched: "opus" });
+  });
+});
+
+describe("modelFamilyToken", () => {
+  it("reduces a claude full id to its family, dropping version + date", () => {
+    expect(modelFamilyToken("claude-sonnet-5")).toBe("sonnet");
+    expect(modelFamilyToken("claude-opus-4-8")).toBe("opus");
+    expect(modelFamilyToken("claude-haiku-4-5-20251001")).toBe("haiku");
+  });
+  it("passes a bare alias through, lowercased", () => {
+    expect(modelFamilyToken("Sonnet")).toBe("sonnet");
+    expect(modelFamilyToken("fable")).toBe("fable");
+  });
+  it("keeps sr-* routing ids verbatim (no claude- prefix)", () => {
+    expect(modelFamilyToken("sr-glm-5")).toBe("sr-glm-5");
+    expect(modelFamilyToken("sr-gemini-2.5-flash")).toBe("sr-gemini-2.5-flash");
+  });
+});

package/telegram-plugin/tests/session-model-file.test.ts

@@ -17,8 +17,10 @@ import {
   readSessionModelFileRaw,
   restoreSessionModelFileRaw,
   clearSessionModelFile,
+  consumeSessionModelCarrierOnHealthyBoot,
   readConfiguredDefaultModel,
   SESSION_MODEL_FILE,
+  SESSION_MODEL_BOOT_ATTEMPTS_FILE,
   CONFIGURED_DEFAULT_MODEL_FILE,
   parseSessionEffort,
   writeSessionEffortFile,
@@ -80,6 +82,27 @@ describe('rollback snapshot (scheduleModelRelaunch dispatch failure)', () => {
   })
 })
 
+describe('consumeSessionModelCarrierOnHealthyBoot (#3284 healthy-boot consume)', () => {
+  it('deletes BOTH the carrier and the bounded-retry attempt counter', () => {
+    writeFileSync(join(dir, SESSION_MODEL_FILE), 'whatever\n')
+    writeFileSync(join(dir, SESSION_MODEL_BOOT_ATTEMPTS_FILE), '2\n')
+    consumeSessionModelCarrierOnHealthyBoot(dir)
+    expect(existsSync(join(dir, SESSION_MODEL_FILE))).toBe(false)
+    expect(existsSync(join(dir, SESSION_MODEL_BOOT_ATTEMPTS_FILE))).toBe(false)
+  })
+
+  it('is idempotent / best-effort when neither file exists (no throw)', () => {
+    expect(() => consumeSessionModelCarrierOnHealthyBoot(dir)).not.toThrow()
+    expect(existsSync(join(dir, SESSION_MODEL_FILE))).toBe(false)
+  })
+
+  it('clears the counter even when the carrier is already gone (wedge that lost its carrier mid-race)', () => {
+    writeFileSync(join(dir, SESSION_MODEL_BOOT_ATTEMPTS_FILE), '1\n')
+    consumeSessionModelCarrierOnHealthyBoot(dir)
+    expect(existsSync(join(dir, SESSION_MODEL_BOOT_ATTEMPTS_FILE))).toBe(false)
+  })
+})
+
 describe('readConfiguredDefaultModel', () => {
   it('reads the trimmed value; null when absent or empty', () => {
     expect(readConfiguredDefaultModel(dir)).toBeNull()