@alumbwe/anvil 1.0.0

package/src/utils/freebuff-agent-selection.ts

@@ -0,0 +1,33 @@
+import {
+  getFreebuffBase3RootAgentIdForModel,
+  getFreebuffRootAgentIdForModel,
+} from '@anvil/common/constants/free-agents'
+
+import { getSelectedFreebuffModel } from '../state/freebuff-model-store'
+import {
+  AGENT_MODE_TO_ID,
+  CLI_HARNESS,
+  IS_FREEBUFF,
+  type AgentMode,
+} from './constants'
+
+/**
+ * Freebuff is locked to LITE (chat-store's setAgentMode is a no-op when
+ * IS_FREEBUFF), so this is effectively "which root does the selected model
+ * run". Both harnesses have a root per picker model; CLI_HARNESS picks the
+ * family. It is currently base3; keeping both branches live preserves the
+ * release-based rollback path for the CLI.
+ */
+export function getFreebuffCliAgentIdForModel(model: string): string {
+  return CLI_HARNESS === 'base3'
+    ? getFreebuffBase3RootAgentIdForModel(model)
+    : getFreebuffRootAgentIdForModel(model)
+}
+
+export function getAgentIdForMode(agentMode: AgentMode): string {
+  if (IS_FREEBUFF && agentMode === 'LITE') {
+    return getFreebuffCliAgentIdForModel(getSelectedFreebuffModel())
+  }
+
+  return AGENT_MODE_TO_ID[agentMode]
+}

package/src/utils/freebuff-instance-owner.ts

@@ -0,0 +1,66 @@
+import fs from 'fs'
+import path from 'path'
+
+import { getConfigDir } from './auth'
+import { logger } from './logger'
+
+interface FreebuffInstanceOwner {
+  instanceId: string
+  pid: number
+}
+
+const OWNER_FILE = 'freebuff-instance-owner.json'
+
+const getOwnerPath = (): string => path.join(getConfigDir(), OWNER_FILE)
+
+function readOwner(): FreebuffInstanceOwner | null {
+  try {
+    const raw = fs.readFileSync(getOwnerPath(), 'utf8')
+    const parsed = JSON.parse(raw) as Partial<FreebuffInstanceOwner>
+    if (
+      typeof parsed.instanceId !== 'string' ||
+      typeof parsed.pid !== 'number'
+    ) {
+      return null
+    }
+    return {
+      instanceId: parsed.instanceId,
+      pid: parsed.pid,
+    }
+  } catch {
+    return null
+  }
+}
+
+function isProcessRunning(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+export function recordFreebuffInstanceOwner(instanceId: string): void {
+  try {
+    fs.mkdirSync(getConfigDir(), { recursive: true })
+    fs.writeFileSync(
+      getOwnerPath(),
+      JSON.stringify({ instanceId, pid: process.pid }, null, 2),
+    )
+  } catch (error) {
+    logger.debug(
+      { error: error instanceof Error ? error.message : String(error) },
+      '[freebuff-session] Failed to record local owner',
+    )
+  }
+}
+
+export function isFreebuffInstanceOwnedByDeadLocalProcess(
+  instanceId: string,
+): boolean {
+  const owner = readOwner()
+  if (!owner || owner.instanceId !== instanceId) return false
+  return !isProcessRunning(owner.pid)
+}

package/src/utils/freebuff-model-navigation.ts

@@ -0,0 +1,50 @@
+export type FreebuffModelNavigationDirection = 'forward' | 'backward'
+
+const FORWARD_KEY_NAMES = new Set(['right', 'down'])
+const BACKWARD_KEY_NAMES = new Set(['left', 'up'])
+const FORWARD_TAB_SEQUENCES = new Set(['\t', '\x1b[9u'])
+const BACKWARD_TAB_SEQUENCES = new Set([
+  '\x1b[Z',
+  '\x1b[9;2u',
+  '\x1b[27;2;9~',
+])
+
+export function nextFreebuffModelId(params: {
+  modelIds: readonly string[]
+  focusedId: string
+  direction: FreebuffModelNavigationDirection
+}): string | null {
+  const { modelIds, focusedId, direction } = params
+  if (modelIds.length === 0) return null
+
+  const currentIdx = modelIds.indexOf(focusedId)
+  if (currentIdx === -1) return modelIds[0] ?? null
+
+  const step = direction === 'forward' ? 1 : -1
+  return modelIds[(currentIdx + step + modelIds.length) % modelIds.length]
+}
+
+export function freebuffModelNavigationDirectionForKey(key: {
+  name?: string
+  shift?: boolean
+  sequence?: string
+  raw?: string
+}): FreebuffModelNavigationDirection | null {
+  const name = (key.name ?? '').toLowerCase()
+  const sequence = key.sequence ?? key.raw ?? ''
+
+  if (FORWARD_KEY_NAMES.has(name)) return 'forward'
+  if (BACKWARD_KEY_NAMES.has(name)) return 'backward'
+
+  if (
+    (name === 'tab' && Boolean(key.shift)) ||
+    BACKWARD_TAB_SEQUENCES.has(sequence)
+  ) {
+    return 'backward'
+  }
+  if (name === 'tab' || FORWARD_TAB_SEQUENCES.has(sequence)) {
+    return 'forward'
+  }
+
+  return null
+}

package/src/utils/freebuff-premium-reset.ts

@@ -0,0 +1,55 @@
+import { FREEBUFF_PREMIUM_SESSION_RESET_TIMEZONE } from '@anvil/common/constants/freebuff-models'
+import { getZonedDayBounds } from '@anvil/common/util/zoned-time'
+
+import type { FreebuffSessionRateLimitByModel } from '@anvil/common/types/freebuff-session'
+
+export function getFreebuffPremiumResetAt(params: {
+  rateLimitsByModel?: FreebuffSessionRateLimitByModel
+  nowMs: number
+}): Date {
+  const { rateLimitsByModel, nowMs } = params
+  const serverResetAt = rateLimitsByModel
+    ? Object.values(rateLimitsByModel)[0]?.resetAt
+    : undefined
+  const parsedServerResetAt = serverResetAt ? new Date(serverResetAt) : null
+
+  if (
+    parsedServerResetAt &&
+    Number.isFinite(parsedServerResetAt.getTime())
+  ) {
+    return parsedServerResetAt
+  }
+
+  return getZonedDayBounds(
+    new Date(nowMs),
+    FREEBUFF_PREMIUM_SESSION_RESET_TIMEZONE,
+  ).resetsAt
+}
+
+/**
+ * Human "resets in …" countdown. Daily pools stop at hours (`withDays` off);
+ * a multi-day window (e.g. a lapsed reset) sets `withDays` so it reads as "2d 5h"
+ * instead of a 100-hour figure.
+ */
+export function formatFreebuffPremiumResetCountdown(
+  resetAt: Date,
+  nowMs: number,
+  { withDays = false }: { withDays?: boolean } = {},
+): string {
+  const diffMs = resetAt.getTime() - nowMs
+  if (!Number.isFinite(diffMs) || diffMs <= 0) return 'now'
+
+  const totalMinutes = Math.max(1, Math.floor(diffMs / 60_000))
+  if (withDays) {
+    const days = Math.floor(totalMinutes / (60 * 24))
+    if (days > 0) {
+      const hours = Math.floor((totalMinutes % (60 * 24)) / 60)
+      return hours === 0 ? `${days}d` : `${days}d ${hours}h`
+    }
+  }
+  const hours = Math.floor(totalMinutes / 60)
+  const minutes = totalMinutes % 60
+
+  if (hours === 0) return `${minutes}m`
+  return minutes === 0 ? `${hours}h` : `${hours}h ${minutes}m`
+}

package/src/utils/freebuff-referral-cache.ts

@@ -0,0 +1,51 @@
+import { getReferralInfo } from '@anvil/common/types/freebuff-session'
+
+import type { FreebuffAccessTier } from '@anvil/common/constants/freebuff-models'
+import type { FreebuffReferralInfo } from '@anvil/common/types/freebuff-session'
+import type { FreebuffSessionResponse } from '../types/freebuff-session'
+
+/**
+ * Process-wide cache of the most recent referral block the server sent for
+ * each access tier.
+ *
+ * The server only attaches `referral` to `none` (landing) responses — once the
+ * user joins (queued/active) or ends a session (ended) it's dropped from the
+ * payload. That breaks the return-to-landing flow: after a session ends the
+ * slot DELETE leaves an `ended` row, so the landing GET sees `ended` (no
+ * referral) until that row is swept, which would otherwise blank the GLM
+ * referral banner for the whole visit. Caching the last-known block lets the
+ * picker re-render it immediately; a later clean `none` GET refreshes it.
+ */
+let referralByAccessTier: Partial<
+  Record<FreebuffAccessTier, FreebuffReferralInfo>
+> = {}
+
+/** Remember the referral block whenever a response includes one, so it can be
+ *  carried across the join → end → return-to-landing round-trip. Active/ended
+ *  responses intentionally omit it and keep the prior value; an authoritative
+ *  `none` response without it clears stale metadata for that tier. */
+export function rememberReferral(session: FreebuffSessionResponse | null): void {
+  const referral = getReferralInfo(session)
+  const accessTier =
+    session && 'accessTier' in session ? session.accessTier : undefined
+  // Full- and limited-tier referral blocks have different meanings. Never
+  // cache one without the tier needed to interpret it safely.
+  if (!accessTier) return
+  if (referral) {
+    referralByAccessTier[accessTier] = referral
+  } else if (session?.status === 'none') {
+    delete referralByAccessTier[accessTier]
+  }
+}
+
+/** The last referral block seen for this tier, if any. */
+export function getCachedReferral(
+  accessTier: FreebuffAccessTier | undefined,
+): FreebuffReferralInfo | undefined {
+  return accessTier ? referralByAccessTier[accessTier] : undefined
+}
+
+/** Clear account-scoped referral metadata when its session owner unmounts. */
+export function clearReferralCache(): void {
+  referralByAccessTier = {}
+}

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

@@ -0,0 +1,243 @@
+import { env } from '@anvil/common/env'
+import {
+  FREEBUFF_COMPACT_SESSION_HEADER,
+  FREEBUFF_INSTANCE_HEADER,
+  FREEBUFF_MODEL_HEADER,
+} from '@anvil/common/constants/freebuff-models'
+
+import { useFreebuffSessionStore } from '../state/freebuff-session-store'
+import { getAuthTokenDetails } from './auth'
+import { IS_FREEBUFF } from './constants'
+
+import type { FreebuffSessionResponse } from '../types/freebuff-session'
+import type { FreebuffSessionServerResponse } from '@anvil/common/types/freebuff-session'
+
+const SESSION_FETCH_TIMEOUT_MS = 20_000
+export type FreebuffSessionMethod = 'POST' | 'GET' | 'DELETE'
+
+export class FreebuffSessionRequestError extends Error {
+  constructor(
+    message: string,
+    readonly statusCode: number,
+    readonly retryAfterMs?: number,
+    readonly errorCode?: string,
+  ) {
+    super(message)
+    this.name = 'FreebuffSessionRequestError'
+  }
+}
+
+export function isFreebuffSessionTimeoutError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (error.name === 'TimeoutError' || /timeout|timed out/i.test(error.message))
+  )
+}
+
+export type FreebuffSessionFailureDisposition = 'retry' | 'stop' | 'unknown'
+
+/** How the poll loop should handle a failed request.
+ *
+ * A POST without a response may already have rotated the active instance, so
+ * repeating it is unsafe without protocol-level idempotency. HTTP 408, 429,
+ * and 503 responses are the exception: edge rejection or admission shedding
+ * produces them before the session mutation can commit. GET is read-only and
+ * can retry transient failures normally. */
+export function classifyFreebuffSessionRequestFailure(
+  method: Extract<FreebuffSessionMethod, 'POST' | 'GET'>,
+  error: unknown,
+): FreebuffSessionFailureDisposition {
+  if (method === 'POST') {
+    if (!(error instanceof FreebuffSessionRequestError)) return 'unknown'
+    // These responses are produced before the session mutation can commit:
+    // 408/429 come from an edge or unparsed response (the endpoint's typed
+    // rate-limit responses are returned above), and a 503 means no handler was
+    // available or admission shed the request. Retrying them cannot repeat a
+    // successful takeover.
+    if ([408, 429, 503].includes(error.statusCode)) {
+      return 'retry'
+    }
+    return error.statusCode >= 400 && error.statusCode < 500
+      ? 'stop'
+      : 'unknown'
+  }
+
+  if (!(error instanceof FreebuffSessionRequestError)) return 'retry'
+  return error.statusCode === 408 ||
+    error.statusCode === 429 ||
+    error.statusCode >= 500
+    ? 'retry'
+    : 'stop'
+}
+
+export function parseRetryAfterMs(
+  value: string | null,
+  nowMs = Date.now(),
+): number | undefined {
+  if (!value) return undefined
+  const seconds = Number(value)
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    const milliseconds = seconds * 1_000
+    return Number.isFinite(milliseconds) ? Math.ceil(milliseconds) : undefined
+  }
+  const dateMs = Date.parse(value)
+  return Number.isFinite(dateMs) ? Math.max(0, dateMs - nowMs) : undefined
+}
+
+/** Combine the caller's abort signal with a per-request timeout. */
+export function sessionFetchSignal(
+  signal: AbortSignal | undefined,
+  timeoutMs: number = SESSION_FETCH_TIMEOUT_MS,
+): AbortSignal {
+  const timeout = AbortSignal.timeout(timeoutMs)
+  return signal ? AbortSignal.any([signal, timeout]) : timeout
+}
+
+function sessionEndpoint(): string {
+  const base = (
+    env.NEXT_PUBLIC_ANVIL_APP_URL || 'https://codebuff.com'
+  ).replace(/\/$/, '')
+  return `${base}/api/v1/freebuff/session`
+}
+
+export async function callFreebuffSession(
+  method: FreebuffSessionMethod,
+  token: string,
+  opts: {
+    instanceId?: string
+    model?: string
+    signal?: AbortSignal
+    compact?: boolean
+  } = {},
+): Promise<FreebuffSessionServerResponse> {
+  const headers: Record<string, string> = { Authorization: `Bearer ${token}` }
+  if (method === 'GET' && opts.instanceId) {
+    headers[FREEBUFF_INSTANCE_HEADER] = opts.instanceId
+  }
+  if (method === 'GET' && opts.compact) {
+    headers[FREEBUFF_COMPACT_SESSION_HEADER] = '1'
+  }
+  if (method === 'POST' && opts.model) {
+    headers[FREEBUFF_MODEL_HEADER] = opts.model
+  }
+
+  const response = await fetch(sessionEndpoint(), {
+    method,
+    headers,
+    signal: sessionFetchSignal(opts.signal),
+  })
+
+  if (response.status === 404) {
+    return { status: 'none' }
+  }
+
+  if (response.status === 403) {
+    const body = (await response
+      .json()
+      .catch(() => null)) as FreebuffSessionServerResponse | null
+    if (
+      body &&
+      (body.status === 'country_blocked' || body.status === 'banned')
+    ) {
+      return body
+    }
+  }
+
+  if (response.status === 409 && method === 'POST') {
+    const body = (await response
+      .json()
+      .catch(() => null)) as FreebuffSessionServerResponse | null
+    if (
+      body &&
+      (body.status === 'model_locked' || body.status === 'model_unavailable')
+    ) {
+      return body
+    }
+  }
+
+  if (response.status === 429 && method === 'POST') {
+    const body = (await response
+      .json()
+      .catch(() => null)) as FreebuffSessionServerResponse | null
+    if (
+      body &&
+      (body.status === 'rate_limited' ||
+        body.status === 'spend_limited' ||
+        body.status === 'ip_capped')
+    ) {
+      return body
+    }
+  }
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => '')
+    let errorCode: string | undefined
+    try {
+      const body = JSON.parse(text) as { error?: unknown }
+      if (typeof body.error === 'string') errorCode = body.error
+    } catch {
+      // Non-JSON errors have no machine-readable code.
+    }
+    throw new FreebuffSessionRequestError(
+      `freebuff session ${method} failed: ${response.status} ${text.slice(0, 200)}`,
+      response.status,
+      parseRetryAfterMs(response.headers.get('retry-after')),
+      errorCode,
+    )
+  }
+
+  return (await response.json()) as FreebuffSessionServerResponse
+}
+
+/** A compact poll omits quota fields that were already returned by admission.
+ * Keep that snapshot only for the same active session; null tells the poller
+ * to fetch one full response before compacting again. */
+export function mergeCompactActiveSession(
+  current: FreebuffSessionResponse | null,
+  next: FreebuffSessionServerResponse,
+): FreebuffSessionServerResponse | null {
+  if (
+    current?.status !== 'active' ||
+    next.status !== 'active' ||
+    current.instanceId !== next.instanceId ||
+    current.model !== next.model
+  ) {
+    return null
+  }
+  return {
+    ...next,
+    rateLimit: next.rateLimit ?? current.rateLimit,
+    rateLimitsByModel: next.rateLimitsByModel ?? current.rateLimitsByModel,
+  }
+}
+
+export function holdsLiveFreebuffSlot(
+  current: FreebuffSessionResponse | null,
+): boolean {
+  if (!current) return false
+  return (
+    current.status === 'active' ||
+    (current.status === 'ended' && Boolean(current.instanceId))
+  )
+}
+
+/** Best-effort DELETE of the caller's session row when it holds a live slot. */
+export async function releaseFreebuffSlot(): Promise<void> {
+  const current = useFreebuffSessionStore.getState().session
+  if (!holdsLiveFreebuffSlot(current)) return
+
+  const { token } = getAuthTokenDetails()
+  if (!token) return
+
+  try {
+    await callFreebuffSession('DELETE', token)
+  } catch {
+    // The server-side sweep is the backstop.
+  }
+}
+
+/** Release the Freebuff slot on exit paths that skip React unmount. */
+export async function endFreebuffSessionBestEffort(): Promise<void> {
+  if (!IS_FREEBUFF) return
+  await releaseFreebuffSlot()
+}

package/src/utils/freebuff-session-display.ts

@@ -0,0 +1,21 @@
+export const FREEBUFF_COUNTDOWN_VISIBLE_MS = 5 * 60_000
+
+export const formatFreebuffSessionCountdown = (ms: number): string => {
+  if (ms <= 0) return 'expiring…'
+  const totalSeconds = Math.ceil(ms / 1000)
+  const m = Math.floor(totalSeconds / 60)
+  const s = totalSeconds % 60
+  return `${m}:${s.toString().padStart(2, '0')}`
+}
+
+export const formatFreebuffSessionRemaining = (ms: number): string => {
+  if (ms <= 0) return 'expiring…'
+  if (ms < FREEBUFF_COUNTDOWN_VISIBLE_MS) {
+    return `${formatFreebuffSessionCountdown(ms)} left`
+  }
+  const totalMinutes = Math.ceil(ms / 60_000)
+  if (totalMinutes < 60) return `${totalMinutes}m left`
+  const hours = Math.floor(totalMinutes / 60)
+  const minutes = totalMinutes % 60
+  return minutes === 0 ? `${hours}h left` : `${hours}h ${minutes}m left`
+}

package/src/utils/freebuff-streak-line.ts

@@ -0,0 +1,93 @@
+// The label/dots/perk-note logic is shared with Freebuff Desktop and lives in
+// common; this module re-exports it and adds the terminal rendering and layout
+// gating only the CLI needs.
+export {
+  FREEBUFF_STREAK_WEEK,
+  getFreebuffStreakBonusNote,
+} from '@anvil/common/util/freebuff-streak-line'
+export type { FreebuffStreakLine } from '@anvil/common/util/freebuff-streak-line'
+
+import {
+  FREEBUFF_STREAK_WEEK,
+  getFreebuffStreakBonusNote,
+  getFreebuffStreakLine as getSharedFreebuffStreakLine,
+} from '@anvil/common/util/freebuff-streak-line'
+
+import type { FreebuffStreakLine } from '@anvil/common/util/freebuff-streak-line'
+
+const FREEBUFF_STREAK_BONUS_MIN_HEIGHT = 30
+
+/** Columns between the count label and its progress dots. */
+export const FREEBUFF_STREAK_LABEL_GAP = 2
+
+/** Columns kept clear between the heading and the streak when they share a
+ *  row. The heading row is laid out space-between inside a shrink-to-fit
+ *  column, so when the row is the widest child there is no free space to
+ *  distribute and the two would otherwise render flush against each other
+ *  ("Start coding for free18 day streak"). This is the floor, and the same
+ *  number decides whether they may share a row at all. */
+export const FREEBUFF_STREAK_INLINE_GAP = 3
+
+/** Progress glyphs for a terminal — the same ●/○ pair the shared module and
+ *  the desktop app use. Bullet and middle dot were tried here because U+25CF
+ *  is missing from a few terminal fonts and lands as a tofu box, but • and ·
+ *  differ only in size: at a glance a partial week and a full one look alike,
+ *  which is the whole point of the row. Filled-vs-hollow reads instantly, and
+ *  the CLI already bets on ●/○ for its agent status indicators, so a font that
+ *  can't draw them is already visibly broken elsewhere.
+ *
+ *  If a font ever fails these, █/░ (Block Elements) is the fallback pair: the
+ *  ASCII logo and the progress bar are built from them, so anything that
+ *  renders the CLI at all renders those. */
+const TERMINAL_DOT_CHARS = { filled: '●', empty: '○' }
+
+/** The streak line as the CLI draws it. */
+export function getFreebuffStreakLine(
+  streak: number,
+): FreebuffStreakLine | null {
+  return getSharedFreebuffStreakLine(streak, TERMINAL_DOT_CHARS)
+}
+
+/** Rendered width of the streak, e.g. "18 day streak  ●●●●●●●+". */
+export function getFreebuffStreakInlineWidth(line: FreebuffStreakLine): number {
+  return line.label.length + FREEBUFF_STREAK_LABEL_GAP + line.dots.length
+}
+
+/** What a user with no streak yet is about to earn. The empty slot is measured
+ *  against it so the row doesn't move on day one. */
+const DAY_ONE_LINE = getFreebuffStreakLine(1)!
+
+/** Whether the heading and the streak can share a row with the inline gap left
+ *  clear between them. A streak long enough to widen its own label (or a
+ *  narrow terminal) pushes the streak onto its own line instead of letting the
+ *  two collide. */
+export function fitsFreebuffStreakOnHeadingRow(params: {
+  /** null when the user has no streak yet — measured as day one. */
+  line: FreebuffStreakLine | null
+  headingWidth: number
+  availableWidth: number
+}): boolean {
+  return (
+    params.headingWidth +
+      FREEBUFF_STREAK_INLINE_GAP +
+      getFreebuffStreakInlineWidth(params.line ?? DAY_ONE_LINE) <=
+    params.availableWidth
+  )
+}
+
+/** Returns the earned perk note only when the landing layout can show it
+ * without crowding the picker or wrapping onto additional rows. */
+export function getFreebuffStreakBonusNoteForLayout(params: {
+  streak: number
+  accessTier: 'full' | 'limited'
+  terminalHeight: number
+  availableWidth: number
+}): string | null {
+  if (params.streak < FREEBUFF_STREAK_WEEK) return null
+  if (params.terminalHeight < FREEBUFF_STREAK_BONUS_MIN_HEIGHT) return null
+
+  const note = getFreebuffStreakBonusNote(params)
+  if (!note || note.length > params.availableWidth) return null
+
+  return note
+}

package/src/utils/git.ts

@@ -0,0 +1,17 @@
+import { existsSync } from 'fs'
+import { dirname, join } from 'path'
+
+export function findGitRoot(params: { cwd: string }): string | null {
+  const { cwd } = params
+
+  let currentDir = cwd
+
+  while (currentDir !== dirname(currentDir)) {
+    if (existsSync(join(currentDir, '.git'))) {
+      return currentDir
+    }
+    currentDir = dirname(currentDir)
+  }
+
+  return null
+}

package/src/utils/helpers.ts

@@ -0,0 +1,47 @@
+let timestampFormatter: Intl.DateTimeFormat | null = null
+export function initTimestampFormatter() {
+  if (timestampFormatter) return
+  try {
+    timestampFormatter = new Intl.DateTimeFormat(undefined, {
+      hour: '2-digit',
+      minute: '2-digit',
+    })
+  } catch {
+    timestampFormatter = null
+  }
+}
+
+export function formatTimestamp(date = new Date()): string {
+  if (timestampFormatter) {
+    return timestampFormatter.format(date)
+  }
+  return date.toLocaleTimeString([], {
+    hour: '2-digit',
+    minute: '2-digit',
+  })
+}
+
+export function formatQueuedPreview(
+  messages: Array<{ content: string }>,
+  maxChars: number = 60,
+): string {
+  if (messages.length === 0) return ''
+
+  const latestMessage = messages[messages.length - 1].content
+  const singleLine = latestMessage.replace(/\s+/g, ' ').trim()
+  if (!singleLine) return ''
+
+  const countSuffix = messages.length > 1 ? ` (+ ${messages.length - 1})` : ''
+  const prefix = '↑ '
+  const suffix = ' ↑'
+  const availableChars =
+    maxChars - prefix.length - suffix.length - countSuffix.length
+
+  let messagePreview = singleLine
+  if (singleLine.length > availableChars) {
+    messagePreview =
+      singleLine.slice(0, Math.max(0, availableChars - 3)) + '...'
+  }
+
+  return `${prefix}${messagePreview}${countSuffix}${suffix}`
+}