`. Crucially, we update the text-
+ * node pointer AFTER the wrap, so the next search step sees the new node
+ * layout rather than the (now detached) original.
+ */
+function highlightMatches(root: Element, query: string): HTMLElement[] {
+ const marks: HTMLElement[] = []
+ const lowerQuery = query.toLowerCase()
+
+ if (!lowerQuery) {
+ return marks
+ }
+
+ let current: Node | null = root.firstChild
+ let textNode: Text | null = null
+
+ // Outer loop: walk element children until we have a text node to search.
+ while (current) {
+ if (current.nodeType === Node.TEXT_NODE) {
+ textNode = current as Text
+ } else if (current.nodeType === Node.ELEMENT_NODE) {
+ const el = current as Element
+
+ // Skip elements we never want to search into. The walker is
+ // deliberately flat (no recursion); a nested in a
+ // becomes a fresh descendant scan via the recursive call below.
+ if (shouldSkipElement(el)) {
+ current = el.nextSibling
+
+ continue
+ }
+
+ // Recurse into the element's descendants.
+ const inner = highlightMatches(el, query)
+
+ marks.push(...inner)
+ current = el.nextSibling
+
+ continue
+ } else {
+ current = current.nextSibling
+
+ continue
+ }
+
+ if (!textNode || !textNode.parentNode) {
+ current = textNode?.nextSibling ?? null
+
+ continue
+ }
+
+ // Search within this text node. Splits may invalidate `textNode`'s
+ // identity, so we re-read it from the parent each iteration.
+ let nodeValue = textNode.nodeValue ?? ''
+ // Capture the text node's own next sibling BEFORE any replaceChild:
+ // once the original node is detached, `.nextSibling` reads null and
+ // the outer walker would stop, skipping every following sibling
+ // subtree (`needleneedle
` searching "needle"
+ // matched only the first). `continueFrom` is the sibling AFTER this
+ // text node — for a fully-consumed match, the walker resumes there.
+ const continueFrom = textNode.nextSibling
+
+ while (true) {
+ const lower = nodeValue.toLowerCase()
+ const idx = lower.indexOf(lowerQuery)
+
+ if (idx === -1) {
+ break
+ }
+
+ const before = nodeValue.slice(0, idx)
+ const matchText = nodeValue.slice(idx, idx + lowerQuery.length)
+ const after = nodeValue.slice(idx + lowerQuery.length)
+ const parent = textNode.parentNode
+
+ if (!parent) {
+ break
+ }
+
+ const fragment = document.createDocumentFragment()
+
+ if (before) {
+ fragment.appendChild(document.createTextNode(before))
+ }
+
+ const mark = document.createElement('mark')
+
+ mark.className = HIGHLIGHT_CLASS
+ mark.textContent = matchText
+ fragment.appendChild(mark)
+
+ // Capture the after-sibling BEFORE replaceChild — replaceChild moves
+ // the fragment's children into the parent and empties the fragment,
+ // so looking at `fragment.lastChild` afterwards would point at a
+ // detached `` (or null if `before` was empty).
+ const afterNode = after ? document.createTextNode(after) : null
+
+ if (afterNode) {
+ fragment.appendChild(afterNode)
+ }
+
+ parent.replaceChild(fragment, textNode)
+
+ marks.push(mark)
+
+ if (!afterNode) {
+ // Whole text node consumed — nothing left to scan in this region.
+ textNode = null
+
+ break
+ }
+
+ textNode = afterNode
+ nodeValue = afterNode.nodeValue ?? ''
+ }
+
+ if (textNode) {
+ current = textNode.nextSibling
+ } else {
+ // The whole text node was consumed by matches — `textNode` was
+ // detached by replaceChild so its own `.nextSibling` is null. Resume
+ // the outer walker from the parent's next sibling (captured before
+ // the first replaceChild), so the sibling subtree is still searched.
+ current = continueFrom
+ }
+ }
+
+ return marks
+}
+
+/** Elements we never want to descend into during a search. Mirrors the
+ * filter the TreeWalker applied in the original design. */
+function shouldSkipElement(el: Element): boolean {
+ const tag = el.tagName
+
+ if (tag === 'SCRIPT' || tag === 'STYLE' || tag === 'NOSCRIPT') {
+ return true
+ }
+
+ if (el.closest(`mark.${HIGHLIGHT_CLASS}`)) {
+ return true
+ }
+
+ if (el.closest('[role="search"]')) {
+ return true
+ }
+
+ return false
+}
+
+/**
+ * True when `root` contains an occurrence of `query` that is NOT inside one
+ * of our find-hit marks. Read-only counterpart of `highlightMatches` with
+ * the identical skip rules, used by the findNext fast path to verify that
+ * the existing marks still cover every match — a stale mark from an earlier
+ * query can satisfy the per-mark text comparison yet leave live occurrences
+ * unwrapped, and stepping on that set would never highlight them.
+ */
+function hasUnmarkedMatch(root: Element, query: string): boolean {
+ const lowerQuery = query.toLowerCase()
+
+ if (!lowerQuery) {
+ return false
+ }
+
+ const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT)
+
+ while (walker.nextNode()) {
+ const node = walker.currentNode as Text
+ const parent = node.parentElement
+
+ if (parent && shouldSkipElement(parent)) {
+ continue
+ }
+
+ if (node.nodeValue?.toLowerCase().includes(lowerQuery)) {
+ return true
+ }
+ }
+
+ return false
+}
+
+/** Remove every find-hit mark we previously added, restoring original text. */
+function clearHighlights(root: Element): void {
+ const marks = root.querySelectorAll(`mark.${HIGHLIGHT_CLASS}`)
+
+ for (const mark of marks) {
+ const parent = mark.parentNode
+
+ if (!parent) {
+ continue
+ }
+
+ while (mark.firstChild) {
+ parent.insertBefore(mark.firstChild, mark)
+ }
+
+ parent.removeChild(mark)
+ parent.normalize()
+ }
+}
+
+/** Mark one element as the active match and scroll it into view. */
+function setActiveMark(mark: HTMLElement | null): void {
+ document.querySelectorAll(`mark[${ACTIVE_ATTR}]`).forEach(el => el.removeAttribute(ACTIVE_ATTR))
+
+ if (!mark) {
+ return
+ }
+
+ mark.setAttribute(ACTIVE_ATTR, '')
+ // Block: 'nearest' so a match already on screen doesn't twitch, but a
+ // match below the fold scrolls into view instead of silently landing off-
+ // screen. Inline: 'nearest' for the same reason. Guarded: jsdom does not
+ // implement scrollIntoView, and the bar still needs to highlight even
+ // when the renderer side has no layout (tests, headless boot, …).
+ if (typeof mark.scrollIntoView === 'function') {
+ mark.scrollIntoView({ block: 'nearest', inline: 'nearest' })
+ }
+}
+
+/** Result of a find / step — the same shape the bar already shows. */
+export interface ScopedFindResult {
+ count: number
+ activeOrdinal: number
+}
+
+export interface ScopedFindOptions {
+ forward: boolean
+ findNext: boolean
+}
+
+const DEFAULT_RESULT: ScopedFindResult = { count: 0, activeOrdinal: 0 }
+
+/**
+ * Run a scoped find against `root`. When `findNext` is true, advance / step
+ * the active mark without re-highlighting (the query has not changed). When
+ * false, drop prior highlights and re-wrap matches for `query`.
+ *
+ * Returns the (count, activeOrdinal) the bar should display. Returning a
+ * plain object instead of pushing into the store keeps this helper testable
+ * without a nanostores harness — the store wires it up.
+ */
+export function performScopedFind(
+ root: Element,
+ query: string,
+ options: ScopedFindOptions
+): ScopedFindResult {
+ if (!query) {
+ clearHighlights(root)
+ setActiveMark(null)
+ // No query, no marks to maintain — stop watching and forget the query.
+ activeQuery = ''
+ lastActiveOrdinal = 0
+ stopObserver()
+
+ return DEFAULT_RESULT
+ }
+
+ const existingMarks = [...root.querySelectorAll(`mark.${HIGHLIGHT_CLASS}`)]
+ // The marks store the ORIGINAL-CASE source slice (`highlightMatches`
+ // writes `mark.textContent = matchText`), so byte-equality against the
+ // typed query fails on the first match whose casing differs — 'Hermes'
+ // for 'hermes', sentence-initial capitals, ALL-CAPS. Without the
+ // case-insensitive comparison, every Enter/⌘G step re-wraps all
+ // highlights, `data-find-active` is lost on the fresh DOM, and the
+ // active ordinal resets to 1 forever (triage finding on #81778).
+ // The per-mark comparison alone is not enough: a stale mark from an
+ // earlier query that survived a raced re-wrap (or external DOM writes)
+ // can match the current query case-insensitively while the mark set no
+ // longer covers every match — stepping would walk old highlights and
+ // never wrap the live ones. Only step when the marks match AND cover
+ // every occurrence (review finding on #81778).
+ const sameQuery =
+ options.findNext &&
+ existingMarks.length > 0 &&
+ existingMarks.every(mark => mark.textContent.toLowerCase() === query.toLowerCase()) &&
+ !hasUnmarkedMatch(root, query)
+
+ let marks = existingMarks
+
+ if (!sameQuery) {
+ // Mutate under the re-entrancy guard so the re-render watcher doesn't
+ // fire on the marks WE are replacing (it has nothing to repair yet).
+ applying = true
+
+ try {
+ clearHighlights(root)
+ marks = highlightMatches(root, query)
+ } finally {
+ applying = false
+ }
+ }
+
+ if (marks.length === 0) {
+ setActiveMark(null)
+ // A query that matches nothing has nothing to maintain.
+ activeQuery = ''
+ lastActiveOrdinal = 0
+ stopObserver()
+
+ return DEFAULT_RESULT
+ }
+
+ const previousActive = root.querySelector(`mark[${ACTIVE_ATTR}]`)
+ let nextIndex = 0
+
+ if (previousActive) {
+ const previousIndex = marks.indexOf(previousActive)
+
+ if (previousIndex !== -1) {
+ nextIndex = options.forward
+ ? (previousIndex + 1) % marks.length
+ : (previousIndex - 1 + marks.length) % marks.length
+ }
+ } else if (!options.forward) {
+ // Entering find mode backwards (Shift+Enter on first press): land on the
+ // last match, matching browser convention.
+ nextIndex = marks.length - 1
+ }
+
+ setActiveMark(marks[nextIndex] ?? null)
+
+ // A live search must survive React re-rendering the transcript under us.
+ // Remember the query + active position and start watching the scope; the
+ // observer re-wraps when a render detaches our marks and re-activates the
+ // same ordinal so the user's place doesn't reset to match #1 on the next
+ // streamed token.
+ activeQuery = query
+ lastActiveOrdinal = nextIndex + 1
+ ensureObserver(root)
+
+ return { count: marks.length, activeOrdinal: nextIndex + 1 }
+}
+
+// ── Re-apply on React re-render ─────────────────────────────────────────────
+/**
+ * Attach the scope watcher, if it isn't already attached. Only observes the
+ * current scope; a fresh `captureFindScope` (or close) detaches it.
+ */
+function ensureObserver(root: Element): void {
+ if (observer && scopeRoot === root) {
+ return
+ }
+
+ stopObserver()
+ observer = new MutationObserver(() => scheduleReapply())
+ observer.observe(root, { childList: true, subtree: true })
+}
+
+function stopObserver(): void {
+ observer?.disconnect()
+ observer = null
+}
+
+/**
+ * Coalesce a mutation burst (one streaming delta) into a single re-apply that
+ * runs on the next microtask. A no-op when the marks still cover the query —
+ * React reusing an untouched region doesn't need any work.
+ */
+function scheduleReapply(): void {
+ if (applying) {
+ // A mutation landed while we were mutating the tree. We'll look again
+ // once this apply finishes rather than recursing now.
+ pending = true
+
+ return
+ }
+
+ if (scheduled || !scopeRoot || !activeQuery) {
+ return
+ }
+
+ scheduled = true
+
+ queueMicrotask(() => {
+ scheduled = false
+
+ if (applying || !scopeRoot || !activeQuery) {
+ return
+ }
+
+ // Nothing to repair: every occurrence is still wrapped (React only
+ // touched a region that doesn't match the query).
+ if (!hasUnmarkedMatch(scopeRoot, activeQuery)) {
+ return
+ }
+
+ reapplying(scopeRoot)
+ })
+}
+
+/**
+ * Re-wrap every occurrence in the scope after React detached our previous
+ * marks, re-activating the position the user was on. Runs with `applying` set
+ * so the observer ignores the mutations WE make, then drains any `pending`
+ * mutation that arrived during the apply.
+ */
+function reapplying(root: HTMLElement): void {
+ const restoreOrdinal = lastActiveOrdinal
+
+ applying = true
+
+ try {
+ clearHighlights(root)
+ const marks = highlightMatches(root, activeQuery)
+
+ if (marks.length === 0) {
+ return
+ }
+
+ // Re-activate the same ordinal the user last stood on, clamped to the
+ // re-wrapped set, so a mid-stream re-render doesn't bounce their place
+ // back to match #1.
+ const nextIndex = Math.min(restoreOrdinal - 1, marks.length - 1)
+ setActiveMark(marks[nextIndex] ?? null)
+ lastActiveOrdinal = nextIndex + 1
+ } finally {
+ applying = false
+ }
+
+ if (pending) {
+ pending = false
+ scheduleReapply()
+ }
+}
+
+/** Tear down highlights and the scope marker — called when the bar closes. */
+export function releaseFindScope(): void {
+ const roots = document.querySelectorAll(`[${ROOT_ATTR}]`)
+
+ for (const root of roots) {
+ clearHighlights(root)
+ root.removeAttribute(ROOT_ATTR)
+ }
+
+ setActiveMark(null)
+ resetScopeState()
+}
diff --git a/apps/desktop/src/lib/gateway-events.test.ts b/apps/desktop/src/lib/gateway-events.test.ts
index 02c3f643ca..5ec527d0bc 100644
--- a/apps/desktop/src/lib/gateway-events.test.ts
+++ b/apps/desktop/src/lib/gateway-events.test.ts
@@ -1,8 +1,14 @@
import { describe, expect, it } from 'vitest'
-import { gatewayEventRequiresSessionId, resolveGatewayEventSessionId } from './gateway-events'
+import { approvalReplaySessionId, gatewayEventRequiresSessionId, resolveGatewayEventSessionId } from './gateway-events'
describe('gateway event routing', () => {
+ it('rehydrates pending approvals on reconnect ready and resumed session info', () => {
+ expect(approvalReplaySessionId('gateway.ready', 'active-1', null)).toBe('active-1')
+ expect(approvalReplaySessionId('session.info', 'active-1', 'routed-1')).toBe('routed-1')
+ expect(approvalReplaySessionId('message.delta', 'active-1', 'routed-1')).toBeNull()
+ })
+
it('drops only unscoped subagent events (genuinely background work)', () => {
expect(gatewayEventRequiresSessionId('subagent.progress')).toBe(true)
expect(gatewayEventRequiresSessionId('subagent.start')).toBe(true)
@@ -37,6 +43,7 @@ describe('gateway event routing', () => {
expect(started).toEqual({
drop: false,
nextUnscopedStreamSessionId: 'session-a',
+ pinned: false,
sessionId: 'session-a'
})
@@ -50,6 +57,7 @@ describe('gateway event routing', () => {
expect(delta).toEqual({
drop: false,
nextUnscopedStreamSessionId: 'session-a',
+ pinned: true,
sessionId: 'session-a'
})
@@ -63,6 +71,7 @@ describe('gateway event routing', () => {
expect(completed).toEqual({
drop: false,
nextUnscopedStreamSessionId: null,
+ pinned: true,
sessionId: 'session-a'
})
})
@@ -78,6 +87,27 @@ describe('gateway event routing', () => {
expect(routed).toEqual({
drop: false,
nextUnscopedStreamSessionId: 'session-b',
+ pinned: false,
+ sessionId: 'session-b'
+ })
+ })
+
+ it('attributes an unpinned stream event to the active session without the pin flag', () => {
+ // A late straggler (no pin left after the previous turn completed) falls
+ // back to the active session. The handler drops this case when the target
+ // session has no live turn — the straggler belongs to a turn that already
+ // ended elsewhere (#43142 family).
+ const routed = resolveGatewayEventSessionId({
+ activeSessionId: 'session-b',
+ eventType: 'thinking.delta',
+ explicitSessionId: '',
+ unscopedStreamSessionId: null
+ })
+
+ expect(routed).toEqual({
+ drop: false,
+ nextUnscopedStreamSessionId: null,
+ pinned: false,
sessionId: 'session-b'
})
})
@@ -93,6 +123,7 @@ describe('gateway event routing', () => {
expect(routed).toEqual({
drop: false,
nextUnscopedStreamSessionId: null,
+ pinned: true,
sessionId: 'session-a'
})
})
diff --git a/apps/desktop/src/lib/gateway-events.ts b/apps/desktop/src/lib/gateway-events.ts
index 4b09ba30d7..6375955510 100644
--- a/apps/desktop/src/lib/gateway-events.ts
+++ b/apps/desktop/src/lib/gateway-events.ts
@@ -17,7 +17,12 @@ function asRecord(payload: unknown): Record {
* Without this, ``explicitSid || activeSessionId`` reattributes live deltas to
* the newly focused chat.
*/
-const UNSCOPED_STREAM_EVENT_TYPES = new Set([
+/** Unscoped stream events that must stay pinned to the session that received
+ * ``message.start`` after the user switches chats mid-turn (#47709 / #48281).
+ * Without this, ``explicitSid || activeSessionId`` reattributes live deltas to
+ * the newly focused chat. Exported so the event handler can tell which events
+ * are pin-eligible when deciding whether an unpinned straggler is legitimate. */
+export const UNSCOPED_STREAM_EVENT_TYPES = new Set([
'approval.request',
'browser.progress',
'clarify.request',
@@ -67,9 +72,30 @@ export interface GatewayEventSessionRouteInput {
export interface GatewayEventSessionRoute {
drop: boolean
nextUnscopedStreamSessionId: null | string
+ /** True when the event was attributed via the pinned stream session rather
+ * than the active-session fallback. The caller uses this to drop late
+ * stragglers: an unpinned stream event landing on a session that has no
+ * live turn belongs to a turn that already ended elsewhere. */
+ pinned: boolean
sessionId: null | string
}
+export function approvalReplaySessionId(
+ eventType: string | undefined,
+ activeSessionId: null | string,
+ routedSessionId: null | string
+): null | string {
+ if (eventType === 'gateway.ready') {
+ return activeSessionId
+ }
+
+ if (eventType === 'session.info') {
+ return routedSessionId
+ }
+
+ return null
+}
+
/**
* Resolve which runtime session owns a gateway event.
*
@@ -92,6 +118,7 @@ export function resolveGatewayEventSessionId({
return {
drop: false,
nextUnscopedStreamSessionId,
+ pinned: true,
sessionId: explicitSessionId
}
}
@@ -100,6 +127,7 @@ export function resolveGatewayEventSessionId({
return {
drop: true,
nextUnscopedStreamSessionId: unscopedStreamSessionId,
+ pinned: false,
sessionId: null
}
}
@@ -124,6 +152,7 @@ export function resolveGatewayEventSessionId({
return {
drop: false,
nextUnscopedStreamSessionId,
+ pinned: streamEvent && eventType !== 'message.start' && Boolean(unscopedStreamSessionId),
sessionId
}
}
diff --git a/apps/desktop/src/lib/icons.ts b/apps/desktop/src/lib/icons.ts
index 6b3d5f80cc..943dd1870a 100644
--- a/apps/desktop/src/lib/icons.ts
+++ b/apps/desktop/src/lib/icons.ts
@@ -80,6 +80,7 @@ import {
IconDots as MoreHorizontal,
IconDots as MoreHorizontalIcon,
IconDotsVertical as MoreVertical,
+ IconNetwork as Network,
IconNotebook as NotebookTabs,
IconPackage as Package,
IconPalette as Palette,
@@ -207,6 +208,7 @@ export {
MoreHorizontal,
MoreHorizontalIcon,
MoreVertical,
+ Network,
NotebookTabs,
Package,
Palette,
diff --git a/apps/desktop/src/lib/image-resize.test.ts b/apps/desktop/src/lib/image-resize.test.ts
new file mode 100644
index 0000000000..cc23de1ff2
--- /dev/null
+++ b/apps/desktop/src/lib/image-resize.test.ts
@@ -0,0 +1,199 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { downscaleDataUrlForPreview } from './image-resize'
+
+// A minimal valid 1x1 red PNG (67 bytes) for testing
+const TINY_PNG_B64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+GkZcAAAAASUVORK5CYII='
+
+const TINY_PNG_DATA_URL = `data:image/png;base64,${TINY_PNG_B64}`
+
+// A 1×1 transparent PNG used as the fallback placeholder
+const FALLBACK_PLACEHOLDER =
+ 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+GkZcAAAAASUVORK5CYII='
+
+describe('downscaleDataUrlForPreview', () => {
+ afterEach(() => {
+ vi.restoreAllMocks()
+ vi.unstubAllGlobals()
+ })
+
+ describe('without createImageBitmap (jsdom default)', () => {
+ it('fails closed when createImageBitmap is unavailable', async () => {
+ await expect(downscaleDataUrlForPreview('data:image/png;base64,ZmFrZQ==')).resolves.toBe(FALLBACK_PLACEHOLDER)
+ })
+
+ it('preserves an external source when resize APIs are unavailable', async () => {
+ await expect(downscaleDataUrlForPreview('not-a-data-url')).resolves.toBe('not-a-data-url')
+ })
+
+ it('preserves a non-image data URL when resize APIs are unavailable', async () => {
+ await expect(downscaleDataUrlForPreview('data:text/plain')).resolves.toBe('data:text/plain')
+ })
+ })
+
+ describe('with mocked createImageBitmap + OffscreenCanvas', () => {
+ /**
+ * Set up the full mock chain: fetch → createImageBitmap → OffscreenCanvas → FileReader.
+ * Mocks a bitmap of the given dimensions so the downscaling logic is exercised.
+ */
+ function setupMocks(bitmapWidth: number, bitmapHeight: number) {
+ let activeBitmaps = 0
+ let maxActiveBitmaps = 0
+
+ const close = vi.fn(() => {
+ activeBitmaps -= 1
+ })
+
+ const drawImage = vi.fn()
+ const convertToBlob = vi.fn(async () => new Blob(['x'], { type: 'image/png' }))
+ const canvasSizes: [number, number][] = []
+
+ const bitmap = { width: bitmapWidth, height: bitmapHeight, close }
+ const ctx = { drawImage }
+
+ class MockOffscreenCanvas {
+ getContext = vi.fn(() => ctx)
+ convertToBlob = convertToBlob
+ constructor(width: number, height: number) {
+ canvasSizes.push([width, height])
+ }
+ }
+
+ // Mock fetch to return a Blob from the data URL
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => ({
+ blob: async () => new Blob([new Uint8Array([0])], { type: 'image/png' })
+ }))
+ )
+ vi.stubGlobal(
+ 'createImageBitmap',
+ vi.fn(async () => {
+ activeBitmaps += 1
+ maxActiveBitmaps = Math.max(maxActiveBitmaps, activeBitmaps)
+
+ return bitmap
+ })
+ )
+ vi.stubGlobal('OffscreenCanvas', MockOffscreenCanvas)
+
+ return { bitmap, close, drawImage, convertToBlob, ctx, canvasSizes, maxActiveBitmaps: () => maxActiveBitmaps }
+ }
+
+ it('returns the original when image is smaller than maxLongEdge', async () => {
+ setupMocks(500, 300)
+
+ const result = await downscaleDataUrlForPreview(TINY_PNG_DATA_URL, 2048)
+ expect(result).toBe(TINY_PNG_DATA_URL)
+ })
+
+ it('downscales when image exceeds the default preview edge', async () => {
+ const { drawImage, close } = setupMocks(4000, 3000)
+
+ // In jsdom, FileReader.readAsDataURL won't actually produce a data URL,
+ // so the function falls through to the fallback placeholder. But the
+ // important thing is that drawImage was called with scaled dimensions
+ // and the bitmap was closed.
+ const result = await downscaleDataUrlForPreview(TINY_PNG_DATA_URL)
+
+ // scale = 512 / 4000 = 0.128 → width=512, height=384
+ expect(drawImage).toHaveBeenCalledWith(expect.anything(), 0, 0, 512, 384)
+ expect(close).toHaveBeenCalled()
+
+ // Result should be the downscaled data URL (from our mocked blob),
+ // NOT the original tiny PNG — the function attempted downscaling.
+ expect(result).not.toBe(TINY_PNG_DATA_URL)
+ // The drawImage was called with correct dimensions and bitmap was cleaned up
+ expect(drawImage).toHaveBeenCalled()
+ expect(close).toHaveBeenCalled()
+ })
+
+ it('keeps every thumbnail bounded for a 72-image composer prompt', async () => {
+ const { canvasSizes, drawImage, maxActiveBitmaps } = setupMocks(6000, 6000)
+
+ await Promise.all(Array.from({ length: 72 }, () => downscaleDataUrlForPreview(TINY_PNG_DATA_URL)))
+
+ expect(canvasSizes).toHaveLength(72)
+ expect(canvasSizes.every(([width, height]) => width === 512 && height === 512)).toBe(true)
+ expect(drawImage).toHaveBeenCalledTimes(72)
+ expect(maxActiveBitmaps()).toBe(1)
+ })
+
+ it('returns placeholder when createImageBitmap throws', async () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => ({
+ blob: async () => new Blob([new Uint8Array([0])], { type: 'image/png' })
+ }))
+ )
+ vi.stubGlobal(
+ 'createImageBitmap',
+ vi.fn(async () => {
+ throw new Error('decode failed')
+ })
+ )
+ vi.stubGlobal(
+ 'OffscreenCanvas',
+ vi.fn(() => ({}))
+ )
+
+ const result = await downscaleDataUrlForPreview(TINY_PNG_DATA_URL, 2048)
+ expect(result).toBe(FALLBACK_PLACEHOLDER)
+ })
+
+ it('closes bitmap even when canvas getContext returns null', async () => {
+ const close = vi.fn()
+ const bitmap = { width: 4000, height: 3000, close }
+
+ class NullCanvas {
+ getContext = () => null
+ constructor(_w: number, _h: number) {}
+ }
+
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => ({
+ blob: async () => new Blob([new Uint8Array([0])], { type: 'image/png' })
+ }))
+ )
+ vi.stubGlobal(
+ 'createImageBitmap',
+ vi.fn(async () => bitmap)
+ )
+ vi.stubGlobal('OffscreenCanvas', NullCanvas)
+
+ const result = await downscaleDataUrlForPreview(TINY_PNG_DATA_URL, 2048)
+ expect(result).toBe(FALLBACK_PLACEHOLDER)
+ expect(close).toHaveBeenCalled()
+ })
+
+ it('uses placeholder instead of original on convertToBlob failure', async () => {
+ const close = vi.fn()
+ const bitmap = { width: 4000, height: 3000, close }
+
+ class BrokenCanvas {
+ getContext = () => ({ drawImage: vi.fn() })
+ convertToBlob = vi.fn(async () => {
+ throw new Error('blob failed')
+ })
+ constructor(_w: number, _h: number) {}
+ }
+
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => ({
+ blob: async () => new Blob([new Uint8Array([0])], { type: 'image/png' })
+ }))
+ )
+ vi.stubGlobal(
+ 'createImageBitmap',
+ vi.fn(async () => bitmap)
+ )
+ vi.stubGlobal('OffscreenCanvas', BrokenCanvas)
+
+ const result = await downscaleDataUrlForPreview(TINY_PNG_DATA_URL, 2048)
+ expect(result).toBe(FALLBACK_PLACEHOLDER)
+ expect(close).toHaveBeenCalled()
+ })
+ })
+})
diff --git a/apps/desktop/src/lib/image-resize.ts b/apps/desktop/src/lib/image-resize.ts
new file mode 100644
index 0000000000..1639488363
--- /dev/null
+++ b/apps/desktop/src/lib/image-resize.ts
@@ -0,0 +1,95 @@
+/**
+ * Downscale a data URL for preview rendering.
+ *
+ * Large images (Retina screenshots, 6000×4000+) cause Chromium to build very
+ * large paint operations when the original is assigned to an ![]()
. This
+ * utility uses createImageBitmap + OffscreenCanvas to resize before display.
+ *
+ * Calls share a one-at-a-time queue. Multi-image attach flows must not keep
+ * dozens of decoded full-resolution bitmaps alive concurrently while their
+ * 512px thumbnails are produced.
+ *
+ * @param dataUrl The full-resolution data URL (data:image/...;base64,...)
+ * @param maxLongEdge Maximum pixel dimension on the longest side (default 512)
+ * @returns A downscaled PNG data URL, the original if already small enough, or
+ * a 1×1 transparent PNG placeholder if downscaling fails.
+ */
+
+/** 1×1 transparent PNG — fail closed so the pill never receives the original. */
+const FALLBACK_PLACEHOLDER =
+ 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+GkZcAAAAASUVORK5CYII='
+
+// Composer pills render at 32 CSS pixels. A 512px source stays sharp on
+// high-density displays while keeping a square RGBA decode to 1 MiB. A 2048px
+// thumbnail can decode to 16 MiB and reproduce Chromium's paint-op pressure.
+const DEFAULT_MAX_LONG_EDGE = 512
+
+let resizeQueue = Promise.resolve()
+
+async function downscaleDataUrl(dataUrl: string, maxLongEdge: number): Promise {
+ try {
+ // fetch(data:) decodes base64 natively in C++ and avoids an O(n) atob loop.
+ const blob = await fetch(dataUrl).then(response => response.blob())
+ const bitmap = await createImageBitmap(blob)
+
+ try {
+ const { width, height } = bitmap
+ const longEdge = Math.max(width, height)
+
+ if (longEdge <= maxLongEdge) {
+ return dataUrl
+ }
+
+ const scale = maxLongEdge / longEdge
+ const newWidth = Math.max(1, Math.round(width * scale))
+ const newHeight = Math.max(1, Math.round(height * scale))
+ const canvas = new OffscreenCanvas(newWidth, newHeight)
+ const ctx = canvas.getContext('2d')
+
+ if (!ctx) {
+ return FALLBACK_PLACEHOLDER
+ }
+
+ ctx.drawImage(bitmap, 0, 0, newWidth, newHeight)
+
+ const resultBlob = await canvas.convertToBlob({ type: 'image/png' })
+ const reader = new FileReader()
+
+ return await new Promise(resolve => {
+ reader.onloadend = () => resolve(typeof reader.result === 'string' ? reader.result : FALLBACK_PLACEHOLDER)
+ reader.onabort = () => resolve(FALLBACK_PLACEHOLDER)
+ reader.onerror = () => resolve(FALLBACK_PLACEHOLDER)
+ reader.readAsDataURL(resultBlob)
+ })
+ } finally {
+ bitmap.close()
+ }
+ } catch {
+ return FALLBACK_PLACEHOLDER
+ }
+}
+
+export async function downscaleDataUrlForPreview(
+ dataUrl: string,
+ maxLongEdge = DEFAULT_MAX_LONG_EDGE
+): Promise {
+ if (!dataUrl.startsWith('data:image/') || dataUrl.indexOf(',') === -1) {
+ return dataUrl
+ }
+
+ // Never hand a full-resolution image to the pill if resize support is absent.
+ // A tiny placeholder is preferable to recreating the renderer failure this
+ // helper exists to prevent.
+ if (typeof createImageBitmap !== 'function' || typeof OffscreenCanvas !== 'function') {
+ return FALLBACK_PLACEHOLDER
+ }
+
+ const task = resizeQueue.then(() => downscaleDataUrl(dataUrl, maxLongEdge))
+
+ resizeQueue = task.then(
+ () => undefined,
+ () => undefined
+ )
+
+ return task
+}
diff --git a/apps/desktop/src/lib/inflight-turn-journal.test.ts b/apps/desktop/src/lib/inflight-turn-journal.test.ts
index 206a122288..8041db1059 100644
--- a/apps/desktop/src/lib/inflight-turn-journal.test.ts
+++ b/apps/desktop/src/lib/inflight-turn-journal.test.ts
@@ -7,11 +7,15 @@ import {
mergeInFlightMessages,
persistInFlightTurnState,
readInFlightTurnJournal,
- recoverInFlightTurnJournal
+ recoverInFlightTurnJournal,
+ resetInFlightTurnJournalStateForTests
} from '@/lib/inflight-turn-journal'
+const STORAGE_KEY = 'hermes.desktop.inflightTurnJournal.v1'
const STORAGE_PREFIX = 'hermes.desktop.inflightTurnJournal.v2:'
-const LEGACY_STORAGE_KEY = 'hermes.desktop.inflightTurnJournal.v1'
+const MIGRATION_KEY = 'hermes.desktop.inflightTurnJournal.v2.migrated'
+
+const sessionStorageKey = (storedSessionId: string) => `${STORAGE_PREFIX}${encodeURIComponent(storedSessionId)}`
function user(id: string, text: string): ChatMessage {
return { id, role: 'user', parts: [{ type: 'text', text }] }
@@ -46,16 +50,94 @@ function journalState(overrides: Partial = {}): Journal
}
beforeEach(() => {
+ resetInFlightTurnJournalStateForTests()
vi.useFakeTimers()
window.localStorage.clear()
})
afterEach(() => {
+ vi.restoreAllMocks()
clearInFlightTurnJournal('stored-1')
vi.useRealTimers()
})
describe('persistInFlightTurnState', () => {
+ it('sweeps expired and oldest session entries once before the first write', () => {
+ const now = Date.now()
+
+ for (let index = 0; index < 25; index += 1) {
+ const sessionId = `old-${index}`
+
+ const snapshot = {
+ messages: [
+ user(`u-${index}`, `prompt-${index}`),
+ assistant(`a-${index}`, `partial-${index}`, { pending: true })
+ ],
+ streamId: `a-${index}`,
+ turnStartedAt: index,
+ updatedAt: now - index * 1_000
+ }
+
+ window.localStorage.setItem(sessionStorageKey(sessionId), JSON.stringify(snapshot))
+ }
+
+ window.localStorage.setItem(
+ sessionStorageKey('expired'),
+ JSON.stringify({
+ messages: [user('expired-u', 'expired'), assistant('expired-a', 'expired', { pending: true })],
+ streamId: 'expired-a',
+ turnStartedAt: 0,
+ updatedAt: now - 8 * 24 * 60 * 60 * 1_000
+ })
+ )
+
+ persistInFlightTurnState(journalState())
+ vi.advanceTimersByTime(400)
+
+ const sessionKeys = Array.from({ length: window.localStorage.length }, (_, index) =>
+ window.localStorage.key(index)
+ ).filter((key): key is string => key?.startsWith(STORAGE_PREFIX) === true)
+
+ expect(sessionKeys).toHaveLength(24)
+ expect(window.localStorage.getItem(sessionStorageKey('expired'))).toBeNull()
+ expect(window.localStorage.getItem(sessionStorageKey('old-24'))).toBeNull()
+ expect(window.localStorage.getItem(sessionStorageKey('stored-1'))).not.toBeNull()
+ })
+
+ it('writes only the current session instead of reading and rewriting the aggregate journal', () => {
+ const localStorage = window.localStorage
+ const storageConstructor = window.Storage
+
+ const spyTarget =
+ typeof storageConstructor === 'function' && localStorage instanceof storageConstructor
+ ? storageConstructor.prototype
+ : localStorage
+
+ const getItem = vi.spyOn(spyTarget, 'getItem')
+ const setItem = vi.spyOn(spyTarget, 'setItem')
+
+ persistInFlightTurnState(journalState())
+ vi.advanceTimersByTime(400)
+
+ expect(getItem).not.toHaveBeenCalledWith(STORAGE_KEY)
+ expect(setItem).not.toHaveBeenCalledWith(STORAGE_KEY, expect.any(String))
+ expect(setItem).toHaveBeenCalledWith(sessionStorageKey('stored-1'), expect.any(String))
+ })
+
+ it('keeps another session snapshot when one session settles', () => {
+ persistInFlightTurnState(journalState())
+ persistInFlightTurnState(journalState({ storedSessionId: 'stored-2' }))
+ vi.advanceTimersByTime(400)
+
+ expect(window.localStorage.getItem(sessionStorageKey('stored-1'))).not.toBeNull()
+ expect(window.localStorage.getItem(sessionStorageKey('stored-2'))).not.toBeNull()
+
+ clearInFlightTurnJournal('stored-2')
+
+ expect(readInFlightTurnJournal('stored-1')).not.toBeNull()
+ expect(readInFlightTurnJournal('stored-2')).toBeNull()
+ })
+
it('journals the running turn tail after the throttle window', () => {
persistInFlightTurnState(journalState())
@@ -88,6 +170,182 @@ describe('persistInFlightTurnState', () => {
expect(tail?.parts).toEqual([{ type: 'text', text: 'partial answer grew' }])
})
+ it('preserves a long user prompt exactly so recovery still matches its transcript row', () => {
+ const prompt = 'prompt '.repeat(8_000)
+
+ persistInFlightTurnState(
+ journalState({
+ messages: [user('u1', prompt), assistant('assistant-stream-1', 'partial', { pending: true })]
+ })
+ )
+ vi.advanceTimersByTime(400)
+
+ const result = recoverInFlightTurnJournal('stored-1', [user('db-u1', prompt)])
+
+ expect(result.messages.map(message => message.id)).toEqual(['db-u1', 'assistant-stream-1'])
+ })
+
+ it('preserves user attachment refs exactly so recovery still matches its transcript row', () => {
+ const attachmentRefs = Array.from({ length: 25 }, (_, index) => `@file:/tmp/input-${index}.txt`)
+ const prompt = user('u1', 'inspect these files')
+ prompt.attachmentRefs = attachmentRefs
+
+ persistInFlightTurnState(
+ journalState({ messages: [prompt, assistant('assistant-stream-1', 'partial', { pending: true })] })
+ )
+ vi.advanceTimersByTime(400)
+
+ const restoredPrompt = user('db-u1', 'inspect these files')
+ restoredPrompt.attachmentRefs = attachmentRefs
+ const result = recoverInFlightTurnJournal('stored-1', [restoredPrompt])
+
+ expect(result.messages.map(message => message.id)).toEqual(['db-u1', 'assistant-stream-1'])
+ })
+
+ it('trims oldest sealed rows when bounded parts exceed the entry cap', () => {
+ const text = 'x'.repeat(60 * 1024)
+
+ const messages = [
+ user('u1', 'do the thing'),
+ assistant('a1', text, { pending: false }),
+ assistant('a2', text, { pending: false }),
+ assistant('a3', text, { pending: false }),
+ assistant('a4', text, { pending: true })
+ ]
+
+ persistInFlightTurnState(journalState({ messages, streamId: 'a4' }))
+ vi.advanceTimersByTime(400)
+
+ const raw = window.localStorage.getItem(sessionStorageKey('stored-1'))
+ const snapshot = JSON.parse(raw!)
+
+ expect(raw?.length).toBeLessThanOrEqual(160 * 1024)
+ expect(snapshot.messages.map((message: ChatMessage) => message.id)).toEqual(['u1', 'a3', 'a4'])
+ })
+
+ it('keeps an older recoverable snapshot when the newest row alone is too large', () => {
+ persistInFlightTurnState(journalState())
+ vi.advanceTimersByTime(400)
+
+ const hugeAssistant: ChatMessage = {
+ id: 'assistant-stream-1',
+ role: 'assistant',
+ parts: Array.from({ length: 3 }, () => ({ type: 'text' as const, text: 'x'.repeat(64 * 1024) })),
+ pending: true
+ }
+
+ persistInFlightTurnState(
+ journalState({ messages: [user('u1', 'do the thing'), hugeAssistant], streamId: hugeAssistant.id })
+ )
+ vi.advanceTimersByTime(400)
+
+ const snapshot = JSON.parse(window.localStorage.getItem(sessionStorageKey('stored-1'))!)
+
+ expect(snapshot.messages[1].parts).toEqual([{ type: 'text', text: 'partial answer' }])
+ })
+
+ it('skips a pathological user prompt instead of truncating its recovery join key', () => {
+ const prompt = 'x'.repeat(64 * 1024 + 1)
+
+ persistInFlightTurnState(
+ journalState({
+ messages: [user('u1', prompt), assistant('assistant-stream-1', 'partial', { pending: true })]
+ })
+ )
+ vi.advanceTimersByTime(400)
+
+ expect(readInFlightTurnJournal('stored-1')).toBeNull()
+ })
+
+ it('does not parse the legacy aggregate when a pathological write discards its session', () => {
+ const legacy = {
+ messages: [user('legacy-u1', 'old prompt'), assistant('legacy-a1', 'old partial', { pending: true })],
+ streamId: 'legacy-a1',
+ turnStartedAt: 1,
+ updatedAt: Date.now()
+ }
+
+ window.localStorage.setItem(STORAGE_KEY, JSON.stringify({ entries: { 'stored-1': legacy }, version: 1 }))
+ const getItem = vi.spyOn(Storage.prototype, 'getItem')
+ const prompt = 'x'.repeat(64 * 1024 + 1)
+
+ persistInFlightTurnState(
+ journalState({
+ messages: [user('u1', prompt), assistant('assistant-stream-1', 'partial', { pending: true })]
+ })
+ )
+ vi.advanceTimersByTime(400)
+
+ expect(getItem).not.toHaveBeenCalledWith(STORAGE_KEY)
+ expect(readInFlightTurnJournal('stored-1')).toBeNull()
+ })
+
+ it('preserves a tombstone while sweeping before legacy migration', () => {
+ const legacy = {
+ messages: [user('legacy-u1', 'old prompt'), assistant('legacy-a1', 'old partial', { pending: true })],
+ streamId: 'legacy-a1',
+ turnStartedAt: 1,
+ updatedAt: Date.now()
+ }
+
+ window.localStorage.setItem(sessionStorageKey('stored-1'), '0')
+ window.localStorage.setItem(STORAGE_KEY, JSON.stringify({ entries: { 'stored-1': legacy }, version: 1 }))
+
+ expect(readInFlightTurnJournal('stored-1')).toBeNull()
+ expect(window.localStorage.getItem(STORAGE_KEY)).toBeNull()
+ expect(window.localStorage.getItem(sessionStorageKey('stored-1'))).toBeNull()
+ })
+
+ it('removes tombstones after the one-shot legacy migration has completed', () => {
+ const key = sessionStorageKey('stored-1')
+
+ window.localStorage.setItem(MIGRATION_KEY, '1')
+ window.localStorage.setItem(key, '0')
+
+ expect(readInFlightTurnJournal('stored-1')).toBeNull()
+ expect(window.localStorage.getItem(key)).toBeNull()
+ })
+
+ it('strips pathological 5 MiB tool payloads before attempting a storage write', () => {
+ const setItem = vi.spyOn(Storage.prototype, 'setItem')
+
+ const oversized: ChatMessage = {
+ id: 'assistant-stream-1',
+ role: 'assistant',
+ parts: [
+ {
+ type: 'tool-call',
+ toolCallId: 'tc-1',
+ toolName: 'terminal',
+ args: { command: 'x'.repeat(5 * 1024 * 1024) },
+ result: 'x'.repeat(5 * 1024 * 1024),
+ isError: true
+ },
+ { type: 'text', text: 'still useful' }
+ ],
+ pending: true
+ }
+
+ persistInFlightTurnState(journalState({ messages: [user('u1', 'do the thing'), oversized] }))
+ vi.advanceTimersByTime(400)
+
+ const raw = window.localStorage.getItem(sessionStorageKey('stored-1'))
+ const snapshot = JSON.parse(raw!)
+ const persistedTool = snapshot.messages[1].parts[0]
+
+ expect(raw?.length).toBeLessThan(256 * 1024)
+ expect(persistedTool).toEqual({
+ args: {},
+ isError: true,
+ result: {},
+ toolCallId: 'tc-1',
+ toolName: 'terminal',
+ type: 'tool-call'
+ })
+ expect(snapshot.messages[1].parts[1]).toEqual({ type: 'text', text: 'still useful' })
+ expect(setItem.mock.calls.every(([, value]) => value.length <= 256 * 1024)).toBe(true)
+ })
+
it('clears the entry the moment the turn settles, cancelling pending writes', () => {
persistInFlightTurnState(journalState())
vi.advanceTimersByTime(400)
@@ -113,52 +371,170 @@ describe('persistInFlightTurnState', () => {
persistInFlightTurnState(journalState())
vi.advanceTimersByTime(400)
- const raw = JSON.parse(window.localStorage.getItem(`${STORAGE_PREFIX}stored-1`)!)
+ const key = sessionStorageKey('stored-1')
+ const raw = JSON.parse(window.localStorage.getItem(key)!)
raw.updatedAt = Date.now() - 8 * 24 * 60 * 60 * 1000
- window.localStorage.setItem(`${STORAGE_PREFIX}stored-1`, JSON.stringify(raw))
+ window.localStorage.setItem(key, JSON.stringify(raw))
expect(readInFlightTurnJournal('stored-1')).toBeNull()
})
- it('writes each session under its own key, untouched by other sessions settling', () => {
- persistInFlightTurnState(journalState())
- persistInFlightTurnState(journalState({ storedSessionId: 'stored-2' }))
- vi.advanceTimersByTime(400)
+ it('isolates storage read, write, and removal failures', () => {
+ const getItem = vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+ throw new Error('read denied')
+ })
- expect(window.localStorage.getItem(`${STORAGE_PREFIX}stored-1`)).not.toBeNull()
- expect(window.localStorage.getItem(`${STORAGE_PREFIX}stored-2`)).not.toBeNull()
+ expect(() => readInFlightTurnJournal('stored-1')).not.toThrow()
+ getItem.mockRestore()
- clearInFlightTurnJournal('stored-2')
+ const setItem = vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+ throw new Error('quota')
+ })
- expect(readInFlightTurnJournal('stored-1')).not.toBeNull()
- expect(readInFlightTurnJournal('stored-2')).toBeNull()
+ expect(() => {
+ persistInFlightTurnState(journalState())
+ vi.advanceTimersByTime(400)
+ }).not.toThrow()
+ setItem.mockRestore()
+
+ const removeItem = vi.spyOn(Storage.prototype, 'removeItem').mockImplementation(() => {
+ throw new Error('remove denied')
+ })
+
+ expect(() => clearInFlightTurnJournal('stored-1')).not.toThrow()
})
- it('recovers entries journaled by the v1 single-key store', () => {
- // A pre-upgrade crash leaves a v1 store behind; the first journal touch
- // after the upgrade must still recover its turns.
+ it('discards malformed optional message metadata instead of throwing during recovery', () => {
window.localStorage.setItem(
- LEGACY_STORAGE_KEY,
+ sessionStorageKey('stored-1'),
JSON.stringify({
- entries: {
- 'stored-legacy': {
- messages: [user('u1', 'legacy prompt'), assistant('a1', 'legacy partial', { pending: true })],
- streamId: 'a1',
- turnStartedAt: 500,
- updatedAt: Date.now()
- }
- },
- version: 1
+ messages: [
+ { id: 'u1', role: 'user', parts: [{ type: 'text', text: 'prompt' }], attachmentRefs: '@file:bad' },
+ { id: 'a1', role: 'assistant', parts: [{ type: 'text', text: 'partial' }], pending: true }
+ ],
+ streamId: 'a1',
+ turnStartedAt: 1,
+ updatedAt: Date.now()
})
)
+ const base = [user('db-u1', 'prompt')]
- const entry = readInFlightTurnJournal('stored-legacy')
+ expect(() => recoverInFlightTurnJournal('stored-1', base)).not.toThrow()
+ expect(readInFlightTurnJournal('stored-1')).toBeNull()
+ })
+})
- expect(entry?.streamId).toBe('a1')
- expect(entry?.messages).toHaveLength(2)
- expect(window.localStorage.getItem(LEGACY_STORAGE_KEY)).toBeNull()
+describe('legacy journal migration', () => {
+ it('migrates the bounded v1 aggregate once and recovers its sessions', () => {
+ const first = {
+ messages: [user('u1', 'one'), assistant('a1', 'partial one', { pending: true })],
+ streamId: 'a1',
+ turnStartedAt: 1,
+ updatedAt: Date.now()
+ }
- clearInFlightTurnJournal('stored-legacy')
+ const second = {
+ messages: [
+ user('u2', 'two'),
+ {
+ id: 'a2',
+ role: 'assistant' as const,
+ parts: [
+ {
+ type: 'tool-call' as const,
+ toolCallId: 'tc-legacy',
+ toolName: 'terminal',
+ args: { command: 'large-output' },
+ result: 'x'.repeat(1024 * 1024)
+ },
+ { type: 'text' as const, text: 'partial two' }
+ ],
+ pending: true
+ }
+ ],
+ streamId: 'a2',
+ turnStartedAt: 2,
+ updatedAt: Date.now()
+ }
+
+ window.localStorage.setItem(STORAGE_KEY, JSON.stringify({ entries: { one: first, two: second }, version: 1 }))
+
+ expect(readInFlightTurnJournal('one')).toEqual(first)
+ const migratedSecondRaw = window.localStorage.getItem(sessionStorageKey('two'))!
+ const migratedSecond = JSON.parse(migratedSecondRaw)
+
+ expect(migratedSecondRaw.length).toBeLessThan(256 * 1024)
+ expect(migratedSecond.messages[1].parts).toEqual([
+ { args: {}, result: {}, toolCallId: 'tc-legacy', toolName: 'terminal', type: 'tool-call' },
+ { text: 'partial two', type: 'text' }
+ ])
+ expect(window.localStorage.getItem(STORAGE_KEY)).toBeNull()
+ expect(window.localStorage.getItem(MIGRATION_KEY)).toBe('1')
+
+ window.localStorage.setItem(STORAGE_KEY, JSON.stringify({ entries: { three: first }, version: 1 }))
+ expect(readInFlightTurnJournal('three')).toBeNull()
+ expect(window.localStorage.getItem(STORAGE_KEY)).not.toBeNull()
+ })
+
+ it('drops an oversized legacy aggregate without parsing it', () => {
+ window.localStorage.setItem(STORAGE_KEY, 'x'.repeat(2 * 1024 * 1024 + 1))
+
+ expect(readInFlightTurnJournal('stored-1')).toBeNull()
+ expect(window.localStorage.getItem(STORAGE_KEY)).toBeNull()
+ expect(window.localStorage.getItem(MIGRATION_KEY)).toBe('1')
+ })
+
+ it('does not overwrite a newer per-session snapshot while migrating another legacy session', () => {
+ persistInFlightTurnState(journalState())
+ vi.advanceTimersByTime(400)
+
+ const legacyCurrent = {
+ messages: [user('legacy-u1', 'old prompt'), assistant('legacy-a1', 'old partial', { pending: true })],
+ streamId: 'legacy-a1',
+ turnStartedAt: 1,
+ updatedAt: Date.now() - 1_000
+ }
+
+ const legacyOther = {
+ messages: [user('u2', 'other prompt'), assistant('a2', 'other partial', { pending: true })],
+ streamId: 'a2',
+ turnStartedAt: 2,
+ updatedAt: Date.now()
+ }
+
+ window.localStorage.setItem(
+ STORAGE_KEY,
+ JSON.stringify({ entries: { 'stored-1': legacyCurrent, other: legacyOther }, version: 1 })
+ )
+
+ expect(readInFlightTurnJournal('other')).toEqual(legacyOther)
+ expect(readInFlightTurnJournal('stored-1')?.messages[0]).toEqual(user('u1', 'do the thing'))
+ })
+
+ it('does not resurrect a legacy entry after that session settles before migration', () => {
+ const legacyCurrent = {
+ messages: [user('legacy-u1', 'old prompt'), assistant('legacy-a1', 'old partial', { pending: true })],
+ streamId: 'legacy-a1',
+ turnStartedAt: 1,
+ updatedAt: Date.now()
+ }
+
+ const legacyOther = {
+ messages: [user('u2', 'other prompt'), assistant('a2', 'other partial', { pending: true })],
+ streamId: 'a2',
+ turnStartedAt: 2,
+ updatedAt: Date.now()
+ }
+
+ window.localStorage.setItem(
+ STORAGE_KEY,
+ JSON.stringify({ entries: { 'stored-1': legacyCurrent, other: legacyOther }, version: 1 })
+ )
+
+ persistInFlightTurnState(journalState({ busy: false, awaitingResponse: false, streamId: null }))
+
+ expect(readInFlightTurnJournal('stored-1')).toBeNull()
+ expect(readInFlightTurnJournal('other')).toEqual(legacyOther)
})
})
@@ -183,7 +559,7 @@ describe('recoverInFlightTurnJournal', () => {
])
const base = [user('u0', 'earlier turn'), assistant('a0', 'earlier reply')]
- const result = recoverInFlightTurnJournal('stored-1', base)
+ const result = recoverInFlightTurnJournal('stored-1', base, { keepPending: true })
expect(result.applied).toBe(true)
expect(result.messages.map(m => m.id)).toEqual(['u0', 'a0', 'u1', 'assistant-stream-1'])
@@ -201,6 +577,9 @@ describe('recoverInFlightTurnJournal', () => {
expect(result.applied).toBe(true)
expect(result.messages.map(m => m.id)).toEqual(['db-u1', 'assistant-stream-1'])
+ // Idle resume: the assistant-tail append path must not resurrect the
+ // stream target either, or the journal entry re-folds on every open.
+ expect(result.streamId).toBeNull()
const tail = result.messages.at(-1)!
expect(tail.pending).toBe(false)
expect(tail.parts[0]).toMatchObject({ type: 'tool-call' })
@@ -283,6 +662,76 @@ describe('recoverInFlightTurnJournal', () => {
expect(merged.id).toBe('assistant-stream-rt9')
expect(merged.parts[1]).toMatchObject({ type: 'text', text: 'a much longer locally journaled partial answer' })
})
+
+ // ── Scrambled-transcript regression (duplicate trailing answers) ───────────
+ // The journal can outlive the turn it recorded (reclaim/reconnect/restart
+ // races skip the settle that would clear it). On resume the fold then
+ // re-appends content that the committed transcript ALREADY holds, rendering
+ // the same answers twice at the end of the conversation. Reported on the
+ // desktop as "the answer was already there, but it was inputted again".
+
+ it('does not re-append committed answers when the journaled user row never persisted', () => {
+ // A resume projection can journal a `user-inflight-*` row that was never
+ // written to the DB (and may even belong to a different conversation).
+ // Because no base user matches it, the fold used to treat the whole tail
+ // as unknown and append it — duplicating the assistant answers below.
+ journalEntry([
+ user('user-inflight-a3c2beb1', 'a stray user bubble that never persisted'),
+ assistant('assistant-stream-1', 'the committed answer')
+ ])
+
+ const base = [user('db-u1', 'the real prompt'), assistant('db-a1', 'the committed answer')]
+ const result = recoverInFlightTurnJournal('stored-1', base, { keepPending: false })
+
+ expect(result.caughtUp).toBe(true)
+ expect(result.applied).toBe(false)
+ expect(result.messages).toBe(base)
+ expect(result.messages.map(m => m.id)).toEqual(['db-u1', 'db-a1'])
+ // The stale entry is cleared so the next resume stays clean.
+ expect(readInFlightTurnJournal('stored-1')).toBeNull()
+ })
+
+ it('does not re-append committed answers when the journal tail has no user row', () => {
+ // A tail captured after a partial hydrate can end on assistant rows with
+ // no user prompt before them. The old code appended them verbatim, so the
+ // transcript ended with a duplicate of an answer that was already settled.
+ journalEntry([assistant('assistant-stream-1', 'the committed answer')])
+
+ const base = [user('db-u1', 'the real prompt'), assistant('db-a1', 'the committed answer')]
+ const result = recoverInFlightTurnJournal('stored-1', base, { keepPending: false })
+
+ expect(result.caughtUp).toBe(true)
+ expect(result.messages).toBe(base)
+ expect(readInFlightTurnJournal('stored-1')).toBeNull()
+ })
+
+ it('keeps appending a genuinely unknown turn (crash recovery still works)', () => {
+ // The staleness check must not swallow a tail the base never saw: that is
+ // the crash-recovery path the journal exists for.
+ journalEntry([user('u1', 'the live prompt'), assistant('assistant-stream-1', 'partial answer', { pending: true })])
+
+ const base = [user('db-u0', 'an earlier turn'), assistant('db-a0', 'earlier reply')]
+ const result = recoverInFlightTurnJournal('stored-1', base, { keepPending: true })
+
+ expect(result.applied).toBe(true)
+ expect(result.caughtUp).toBe(false)
+ expect(result.messages.map(m => m.id)).toEqual(['db-u0', 'db-a0', 'u1', 'assistant-stream-1'])
+ expect(readInFlightTurnJournal('stored-1')).not.toBeNull()
+ })
+
+ it('does not resurrect the journal streamId on a not-running resume (journal self-clear)', () => {
+ // The fold used to carry the stale entry's streamId onto the resumed state
+ // even when the backend reported the session idle. persistInFlightTurnState
+ // then re-wrote the journal instead of clearing it, so the same stale tail
+ // was folded again on every open — the scramble never healed.
+ journalEntry([user('u1', 'do the thing'), assistant('assistant-stream-1', 'partial answer', { pending: true })])
+
+ const base = [user('db-u0', 'an earlier turn'), assistant('db-a0', 'earlier reply')]
+ const result = recoverInFlightTurnJournal('stored-1', base, { keepPending: false })
+
+ expect(result.applied).toBe(true)
+ expect(result.streamId).toBeNull()
+ })
})
describe('mergeInFlightMessages', () => {
diff --git a/apps/desktop/src/lib/inflight-turn-journal.ts b/apps/desktop/src/lib/inflight-turn-journal.ts
index 27912970ff..31a314bb05 100644
--- a/apps/desktop/src/lib/inflight-turn-journal.ts
+++ b/apps/desktop/src/lib/inflight-turn-journal.ts
@@ -16,20 +16,34 @@ import { type ChatMessage, type ChatMessagePart, chatMessageText } from '@/lib/c
* Best-effort by design: storage failures must never break chat streaming.
*/
-/** One localStorage key PER SESSION. The v1 single-key store meant every
- * throttled write re-parsed and re-stringified EVERY busy session's tail —
- * with a grid of concurrent streams that was a whole-store JSON round-trip
- * dozens of times a second, all on the main thread. Per-session keys make a
- * write O(own tail) regardless of how many other sessions are streaming. */
-const STORAGE_PREFIX = 'hermes.desktop.inflightTurnJournal.v2:'
const LEGACY_STORAGE_KEY = 'hermes.desktop.inflightTurnJournal.v1'
-const MAX_ENTRIES = 24
+const STORAGE_PREFIX = 'hermes.desktop.inflightTurnJournal.v2:'
+const LEGACY_MIGRATION_KEY = 'hermes.desktop.inflightTurnJournal.v2.migrated'
+const DISCARDED_SNAPSHOT_RAW = '0'
+const STORE_VERSION = 1
+const MAX_SESSION_STORE_CHARS = 4 * 1024 * 1024
const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
+// Keep the worst-case v2 namespace below a conservative localStorage budget
+// while retaining the 24 newest session slots for ordinary small snapshots.
+const MAX_ENTRY_CHARS = 160 * 1024
+const MAX_ENTRIES = Math.min(24, Math.floor(MAX_SESSION_STORE_CHARS / MAX_ENTRY_CHARS))
+const MAX_LEGACY_STORE_CHARS = 2 * 1024 * 1024
+const MAX_SESSION_KEY_CHARS = 512
+const MAX_JOURNALED_MESSAGES = 24
+const MAX_TEXT_PART_CHARS = 64 * 1024
+const MAX_METADATA_CHARS = 2 * 1024
+const MAX_USER_ATTACHMENT_REFS = 256
+const MAX_USER_ATTACHMENT_REF_CHARS = 64 * 1024
/** Streaming repaints arrive every ~33ms; localStorage writes are synchronous.
* Trailing-edge throttle keeps the journal off the hot path — a crash costs at
* most this much of the newest tail. */
const PERSIST_THROTTLE_MS = 400
+// A renderer can accumulate one entry per session over its lifetime. Sweep the
+// bounded v2 namespace once on first journal access; never scan it on the
+// 400ms streaming write path.
+let sessionStoreSwept = false
+
export interface InFlightTurnSnapshot {
messages: ChatMessage[]
streamId: null | string
@@ -46,6 +60,11 @@ export interface JournalableSessionState {
turnStartedAt: null | number
}
+interface JournalStore {
+ entries: Record
+ version: typeof STORE_VERSION
+}
+
export interface InFlightRecoveryResult {
applied: boolean
/** The base transcript already contains the journaled turn's completed
@@ -64,133 +83,431 @@ function storage(): Storage | null {
}
}
-const entryKey = (storedSessionId: string) => `${STORAGE_PREFIX}${storedSessionId}`
-
-function isExpired(entry: InFlightTurnSnapshot, now = Date.now()): boolean {
- return now - entry.updatedAt > MAX_AGE_MS
-}
-
-function loadEntry(storedSessionId: string): InFlightTurnSnapshot | null {
- const store = storage()
-
- if (!store) {
- return null
- }
-
+function sessionStorageKey(storedSessionId: string): null | string {
try {
- const raw = store.getItem(entryKey(storedSessionId))
- const parsed = raw ? (JSON.parse(raw) as InFlightTurnSnapshot) : null
+ const encoded = encodeURIComponent(storedSessionId)
- return parsed && typeof parsed.updatedAt === 'number' && Array.isArray(parsed.messages) ? parsed : null
+ return encoded.length > 0 && encoded.length <= MAX_SESSION_KEY_CHARS ? `${STORAGE_PREFIX}${encoded}` : null
} catch {
return null
}
}
-function saveEntry(storedSessionId: string, entry: InFlightTurnSnapshot): void {
+function readRaw(store: Storage, key: string): null | string {
try {
- storage()?.setItem(entryKey(storedSessionId), JSON.stringify(entry))
+ return store.getItem(key)
} catch {
- // Quota/private-mode failures: the journal is a recovery aid, not truth.
+ return null
}
}
-function removeEntry(storedSessionId: string): void {
+function removeRaw(store: Storage, key: string): void {
try {
- storage()?.removeItem(entryKey(storedSessionId))
+ store.removeItem(key)
} catch {
- // Same best-effort stance as saveEntry.
+ // Best-effort recovery state must not interrupt chat streaming.
}
}
-// Split a v1 single-key store into per-session entries. Checked on every
-// journal touch (a null getItem is free); a populated v1 store exists at most
-// once, right after the upgrade.
-function migrateLegacyStore(store: Storage): void {
+function writeRaw(store: Storage, key: string, value: string): boolean {
try {
- const legacy = store.getItem(LEGACY_STORAGE_KEY)
+ store.setItem(key, value)
- if (!legacy) {
- return
- }
+ return true
+ } catch {
+ return false
+ }
+}
- const parsed = JSON.parse(legacy)
+function isSnapshot(value: unknown): value is InFlightTurnSnapshot {
+ if (!value || typeof value !== 'object') {
+ return false
+ }
- if (parsed && typeof parsed.entries === 'object' && !Array.isArray(parsed.entries)) {
- for (const [id, entry] of Object.entries(parsed.entries as Record)) {
- saveEntry(id, entry)
+ const snapshot = value as Partial
+
+ return (
+ Array.isArray(snapshot.messages) &&
+ snapshot.messages.every(
+ message =>
+ Boolean(message) &&
+ typeof message === 'object' &&
+ typeof message.id === 'string' &&
+ ['assistant', 'system', 'tool', 'user'].includes(message.role) &&
+ Array.isArray(message.parts) &&
+ message.parts.every(
+ part =>
+ Boolean(part) &&
+ typeof part === 'object' &&
+ typeof part.type === 'string' &&
+ (part.type !== 'text' && part.type !== 'reasoning'
+ ? part.type !== 'tool-call' ||
+ (typeof part.toolName === 'string' &&
+ (part.toolCallId === undefined || typeof part.toolCallId === 'string') &&
+ (part.isError === undefined || typeof part.isError === 'boolean'))
+ : typeof part.text === 'string' && (part.parentId === undefined || typeof part.parentId === 'string'))
+ ) &&
+ (message.timestamp === undefined ||
+ (typeof message.timestamp === 'number' && Number.isFinite(message.timestamp))) &&
+ (message.pending === undefined || typeof message.pending === 'boolean') &&
+ (message.error === undefined || typeof message.error === 'string') &&
+ (message.branchGroupId === undefined || typeof message.branchGroupId === 'string') &&
+ (message.hidden === undefined || typeof message.hidden === 'boolean') &&
+ (message.interim === undefined || typeof message.interim === 'boolean') &&
+ (message.attachmentRefs === undefined ||
+ (Array.isArray(message.attachmentRefs) && message.attachmentRefs.every(ref => typeof ref === 'string'))) &&
+ (message.rowId === undefined || (typeof message.rowId === 'number' && Number.isFinite(message.rowId)))
+ ) &&
+ (snapshot.streamId === null || typeof snapshot.streamId === 'string') &&
+ (snapshot.turnStartedAt === null || typeof snapshot.turnStartedAt === 'number') &&
+ typeof snapshot.updatedAt === 'number' &&
+ Number.isFinite(snapshot.updatedAt)
+ )
+}
+
+function parseSnapshot(raw: string): InFlightTurnSnapshot | null {
+ if (raw.length > MAX_ENTRY_CHARS) {
+ return null
+ }
+
+ try {
+ const parsed = JSON.parse(raw)
+
+ return isSnapshot(parsed) ? parsed : null
+ } catch {
+ return null
+ }
+}
+
+function serializeSnapshot(snapshot: InFlightTurnSnapshot): string | null {
+ let messages = snapshot.messages
+
+ while (messages.length > 0) {
+ try {
+ const raw = JSON.stringify({ ...snapshot, messages })
+
+ if (raw.length <= MAX_ENTRY_CHARS) {
+ return raw
}
+ } catch {
+ return null
}
- } catch {
- // A corrupt v1 store has nothing worth carrying over.
+
+ // Keep the join-key row and newest assistant progress while dropping the
+ // oldest sealed rows. If those two rows alone do not fit, the caller must
+ // avoid replacing an older recoverable snapshot with a tombstone.
+ if (messages.length <= 2) {
+ return null
+ }
+
+ messages = [messages[0], ...messages.slice(2)]
}
- try {
- store.removeItem(LEGACY_STORAGE_KEY)
- } catch {
- // Best-effort, like every other journal write.
- }
+ return null
}
-// One-time prune per renderer: drop expired/overflow entries. Startup-only on
-// purpose — entries clear on settle, so anything left over is crash residue,
-// and enumerating localStorage on the write path would defeat the point.
-let housekeepingDone = false
-
-function ensureHousekeeping(): void {
- const store = storage()
-
- if (!store) {
+function sweepSessionStore(store: Storage, reserveSlot = false): void {
+ if (sessionStoreSwept) {
return
}
- migrateLegacyStore(store)
-
- if (housekeepingDone) {
- return
- }
-
- housekeepingDone = true
+ sessionStoreSwept = true
try {
- const keys: string[] = []
+ const sessionKeys: string[] = []
for (let index = 0; index < store.length; index += 1) {
const key = store.key(index)
if (key?.startsWith(STORAGE_PREFIX)) {
- keys.push(key)
+ sessionKeys.push(key)
}
}
- const live: { key: string; updatedAt: number }[] = []
+ const liveEntries: Array<{ key: string; snapshot: InFlightTurnSnapshot }> = []
+ const migrated = readRaw(store, LEGACY_MIGRATION_KEY) !== null
- for (const key of keys) {
- let entry: InFlightTurnSnapshot | null = null
+ for (const key of sessionKeys) {
+ const raw = readRaw(store, key)
- try {
- entry = JSON.parse(store.getItem(key) ?? '') as InFlightTurnSnapshot
- } catch {
- // Unparseable — prune below.
+ // A tombstone is intentional state. It suppresses the stale v1
+ // predecessor until the one-shot migration removes the aggregate.
+ if (raw === DISCARDED_SNAPSHOT_RAW) {
+ if (migrated) {
+ removeRaw(store, key)
+ }
+
+ continue
}
- if (!entry || typeof entry.updatedAt !== 'number' || isExpired(entry)) {
- store.removeItem(key)
- } else {
- live.push({ key, updatedAt: entry.updatedAt })
+ const snapshot = raw ? parseSnapshot(raw) : null
+
+ if (!snapshot || isExpired(snapshot)) {
+ removeRaw(store, key)
+
+ continue
+ }
+
+ liveEntries.push({ key, snapshot })
+ }
+
+ liveEntries
+ .sort((left, right) => right.snapshot.updatedAt - left.snapshot.updatedAt)
+ .slice(reserveSlot ? MAX_ENTRIES - 1 : MAX_ENTRIES)
+ .forEach(entry => removeRaw(store, entry.key))
+ } catch {
+ // The journal is best effort; a storage enumeration failure must not
+ // interrupt renderer work or turn persistence.
+ }
+}
+
+function boundedString(value: string, maxChars: number): string {
+ return value.length <= maxChars ? value : value.slice(0, maxChars)
+}
+
+function boundedPart(part: ChatMessagePart): ChatMessagePart | null {
+ if (part.type === 'text') {
+ return {
+ type: 'text',
+ text: boundedString(part.text, MAX_TEXT_PART_CHARS),
+ ...(part.parentId === undefined ? {} : { parentId: boundedString(part.parentId, MAX_METADATA_CHARS) })
+ }
+ }
+
+ if (part.type === 'reasoning') {
+ return {
+ type: 'reasoning',
+ text: boundedString(part.text, MAX_TEXT_PART_CHARS),
+ ...(part.parentId === undefined ? {} : { parentId: boundedString(part.parentId, MAX_METADATA_CHARS) })
+ }
+ }
+
+ if (part.type === 'tool-call') {
+ // Tool payloads can contain multi-megabyte command output. Recovery only
+ // needs invocation identity and failure state; args/results are available
+ // from the backend transcript when it survives.
+ return {
+ type: 'tool-call',
+ toolName: boundedString(part.toolName, MAX_METADATA_CHARS),
+ args: {},
+ ...(part.toolCallId === undefined ? {} : { toolCallId: boundedString(part.toolCallId, MAX_METADATA_CHARS) }),
+ ...(part.result === undefined ? {} : { result: {} }),
+ ...(part.isError === undefined ? {} : { isError: part.isError })
+ }
+ }
+
+ // Rich file/image/data/source parts can embed large payloads. They are not
+ // required for in-flight text/tool recovery and remain backend-owned.
+ return null
+}
+
+function boundedMessages(messages: ChatMessage[]): ChatMessage[] | null {
+ const bounded =
+ messages.length <= MAX_JOURNALED_MESSAGES
+ ? messages
+ : [messages[0], ...messages.slice(-(MAX_JOURNALED_MESSAGES - 1))]
+
+ // User text and attachment refs are the recovery join key. Truncating either
+ // could attach a journal tail to the wrong transcript row, so pathological
+ // prompts skip journaling instead of weakening the match.
+ if (
+ bounded.some(message => {
+ if (message.role !== 'user') {
+ return false
+ }
+
+ if (
+ message.parts.some(
+ part => (part.type === 'text' || part.type === 'reasoning') && part.text.length > MAX_TEXT_PART_CHARS
+ )
+ ) {
+ return true
+ }
+
+ const refs = message.attachmentRefs
+
+ if (!refs) {
+ return false
+ }
+
+ if (refs.length > MAX_USER_ATTACHMENT_REFS) {
+ return true
+ }
+
+ let chars = 0
+
+ for (const ref of refs) {
+ chars += ref.length
+
+ if (chars > MAX_USER_ATTACHMENT_REF_CHARS) {
+ return true
+ }
+ }
+
+ return false
+ })
+ ) {
+ return null
+ }
+
+ return bounded.map(message => ({
+ id: boundedString(message.id, MAX_METADATA_CHARS),
+ role: message.role,
+ parts: message.parts.map(boundedPart).filter((part): part is ChatMessagePart => part !== null),
+ ...(message.timestamp === undefined ? {} : { timestamp: message.timestamp }),
+ ...(message.pending === undefined ? {} : { pending: message.pending }),
+ ...(message.error === undefined ? {} : { error: boundedString(message.error, MAX_METADATA_CHARS) }),
+ ...(message.branchGroupId === undefined
+ ? {}
+ : { branchGroupId: boundedString(message.branchGroupId, MAX_METADATA_CHARS) }),
+ ...(message.hidden === undefined ? {} : { hidden: message.hidden }),
+ ...(message.interim === undefined ? {} : { interim: message.interim }),
+ ...(message.attachmentRefs === undefined
+ ? {}
+ : {
+ attachmentRefs:
+ message.role === 'user'
+ ? [...message.attachmentRefs]
+ : message.attachmentRefs
+ .slice(0, MAX_USER_ATTACHMENT_REFS)
+ .map(ref => boundedString(ref, MAX_METADATA_CHARS))
+ }),
+ ...(message.rowId === undefined ? {} : { rowId: message.rowId })
+ }))
+}
+
+function migrateLegacyStore(store: Storage): void {
+ if (readRaw(store, LEGACY_MIGRATION_KEY) !== null) {
+ return
+ }
+
+ const raw = readRaw(store, LEGACY_STORAGE_KEY)
+
+ if (raw === null) {
+ return
+ }
+
+ // Claim the migration before touching the aggregate. If storage is failing,
+ // skip legacy recovery rather than retrying an expensive parse on every read.
+ if (!writeRaw(store, LEGACY_MIGRATION_KEY, '1')) {
+ return
+ }
+
+ // Release the multi-megabyte aggregate before allocating per-session v2
+ // entries. The captured string remains available for this one migration.
+ removeRaw(store, LEGACY_STORAGE_KEY)
+
+ if (!raw) {
+ return
+ }
+
+ if (raw.length > MAX_LEGACY_STORE_CHARS) {
+ return
+ }
+
+ try {
+ const parsed = JSON.parse(raw) as Partial
+
+ if (
+ parsed.version !== STORE_VERSION ||
+ !parsed.entries ||
+ typeof parsed.entries !== 'object' ||
+ Array.isArray(parsed.entries)
+ ) {
+ return
+ }
+
+ const existingV2Keys = new Set()
+
+ for (let index = 0; index < store.length; index += 1) {
+ const key = store.key(index)
+
+ if (key?.startsWith(STORAGE_PREFIX)) {
+ existingV2Keys.add(key)
}
}
- live.sort((a, b) => b.updatedAt - a.updatedAt)
+ const entries = Object.entries(parsed.entries)
+ .filter((entry): entry is [string, InFlightTurnSnapshot] => isSnapshot(entry[1]) && !isExpired(entry[1]))
+ .sort((a, b) => b[1].updatedAt - a[1].updatedAt)
+ .slice(0, Math.max(0, MAX_ENTRIES - existingV2Keys.size))
- for (const { key } of live.slice(MAX_ENTRIES)) {
- store.removeItem(key)
+ for (const [storedSessionId, snapshot] of entries) {
+ const key = sessionStorageKey(storedSessionId)
+ const messages = boundedMessages(snapshot.messages)
+ const value = messages ? serializeSnapshot({ ...snapshot, messages }) : null
+
+ // A v2 snapshot may have been written before the one-shot migration ran.
+ // Never replace newer per-session state with its stale v1 predecessor.
+ if (key && value && readRaw(store, key) === null) {
+ if (writeRaw(store, key, value)) {
+ existingV2Keys.add(key)
+ }
+ }
}
} catch {
- // Best-effort, like every other journal write.
+ // Malformed legacy data is discarded below.
}
}
+function discardSnapshot(store: Storage, key: string): void {
+ // Migrate first so an existing v2 key suppresses its stale v1 predecessor,
+ // then remove the current session. This keeps every discard path from
+ // resurrecting legacy state on a later read.
+ migrateLegacyStore(store)
+ removeRaw(store, key)
+}
+
+function readSnapshot(storedSessionId: string): InFlightTurnSnapshot | null {
+ const store = storage()
+ const key = sessionStorageKey(storedSessionId)
+
+ if (!store || !key) {
+ return null
+ }
+
+ sweepSessionStore(store)
+
+ let raw = readRaw(store, key)
+
+ if (!raw) {
+ migrateLegacyStore(store)
+ raw = readRaw(store, key)
+ }
+
+ if (!raw) {
+ return null
+ }
+
+ const snapshot = parseSnapshot(raw)
+
+ if (!snapshot || isExpired(snapshot)) {
+ discardSnapshot(store, key)
+
+ return null
+ }
+
+ return snapshot
+}
+
+function removeSnapshot(storedSessionId: string): void {
+ const store = storage()
+ const key = sessionStorageKey(storedSessionId)
+
+ if (store && key) {
+ sweepSessionStore(store)
+
+ // Settling a session before the one-shot migration must clear its legacy
+ // entry too; otherwise a later read can migrate and resurrect stale state.
+ // This aggregate parse is terminal-transition work, never a stream write.
+ discardSnapshot(store, key)
+ }
+}
+
+function isExpired(entry: InFlightTurnSnapshot, now = Date.now()): boolean {
+ return now - entry.updatedAt > MAX_AGE_MS
+}
+
function cloneMessages(messages: ChatMessage[]): ChatMessage[] {
try {
return JSON.parse(JSON.stringify(messages)) as ChatMessage[]
@@ -286,7 +603,7 @@ function recoverableTail(messages: ChatMessage[], streamId: null | string): Chat
}
}
- return cloneMessages(visible.slice(start))
+ return visible.slice(start)
}
function normalizeRecoveredTail(tail: ChatMessage[], keepPending: boolean): ChatMessage[] {
@@ -376,6 +693,32 @@ function withoutBaseIds(rows: ChatMessage[], baseMessages: ChatMessage[]): ChatM
return rows.filter(row => !baseIds.has(row.id))
}
+/** Whether every recoverable assistant row in the journal tail already exists
+ * as committed text in the base transcript. When true, the journal outlived
+ * the turn it recorded and appending it would re-render the same answers at
+ * the end of the transcript (the "scrambled conversation" regression). */
+function journalTailAlreadyCommitted(tailAssistants: ChatMessage[], baseMessages: ChatMessage[]): boolean {
+ const recoverable = tailAssistants.filter(assistantHasRecoverableContent)
+
+ if (recoverable.length === 0) {
+ return false
+ }
+
+ const baseTexts = new Set(
+ baseMessages
+ .filter(message => message.role === 'assistant' && !message.hidden)
+ .map(message => normalizedText(chatMessageText(message)))
+ )
+
+ return recoverable.every(message => {
+ const text = normalizedText(chatMessageText(message))
+
+ // Error-only rows carry no text to verify against — keep the conservative
+ // append path rather than risk dropping a recoverable failure.
+ return text.length > 0 && baseTexts.has(text)
+ })
+}
+
export function mergeInFlightMessages(
baseMessages: ChatMessage[],
tailMessages: ChatMessage[],
@@ -402,15 +745,27 @@ export function mergeInFlightMessages(
const matchingUserIndex = tailUser ? baseMessages.findLastIndex(message => userMessagesMatch(message, tailUser)) : -1
if (matchingUserIndex < 0) {
- // Base doesn't know this turn at all (user row was never persisted):
- // append the whole tail.
+ // No base user matches the tail's user row (a projected user-inflight row
+ // that never persisted, or a tail captured without its user prompt). If the
+ // tail's answers are already committed in the transcript, the journal is
+ // stale — appending it would re-render the same replies at the end of the
+ // conversation. Otherwise, the base never saw this turn at all: append the
+ // whole tail (the crash-recovery path the journal exists for).
+ if (journalTailAlreadyCommitted(tailAssistants, baseMessages)) {
+ return { ...noop, caughtUp: true }
+ }
+
const streamId = lastJournalRow?.id ?? null
return {
applied: true,
caughtUp: false,
messages: [...baseMessages, ...withoutBaseIds(tail, baseMessages)],
- streamId,
+ // Only a genuinely running turn keeps a live stream target. On an idle
+ // resume, carrying the stale streamId would keep the journal entry alive
+ // (persistInFlightTurnState only clears when streamId is null) and the
+ // same tail would be folded again on every open.
+ streamId: options.keepPending ? streamId : null,
turnStartedAt: null
}
}
@@ -442,7 +797,11 @@ export function mergeInFlightMessages(
applied: true,
caughtUp: false,
messages: [...baseMessages, ...withoutBaseIds(tailAssistants, baseMessages)],
- streamId,
+ // Same idle-resume rule as the other exit paths: only a running turn
+ // keeps the stream target alive. Carrying the stale streamId here kept
+ // the journal entry alive (persistInFlightTurnState only clears when
+ // streamId is null), so the same tail was folded again on every open.
+ streamId: options.keepPending ? streamId : null,
turnStartedAt: null
}
}
@@ -464,12 +823,32 @@ export function mergeInFlightMessages(
...baseMessages.slice(projectionIndex + 1)
]
- return { applied: true, caughtUp: false, messages, streamId: merged.id, turnStartedAt: null }
+ return {
+ applied: true,
+ caughtUp: false,
+ messages,
+ // Same idle-resume rule as the append path: only a running turn keeps the
+ // stream target alive, so an idle resume clears the journal instead of
+ // re-folding the same tail on every open.
+ streamId: options.keepPending ? merged.id : null,
+ turnStartedAt: null
+ }
}
const persistTimers = new Map>()
const persistLatest = new Map()
+/** @internal Test-only reset for module-scoped throttles and sweep state. */
+export function resetInFlightTurnJournalStateForTests(): void {
+ for (const timer of persistTimers.values()) {
+ clearTimeout(timer)
+ }
+
+ persistTimers.clear()
+ persistLatest.clear()
+ sessionStoreSwept = false
+}
+
function writeSnapshot(storedSessionId: string, state: JournalableSessionState): void {
const tail = recoverableTail(state.messages, state.streamId)
@@ -477,13 +856,63 @@ function writeSnapshot(storedSessionId: string, state: JournalableSessionState):
return
}
- ensureHousekeeping()
- saveEntry(storedSessionId, {
- messages: tail,
+ const store = storage()
+ const key = sessionStorageKey(storedSessionId)
+
+ if (!store || !key) {
+ return
+ }
+
+ sweepSessionStore(store, true)
+
+ const messages = boundedMessages(tail)
+
+ if (!messages) {
+ // Keep the timer write path free of aggregate migration. This tiny invalid
+ // v2 value suppresses the stale v1 predecessor until read/settle performs
+ // the one-shot migration and removes it.
+ tombstoneUnlessRecoverable(store, key)
+
+ return
+ }
+
+ const raw = serializeSnapshot({
+ messages,
streamId: state.streamId,
turnStartedAt: state.turnStartedAt,
updatedAt: Date.now()
})
+
+ if (!raw) {
+ // Preserve an older bounded snapshot if the newest assistant row alone is
+ // too large. A tombstone is only needed when there is no recoverable v2
+ // value, so stale v1 state cannot be resurrected on a later read.
+ tombstoneUnlessRecoverable(store, key)
+
+ return
+ }
+
+ if (!writeRaw(store, key, raw)) {
+ // A quota failure must not leave an older, misleading snapshot behind, or
+ // let the stale v1 predecessor be resurrected on a later read.
+ tombstoneUnlessRecoverable(store, key)
+ }
+}
+
+function tombstoneUnlessRecoverable(store: Storage, key: string): void {
+ const previous = readRaw(store, key)
+
+ if (previous) {
+ const snapshot = parseSnapshot(previous)
+
+ if (snapshot && !isExpired(snapshot)) {
+ return
+ }
+ }
+
+ if (!writeRaw(store, key, DISCARDED_SNAPSHOT_RAW)) {
+ removeRaw(store, key)
+ }
}
/** Persist the running turn's visible tail (throttled), or clear the entry the
@@ -527,20 +956,7 @@ export function readInFlightTurnJournal(storedSessionId: null | string): InFligh
return null
}
- ensureHousekeeping()
- const entry = loadEntry(storedSessionId)
-
- if (!entry) {
- return null
- }
-
- if (isExpired(entry)) {
- removeEntry(storedSessionId)
-
- return null
- }
-
- return entry
+ return readSnapshot(storedSessionId)
}
/** Fold a journaled in-flight tail back onto a restored transcript. A no-op
@@ -570,7 +986,11 @@ export function recoverInFlightTurnJournal(
return {
...recovered,
- streamId: recovered.applied ? (recovered.streamId ?? snapshot.streamId) : null,
+ // Never resurrect a stale stream target on an idle resume: with
+ // keepPending=false the session is not running, so the recovered rows are
+ // settled history and the journal must clear on the next state update —
+ // otherwise the same stale tail is folded again on every open.
+ streamId: recovered.applied ? (recovered.streamId ?? (options.keepPending ? snapshot.streamId : null)) : null,
turnStartedAt: recovered.applied ? snapshot.turnStartedAt : null
}
}
@@ -588,6 +1008,6 @@ export function clearInFlightTurnJournal(storedSessionId: null | string): void {
}
persistLatest.delete(storedSessionId)
- ensureHousekeeping()
- removeEntry(storedSessionId)
+
+ removeSnapshot(storedSessionId)
}
diff --git a/apps/desktop/src/lib/keybinds/actions.test.ts b/apps/desktop/src/lib/keybinds/actions.test.ts
new file mode 100644
index 0000000000..dafc92a5ce
--- /dev/null
+++ b/apps/desktop/src/lib/keybinds/actions.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+
+import { en } from '@/i18n/en'
+
+import { defaultBindings, KEYBIND_ACTIONS, keybindAction } from './actions'
+
+describe('session.archive keybind action', () => {
+ it('is registered under the session category', () => {
+ const action = keybindAction('session.archive')
+
+ expect(action).toBeDefined()
+ expect(action?.category).toBe('session')
+ })
+
+ it('ships unbound so it does not claim a chord for every user', () => {
+ const action = keybindAction('session.archive')
+
+ expect(action?.defaults).toEqual([])
+ // A missing entry would silently drop from the panel; an accidental
+ // default binding would change behaviour for everyone. Guard both.
+ expect(defaultBindings()['session.archive']).toEqual([])
+ })
+
+ it('has an English label so it renders in the shortcuts panel', () => {
+ expect(en.keybinds.actions['session.archive']).toBe('Archive current session')
+ })
+
+ it('appears exactly once in KEYBIND_ACTIONS', () => {
+ const matches = KEYBIND_ACTIONS.filter(action => action.id === 'session.archive')
+
+ expect(matches).toHaveLength(1)
+ })
+})
diff --git a/apps/desktop/src/lib/keybinds/actions.ts b/apps/desktop/src/lib/keybinds/actions.ts
index b042cd4f6e..768192b5e9 100644
--- a/apps/desktop/src/lib/keybinds/actions.ts
+++ b/apps/desktop/src/lib/keybinds/actions.ts
@@ -76,16 +76,25 @@ export const KEYBIND_ACTIONS: readonly KeybindActionMeta[] = [
{ id: 'profile.create', category: 'profiles', defaults: [] },
// ── Session ──────────────────────────────────────────────────────────────
- { id: 'session.new', category: 'session', defaults: ['mod+n', 'shift+n'] },
+ // `shift+n` was dropped from the defaults (#76185): a bare shifted letter
+ // hijacked normal typing — pressing uppercase N outside an input (or via an
+ // IME) created a new session unexpectedly. The deliberate ⌘/Ctrl+N chord
+ // stays; users who liked ⇧N can rebind it in the panel.
+ { id: 'session.new', category: 'session', defaults: ['mod+n'] },
{ id: 'session.newTab', category: 'session', defaults: ['mod+t'] },
{ id: 'session.newWindow', category: 'session', defaults: ['mod+shift+n'] },
// ⌃Tab / ⌃⇧Tab — the universal tab-cycle chord. Literally Control, not Cmd
// (macOS reserves Cmd+Tab for app switching); see `ctrl` in combo.ts.
- { id: 'session.next', category: 'session', defaults: ['ctrl+tab'] },
- { id: 'session.prev', category: 'session', defaults: ['ctrl+shift+tab'] },
+ { id: 'session.next', category: 'session', defaults: ['ctrl+tab', 'ctrl+pagedown'] },
+ { id: 'session.prev', category: 'session', defaults: ['ctrl+shift+tab', 'ctrl+pageup'] },
...SESSION_SLOT_ACTIONS,
{ id: 'session.focusSearch', category: 'session', defaults: ['mod+shift+f'] },
{ id: 'session.togglePin', category: 'session', defaults: [] },
+ // Archive the active session. Ships unbound (like `session.togglePin`) so an
+ // irreversible-feeling, mouse-only action doesn't silently claim a chord for
+ // every user — surfaced in the panel for opt-in binding (the issue suggests
+ // ⌘⇧⌫ / Ctrl+Shift+⌫).
+ { id: 'session.archive', category: 'session', defaults: [] },
// ⌘⇧B — "b" for branch: spin up a new git worktree from the active repo.
{ id: 'workspace.newWorktree', category: 'session', defaults: ['mod+shift+b'] },
// ⌘O — the editor-standard "open folder" chord (VS Code ⌘O, Zed's
@@ -140,7 +149,7 @@ export const KEYBIND_ACTIONS: readonly KeybindActionMeta[] = [
// is a no-op. ⌘⇧T reopens the last closed tab where it was.
{ id: 'view.closeTab', category: 'view', defaults: ['mod+w'] },
{ id: 'view.reopenTab', category: 'view', defaults: ['mod+shift+t'] },
- // ⌘F — open the find-in-page bar. `comboAllowedInInput` lets the combo
+ // ⌘F — open the find-in-page bar. `actionAllowedInInput` lets this action
// fire from inside a textarea / contenteditable (matches browser behavior
// so typing in the composer and pressing ⌘F focuses find, not 'f').
{ id: 'view.findInPage', category: 'view', defaults: ['mod+f'] },
diff --git a/apps/desktop/src/lib/keybinds/combo.test.ts b/apps/desktop/src/lib/keybinds/combo.test.ts
index 3147538ac3..0e30d92534 100644
--- a/apps/desktop/src/lib/keybinds/combo.test.ts
+++ b/apps/desktop/src/lib/keybinds/combo.test.ts
@@ -82,6 +82,13 @@ describe('comboFromEvent — ctrl as a distinct modifier on macOS', () => {
expect(comboFromEvent(keydown({ code: 'Tab', ctrlKey: true }))).toBe('mod+tab')
expect(comboFromEvent(keydown({ code: 'Tab', ctrlKey: true, shiftKey: true }))).toBe('mod+shift+tab')
})
+
+ it('recognizes PageUp and PageDown chords', async () => {
+ const { comboFromEvent } = await loadCombo('MacIntel')
+
+ expect(comboFromEvent(keydown({ code: 'PageUp', ctrlKey: true }))).toBe('ctrl+pageup')
+ expect(comboFromEvent(keydown({ code: 'PageDown', ctrlKey: true }))).toBe('ctrl+pagedown')
+ })
})
describe('canonicalizeCombo', () => {
@@ -104,27 +111,84 @@ describe('canonicalizeCombo', () => {
describe('formatCombo — honest Control labels', () => {
it('renders the Control glyph on macOS', async () => {
- const { formatCombo } = await loadCombo('MacIntel')
+ const { formatCombo, formatModifierToken } = await loadCombo('MacIntel')
expect(formatCombo('ctrl+tab')).toBe('⌃⇥')
expect(formatCombo('ctrl+shift+tab')).toBe('⌃⇧⇥')
+ expect(formatCombo('mod+enter')).toBe('⌘↵')
+ expect(formatModifierToken('mod')).toBe('⌘')
})
- it('renders "Ctrl+…" off macOS (base key keeps its glyph)', async () => {
- const { formatCombo } = await loadCombo('Win32')
+ it.each(['Linux x86_64', 'Win32'])('renders "Ctrl+…" off macOS on %s (base key keeps its glyph)', async platform => {
+ const { formatCombo, formatModifierToken } = await loadCombo(platform)
expect(formatCombo('ctrl+tab')).toBe('Ctrl+⇥')
expect(formatCombo('ctrl+shift+tab')).toBe('Ctrl+Shift+⇥')
+ expect(formatCombo('mod+enter')).toBe('Ctrl+↵')
+ expect(formatModifierToken('mod')).toBe('Ctrl')
+ })
+
+ it('renders PageUp and PageDown with compact labels', async () => {
+ const { formatCombo } = await loadCombo('Win32')
+
+ expect(formatCombo('ctrl+pageup')).toBe('Ctrl+PgUp')
+ expect(formatCombo('ctrl+pagedown')).toBe('Ctrl+PgDn')
})
})
-describe('comboAllowedInInput', () => {
- it('lets ctrl combos fire while typing (e.g. ⌃Tab from the composer)', async () => {
- const { comboAllowedInInput } = await loadCombo('MacIntel')
+describe('actionAllowedInInput', () => {
+ it('keeps only explicit text-entry-safe global actions active while typing', async () => {
+ const { actionAllowedInInput } = await loadCombo('MacIntel')
- expect(comboAllowedInInput('ctrl+tab')).toBe(true)
- expect(comboAllowedInInput('ctrl+shift+tab')).toBe(true)
- expect(comboAllowedInInput('mod+k')).toBe(true)
- expect(comboAllowedInInput('shift+x')).toBe(false)
+ expect(actionAllowedInInput('session.next', 'ctrl+tab')).toBe(true)
+ expect(actionAllowedInInput('session.prev', 'ctrl+shift+tab')).toBe(true)
+ expect(actionAllowedInInput('nav.commandPalette', 'mod+k')).toBe(true)
+ expect(actionAllowedInInput('view.findInPage', 'mod+f')).toBe(true)
+ expect(actionAllowedInInput('nav.skills', 'mod+k')).toBe(false)
+ expect(actionAllowedInInput('view.showTerminal', 'ctrl+`')).toBe(false)
+ expect(actionAllowedInInput('profile.next', 'mod+shift+]')).toBe(false)
+ })
+
+ it('leaves text navigation chords with the focused input even when rebound to an allowed action', async () => {
+ const { actionAllowedInInput } = await loadCombo('Win32')
+
+ expect(actionAllowedInInput('session.next', 'mod+right')).toBe(false)
+ expect(actionAllowedInInput('session.prev', 'mod+left')).toBe(false)
+ expect(actionAllowedInInput('nav.commandPalette', 'mod+pageup')).toBe(false)
+ expect(actionAllowedInInput('view.findInPage', 'mod+end')).toBe(false)
+ })
+})
+
+describe('comboFromEvent — IME composition keydowns never resolve to combos (#84957)', () => {
+ it('returns null while a composition is in progress (isComposing)', async () => {
+ const { comboFromEvent } = await loadCombo('MacIntel')
+
+ // Typing 你 with a Chinese IME: the preedit keydowns carry isComposing.
+ // Before the guard, these canonicalized to combos and fired keybinds
+ // (e.g. dispatched `session.new` mid-composition).
+ expect(comboFromEvent(keydown({ code: 'KeyN', isComposing: true, key: 'n' }))).toBeNull()
+ expect(comboFromEvent(keydown({ code: 'Enter', isComposing: true, key: 'Enter' }))).toBeNull()
+ expect(comboFromEvent(keydown({ code: 'Space', isComposing: true, key: ' ' }))).toBeNull()
+ })
+
+ it('returns null for the legacy key="Process" (VK_PROCESSKEY) keydown', async () => {
+ const { comboFromEvent } = await loadCombo('Win32')
+
+ expect(comboFromEvent(keydown({ code: 'KeyW', key: 'Process' }))).toBeNull()
+ })
+
+ it('ignores IME-synthesized modifier-name keys on non-modifier codes', async () => {
+ const { comboFromEvent } = await loadCombo('Win32')
+
+ // Q9 2002-style legacy IMEs synthesize key="Control" with code="KeyW",
+ // which would otherwise canonicalize to a phantom ctrl+w (close tab).
+ expect(comboFromEvent(keydown({ code: 'KeyW', key: 'Control' }))).toBeNull()
+ expect(comboFromEvent(keydown({ code: 'KeyA', key: 'Shift' }))).toBeNull()
+ })
+
+ it('still resolves real combos after composition ends', async () => {
+ const { comboFromEvent } = await loadCombo('MacIntel')
+
+ expect(comboFromEvent(keydown({ code: 'KeyN', isComposing: false, key: 'n', metaKey: true }))).toBe('mod+n')
})
})
diff --git a/apps/desktop/src/lib/keybinds/combo.ts b/apps/desktop/src/lib/keybinds/combo.ts
index 78f91e96e2..4409142cb4 100644
--- a/apps/desktop/src/lib/keybinds/combo.ts
+++ b/apps/desktop/src/lib/keybinds/combo.ts
@@ -33,6 +33,8 @@ const CODE_TO_KEY: Record = {
Escape: 'escape',
Backspace: 'backspace',
Tab: 'tab',
+ PageUp: 'pageup',
+ PageDown: 'pagedown',
ArrowUp: 'up',
ArrowDown: 'down',
ArrowLeft: 'left',
@@ -50,6 +52,9 @@ const MODIFIER_CODES = new Set([
'ShiftRight'
])
+// Modifier names as reported by `event.key` on a bare modifier keydown.
+const MODIFIER_KEYS = new Set(['Alt', 'Control', 'Meta', 'Shift'])
+
function baseKeyFromCode(code: string): string | null {
if (code.startsWith('Key')) {
return code.slice(3).toLowerCase()
@@ -101,10 +106,28 @@ function baseKeyFromEventKey(key: string, shiftKey: boolean): string | null {
// Returns the canonical combo for a keydown, or null while only modifiers are
// held (so capture mode keeps waiting for a real key).
export function comboFromEvent(event: KeyboardEvent): string | null {
+ // IME composition (Chinese/Japanese/Korean input): the keydown events
+ // during composition carry preedit keystrokes and the commit keypress
+ // (Enter/Space/Shift for candidate selection). Treating them as combos
+ // fires unrelated keybinds — e.g. typing 你 with a Chinese IME sent a
+ // keydown that dispatched `session.new` and silently opened a new session.
+ // Bail out entirely while composing.
+ if (event.isComposing || event.key === 'Process') {
+ return null
+ }
+
if (MODIFIER_CODES.has(event.code)) {
return null
}
+ // A keydown whose `key` is a modifier name but whose `code` is a regular
+ // key is not a real modifier chord — legacy IMEs that synthesize keystrokes
+ // (Q9 2002 sends key="Control" with code="KeyW") produce these, and they
+ // would canonicalize to phantom combos (Ctrl+W → close active tab). Ignore.
+ if (MODIFIER_KEYS.has(event.key)) {
+ return null
+ }
+
const base = baseKeyFromEventKey(event.key, event.shiftKey) ?? baseKeyFromCode(event.code)
if (!base) {
@@ -148,6 +171,8 @@ const TOKEN_LABELS: Record = {
escape: 'Esc',
backspace: '⌫',
tab: '⇥',
+ pageup: 'PgUp',
+ pagedown: 'PgDn',
space: 'Space',
up: '↑',
down: '↓',
@@ -167,7 +192,7 @@ function labelForBase(base: string): string {
return base.length === 1 ? base.toUpperCase() : base
}
-function labelForMod(mod: string): string {
+export function formatModifierToken(mod: string): string {
if (mod === 'mod') {
return IS_MAC ? '⌘' : 'Ctrl'
}
@@ -193,7 +218,7 @@ export function comboTokens(combo: string): string[] {
const parts = combo.split('+')
const base = parts.pop() ?? ''
- return [...parts.map(labelForMod), labelForBase(base)]
+ return [...parts.map(formatModifierToken), labelForBase(base)]
}
// Human-readable label, e.g. "⌘⇧K" on macOS, "Ctrl+Shift+K" elsewhere.
@@ -223,8 +248,27 @@ export function isEditableTarget(target: EventTarget | null): boolean {
)
}
-// A primary modifier (Cmd/Ctrl/Control) fires even while typing (e.g. ⌘K or
-// ⌃Tab from the composer); bare/Shift-only combos are suppressed in inputs.
-export function comboAllowedInInput(combo: string): boolean {
- return /^(?:mod|ctrl)(?:\+|$)/.test(combo)
+const INPUT_SAFE_ACTIONS = new Set([
+ 'composer.modelPicker',
+ 'composer.voice',
+ 'keybinds.openPanel',
+ 'nav.commandPalette',
+ 'session.next',
+ 'session.prev',
+ 'view.findInPage'
+])
+
+const TEXT_NAVIGATION_KEYS = new Set(['up', 'down', 'left', 'right', 'home', 'end', 'pageup', 'pagedown'])
+
+// Only explicit text-entry-safe actions fire while typing. Editing/navigation
+// chords such as Ctrl+Arrow/PageUp must stay with the input even if a user
+// rebinds them to a global navigation action.
+export function actionAllowedInInput(actionId: string, combo: string): boolean {
+ const base = combo.split('+').pop()
+
+ if (base && TEXT_NAVIGATION_KEYS.has(base)) {
+ return false
+ }
+
+ return INPUT_SAFE_ACTIONS.has(actionId)
}
diff --git a/apps/desktop/src/lib/keybinds/contributed-actions.test.ts b/apps/desktop/src/lib/keybinds/contributed-actions.test.ts
index 0b82242789..74e20cb061 100644
--- a/apps/desktop/src/lib/keybinds/contributed-actions.test.ts
+++ b/apps/desktop/src/lib/keybinds/contributed-actions.test.ts
@@ -54,7 +54,9 @@ describe('contributed keybind actions', () => {
// The built-in keeps its own combo and its own (i18n) label — the
// contribution is filtered out rather than overriding core.
- expect(bindingsFor('session.new')).toEqual(['mod+n', 'shift+n'])
+ // (bare shift+n was removed from session.new defaults — it hijacked
+ // typing a capital N into focused inputs, #76185)
+ expect(bindingsFor('session.new')).toEqual(['mod+n'])
expect(allKeybindActions().filter(a => a.id === 'session.new')).toHaveLength(1)
dispose()
diff --git a/apps/desktop/src/lib/mcp-brands.tsx b/apps/desktop/src/lib/mcp-brands.tsx
index c587bb550f..10a8e6136b 100644
--- a/apps/desktop/src/lib/mcp-brands.tsx
+++ b/apps/desktop/src/lib/mcp-brands.tsx
@@ -7,12 +7,17 @@
* a favicon service for it would leak that hostname off-box.
*/
import {
+ SiAirtable,
+ SiAsana,
SiAtlassian,
SiDatadog,
SiFigma,
SiGithub,
SiGitlab,
+ SiHuggingface,
+ SiIntercom,
SiLinear,
+ SiNetlify,
SiNotion,
SiPaypal,
SiPostgresql,
@@ -21,6 +26,7 @@ import {
SiStripe,
SiSupabase,
SiVercel,
+ SiWebflow,
SiZapier
} from '@icons-pack/react-simple-icons'
import type { ComponentType, SVGProps } from 'react'
@@ -35,12 +41,18 @@ export interface McpBrand {
}
export const MCP_BRAND_ICONS: Record = {
+ airtable: { Icon: SiAirtable, color: '#18BFFF' },
+ asana: { Icon: SiAsana, color: '#F06A6A' },
atlassian: { Icon: SiAtlassian, color: '#0052CC' },
datadog: { Icon: SiDatadog, color: '#632CA6' },
figma: { Icon: SiFigma, color: '#F24E1E' },
github: { Icon: SiGithub, color: '#181717', monochrome: true },
gitlab: { Icon: SiGitlab, color: '#FC6D26' },
+ hugging_face: { Icon: SiHuggingface, color: '#FFD21E' },
+ huggingface: { Icon: SiHuggingface, color: '#FFD21E' },
+ intercom: { Icon: SiIntercom, color: '#6AFDEF' },
linear: { Icon: SiLinear, color: '#5E6AD2' },
+ netlify: { Icon: SiNetlify, color: '#00C7B7' },
notion: { Icon: SiNotion, color: '#000000', monochrome: true },
paypal: { Icon: SiPaypal, color: '#003087' },
postgres: { Icon: SiPostgresql, color: '#4169E1' },
@@ -50,6 +62,7 @@ export const MCP_BRAND_ICONS: Record = {
stripe: { Icon: SiStripe, color: '#635BFF' },
supabase: { Icon: SiSupabase, color: '#3FCF8E' },
vercel: { Icon: SiVercel, color: '#000000', monochrome: true },
+ webflow: { Icon: SiWebflow, color: '#146EF5' },
zapier: { Icon: SiZapier, color: '#FF4A00' }
}
diff --git a/apps/desktop/src/lib/mcp-directory.ts b/apps/desktop/src/lib/mcp-directory.ts
index 107fb14479..0426979abb 100644
--- a/apps/desktop/src/lib/mcp-directory.ts
+++ b/apps/desktop/src/lib/mcp-directory.ts
@@ -1,22 +1,23 @@
/**
- * The desktop's own MCP suggestion directory — deliberately NOT the
- * Nous-approved install catalog (`optional-mcps/`).
+ * COMPATIBILITY RUNG — superseded by the MCP catalog's `suggest` metadata.
*
- * The catalog is a trust boundary: presence there means a reviewed, pinned
- * manifest, and it only grows via PR. This directory is a different thing —
- * a renderer-local map of well-known OFFICIAL remote MCP endpoints (vendor
- * docs linked per entry) used for two purposes:
+ * The Nous-approved install catalog (`optional-mcps//manifest.yaml`)
+ * is now the single source of truth for suggestible servers: each hosted
+ * remote entry declares its own `suggest.keywords` / `suggest.hosts`, served
+ * through `GET /api/mcp/catalog`. The suggestion provider and the inline
+ * setup card read the catalog first.
*
- * 1. keyword → suggestion pills over the composer ("you typed jira…"),
- * 2. giving the inline setup card a config to write via the ordinary
- * `POST /api/mcp/servers` endpoint — the exact same path as pasting the
- * vendor's snippet into the Capabilities editor by hand.
+ * This static list remains ONLY for older backends whose catalog responses
+ * carry no `suggest` field (the provider falls back to it when the catalog
+ * yields zero suggestible entries). Do not add new vendors here — add a
+ * manifest under `optional-mcps/` instead. Remove this file at the next
+ * backend contract bump.
*
- * Nothing here changes base Hermes behavior: no backend code reads this file,
- * entries are URL-only remotes (no local process is ever spawned from a
- * suggestion), and every install still lands in config.yaml through the
- * existing validated endpoint. If an entry ALSO exists in the install catalog
- * (e.g. linear, figma), the setup card prefers the catalog path.
+ * GitHub is intentionally absent (here AND in the catalog): its hosted MCP
+ * requires each MCP host to provide its own OAuth app (generic Dynamic
+ * Client Registration 404s at /register), and the bundled github/* skills
+ * via the gh CLI are the more capable integration. The composer's github
+ * suggestion provider offers the `github-auth` skill instead.
*/
export interface McpDirectoryEntry {
/** Server name as it will appear in mcp_servers config. */
@@ -75,15 +76,10 @@ export const MCP_DIRECTORY: McpDirectoryEntry[] = [
name: 'datadog',
url: 'https://mcp.datadoghq.com/api/unstable/mcp-server/mcp'
},
- {
- description: 'Repos, issues, and pull requests via GitHub’s hosted MCP.',
- docs: 'https://docs.github.com/en/copilot/customizing-copilot/using-model-context-protocol/using-the-github-mcp-server',
- // No hosts on purpose: github.com links are everywhere in a coding chat
- // (commits, PRs under review, pasted diffs) and would fire constantly.
- keywords: ['github'],
- name: 'github',
- url: 'https://api.githubcopilot.com/mcp/'
- },
+ // GitHub's hosted MCP is intentionally absent. Directory entries are wired
+ // through generic Dynamic Client Registration, but GitHub requires each MCP
+ // host to provide its own OAuth app (or use a PAT). Advertising it here makes
+ // both the composer pill and setup_mcp fail at /register with HTTP 404.
{
description: 'Pages and databases from your Notion workspace.',
docs: 'https://developers.notion.com/docs/mcp',
@@ -99,6 +95,93 @@ export const MCP_DIRECTORY: McpDirectoryEntry[] = [
keywords: ['stripe'],
name: 'stripe',
url: 'https://mcp.stripe.com'
+ },
+ {
+ description: 'Deployments, logs, and projects via Vercel’s hosted MCP.',
+ docs: 'https://vercel.com/docs/mcp',
+ // No `vercel.app` on purpose (same rule as GitHub): pasted deploy-preview
+ // links are about the site being previewed, not about managing Vercel.
+ hosts: ['vercel.com'],
+ keywords: ['vercel'],
+ name: 'vercel',
+ url: 'https://mcp.vercel.com'
+ },
+ {
+ description: 'Database, auth, and storage from your Supabase projects.',
+ docs: 'https://supabase.com/docs/guides/ai-tools/mcp',
+ hosts: ['supabase.com', 'supabase.co'],
+ keywords: ['supabase'],
+ name: 'supabase',
+ url: 'https://mcp.supabase.com/mcp'
+ },
+ {
+ description: 'Sites, deploys, and env vars via Netlify’s hosted MCP.',
+ docs: 'https://docs.netlify.com/build/build-with-ai/agent-setup-guides/agent-setup-overview/',
+ // No `netlify.app` for the same deploy-preview reason as vercel.app.
+ hosts: ['netlify.com'],
+ keywords: ['netlify'],
+ name: 'netlify',
+ url: 'https://netlify-mcp.netlify.app/mcp'
+ },
+ {
+ description: 'Models, datasets, Spaces, and papers from the Hugging Face Hub.',
+ docs: 'https://huggingface.co/docs/hub/agents-mcp',
+ hosts: ['huggingface.co', 'hf.co'],
+ keywords: ['hugging face', 'huggingface'],
+ // Underscored so prettyName renders "Hugging Face", not "Huggingface".
+ name: 'hugging_face',
+ url: 'https://huggingface.co/mcp'
+ },
+ {
+ description: 'Tasks, projects, and goals from your Asana workspace.',
+ docs: 'https://developers.asana.com/docs/using-asanas-mcp-server',
+ hosts: ['asana.com'],
+ keywords: ['asana'],
+ name: 'asana',
+ url: 'https://mcp.asana.com/sse'
+ },
+ {
+ description: 'Conversations, tickets, and customer data from Intercom.',
+ docs: 'https://developers.intercom.com/docs/guides/mcp',
+ hosts: ['intercom.com', 'intercom.io'],
+ keywords: ['intercom'],
+ name: 'intercom',
+ url: 'https://mcp.intercom.com/mcp'
+ },
+ {
+ description: 'Bases, tables, and records from your Airtable workspace.',
+ docs: 'https://support.airtable.com/articles/9897799762-using-the-airtable-mcp-server',
+ hosts: ['airtable.com'],
+ keywords: ['airtable'],
+ name: 'airtable',
+ url: 'https://mcp.airtable.com/mcp'
+ },
+ {
+ description: 'Sites, CMS collections, and pages via Webflow’s hosted MCP.',
+ docs: 'https://developers.webflow.com/mcp/reference/getting-started',
+ // No `webflow.io` — that's published staging sites, not Webflow intent.
+ hosts: ['webflow.com'],
+ keywords: ['webflow'],
+ name: 'webflow',
+ url: 'https://mcp.webflow.com/mcp'
+ },
+ {
+ description: 'Payments, invoices, and subscriptions via PayPal’s hosted MCP.',
+ docs: 'https://developer.paypal.com/tools/mcp-server/',
+ hosts: ['developer.paypal.com'],
+ keywords: ['paypal'],
+ name: 'paypal',
+ url: 'https://mcp.paypal.com/sse'
+ },
+ {
+ description: 'Catalog, orders, and payments via Square’s hosted MCP.',
+ docs: 'https://developer.squareup.com/docs/mcp',
+ hosts: ['squareup.com'],
+ // "square" the English word is everywhere ("square brackets", "square
+ // corners") — only the unambiguous brand form triggers.
+ keywords: ['squareup'],
+ name: 'square',
+ url: 'https://mcp.squareup.com/sse'
}
]
diff --git a/apps/desktop/src/lib/media.remote.test.ts b/apps/desktop/src/lib/media.remote.test.ts
index c16835cd67..72b8eabb14 100644
--- a/apps/desktop/src/lib/media.remote.test.ts
+++ b/apps/desktop/src/lib/media.remote.test.ts
@@ -1,5 +1,3 @@
-// @vitest-environment jsdom
-// downloadGatewayMediaFile drives an click, so these need a DOM.
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { $connection } from '@/store/session'
@@ -11,6 +9,7 @@ import {
isInlineMediaSrc,
isRemoteGateway,
mediaExternalUrl,
+ mediaGatewayStreamUrl,
resolveMediaDisplaySrc,
resolveMediaPlaybackSrc
} from './media'
@@ -78,6 +77,24 @@ describe('mediaExternalUrl', () => {
})
})
+describe('mediaGatewayStreamUrl', () => {
+ afterEach(() => {
+ $connection.set(null)
+ })
+
+ it('rewrites gateway-local media to the main-process remote stream proxy', () => {
+ $connection.set({ mode: 'remote', baseUrl: 'https://gw', token: 's e/cret' } as never)
+ expect(mediaGatewayStreamUrl('file:///tmp/a b.mp4')).toBe('hermes-media://remote/%2Ftmp%2Fa%20b.mp4')
+ })
+
+ it('supports OAuth remotes with no renderer-visible token and scopes pool profiles', () => {
+ $connection.set({ authMode: 'oauth', mode: 'remote', profile: 'voice reviewer', token: null } as never)
+ expect(mediaGatewayStreamUrl('/tmp/a.mp4')).toBe(
+ 'hermes-media://remote/%2Ftmp%2Fa.mp4?profile=voice%20reviewer'
+ )
+ })
+})
+
describe('resolveMediaDisplaySrc', () => {
const api = vi.fn(async ({ path }: { path: string }) => {
if (path.startsWith('/api/fs/read-data-url?')) {
@@ -155,12 +172,12 @@ describe('resolveMediaPlaybackSrc', () => {
)
})
- it('routes gateway-local video through the authenticated download endpoint', async () => {
+ it('routes OAuth gateway-local video through the authenticated main-process proxy', async () => {
vi.stubGlobal('window', { hermesDesktop: { api: vi.fn() } })
- $connection.set({ mode: 'remote', baseUrl: 'https://gateway.test', token: 's e/cret' } as never)
+ $connection.set({ authMode: 'oauth', mode: 'remote', profile: 'default', token: null } as never)
await expect(resolveMediaPlaybackSrc('/root/outputs/render.mp4')).resolves.toBe(
- 'https://gateway.test/api/files/download?path=%2Froot%2Foutputs%2Frender.mp4&token=s%20e%2Fcret'
+ 'hermes-media://remote/%2Froot%2Foutputs%2Frender.mp4?profile=default'
)
})
@@ -205,49 +222,37 @@ describe('gatewayMediaDataUrl', () => {
})
describe('downloadGatewayMediaFile', () => {
- const api = vi.fn(async ({ path }: { path: string }) => {
- if (path.startsWith('/api/fs/read-data-url?')) {
- return { dataUrl: 'data:text/markdown;base64,IyByZXBvcnQ=' }
- }
-
- throw new Error(`unexpected path ${path}`)
- })
-
- let clickSpy: ReturnType
+ const saveGatewayFile = vi.fn(async () => ({ path: '/Users/me/Downloads/report.md', saved: true }))
beforeEach(() => {
- api.mockClear()
- vi.stubGlobal('window', { hermesDesktop: { api }, setTimeout: vi.fn() })
- vi.stubGlobal(
- 'fetch',
- vi.fn(async () => ({ blob: async () => new Blob(['# report'], { type: 'text/markdown' }) }))
- )
- URL.createObjectURL = vi.fn(() => 'blob:remote-artifact')
- URL.revokeObjectURL = vi.fn()
- clickSpy = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {})
- $connection.set({ mode: 'remote' } as never)
+ saveGatewayFile.mockClear()
+ vi.stubGlobal('window', { hermesDesktop: { saveGatewayFile } })
+ $connection.set({ mode: 'remote', profile: 'docker-gw' } as never)
})
afterEach(() => {
vi.unstubAllGlobals()
- vi.clearAllMocks()
- clickSpy.mockRestore()
$connection.set(null)
})
- it('downloads gateway files through the desktop fs bridge', async () => {
- await downloadGatewayMediaFile('file:///Users/me/project/report.md')
-
- expect(api).toHaveBeenCalledWith({
- path: '/api/fs/read-data-url?path=%2FUsers%2Fme%2Fproject%2Freport.md'
+ it('downloads gateway files through the native desktop save bridge', async () => {
+ await expect(downloadGatewayMediaFile('file:///Users/me/project/a%20b.md')).resolves.toEqual({
+ path: '/Users/me/Downloads/report.md',
+ saved: true
+ })
+
+ expect(saveGatewayFile).toHaveBeenCalledWith({
+ path: '/Users/me/project/a b.md',
+ profile: 'docker-gw',
+ suggestedName: 'a b.md'
})
- expect(clickSpy).toHaveBeenCalledOnce()
})
- it('rejects when the gateway refuses the file read', async () => {
- api.mockRejectedValueOnce(new Error('403 File is not readable'))
+ it('rejects when the desktop bridge is unavailable', async () => {
+ vi.stubGlobal('window', { hermesDesktop: {} })
- await expect(downloadGatewayMediaFile('/Users/me/project/report.md')).rejects.toThrow('403')
- expect(clickSpy).not.toHaveBeenCalled()
+ await expect(downloadGatewayMediaFile('/Users/me/project/report.md')).rejects.toThrow(
+ 'Desktop file download bridge'
+ )
})
})
diff --git a/apps/desktop/src/lib/media.ts b/apps/desktop/src/lib/media.ts
index 33bcfbd963..97404eb189 100644
--- a/apps/desktop/src/lib/media.ts
+++ b/apps/desktop/src/lib/media.ts
@@ -83,16 +83,16 @@ export async function resolveMediaDisplaySrc(path: string): Promise {
}
// Audio/video need a seekable source instead of a whole-file data URL. Keep
-// remote URLs untouched, route gateway-local files through the authenticated
-// download endpoint, and reserve the Electron protocol for files on this
-// desktop machine.
+// remote URLs untouched and route filesystem paths through the Electron media
+// protocol. Its main-process handler reads local files directly or proxies a
+// remote gateway with the connection's bearer/cookie/token authentication.
export async function resolveMediaPlaybackSrc(path: string): Promise {
if (isInlineMediaSrc(path)) {
return path
}
if (window.hermesDesktop && ['audio', 'video'].includes(mediaKind(path))) {
- return isRemoteGateway() ? mediaExternalUrl(path) : mediaStreamUrl(path)
+ return isRemoteGateway() ? mediaGatewayStreamUrl(path) : mediaStreamUrl(path)
}
return resolveMediaDisplaySrc(path)
@@ -119,6 +119,23 @@ export function mediaExternalUrl(path: string): string {
return /^file:/i.test(path) ? path : `file://${path}`
}
+// Remote gateway audio/video is proxied by the Electron main process. OAuth
+// connections intentionally expose no static token to the renderer, so a bare
+// HTTPS source cannot authenticate reliably. The custom protocol keeps secrets
+// out of renderer URLs while forwarding Range requests to /api/files/stream.
+export function mediaGatewayStreamUrl(path: string): string {
+ const conn = $connection.get()
+
+ if (isRemoteGateway()) {
+ const file = encodeURIComponent(filePathFromMediaPath(path))
+ const profile = conn?.profile ? `?profile=${encodeURIComponent(conn.profile)}` : ''
+
+ return `hermes-media://remote/${file}${profile}`
+ }
+
+ return mediaExternalUrl(path)
+}
+
// Custom Electron scheme (registered in electron/main.ts) that streams a local
// file with Range support. Used for audio/video so playback bypasses the data
// URL size cap and supports seeking. `path` may be a plain path or `file://…`.
@@ -165,25 +182,25 @@ export async function gatewayMediaDataUrl(path: string): Promise {
}
// Remote-mode replacement for opening gateway-local file paths with file://.
-// The file lives on the gateway, so fetch it over the authenticated fs bridge
-// and hand the bytes to the local browser shell as a download.
-export async function downloadGatewayMediaFile(path: string): Promise {
- const dataUrl = await readDesktopFileDataUrl(filePathFromMediaPath(path))
+// The file lives on the gateway, so ask the Electron main process to fetch the
+// bytes through the authenticated backend connection and save them locally. This
+// avoids browser/OS downloads losing OAuth cookies and avoids the data-URL cap
+// used by preview endpoints.
+export async function downloadGatewayMediaFile(
+ path: string
+): Promise<{ canceled?: boolean; path?: string; saved: boolean }> {
+ const file = filePathFromMediaPath(path)
+ const conn = $connection.get()
- if (!dataUrl) {
- throw new Error('Gateway returned no file data')
+ if (!window.hermesDesktop?.saveGatewayFile) {
+ throw new Error('Desktop file download bridge is unavailable')
}
- const response = await fetch(dataUrl)
- const blobUrl = URL.createObjectURL(await response.blob())
- const anchor = document.createElement('a')
- anchor.href = blobUrl
- anchor.download = mediaName(path)
- anchor.rel = 'noopener noreferrer'
- document.body.appendChild(anchor)
- anchor.click()
- anchor.remove()
- window.setTimeout(() => URL.revokeObjectURL(blobUrl), 30_000)
+ return window.hermesDesktop.saveGatewayFile({
+ path: file,
+ profile: conn?.profile,
+ suggestedName: mediaName(file)
+ })
}
export function mediaDisplayLabel(path: string): string {
diff --git a/apps/desktop/src/lib/model-options.test.ts b/apps/desktop/src/lib/model-options.test.ts
index c855b6d234..4220d7494c 100644
--- a/apps/desktop/src/lib/model-options.test.ts
+++ b/apps/desktop/src/lib/model-options.test.ts
@@ -16,7 +16,11 @@ describe('requestModelOptions', () => {
})
it('uses the connected gateway even before a session exists', async () => {
- const gatewayPayload = { model: 'BeastMode', provider: 'moa', providers: [] }
+ const gatewayPayload = {
+ model: 'BeastMode',
+ provider: 'moa',
+ providers: [{ models: ['BeastMode'], name: 'Mixture of Agents', slug: 'moa' }]
+ }
const gateway = {
request: vi.fn(() => Promise.resolve(gatewayPayload))
@@ -28,6 +32,71 @@ describe('requestModelOptions', () => {
expect(getGlobalModelOptions).not.toHaveBeenCalled()
})
+ it('recovers an empty gateway catalog through profile-scoped REST without replacing the session selection', async () => {
+ const gatewayPayload = { model: 'hermes-local', provider: 'hermes-local' }
+
+ const restPayload = {
+ model: 'profile-default',
+ provider: 'openai-codex',
+ providers: [{ models: ['hermes-local'], name: 'Hermes Local vLLM', slug: 'hermes-local' }]
+ }
+
+ const gateway = {
+ request: vi.fn(() => Promise.resolve(gatewayPayload))
+ }
+
+ vi.mocked(getGlobalModelOptions).mockResolvedValueOnce(restPayload)
+
+ await expect(requestModelOptions({ gateway: gateway as never, sessionId: 'session-1' })).resolves.toEqual({
+ ...restPayload,
+ model: 'hermes-local',
+ provider: 'hermes-local'
+ })
+
+ expect(getGlobalModelOptions).toHaveBeenCalledWith({ explicitOnly: true })
+ })
+
+ it('recovers through profile-scoped REST when the gateway catalog request fails', async () => {
+ const restPayload = {
+ model: 'hermes-local',
+ provider: 'hermes-local',
+ providers: [{ models: ['hermes-local'], name: 'Hermes Local vLLM', slug: 'hermes-local' }]
+ }
+
+ const gateway = {
+ request: vi.fn(() => Promise.reject(new Error('gateway request unavailable')))
+ }
+
+ vi.mocked(getGlobalModelOptions).mockResolvedValueOnce(restPayload)
+
+ await expect(requestModelOptions({ gateway: gateway as never, sessionId: 'session-1' })).resolves.toEqual(
+ restPayload
+ )
+ expect(getGlobalModelOptions).toHaveBeenCalledWith({ explicitOnly: true })
+ })
+
+ it('preserves the gateway error when its REST recovery path also fails', async () => {
+ const gatewayError = new Error('gateway request unavailable')
+
+ const gateway = {
+ request: vi.fn(() => Promise.reject(gatewayError))
+ }
+
+ vi.mocked(getGlobalModelOptions).mockRejectedValueOnce(new Error('REST request unavailable'))
+
+ await expect(requestModelOptions({ gateway: gateway as never })).rejects.toBe(gatewayError)
+ })
+
+ it('keeps the gateway result when both catalog paths have no selectable models', async () => {
+ const gatewayPayload = { model: 'hermes-local', provider: 'hermes-local', providers: [] }
+
+ const gateway = {
+ request: vi.fn(() => Promise.resolve(gatewayPayload))
+ }
+
+ await expect(requestModelOptions({ gateway: gateway as never })).resolves.toBe(gatewayPayload)
+ })
+
it('passes the active session id and refresh flag through the gateway', async () => {
const gateway = {
request: vi.fn(() => Promise.resolve(globalOptions))
@@ -40,6 +109,7 @@ describe('requestModelOptions', () => {
refresh: true,
session_id: 'session-1'
})
+ expect(getGlobalModelOptions).toHaveBeenCalledWith({ explicitOnly: true, refresh: true })
})
it('falls back to REST when no gateway is connected', async () => {
diff --git a/apps/desktop/src/lib/model-options.ts b/apps/desktop/src/lib/model-options.ts
index 0173b6f2b4..6add1bc684 100644
--- a/apps/desktop/src/lib/model-options.ts
+++ b/apps/desktop/src/lib/model-options.ts
@@ -50,7 +50,11 @@ export function modelOptionsQueryKey(profile: null | string | undefined, session
return ['model-options', profileKey, sessionId || 'global'] as const
}
-export function requestModelOptions({
+function hasSelectableModels(options: ModelOptionsResponse | null | undefined): boolean {
+ return options?.providers?.some(provider => (provider.models?.length ?? 0) > 0) ?? false
+}
+
+export async function requestModelOptions({
explicitOnly = true,
gateway,
refresh = false,
@@ -71,7 +75,43 @@ export function requestModelOptions({
params.explicit_only = true
}
- return gateway.request('model.options', params)
+ let gatewayError: unknown
+ let gatewayOptions: ModelOptionsResponse | undefined
+
+ try {
+ gatewayOptions = await gateway.request('model.options', params)
+ } catch (error) {
+ gatewayError = error
+ }
+
+ if (gatewayOptions && hasSelectableModels(gatewayOptions)) {
+ return gatewayOptions
+ }
+
+ // A connected Desktop gateway can occasionally return only the current
+ // provider/model (or an empty provider list) while its authenticated REST
+ // catalog is already populated. Recover through the same profile-scoped
+ // endpoint Settings uses, but keep the live session selection authoritative.
+ try {
+ const restOptions = await getGlobalModelOptions({ explicitOnly, ...(refresh ? { refresh: true } : {}) })
+
+ if (hasSelectableModels(restOptions)) {
+ return {
+ ...restOptions,
+ ...(gatewayOptions?.provider ? { provider: gatewayOptions.provider } : {}),
+ ...(gatewayOptions?.model ? { model: gatewayOptions.model } : {})
+ }
+ }
+ } catch {
+ // Preserve the gateway result (or its original error) when the recovery
+ // path is unavailable.
+ }
+
+ if (gatewayOptions) {
+ return gatewayOptions
+ }
+
+ throw gatewayError
}
return getGlobalModelOptions({ explicitOnly, ...(refresh ? { refresh: true } : {}) })
diff --git a/apps/desktop/src/lib/persisted.test.ts b/apps/desktop/src/lib/persisted.test.ts
new file mode 100644
index 0000000000..95eaa3ff36
--- /dev/null
+++ b/apps/desktop/src/lib/persisted.test.ts
@@ -0,0 +1,66 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { Codecs, persistentAtom } from './persisted'
+
+// Unique key per test run — persistentAtom instances are singletons per call,
+// so tests mint fresh keys instead of sharing one.
+let counter = 0
+const freshKey = () => `test.persisted.${++counter}`
+
+describe('persistentAtom', () => {
+ beforeEach(() => {
+ window.localStorage.clear()
+ })
+
+ it('seeds from a stored value', () => {
+ const key = freshKey()
+ window.localStorage.setItem(key, JSON.stringify({ a: 1 }))
+
+ const $value = persistentAtom>(key, {})
+
+ expect($value.get()).toEqual({ a: 1 })
+ })
+
+ it('does NOT write at creation — an empty read must never clobber storage', () => {
+ // A cold boot can evaluate the bundle against a storage snapshot that has
+ // not caught up yet (early hidden/boot load). If creation echoed the
+ // fallback back out, that load would overwrite the real record other
+ // loads are about to read. Creation must be read-only.
+ const key = freshKey()
+ persistentAtom>(key, {})
+
+ expect(window.localStorage.getItem(key)).toBeNull()
+ })
+
+ it('leaves an existing stored value untouched at creation even when it fails to decode', () => {
+ const key = freshKey()
+ window.localStorage.setItem(key, 'not json')
+
+ const $value = persistentAtom>(key, { fallback: 1 })
+
+ expect($value.get()).toEqual({ fallback: 1 })
+ // The corrupt value survives until a real write replaces it — creation
+ // never writes.
+ expect(window.localStorage.getItem(key)).toBe('not json')
+ })
+
+ it('persists real changes', () => {
+ const key = freshKey()
+ const $value = persistentAtom>(key, {})
+
+ $value.set({ b: 2 })
+
+ expect(window.localStorage.getItem(key)).toBe(JSON.stringify({ b: 2 }))
+ })
+
+ it('removes the key when the codec encodes null', () => {
+ const key = freshKey()
+ window.localStorage.setItem(key, JSON.stringify(['x']))
+
+ const $value = persistentAtom(key, [], Codecs.stringArray)
+
+ $value.set([])
+
+ expect(window.localStorage.getItem(key)).toBeNull()
+ })
+})
diff --git a/apps/desktop/src/lib/persisted.ts b/apps/desktop/src/lib/persisted.ts
index 95cd0335ae..f9d3c7c400 100644
--- a/apps/desktop/src/lib/persisted.ts
+++ b/apps/desktop/src/lib/persisted.ts
@@ -72,7 +72,26 @@ export function persistentAtom(key: string, fallback: T, codec: Codec = Co
const $value = atom(initial)
- $value.subscribe(value => writeKey(key, codec.encode(value)))
+ // Persist CHANGES only — never the creation-time value. nanostores'
+ // subscribe fires immediately, and writing what was just read back is a
+ // no-op at best; at worst it is a data-loss clobber: on a cold boot the
+ // renderer bundle can run against a storage snapshot that has not caught
+ // up yet (an early hidden/boot load of the same bundle sees an empty
+ // area), and echoing the fallback back out overwrites the real record
+ // other loads are about to read. Observed with the unread-dot records:
+ // the early load wrote `{}` over a populated store between the disk read
+ // and the main window's module init.
+ let creationEmission = true
+
+ $value.subscribe(value => {
+ if (creationEmission) {
+ creationEmission = false
+
+ return
+ }
+
+ writeKey(key, codec.encode(value))
+ })
return $value
}
diff --git a/apps/desktop/src/lib/renderer-loop-pause.test.ts b/apps/desktop/src/lib/renderer-loop-pause.test.ts
new file mode 100644
index 0000000000..46563c627a
--- /dev/null
+++ b/apps/desktop/src/lib/renderer-loop-pause.test.ts
@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { installRendererAnimationPauseState, RENDERER_ANIMATIONS_PAUSED_ATTRIBUTE } from './renderer-loop-pause'
+
+describe('installRendererAnimationPauseState', () => {
+ afterEach(() => {
+ document.documentElement.removeAttribute(RENDERER_ANIMATIONS_PAUSED_ATTRIBUTE)
+ vi.restoreAllMocks()
+ })
+
+ it('pauses on blur, resumes on focus, and cleans up its root state', () => {
+ let focused = true
+ vi.spyOn(document, 'hasFocus').mockImplementation(() => focused)
+
+ const dispose = installRendererAnimationPauseState()
+ expect(document.documentElement.hasAttribute(RENDERER_ANIMATIONS_PAUSED_ATTRIBUTE)).toBe(false)
+
+ focused = false
+ window.dispatchEvent(new Event('blur'))
+ expect(document.documentElement.hasAttribute(RENDERER_ANIMATIONS_PAUSED_ATTRIBUTE)).toBe(true)
+
+ focused = true
+ window.dispatchEvent(new Event('focus'))
+ expect(document.documentElement.hasAttribute(RENDERER_ANIMATIONS_PAUSED_ATTRIBUTE)).toBe(false)
+
+ focused = false
+ window.dispatchEvent(new Event('blur'))
+ dispose()
+ expect(document.documentElement.hasAttribute(RENDERER_ANIMATIONS_PAUSED_ATTRIBUTE)).toBe(false)
+ })
+})
diff --git a/apps/desktop/src/lib/renderer-loop-pause.ts b/apps/desktop/src/lib/renderer-loop-pause.ts
index 88b9e3559b..55fb19b1c7 100644
--- a/apps/desktop/src/lib/renderer-loop-pause.ts
+++ b/apps/desktop/src/lib/renderer-loop-pause.ts
@@ -3,6 +3,8 @@ interface WindowStatePayload {
isVisible?: boolean
}
+export const RENDERER_ANIMATIONS_PAUSED_ATTRIBUTE = 'data-renderer-animations-paused'
+
export function createRendererLoopPauseController(onChange: () => void, { pauseWhenUnfocused = true } = {}) {
let windowPaused = false
let windowFocused = document.hasFocus()
@@ -48,3 +50,23 @@ export function createRendererLoopPauseController(onChange: () => void, { pauseW
isPaused: () => document.visibilityState === 'hidden' || (pauseWhenUnfocused && !windowFocused) || windowPaused
}
}
+
+/**
+ * Mirrors the main window's observability onto :root so continuous decorative
+ * CSS animations can sleep with the JS renderer loops. The caller owns the
+ * returned cleanup; overlay windows intentionally do not install this state.
+ */
+export function installRendererAnimationPauseState(): () => void {
+ const root = document.documentElement
+ let controller: ReturnType
+
+ const sync = () => root.toggleAttribute(RENDERER_ANIMATIONS_PAUSED_ATTRIBUTE, controller.isPaused())
+
+ controller = createRendererLoopPauseController(sync)
+ sync()
+
+ return () => {
+ controller.dispose()
+ root.removeAttribute(RENDERER_ANIMATIONS_PAUSED_ATTRIBUTE)
+ }
+}
diff --git a/apps/desktop/src/lib/session-signatures.test.ts b/apps/desktop/src/lib/session-signatures.test.ts
index aeecd19b61..0c4c280c8e 100644
--- a/apps/desktop/src/lib/session-signatures.test.ts
+++ b/apps/desktop/src/lib/session-signatures.test.ts
@@ -4,7 +4,8 @@ import type { SessionInfo } from '@/hermes'
import { sameCronSignature, sessionMessagesSignature } from './session-signatures'
-const session = (id: string, title: string | null): SessionInfo => ({ id, title }) as SessionInfo
+const session = (id: string, title: string | null, extra: Partial = {}): SessionInfo =>
+ ({ id, title, ...extra }) as SessionInfo
describe('sameCronSignature', () => {
it('is false when the lengths differ', () => {
@@ -28,6 +29,28 @@ describe('sameCronSignature', () => {
const b = [session('b', 't'), session('a', 't')]
expect(sameCronSignature(a, b)).toBe(false)
})
+
+ // A pin-only page must reach $sessions: session-pin-sync treats the row as
+ // authoritative and releases its write guard when a page confirms the value
+ // it wrote. Gating that page out froze the row and re-pinned what the user
+ // had just unpinned (#76919).
+ it('is false when only the pinned flag changed', () => {
+ const a = [session('a', 't', { pinned: true })]
+ const b = [session('a', 't', { pinned: false })]
+ expect(sameCronSignature(a, b)).toBe(false)
+ })
+
+ it('is false when only the archived flag changed', () => {
+ const a = [session('a', 't', { archived: false })]
+ const b = [session('a', 't', { archived: true })]
+ expect(sameCronSignature(a, b)).toBe(false)
+ })
+
+ it('is true when both flags match', () => {
+ const a = [session('a', 't', { archived: false, pinned: true })]
+ const b = [session('a', 't', { archived: false, pinned: true })]
+ expect(sameCronSignature(a, b)).toBe(true)
+ })
})
describe('sessionMessagesSignature', () => {
diff --git a/apps/desktop/src/lib/session-signatures.ts b/apps/desktop/src/lib/session-signatures.ts
index 4ef20e1fab..fac4725422 100644
--- a/apps/desktop/src/lib/session-signatures.ts
+++ b/apps/desktop/src/lib/session-signatures.ts
@@ -23,7 +23,14 @@ export function sameCronSignature(a: SessionInfo[], b: SessionInfo[]): boolean {
session.preview === other.preview &&
session.message_count === other.message_count &&
session.last_active === other.last_active &&
- session.ended_at === other.ended_at
+ session.ended_at === other.ended_at &&
+ // Row STATE, not just row content: session-pin-sync reconciles the
+ // sidebar's pins against `pinned` on the rows in this atom, so a page
+ // whose only delta is a flag has to swap in or the reconciler reads a
+ // frozen copy forever. An idle conversation never moves any of the
+ // fields above again, which is exactly when a pin gets toggled (#76919).
+ session.pinned === other.pinned &&
+ session.archived === other.archived
)
})
}
diff --git a/apps/desktop/src/lib/statusbar.tsx b/apps/desktop/src/lib/statusbar.tsx
index 0c0d22599c..01ca3b645a 100644
--- a/apps/desktop/src/lib/statusbar.tsx
+++ b/apps/desktop/src/lib/statusbar.tsx
@@ -1,6 +1,7 @@
-import { useEffect, useState } from 'react'
+import { useState } from 'react'
import { StableText } from '@/components/chat/stable-text'
+import { useViewedInterval } from '@/hooks/use-viewed-interval'
import { compactNumber } from '@/lib/format'
import type { UsageStats } from '@/types/hermes'
@@ -61,17 +62,7 @@ export function contextBarLabel(usage: UsageStats): string {
export function LiveDuration({ since }: { since: number | null | undefined }) {
const [now, setNow] = useState(() => Date.now())
- useEffect(() => {
- if (!since) {
- return
- }
-
- const tick = () => setNow(Date.now())
- tick()
- const timer = window.setInterval(tick, 1000)
-
- return () => window.clearInterval(timer)
- }, [since])
+ useViewedInterval(() => setNow(Date.now()), 1000, Boolean(since))
if (!since) {
return null
diff --git a/apps/desktop/src/lib/tool-run-continuity.test.ts b/apps/desktop/src/lib/tool-run-continuity.test.ts
index a009053db3..1955565410 100644
--- a/apps/desktop/src/lib/tool-run-continuity.test.ts
+++ b/apps/desktop/src/lib/tool-run-continuity.test.ts
@@ -248,3 +248,37 @@ describe('run identity', () => {
expect(runs.map(run => run.map(t => t.toolCallId))).toEqual([['a'], ['b']])
})
})
+
+describe('coalesced tool lifecycle', () => {
+ it('keeps the latest completion boundary from a folded tool-only message', () => {
+ const messages: ChatMessage[] = [
+ {
+ completedAt: 2,
+ id: 'assistant-text',
+ parts: [assistantTextPart('Checking.')],
+ role: 'assistant',
+ timestamp: 1
+ },
+ {
+ id: 'assistant-tool',
+ parts: [
+ {
+ args: {} as never,
+ argsText: '{}',
+ completedAt: 5,
+ timestamp: 3,
+ toolCallId: 'call-1',
+ toolName: 'terminal',
+ type: 'tool-call'
+ }
+ ],
+ role: 'assistant',
+ timestamp: 3
+ }
+ ]
+
+ const [merged] = coalesceToolOnlyAssistants(messages, createToolMergeCache())
+
+ expect(merged.completedAt).toBe(5)
+ })
+})
diff --git a/apps/desktop/src/lib/version-status.test.ts b/apps/desktop/src/lib/version-status.test.ts
index 54a4bb2d57..0ea9408039 100644
--- a/apps/desktop/src/lib/version-status.test.ts
+++ b/apps/desktop/src/lib/version-status.test.ts
@@ -30,6 +30,18 @@ describe('resolveVersionStatus', () => {
expect(status.tooltip).toContain('12 commits behind main')
})
+ // FAIL-BEFORE (#84591 class): a shallow install reports behind:null +
+ // updateAvailable. The client target ignored updateAvailable entirely, so
+ // the statusbar showed no update at all — and further back, the fabricated
+ // behind:1 rendered a frozen "(+1)" while the real distance grew to 61.
+ it('shows a count-free update hint when the client count is unknown', () => {
+ const status = client({ behind: 0, updateAvailable: true, version: '0.4.2' })
+
+ expect(status.label).toBe(`v0.4.2 (${copy.update})`)
+ expect(status.label).not.toContain('+1')
+ expect(status.hasUpdate).toBe(true)
+ })
+
it('names the client as one of two versions in remote mode', () => {
expect(client({ remote: true, version: '0.4.2' }).label).toBe('client v0.4.2')
})
diff --git a/apps/desktop/src/lib/version-status.ts b/apps/desktop/src/lib/version-status.ts
index 030464e8ec..0b292c9f31 100644
--- a/apps/desktop/src/lib/version-status.ts
+++ b/apps/desktop/src/lib/version-status.ts
@@ -39,7 +39,7 @@ export interface VersionStatusInput {
/** Client only: short commit sha of the running build. */
sha?: null | string
target: UpdateTarget
- /** Backend only: an update the commit count can't express (pip installs). */
+ /** An update the commit count can't express (shallow clones, pip installs). */
updateAvailable?: boolean
version?: null | string
}
@@ -70,7 +70,12 @@ export function resolveVersionStatus({
}: VersionStatusInput): VersionStatusResult {
const client = target === 'client'
const busy = applying || restarting
- const available = behind > 0 || (!client && !!updateAvailable)
+ // updateAvailable covers every "behind but uncountable" shape: shallow
+ // installer clones (behind === null upstream, coalesced to 0 by callers),
+ // SSH-official presence-only checks, and pip installs. It applies to BOTH
+ // targets — the client statusbar item is how a shallow desktop install
+ // learns it's stale at all.
+ const available = behind > 0 || !!updateAvailable
// A client with no version still identifies itself by sha; a backend can't.
const named = version ?? (client ? sha : null) ?? copy.unknown
diff --git a/apps/desktop/src/main.tsx b/apps/desktop/src/main.tsx
index b2ef156a43..39e21ce743 100644
--- a/apps/desktop/src/main.tsx
+++ b/apps/desktop/src/main.tsx
@@ -25,6 +25,7 @@ import { RootTooltipProvider } from './components/ui/tooltip'
import { I18nProvider } from './i18n'
import { installClipboardShim } from './lib/clipboard'
import { queryClient } from './lib/query-client'
+import { installRendererAnimationPauseState } from './lib/renderer-loop-pause'
import { ThemeProvider } from './themes/context'
installClipboardShim()
@@ -50,6 +51,11 @@ if (winParam === 'overlay') {
} else if (winParam === 'wake') {
void import('./app/wake-indicator/wake-indicator-root').then(({ mountWakeIndicator }) => mountWakeIndicator())
} else {
+ // CSS animations do not inherit Chromium's JS-loop pause policy. Mirror the
+ // main window's focus/visibility state to :root so decorative infinite
+ // animations stop producing frames when nobody can see them.
+ installRendererAnimationPauseState()
+
createRoot(document.getElementById('root')!).render(
diff --git a/apps/desktop/src/plugins/kanban/board.tsx b/apps/desktop/src/plugins/kanban/board.tsx
index 3c4cdd9f97..2124e8dcd0 100644
--- a/apps/desktop/src/plugins/kanban/board.tsx
+++ b/apps/desktop/src/plugins/kanban/board.tsx
@@ -4,8 +4,8 @@
* header row (count, filter kebab, search, settings, new task — the board
* SWITCHER lives in the titlebar, see board-switcher.tsx), columns in
* BOARD_COLUMNS order, drag-to-move (optimistic, workflow-checked),
- * ⌘-click multi-select with a floating bulk bar, right-click actions, and
- * the detail drawer. Dispatch nudges ride every write (see api.ts).
+ * primary-modifier-click multi-select with a floating bulk bar, right-click
+ * actions, and the detail drawer. Dispatch nudges ride every write (see api.ts).
*/
import {
@@ -30,6 +30,7 @@ import {
DropdownMenuSeparator,
DropdownMenuTrigger,
ErrorState,
+ formatModifierToken,
host,
Input,
Loader,
@@ -309,7 +310,7 @@ function Card({
onToggleSelect(task.id)}>
- {selected ? k.deselect : k.select}
+ {selected ? k.deselect : k.select(formatModifierToken('mod'))}
{columns
diff --git a/apps/desktop/src/plugins/kanban/i18n.ts b/apps/desktop/src/plugins/kanban/i18n.ts
index e751f698c8..34a64fccbb 100644
--- a/apps/desktop/src/plugins/kanban/i18n.ts
+++ b/apps/desktop/src/plugins/kanban/i18n.ts
@@ -29,7 +29,7 @@ type KanbanMessages = {
noMatch: string
noTasks: string
open: string
- select: string
+ select: (modifier: string) => string
deselect: string
moveTo: (label: string) => string
delete: string
@@ -217,7 +217,7 @@ const en: KanbanMessages = {
noMatch: 'No tasks match the filters',
noTasks: 'No tasks on this board',
open: 'Open',
- select: 'Select (⌘-click)',
+ select: modifier => `Select (${modifier}-click)`,
deselect: 'Deselect',
moveTo: label => `Move to ${label}`,
delete: 'Delete',
@@ -409,7 +409,7 @@ const ja: KanbanMessages = {
noMatch: 'フィルタに一致するタスクはありません',
noTasks: 'このボードにタスクはありません',
open: '開く',
- select: '選択（⌘クリック）',
+ select: modifier => `選択（${modifier}クリック）`,
deselect: '選択解除',
moveTo: label => `${label} へ移動`,
delete: '削除',
@@ -600,7 +600,7 @@ const zh: KanbanMessages = {
noMatch: '没有符合筛选条件的任务',
noTasks: '此面板暂无任务',
open: '打开',
- select: '选择（⌘点击）',
+ select: modifier => `选择（${modifier}点击）`,
deselect: '取消选择',
moveTo: label => `移动到 ${label}`,
delete: '删除',
@@ -788,7 +788,7 @@ const zhHant: KanbanMessages = {
noMatch: '沒有符合篩選條件的任務',
noTasks: '此面板尚無任務',
open: '開啟',
- select: '選取（⌘點擊）',
+ select: modifier => `選取（${modifier}點擊）`,
deselect: '取消選取',
moveTo: label => `移至 ${label}`,
delete: '刪除',
diff --git a/apps/desktop/src/sdk/index.ts b/apps/desktop/src/sdk/index.ts
index d3d9ae923e..adf70aa325 100644
--- a/apps/desktop/src/sdk/index.ts
+++ b/apps/desktop/src/sdk/index.ts
@@ -24,7 +24,7 @@ import { openSession, type OpenSessionIntent } from '@/app/open-session'
import { $narrowViewport } from '@/components/pane-shell/tree/store'
import { onGatewayEvent } from '@/contrib/events'
import { getLogs, getStatus } from '@/hermes'
-import { $gateway } from '@/store/gateway'
+import { $gateway, openGatewayForProfile } from '@/store/gateway'
import { notify, notifyError } from '@/store/notifications'
import { $activeGatewayProfile, ensureGatewayProfile, newSessionInProfile, setShowAllProfiles } from '@/store/profile'
import { $activeSessionId, $currentCwd, $currentModel, $gatewayState } from '@/store/session'
@@ -96,6 +96,23 @@ export const host = {
* unified all-profiles view instead of narrowing it to the target
* profile's sessions — a cross-profile open from a plugin surface is a
* navigation, not a scope choice; pass false to also scope the sidebar. */
+ /** Pre-dial a profile's gateway socket in the background — pool-only, no
+ * activation, no navigation, no scope change (openGatewayForProfile; it
+ * already no-ops for shared-remote routes and the primary). Roster UIs
+ * call this after mount so the FIRST click on an agent doesn't pay the
+ * whole backend spawn + socket dial latency. Fire-and-forget: failures
+ * are swallowed — the click path re-runs its own ensure and surfaces
+ * errors properly. */
+ warmProfile: (profile: string): void => {
+ const name = (profile ?? '').trim()
+
+ if (!name || name === $activeGatewayProfile.get()) {
+ return
+ }
+
+ void openGatewayForProfile(name).catch(() => undefined)
+ },
+
openSession: async (
storedSessionId: string,
options: { intent?: OpenSessionIntent; keepAllProfilesScope?: boolean; profile?: null | string } = {}
@@ -284,6 +301,7 @@ export { triggerHaptic as haptic } from '@/lib/haptics'
/** The app's lucide icon set (RefreshCw, LayoutDashboard, Activity, …). */
export * as icons from '@/lib/icons'
export { type KeybindContribution, KEYBINDS_AREA } from '@/lib/keybinds/actions'
+export { formatModifierToken } from '@/lib/keybinds/combo'
/** The app's deterministic identity color for a name (profiles, assignees,
* authors) + its translucent tag fill — so plugin-rendered identities read
* the same hue as everywhere else. */
diff --git a/apps/desktop/src/store/clarify.test.ts b/apps/desktop/src/store/clarify.test.ts
index aec413b5b3..072fd0c3f9 100644
--- a/apps/desktop/src/store/clarify.test.ts
+++ b/apps/desktop/src/store/clarify.test.ts
@@ -18,6 +18,7 @@ function clarify(sessionId: string | null, requestId: string): ClarifyRequest {
requestId,
question: `question-${requestId}`,
choices: null,
+ multiSelect: false,
sessionId
}
}
diff --git a/apps/desktop/src/store/clarify.ts b/apps/desktop/src/store/clarify.ts
index 6dfc275e75..2bf13d516d 100644
--- a/apps/desktop/src/store/clarify.ts
+++ b/apps/desktop/src/store/clarify.ts
@@ -7,6 +7,7 @@ export interface ClarifyRequest {
requestId: string
question: string
choices: string[] | null
+ multiSelect: boolean
sessionId: string | null
}
diff --git a/apps/desktop/src/store/composer-popout-preference.test.ts b/apps/desktop/src/store/composer-popout-preference.test.ts
new file mode 100644
index 0000000000..ab5865bd84
--- /dev/null
+++ b/apps/desktop/src/store/composer-popout-preference.test.ts
@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const GESTURES_KEY = 'hermes.desktop.composerPopout.gesturesEnabled'
+const LEGACY_ENABLED_KEY = 'hermes.desktop.composerPopout.enabled'
+const ZONES_KEY = 'hermes.desktop.composerPopout.zones.v1'
+
+const loadStore = () => import('./composer-popout')
+
+describe('composer pop-out preference', () => {
+ beforeEach(() => {
+ window.localStorage.clear()
+ vi.resetModules()
+ })
+
+ it('docks every floating zone, preserves positions, and persists the lock', async () => {
+ const first = await loadStore()
+
+ first.setComposerPopoutPosition('left', { bottom: 100, right: 100 })
+ first.setComposerPoppedOut('left', true)
+ first.setComposerPopoutPosition('right', { bottom: 200, right: 200 })
+ first.setComposerPoppedOut('right', true)
+
+ first.setComposerPopoutGesturesEnabled(false)
+
+ expect(first.$composerPopoutGesturesEnabled.get()).toBe(false)
+ expect(first.getComposerPopoutZone('left')).toEqual({
+ poppedOut: false,
+ position: { bottom: 100, right: 100 }
+ })
+ expect(first.getComposerPopoutZone('right')).toEqual({
+ poppedOut: false,
+ position: { bottom: 200, right: 200 }
+ })
+ expect(window.localStorage.getItem(GESTURES_KEY)).toBe('false')
+ expect(window.localStorage.getItem(LEGACY_ENABLED_KEY)).toBe('false')
+
+ vi.resetModules()
+ const reloaded = await loadStore()
+
+ expect(reloaded.$composerPopoutGesturesEnabled.get()).toBe(false)
+ expect(reloaded.getComposerPopoutZone('left').poppedOut).toBe(false)
+ expect(reloaded.getComposerPopoutZone('right').poppedOut).toBe(false)
+ })
+
+ it('normalizes stale floating zones when the persisted preference is disabled', async () => {
+ window.localStorage.setItem(GESTURES_KEY, 'false')
+ window.localStorage.setItem(
+ ZONES_KEY,
+ JSON.stringify({ stale: { poppedOut: true, position: { bottom: 48, right: 64 } } })
+ )
+
+ const store = await loadStore()
+
+ expect(store.getComposerPopoutZone('stale')).toEqual({
+ poppedOut: false,
+ position: { bottom: 48, right: 64 }
+ })
+ })
+
+ it('keeps pop-out gestures enabled by default', async () => {
+ const store = await loadStore()
+
+ expect(store.$composerPopoutGesturesEnabled.get()).toBe(true)
+ })
+})
diff --git a/apps/desktop/src/store/composer-popout.ts b/apps/desktop/src/store/composer-popout.ts
index a5d3b5ab6d..ea6ec7e464 100644
--- a/apps/desktop/src/store/composer-popout.ts
+++ b/apps/desktop/src/store/composer-popout.ts
@@ -1,14 +1,17 @@
import { atom, computed, type ReadableAtom } from 'nanostores'
-import { persistString, storedString } from '@/lib/storage'
+import { persistBoolean, persistString, storedBoolean, storedString } from '@/lib/storage'
const POPOUT_STORAGE_KEY = 'hermes.desktop.composerPopout.zones.v1'
+const POPOUT_GESTURES_ENABLED_STORAGE_KEY = 'hermes.desktop.composerPopout.gesturesEnabled'
// Pre-zone keys: one flag + one position for the whole window. Read at load to
// seed the first zone the user touches (see `legacySeed`), never written again.
const LEGACY_ENABLED_KEY = 'hermes.desktop.composerPopout.enabled'
const LEGACY_POSITION_KEY = 'hermes.desktop.composerPopout.position'
+const gesturesEnabledAtLoad = storedBoolean(POPOUT_GESTURES_ENABLED_STORAGE_KEY, true)
+
/** Where the floating composer's bottom-right corner sits, measured as an inset
* from the viewport's bottom/right edges. Anchoring to the bottom-right keeps
* the box visually pinned to its default corner as the window resizes and as
@@ -63,7 +66,7 @@ function load(): Record {
const zone = value as null | Partial
if (typeof zone?.poppedOut === 'boolean' && isPosition(zone.position)) {
- out[id] = { poppedOut: zone.poppedOut, position: { ...zone.position } }
+ out[id] = { poppedOut: gesturesEnabledAtLoad && zone.poppedOut, position: { ...zone.position } }
}
}
} catch {
@@ -80,6 +83,7 @@ function load(): Record {
* put it), while a split zone beside them keeps its own — popping out on the
* left doesn't fling a composer out of the right. */
export const $composerPopoutZones = atom>(load())
+export const $composerPopoutGesturesEnabled = atom(gesturesEnabledAtLoad)
/** Write-through to storage. Called explicitly — NOT on every store change: a
* drag updates the position once per frame, and serializing every zone to
@@ -91,7 +95,9 @@ const persistZones = () => persistString(POPOUT_STORAGE_KEY, JSON.stringify($com
* — but ONLY until they touch any zone. Once real per-zone state exists, that
* is the truth, and a zone split later starts docked like any other. */
let legacySeed: PopoutZoneState | null =
- storedString(LEGACY_ENABLED_KEY) === 'true' ? { poppedOut: true, position: legacyPosition() } : null
+ gesturesEnabledAtLoad && storedString(LEGACY_ENABLED_KEY) === 'true'
+ ? { poppedOut: true, position: legacyPosition() }
+ : null
const zoneState = (zones: Record, groupId: string): PopoutZoneState =>
zones[groupId] ?? legacySeed ?? DEFAULT_ZONE
@@ -223,6 +229,32 @@ export function setComposerPoppedOut(groupId: string, value: boolean) {
persistZones()
}
+export function setComposerPopoutGesturesEnabled(value: boolean) {
+ $composerPopoutGesturesEnabled.set(value)
+ persistBoolean(POPOUT_GESTURES_ENABLED_STORAGE_KEY, value)
+
+ if (value) {
+ return
+ }
+
+ // Turning the feature off is an immediate lock-to-dock action for every
+ // layout zone, not merely a promise to ignore the next gesture. Keep each
+ // zone's resting position so opting back in restores where the user put it.
+ const zones = $composerPopoutZones.get()
+
+ const docked = Object.fromEntries(
+ Object.entries(zones).map(([groupId, zone]) => [groupId, { ...zone, poppedOut: false }])
+ )
+
+ legacySeed = null
+ $composerPopoutZones.set(docked)
+ persistZones()
+
+ // Neutralize the pre-zone singleton migration seed too, otherwise a reload
+ // with no materialized zones could revive an old floating composer.
+ persistBoolean(LEGACY_ENABLED_KEY, false)
+}
+
/** Move this zone's box. Used per-frame during a drag, so it only writes the
* in-memory store by default; pass `persist` for the resting position on
* release. Returns the clamped position so callers can sync their live ref. */
diff --git a/apps/desktop/src/store/composer-suggestions.test.ts b/apps/desktop/src/store/composer-suggestions.test.ts
index 2dc3d6337b..e76c56a2f4 100644
--- a/apps/desktop/src/store/composer-suggestions.test.ts
+++ b/apps/desktop/src/store/composer-suggestions.test.ts
@@ -80,4 +80,47 @@ describe('composer suggestion bus', () => {
offerSuggestions('s6', 'test', [])
})
+
+ it('replaces an offer whose rendered copy changed under the same key', () => {
+ offerSuggestions('s7', 'test', [{ ...suggestion('linear'), tip: 'because you mentioned “linear”' }])
+ offerSuggestions('s7', 'test', [{ ...suggestion('linear'), tip: 'because you pasted linear.app' }])
+
+ // Same key, new trigger — the strip must paint the new reason, not the
+ // first one it ever saw.
+ expect(($composerSuggestionsBySession.get().s7 ?? []).map(s => s.tip)).toEqual(['because you pasted linear.app'])
+
+ offerSuggestions('s7', 'test', [])
+ })
+
+ it('re-offering the same key swaps in the fresh invoke closure', async () => {
+ const calls: string[] = []
+
+ const offer = (tag: string) =>
+ offerSuggestions('s8', 'test', [
+ { ...suggestion('linear'), invoke: async () => void calls.push(tag), label: `Add linear ${tag}` }
+ ])
+
+ offer('first')
+ offer('second')
+
+ await ($composerSuggestionsBySession.get().s8 ?? [])[0]!.invoke({ cancelled: () => false, sessionId: 's8' })
+
+ // A pinned first object means the pill runs work built for a draft the
+ // user has since changed.
+ expect(calls).toEqual(['second'])
+
+ offerSuggestions('s8', 'test', [])
+ })
+
+ it('keeps the array reference when nothing the pill paints changed', () => {
+ offerSuggestions('s9', 'test', [suggestion('linear')])
+
+ const first = $composerSuggestionsBySession.get().s9
+
+ offerSuggestions('s9', 'test', [suggestion('linear')])
+
+ expect($composerSuggestionsBySession.get().s9).toBe(first)
+
+ offerSuggestions('s9', 'test', [])
+ })
})
diff --git a/apps/desktop/src/store/composer-suggestions.ts b/apps/desktop/src/store/composer-suggestions.ts
index d0724ddd88..a241c3395a 100644
--- a/apps/desktop/src/store/composer-suggestions.ts
+++ b/apps/desktop/src/store/composer-suggestions.ts
@@ -67,8 +67,31 @@ export const $composerSuggestionsBySession = atom sessionId ?? ''
+// Everything the pill actually paints. Compared field-by-field rather than by
+// key alone: a provider rebuilds its suggestion objects on every sample, so
+// key equality is true constantly, and treating that as "no change" pins the
+// FIRST object forever — the strip then paints a stale tip and, worse, calls a
+// stale `invoke` closure. Comparing the rendered copy keeps the cheap bail-out
+// for the common case (same draft, same match) while letting a genuinely
+// changed offer through.
+const RENDERED: readonly (keyof ComposerSuggestion)[] = [
+ 'brand',
+ 'doneLabel',
+ 'doneTip',
+ 'icon',
+ 'label',
+ 'tip',
+ 'workingLabel',
+ 'workingTip'
+]
+
const sameSuggestions = (a: readonly ComposerSuggestion[], b: readonly ComposerSuggestion[]) =>
- a.length === b.length && a.every((x, i) => suggestionKey(x) === suggestionKey(b[i]!))
+ a.length === b.length &&
+ a.every((x, i) => {
+ const y = b[i]!
+
+ return suggestionKey(x) === suggestionKey(y) && RENDERED.every(field => x[field] === y[field])
+ })
function write(sessionId: string | null | undefined, suggestions: ComposerSuggestion[]): void {
const key = keyFor(sessionId)
diff --git a/apps/desktop/src/store/composer.test.ts b/apps/desktop/src/store/composer.test.ts
index d5445ea64c..0fc034b1d9 100644
--- a/apps/desktop/src/store/composer.test.ts
+++ b/apps/desktop/src/store/composer.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
import {
$composerAttachments,
@@ -6,6 +6,8 @@ import {
addComposerAttachment,
clearSessionDraft,
type ComposerAttachment,
+ createComposerAttachmentOccurrenceId,
+ createComposerAttachmentScope,
migrateSessionDraft,
removeComposerAttachment,
requestVoiceConversationStart,
@@ -61,6 +63,147 @@ describe('updateComposerAttachment', () => {
expect(updated).toBe(false)
expect($composerAttachments.get()).toHaveLength(0)
})
+
+ it('updates only the exact attachment occurrence captured before an async operation', () => {
+ const scope = createComposerAttachmentScope()
+
+ const first = attachment({
+ id: 'image:a',
+ kind: 'image',
+ occurrenceId: createComposerAttachmentOccurrenceId(),
+ path: '/tmp/a.png'
+ })
+
+ const replacement = attachment({
+ id: 'image:a',
+ kind: 'image',
+ occurrenceId: createComposerAttachmentOccurrenceId(),
+ path: '/tmp/a.png'
+ })
+
+ scope.add(first)
+ scope.remove(first.id)
+ scope.add(replacement)
+
+ expect(scope.updateIfCurrent(first, { thumbnailUrl: 'data:image/png;base64,stale' })).toBe(false)
+ expect(scope.$attachments.get()).toEqual([replacement])
+ expect(scope.updateIfCurrent(replacement, { thumbnailUrl: 'data:image/png;base64,current' })).toBe(true)
+ expect(scope.$attachments.get()[0]?.thumbnailUrl).toBe('data:image/png;base64,current')
+ })
+
+ it('recognizes the same attachment occurrence after a session-draft clone', () => {
+ const scope = createComposerAttachmentScope()
+
+ const original = attachment({
+ id: 'image:draft',
+ kind: 'image',
+ occurrenceId: createComposerAttachmentOccurrenceId(),
+ path: '/tmp/draft.png'
+ })
+
+ stashSessionDraft('session-a', '', [original])
+ const restored = takeSessionDraft('session-a').attachments[0]!
+ scope.add(restored)
+
+ expect(restored).not.toBe(original)
+ expect(scope.updateIfCurrent(original, { thumbnailUrl: 'data:image/png;base64,current' })).toBe(true)
+ expect(scope.$attachments.get()[0]?.thumbnailUrl).toBe('data:image/png;base64,current')
+ clearSessionDraft('session-a')
+ })
+
+ it('merges concurrent staging fields without discarding an existing thumbnail', () => {
+ const scope = createComposerAttachmentScope()
+
+ const original = attachment({
+ id: 'image:staging',
+ kind: 'image',
+ occurrenceId: createComposerAttachmentOccurrenceId(),
+ path: 'C:\\Users\\alice\\Pictures\\photo.png'
+ })
+
+ scope.add(original)
+ expect(scope.updateIfCurrent(original, { thumbnailUrl: 'data:image/png;base64,current' })).toBe(true)
+ expect(
+ scope.updateIfCurrent(original, {
+ attachedSessionId: 'session-1',
+ path: '/root/.hermes/attachments/photo.png',
+ uploadState: undefined
+ })
+ ).toBe(true)
+
+ expect(scope.$attachments.get()[0]).toMatchObject({
+ attachedSessionId: 'session-1',
+ path: '/root/.hermes/attachments/photo.png',
+ thumbnailUrl: 'data:image/png;base64,current'
+ })
+ })
+
+ it('removes submitted occurrences while preserving unrelated attachments', () => {
+ const scope = createComposerAttachmentScope()
+
+ const submitted = attachment({
+ id: 'image:submitted',
+ kind: 'image',
+ occurrenceId: 'occurrence-submitted'
+ })
+
+ const other = attachment({ id: 'file:other', occurrenceId: 'occurrence-other' })
+
+ scope.add(submitted)
+ scope.add(other)
+ scope.removeOccurrences([submitted])
+
+ expect(scope.$attachments.get()).toEqual([other])
+ })
+
+ it('preserves a same-id replacement of a submitted occurrence', () => {
+ const scope = createComposerAttachmentScope()
+
+ const submitted = attachment({
+ id: 'image:submitted',
+ kind: 'image',
+ occurrenceId: 'occurrence-submitted'
+ })
+
+ const replacement = attachment({
+ ...submitted,
+ occurrenceId: 'occurrence-replacement'
+ })
+
+ scope.add(replacement)
+ scope.removeOccurrences([submitted])
+
+ expect(scope.$attachments.get()).toEqual([replacement])
+ })
+
+ it('preserves a newer same-id legacy attachment and still emits on successful cleanup', () => {
+ const scope = createComposerAttachmentScope()
+ const submitted = attachment({ id: 'url:https://example.com', kind: 'url', label: 'old' })
+ const replacement = attachment({ id: submitted.id, kind: 'url', label: 'new' })
+ const listener = vi.fn()
+ const unlisten = scope.$attachments.listen(listener)
+
+ scope.add(submitted)
+ scope.remove(submitted.id)
+ scope.add(replacement)
+ listener.mockClear()
+
+ scope.removeOccurrences([submitted])
+
+ expect(scope.$attachments.get()).toEqual([replacement])
+ expect(listener).toHaveBeenCalledTimes(1)
+ unlisten()
+ })
+
+ it('removes the exact submitted legacy attachment', () => {
+ const scope = createComposerAttachmentScope()
+ const submitted = attachment({ id: 'url:https://example.com', kind: 'url' })
+
+ scope.add(submitted)
+ scope.removeOccurrences([submitted])
+
+ expect(scope.$attachments.get()).toEqual([])
+ })
})
describe('session drafts', () => {
diff --git a/apps/desktop/src/store/composer.ts b/apps/desktop/src/store/composer.ts
index 1b6847a537..81cb6e5129 100644
--- a/apps/desktop/src/store/composer.ts
+++ b/apps/desktop/src/store/composer.ts
@@ -5,11 +5,19 @@ import { triggerHaptic } from '@/lib/haptics'
export interface ComposerAttachment {
id: string
+ /** Renderer-lifetime identity for one attachment occurrence. Unlike `id`,
+ * which is content/path-derived, this survives draft cloning but changes
+ * when the user removes and re-adds the same attachment. */
+ occurrenceId?: string
kind: 'file' | 'folder' | 'image' | 'review' | 'terminal' | 'url'
label: string
detail?: string
refText?: string
+ /** Legacy/on-demand full source. New local image chips omit this and read
+ * `path` only when the lightbox opens, avoiding retained multi-MB base64. */
previewUrl?: string
+ /** Downscaled data URL for the attachment card and optimistic bubble only. */
+ thumbnailUrl?: string
path?: string
attachedSessionId?: string
/** Set while the file/image bytes are being staged into the session
@@ -18,6 +26,8 @@ export interface ComposerAttachment {
uploadState?: 'uploading' | 'error'
}
+export type ComposerAttachmentPatch = Partial>
+
export const $composerDraft = atom('')
export const $composerAttachments = atom([])
export const $composerTerminalSelections = atom>({})
@@ -27,6 +37,7 @@ export const $composerTerminalSelections = atom>({})
export const $voiceConversationStartRequest = atom(0)
let nextVoiceStartRequest = 0
let handledVoiceStartRequest = 0
+export const createComposerAttachmentOccurrenceId = (): string => crypto.randomUUID()
export const requestVoiceConversationStart = (): void => $voiceConversationStartRequest.set(++nextVoiceStartRequest)
@@ -53,8 +64,18 @@ export interface ComposerAttachmentScope {
add(attachment: ComposerAttachment): void
clear(): void
remove(id: string): ComposerAttachment | null
+ removeOccurrences(attachments: readonly ComposerAttachment[]): void
setUploadState(id: string, uploadState?: ComposerAttachment['uploadState']): void
update(attachment: ComposerAttachment): boolean
+ updateIfCurrent(expected: ComposerAttachment, patch: ComposerAttachmentPatch): boolean
+}
+
+function attachmentOccurrenceIndex(attachments: ComposerAttachment[], expected: ComposerAttachment): number {
+ return attachments.findIndex(item =>
+ expected.occurrenceId === undefined
+ ? item === expected
+ : item.id === expected.id && item.occurrenceId === expected.occurrenceId
+ )
}
export function createComposerAttachmentScope($attachments = atom([])): ComposerAttachmentScope {
@@ -79,6 +100,28 @@ export function createComposerAttachmentScope($attachments = atom attachment.occurrenceId !== undefined)
+ .map(attachment => `${attachment.id}\u0000${attachment.occurrenceId}`)
+ )
+
+ const submittedLegacy = new Set(attachments.filter(attachment => attachment.occurrenceId === undefined))
+
+ const next = current.filter(attachment =>
+ attachment.occurrenceId === undefined
+ ? !submittedLegacy.has(attachment)
+ : !submittedOccurrences.has(`${attachment.id}\u0000${attachment.occurrenceId}`)
+ )
+
+ // Preserve clear()'s notification semantics even when no captured
+ // occurrence remains. Some composer consumers settle local state on the
+ // successful-submit store emission.
+ $attachments.set(next)
+ },
setUploadState(id, uploadState) {
const current = $attachments.get()
const index = current.findIndex(attachment => attachment.id === id)
@@ -103,6 +146,20 @@ export function createComposerAttachmentScope($attachments = atom(loadPersistedDraftTexts())
+/**
+ * Patch one asynchronous attachment occurrence wherever the main composer owns
+ * it. During a session switch the occurrence moves from the live atom into the
+ * per-session in-memory draft stash; a preview may finish on either side of
+ * that handoff. Updating both stores is safe because occurrence ids are unique,
+ * and merging into the latest object preserves concurrent staging metadata.
+ */
+export function patchMainComposerAttachmentOccurrence(
+ expected: ComposerAttachment,
+ patch: ComposerAttachmentPatch
+): boolean {
+ let updated = mainComposerScope.updateIfCurrent(expected, patch)
+
+ for (const [key, draft] of draftsBySession) {
+ const index = attachmentOccurrenceIndex(draft.attachments, expected)
+
+ if (index < 0) {
+ continue
+ }
+
+ const attachments = [...draft.attachments]
+ attachments[index] = { ...attachments[index]!, ...patch }
+ draftsBySession.set(key, { ...draft, attachments })
+ updated = true
+ }
+
+ return updated
+}
+
/**
* What each unsent draft would be called, keyed the same way its text is.
*
diff --git a/apps/desktop/src/store/cron.test.ts b/apps/desktop/src/store/cron.test.ts
new file mode 100644
index 0000000000..2e69343548
--- /dev/null
+++ b/apps/desktop/src/store/cron.test.ts
@@ -0,0 +1,39 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { $cronJobs, beginCronJobsRequest, commitCronJobsRequest, setCronJobs, updateCronJobs } from './cron'
+
+const oldJob = { id: 'old' } as never
+const newJob = { id: 'new' } as never
+
+describe('cron jobs request fencing', () => {
+ beforeEach(() => {
+ setCronJobs([])
+ })
+
+ it('rejects an older refresh after a newer refresh commits', () => {
+ const older = beginCronJobsRequest('all')
+ const newer = beginCronJobsRequest('all')
+
+ expect(commitCronJobsRequest(newer, [newJob])).toBe(true)
+ expect(commitCronJobsRequest(older, [oldJob])).toBe(false)
+ expect($cronJobs.get()).toEqual([newJob])
+ })
+
+ it('rejects a refresh from the previous profile scope', () => {
+ const work = beginCronJobsRequest('work')
+
+ beginCronJobsRequest('personal')
+
+ expect(commitCronJobsRequest(work, [oldJob])).toBe(false)
+ expect($cronJobs.get()).toEqual([])
+ })
+
+ it('rejects an in-flight poll after a local mutation', () => {
+ const poll = beginCronJobsRequest('all')
+
+ updateCronJobs(() => [newJob])
+
+ expect(commitCronJobsRequest(poll, [oldJob])).toBe(false)
+ expect($cronJobs.get()).toEqual([newJob])
+ })
+})
diff --git a/apps/desktop/src/store/cron.ts b/apps/desktop/src/store/cron.ts
index f017f60dc1..b6df8cb0fc 100644
--- a/apps/desktop/src/store/cron.ts
+++ b/apps/desktop/src/store/cron.ts
@@ -6,11 +6,81 @@ import type { CronJob } from '@/types/hermes'
// the job — schedule, state, live next-run countdown — makes the job the
// first-class entity; its runs (sessions) resolve under it in the cron detail.
export const $cronJobs = atom([])
-export const setCronJobs = (jobs: CronJob[]) => $cronJobs.set(jobs)
+
+export interface CronJobsRequest {
+ generation: number
+ scope: string
+}
+
+export interface CronJobsScopeToken {
+ generation: number
+ scope: string
+}
+
+let cronJobsRequestGeneration = 0
+let cronJobsRequestScope = ''
+let cronJobsScopeGeneration = 0
+
+function activateCronJobsScope(scope: string): void {
+ if (scope === cronJobsRequestScope) {
+ return
+ }
+
+ cronJobsRequestScope = scope
+ cronJobsRequestGeneration += 1
+ cronJobsScopeGeneration += 1
+}
+
+export function beginCronJobsRequest(scope: string): CronJobsRequest {
+ activateCronJobsScope(scope)
+ cronJobsRequestGeneration += 1
+
+ return { generation: cronJobsRequestGeneration, scope }
+}
+
+export function beginCronJobsAction(scope: string): CronJobsScopeToken {
+ activateCronJobsScope(scope)
+
+ return { generation: cronJobsScopeGeneration, scope }
+}
+
+export function isCronJobsScopeCurrent(token: CronJobsScopeToken): boolean {
+ return token.scope === cronJobsRequestScope && token.generation === cronJobsScopeGeneration
+}
+
+export function isCronJobsRequestCurrent(request: CronJobsRequest): boolean {
+ return request.scope === cronJobsRequestScope && request.generation === cronJobsRequestGeneration
+}
+
+export function invalidateCronJobsRequests(): void {
+ cronJobsRequestGeneration += 1
+ cronJobsScopeGeneration += 1
+}
+
+export function commitCronJobsRequest(request: CronJobsRequest, jobs: CronJob[]): boolean {
+ if (!isCronJobsRequestCurrent(request)) {
+ return false
+ }
+
+ // Consume the token so neither a duplicate completion nor any older request
+ // can publish after this authoritative snapshot.
+ cronJobsRequestGeneration += 1
+ $cronJobs.set(jobs)
+
+ return true
+}
+
+export const setCronJobs = (jobs: CronJob[]) => {
+ cronJobsRequestGeneration += 1
+ $cronJobs.set(jobs)
+}
// In-place edit so the cron overlay's mutations (create/edit/delete/pause/…)
// land in the same atom the sidebar renders — no stale list until the next poll.
-export const updateCronJobs = (fn: (jobs: CronJob[]) => CronJob[]) => $cronJobs.set(fn($cronJobs.get()))
+export const updateCronJobs = (fn: (jobs: CronJob[]) => CronJob[]) => {
+ cronJobsRequestGeneration += 1
+ $cronJobs.set(fn($cronJobs.get()))
+}
// One-shot focus target: clicking "Manage" on a job sets this, then opens the
// cron overlay, which reads it once to select + scroll to that job. Cleared
diff --git a/apps/desktop/src/store/disable-f12.ts b/apps/desktop/src/store/disable-f12.ts
new file mode 100644
index 0000000000..5686cfc395
--- /dev/null
+++ b/apps/desktop/src/store/disable-f12.ts
@@ -0,0 +1,26 @@
+/**
+ * Disable F12 DevTools shortcut — a device-local preference.
+ *
+ * When enabled, F12 is blocked in the main process (before-input-event).
+ * Ctrl+Shift+I (or Cmd+Opt+I on Mac) still works regardless.
+ * Mirrors the toggle to the main process via IPC.
+ */
+
+import { atom } from 'nanostores'
+
+import { persistBoolean, storedBoolean } from '@/lib/storage'
+
+const KEY = 'hermes.desktop.disableF12.v1'
+
+export const $disableF12 = atom(typeof window === 'undefined' ? false : storedBoolean(KEY, false))
+
+export function setDisableF12(on: boolean): void {
+ $disableF12.set(on)
+}
+
+if (typeof window !== 'undefined') {
+ $disableF12.subscribe(on => {
+ persistBoolean(KEY, on)
+ window.hermesDesktop?.setDisableF12?.(on)
+ })
+}
diff --git a/apps/desktop/src/store/display-timestamps.ts b/apps/desktop/src/store/display-timestamps.ts
new file mode 100644
index 0000000000..75e30673f9
--- /dev/null
+++ b/apps/desktop/src/store/display-timestamps.ts
@@ -0,0 +1,20 @@
+/**
+ * `display.timestamps` — one config key for message timestamps everywhere.
+ *
+ * The same config.yaml key that puts [HH:MM] stamps on classic-CLI labels
+ * gates the desktop transcript's per-message / per-tool-run timeline
+ * timestamps (#41531, #65272, #68052). Off by default, matching the CLI
+ * default in hermes_cli/config_defaults.py.
+ *
+ * Display-only: reading or toggling it never mutates model context, so it is
+ * prompt-cache safe. Hover tooltips with the exact time (#70450) are NOT
+ * gated — they add no visual noise until the user asks for them.
+ */
+
+import { atom } from 'nanostores'
+
+export const $displayTimestamps = atom(false)
+
+export function setDisplayTimestampsFromConfig(value: unknown): void {
+ $displayTimestamps.set(value === true || value === 'true' || value === 1)
+}
diff --git a/apps/desktop/src/store/find-in-page.ts b/apps/desktop/src/store/find-in-page.ts
index 463209cf08..037d4daa30 100644
--- a/apps/desktop/src/store/find-in-page.ts
+++ b/apps/desktop/src/store/find-in-page.ts
@@ -1,5 +1,12 @@
import { atom } from 'nanostores'
+import {
+ captureFindScope,
+ currentFindScope,
+ performScopedFind,
+ releaseFindScope
+} from '@/lib/find-in-page-scope'
+
export interface FindInPageState {
active: boolean
query: string
@@ -11,61 +18,104 @@ const EMPTY: FindInPageState = { active: false, query: '', matchOrdinal: 0, matc
export const $findInPage = atom({ ...EMPTY })
+/**
+ * Open the find bar and capture the CURRENT VIEW as the search scope.
+ *
+ * Capturing once at open time (rather than re-resolving on every keystroke)
+ * means a mid-search route change can't silently re-home the highlights onto
+ * a different session — the FindBar's `useLocation` cleanup closes the bar
+ * before the route flips, so the scope the user actually sees in the input
+ * is the only one ever searched. See apps/desktop/src/components/find-bar.tsx
+ * for the route-change close logic; see lib/find-in-page-scope.ts for the
+ * "current view" predicate (#81726).
+ */
export function openFindBar(): void {
$findInPage.set({ ...EMPTY, active: true })
+ captureFindScope()
}
export function closeFindBar(): void {
- // Already closed: don't re-issue stopFindInPage. Escape is a shared gesture
- // (the switcher and dialogs claim it too), so a stray second close must not
- // reach into Electron again.
+ // Already closed: don't re-issue clear. Escape is a shared gesture (the
+ // switcher and dialogs claim it too), so a stray second close must not
+ // re-strip highlights from a bar that has already been torn down.
if (!$findInPage.get().active) {
return
}
$findInPage.set({ ...EMPTY })
- // Clears both the search and the native highlight/selection in the page.
- void window.hermesDesktop?.stopFindInPage()
+ // Strip highlights and the scope marker from the DOM we previously wrapped.
+ releaseFindScope()
}
-export function setFindQuery(query: string): void {
+export async function setFindQuery(query: string): Promise {
const prev = $findInPage.get()
// Never search for a closed bar. The component clears its debounce on
// close, but a timer that already fired (or any late caller) must not
- // re-issue a find and re-highlight the page after the user pressed Escape.
+ // re-wrap matches after the user pressed Escape.
if (!prev.active) {
return
}
if (!query) {
$findInPage.set({ ...prev, query: '', matchOrdinal: 0, matchCount: 0 })
- void window.hermesDesktop?.stopFindInPage()
+ const scope = currentFindScope()
+
+ if (scope) {
+ // Re-run the scoped walker with an empty query — same code path,
+ // strips highlights + zeroes the counter without special-casing.
+ performScopedFind(scope, '', { forward: true, findNext: false })
+ }
return
}
- $findInPage.set({ ...prev, query })
- void window.hermesDesktop?.findInPage(query, { forward: true, findNext: false })
+ const scope = currentFindScope()
+
+ if (!scope) {
+ // No chat surface to search (e.g. settings page, command center). The
+ // bar still accepts a query for parity with the bridge-driven path, but
+ // matches will be zero — there's nothing on screen that IS a "view".
+ $findInPage.set({ ...prev, query, matchOrdinal: 0, matchCount: 0 })
+
+ return
+ }
+
+ const result = performScopedFind(scope, query, { forward: true, findNext: false })
+
+ $findInPage.set({ ...prev, query, matchOrdinal: result.activeOrdinal, matchCount: result.count })
}
export function findNext(): void {
- const { query } = $findInPage.get()
-
- if (query) {
- void window.hermesDesktop?.findInPage(query, { forward: true, findNext: true })
- }
+ step(true)
}
export function findPrevious(): void {
- const { query } = $findInPage.get()
-
- if (query) {
- void window.hermesDesktop?.findInPage(query, { forward: false, findNext: true })
- }
+ step(false)
}
-/** Called by the preload bridge when `found-in-page` fires on webContents. */
+function step(forward: boolean): void {
+ const { query } = $findInPage.get()
+
+ if (!query) {
+ return
+ }
+
+ const scope = currentFindScope()
+
+ if (!scope) {
+ return
+ }
+
+ const result = performScopedFind(scope, query, { forward, findNext: true })
+
+ $findInPage.set({ ...$findInPage.get(), matchOrdinal: result.activeOrdinal, matchCount: result.count })
+}
+
+/** Called by the preload bridge when `found-in-page` fires on webContents.
+ * Retained for the multi-window case (a secondary session window still uses
+ * the Electron bridge — see electron/find-in-page.ts); the renderer-side
+ * walker for the primary window never fires this. */
export function updateFindResults(activeMatch: number, count: number): void {
const prev = $findInPage.get()
$findInPage.set({ ...prev, matchOrdinal: activeMatch, matchCount: count })
@@ -84,6 +134,10 @@ let detachListener: (() => void) | undefined
* Subscribe to `found-in-page` results. Returns a release fn; the underlying
* bridge listener is installed on the first subscriber and removed when the
* last one releases. Safe to call from an effect with a `[]` dep list.
+ *
+ * Kept for secondary-window renderers that still drive search via the
+ * Electron bridge. The primary window's renderer-side walker calls
+ * `updateFindResults` synchronously and never wires this listener.
*/
export function initFindInPageListener(): () => void {
listenerRefs += 1
@@ -128,3 +182,50 @@ export function resetFindInPageListenerForTest(): void {
detachListener = undefined
listenerRefs = 0
}
+
+// Same refcount pattern as `initFindInPageListener`, but for the
+// "main-process Ctrl/Cmd+F forwarded to renderer" channel. On Pop!_OS /
+// GNOME-based Linux distros the GTK compositor grabs Ctrl+F before the
+// renderer's keydown listener can fire — the main process intercepts the
+// chord via `before-input-event` and emits this IPC, so the renderer can
+// still open the FindBar (#81727).
+let openFindBarRefs = 0
+let detachOpenFindBar: (() => void) | undefined
+
+export function initOpenFindBarListener(): () => void {
+ openFindBarRefs += 1
+
+ if (openFindBarRefs === 1) {
+ detachOpenFindBar = window.hermesDesktop?.onOpenFindBarRequested?.(() => {
+ openFindBar()
+ })
+ }
+
+ let released = false
+
+ return () => {
+ if (released) {
+ return
+ }
+
+ released = true
+ openFindBarRefs -= 1
+
+ if (openFindBarRefs === 0) {
+ detachOpenFindBar?.()
+ detachOpenFindBar = undefined
+ }
+ }
+}
+
+/** Test seam: number of live "open find bar" subscriptions. */
+export function openFindBarListenerCount(): number {
+ return openFindBarRefs
+}
+
+/** Test seam: detach the open-find-bar bridge listener and zero the refcount. */
+export function resetOpenFindBarListenerForTest(): void {
+ detachOpenFindBar?.()
+ detachOpenFindBar = undefined
+ openFindBarRefs = 0
+}
diff --git a/apps/desktop/src/store/gateway-shared-remote.test.ts b/apps/desktop/src/store/gateway-shared-remote.test.ts
new file mode 100644
index 0000000000..7d3d33c501
--- /dev/null
+++ b/apps/desktop/src/store/gateway-shared-remote.test.ts
@@ -0,0 +1,141 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// The global-remote share (backend routing case 3): every profile is served
+// by the PRIMARY backend over one host, and getConnection() explicitly tags
+// the shared descriptor with `sharedPrimary`. Dialing a second WebSocket at it
+// used to fail over SSH (per-backend tunnel/ticket) and poison the active
+// gateway with a closed socket — "Hermes gateway is not connected" for every
+// profile except the primary. Pooled backends (own-remote override, local
+// named profile) also carry `profile` for WS URL minting, so `profile` alone
+// cannot identify the shared-primary route. These tests pin the fix: only a
+// `sharedPrimary` descriptor activates the primary socket; a pooled descriptor
+// that also carries `profile` must still dial its own socket.
+
+const gatewayMocks = vi.hoisted(() => ({
+ connect: vi.fn(async (_wsUrl: string): Promise => {
+ throw new Error('dialed a socket for a shared-primary profile')
+ }),
+ setConnection: vi.fn()
+}))
+
+vi.mock('@/hermes', () => ({
+ HermesGateway: class {
+ connectionState = 'closed'
+ connect = async (wsUrl: string): Promise => {
+ await gatewayMocks.connect(wsUrl)
+ this.connectionState = 'open'
+ }
+ close = vi.fn()
+ onEvent = vi.fn(() => () => {})
+ onState = vi.fn(() => () => {})
+ }
+}))
+vi.mock('@/store/session', () => ({
+ setConnection: gatewayMocks.setConnection,
+ setGatewayState: vi.fn()
+}))
+vi.mock('@/store/notify-baseline', () => ({ markNativeNotifyBaseline: vi.fn() }))
+
+const {
+ $gateway,
+ closeSecondaryGateways,
+ configureGatewayRegistry,
+ ensureActiveGatewayOpen,
+ ensureGatewayForProfile,
+ setPrimaryGateway
+} = await import('./gateway')
+
+type DesktopStub = { getConnection: ReturnType }
+
+function installDesktop(stub: DesktopStub): void {
+ ;(window as unknown as { hermesDesktop: unknown }).hermesDesktop = stub
+}
+
+function makePrimary(): { connectionState: string } {
+ // Only connectionState is consulted by setActive/isOpen for these paths.
+ return { connectionState: 'open' }
+}
+
+beforeEach(() => {
+ configureGatewayRegistry({
+ onEvent: vi.fn(),
+ primaryProfile: 'default'
+ } as never)
+})
+
+afterEach(() => {
+ closeSecondaryGateways()
+ vi.clearAllMocks()
+ delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
+})
+
+describe('ensureGatewayForProfile under a shared global remote', () => {
+ it('activates the primary socket for an explicitly shared-primary descriptor', async () => {
+ const primary = makePrimary()
+ setPrimaryGateway(primary as never, 'default')
+ installDesktop({
+ // Shared descriptor: primary connection tagged with the profile scope
+ // AND the explicit sharedPrimary marker.
+ getConnection: vi.fn(async () => ({ port: 4242, profile: 'venture', sharedPrimary: true, token: 't' }))
+ })
+
+ await ensureGatewayForProfile('venture')
+
+ expect(gatewayMocks.connect).not.toHaveBeenCalled()
+ expect($gateway.get()).toBe(primary)
+ })
+
+ it('dials the exact WebSocket URL for a pooled profile descriptor that carries profile', async () => {
+ const primary = makePrimary()
+ const remoteWsUrl = 'wss://remote.invalid/api/ws?token=fake-test-token'
+
+ setPrimaryGateway(primary as never, 'default')
+ installDesktop({
+ // Pooled descriptor: carries `profile` for WS URL minting but is NOT
+ // shared-primary (no marker) — it must dial its own socket, not reuse
+ // the primary. This is the local named / own-remote profile case.
+ getConnection: vi.fn(async () => ({
+ authMode: 'token',
+ baseUrl: 'https://remote.invalid',
+ mode: 'remote',
+ profile: 'worker',
+ token: 'fake-test-token',
+ wsUrl: remoteWsUrl
+ }))
+ })
+ gatewayMocks.connect.mockResolvedValueOnce(undefined)
+
+ await ensureGatewayForProfile('worker')
+
+ expect(gatewayMocks.connect).toHaveBeenCalledOnce()
+ expect(gatewayMocks.connect).toHaveBeenCalledWith(remoteWsUrl)
+ expect($gateway.get()).not.toBe(primary)
+ })
+
+ it('refreshes the active connection after a pooled profile reconnect succeeds', async () => {
+ const connection = {
+ authMode: 'token',
+ baseUrl: 'https://worker.invalid',
+ mode: 'remote',
+ profile: 'worker',
+ token: 'fake-test-token',
+ wsUrl: 'wss://worker.invalid/api/ws?token=fake-test-token'
+ }
+
+ const getConnection = vi.fn(async () => connection)
+
+ setPrimaryGateway(makePrimary() as never, 'default')
+ installDesktop({ getConnection })
+
+ gatewayMocks.connect.mockRejectedValueOnce(new Error('temporarily offline')).mockResolvedValueOnce(undefined)
+
+ await ensureGatewayForProfile('worker')
+
+ expect(gatewayMocks.setConnection).not.toHaveBeenCalled()
+
+ await ensureActiveGatewayOpen()
+
+ expect(gatewayMocks.setConnection).toHaveBeenCalledOnce()
+ expect(gatewayMocks.setConnection).toHaveBeenCalledWith(connection)
+ })
+})
diff --git a/apps/desktop/src/store/gateway-switch.ts b/apps/desktop/src/store/gateway-switch.ts
index 0338f06bc4..3003be4b32 100644
--- a/apps/desktop/src/store/gateway-switch.ts
+++ b/apps/desktop/src/store/gateway-switch.ts
@@ -58,7 +58,11 @@ export function wipeSessionListsForGatewaySwitch(): void {
setMessagingTruncated(false)
// Clearing $sessionStates automatically clears $workingSessionIds and
// $attentionSessionIds (computed) and $stalledSessionIds (owned beside it).
- // $unreadFinishedSessionIds is separate, so wipe it explicitly.
+ // $unreadFinishedSessionIds is separate, so wipe it explicitly. Only the
+ // transient paint layer is wiped: the persisted markers/watermarks in
+ // session-unread.ts are keyed by durable session id and repaint the rows
+ // that are still unread once the next gateway's lists load — so a profile
+ // round-trip doesn't swallow green dots.
clearAllSessionStates()
resetLiveRuntimeTracking()
resetLiveSync()
diff --git a/apps/desktop/src/store/gateway.ts b/apps/desktop/src/store/gateway.ts
index 149235e42f..8e73a1bfbf 100644
--- a/apps/desktop/src/store/gateway.ts
+++ b/apps/desktop/src/store/gateway.ts
@@ -4,7 +4,7 @@ import { atom } from 'nanostores'
import { HermesGateway } from '@/hermes'
import { reconnectBackoffDelayMs } from '@/lib/reconnect-backoff'
import { markNativeNotifyBaseline } from '@/store/notify-baseline'
-import { setGatewayState } from '@/store/session'
+import { setConnection, setGatewayState } from '@/store/session'
// ── Multi-profile gateway routing ──────────────────────────────────────────
// Concurrent sessions across profiles need concurrent sockets: the renderer's
@@ -177,6 +177,11 @@ async function openSecondary(entry: Secondary): Promise {
const conn = await desktop.getConnection(entry.profile)
const wsUrl = await resolveGatewayWsUrl(desktop, conn)
await entry.gateway.connect(wsUrl)
+
+ if (g.activeKey === entry.profile) {
+ setConnection(conn)
+ }
+
void desktop.touchBackend?.(entry.profile).catch(() => undefined)
}
@@ -247,6 +252,31 @@ function createSecondary(profile: string): Secondary {
return entry
}
+// True when `profile`'s backend route resolves to the SHARED primary backend
+// (global-remote case 3 in resolveProfileBackendRoute). Both shared-primary and
+// pooled descriptors carry `profile` so WebSocket URL minting targets the right
+// profile. `sharedPrimary` is the explicit discriminator; treating every tagged
+// descriptor as shared strands local/own-remote pooled profiles on the default
+// socket. Dialing a second socket at the shared descriptor is wrong — over SSH
+// the second dial fails (tunnel/token are per-backend) and the closed socket
+// poisons the active gateway with "not connected" even though the primary is
+// open right next to it.
+async function sharedPrimaryRoute(profile: string): Promise {
+ const desktop = window.hermesDesktop
+
+ if (!desktop) {
+ return false
+ }
+
+ try {
+ const conn = await desktop.getConnection(profile)
+
+ return Boolean(conn && typeof conn === 'object' && (conn as { sharedPrimary?: boolean }).sharedPrimary === true)
+ } catch {
+ return false
+ }
+}
+
// Open `profile`'s socket WITHOUT making it active — the hover-intent pre-warm
// (store/profile). Runs the same spawn + connect chain as a real switch, so by
// click time ensureGatewayForProfile finds an open socket and just activates
@@ -260,6 +290,11 @@ export async function openGatewayForProfile(profile: string): Promise {
return
}
+ if (await sharedPrimaryRoute(key)) {
+ // Served by the primary backend — there is no per-profile socket to warm.
+ return
+ }
+
const entry = g.secondaries.get(key) ?? createSecondary(key)
entry.wantOpen = true
@@ -279,6 +314,17 @@ export async function ensureGatewayForProfile(profile: string): Promise {
return
}
+ // Global-remote share (routing case 3): one remote host serves every
+ // profile through the PRIMARY socket, scoped per request. Activate the
+ // primary instead of dialing a doomed duplicate socket at the same
+ // descriptor — $activeGatewayProfile still moves to `key`, so request
+ // scoping and profile-aware surfaces behave identically.
+ if (await sharedPrimaryRoute(key)) {
+ setActive(g.primaryProfile)
+
+ return
+ }
+
let entry = g.secondaries.get(key)
if (!entry) {
diff --git a/apps/desktop/src/store/prompts.test.ts b/apps/desktop/src/store/prompts.test.ts
index a761adf6f2..bbe2d2f2ca 100644
--- a/apps/desktop/src/store/prompts.test.ts
+++ b/apps/desktop/src/store/prompts.test.ts
@@ -10,6 +10,8 @@ import {
clearApprovalRequest,
clearSecretRequest,
clearSudoRequest,
+ receiveApprovalRequest,
+ replayPendingApproval,
setApprovalRequest,
setSecretRequest,
setSudoRequest
@@ -67,6 +69,66 @@ describe('approval prompt store', () => {
expect($approvalRequest.get()?.allowPermanent).toBe(false)
})
+
+ it('correlates clearing to the exact approval request id', () => {
+ setApprovalRequest({ command: 'x', description: 'd', requestId: 'r1', sessionId: 's1' })
+
+ clearApprovalRequest('s1', 'stale')
+ expect($approvalRequest.get()?.requestId).toBe('r1')
+ clearApprovalRequest('s1', 'r1')
+ expect($approvalRequest.get()).toBeNull()
+ })
+
+ it('acknowledges an approval only after parking it', async () => {
+ const calls: Array<[string, Record]> = []
+
+ const gateway = {
+ request: async (method: string, params: Record) => {
+ calls.push([method, params])
+
+ return { acknowledged: true }
+ }
+ }
+
+ await receiveApprovalRequest(gateway, {
+ command: 'x',
+ description: 'd',
+ requestId: 'r1',
+ sessionId: 's1'
+ })
+
+ expect($approvalRequest.get()?.requestId).toBe('r1')
+ expect(calls).toEqual([['approval.received', { request_id: 'r1', session_id: 's1' }]])
+ })
+
+ it('replays and acknowledges the oldest unresolved approval after reconnect', async () => {
+ const calls: Array<[string, Record]> = []
+
+ const gateway = {
+ request: async (method: string, params: Record) => {
+ calls.push([method, params])
+
+ if (method === 'approval.pending') {
+ return {
+ approvals: [
+ { command: 'first', description: 'd1', request_id: 'r1' },
+ { command: 'second', description: 'd2', request_id: 'r2' }
+ ]
+ }
+ }
+
+ return { acknowledged: true }
+ }
+ }
+
+ await replayPendingApproval(gateway, 's1')
+
+ expect($approvalRequest.get()?.requestId).toBe('r1')
+ expect(calls).toEqual([
+ ['approval.pending', { session_id: 's1' }],
+ ['approval.received', { request_id: 'r1', session_id: 's1' }]
+ ])
+ })
})
describe('sudo prompt store', () => {
@@ -144,7 +206,7 @@ describe('$activeSessionAwaitingInput', () => {
clearApprovalRequest('s1')
expect($activeSessionAwaitingInput.get()).toBe(false)
- setClarifyRequest({ choices: null, question: 'q', requestId: 'c1', sessionId: 's1' })
+ setClarifyRequest({ choices: null, multiSelect: false, question: 'q', requestId: 'c1', sessionId: 's1' })
expect($activeSessionAwaitingInput.get()).toBe(true)
})
diff --git a/apps/desktop/src/store/prompts.ts b/apps/desktop/src/store/prompts.ts
index 0efe97515a..da9c7dedb5 100644
--- a/apps/desktop/src/store/prompts.ts
+++ b/apps/desktop/src/store/prompts.ts
@@ -67,18 +67,32 @@ function keyedPromptStore(): PromptStore {
}
}
-// Approval is session-keyed on the backend (one in-flight approval per session,
-// resolved via approval.respond {choice, session_id}). It carries no request_id,
-// unlike sudo/secret which are _block()-style request/response.
+// Approval is session-keyed on the backend and correlated by `request_id` when
+// available (legacy ID-free responses remain FIFO-compatible). Resolved via
+// approval.respond {choice, request_id, session_id}.
export interface ApprovalRequest extends KeyedPrompt {
// false when the backend won't honor a permanent allow (tirith warning) → hide "Always allow".
allowPermanent?: boolean
choices?: string[]
command: string
description: string
+ requestId?: string
smartDenied?: boolean
}
+interface ApprovalGateway {
+ request: (method: string, params: Record) => Promise
+}
+
+interface PendingApprovalPayload {
+ allow_permanent?: boolean
+ choices?: unknown
+ command?: unknown
+ description?: unknown
+ request_id?: unknown
+ smart_denied?: boolean
+}
+
export interface SudoRequest extends KeyedPrompt {
requestId: string
}
@@ -101,6 +115,46 @@ export const $approvalRequest = approval.$active
export const setApprovalRequest = approval.set
export const clearApprovalRequest = approval.clear
+export async function receiveApprovalRequest(gateway: ApprovalGateway | null, request: ApprovalRequest): Promise {
+ setApprovalRequest(request)
+
+ if (gateway && request.requestId && request.sessionId) {
+ await gateway.request('approval.received', {
+ request_id: request.requestId,
+ session_id: request.sessionId
+ })
+ }
+}
+
+export async function replayPendingApproval(gateway: ApprovalGateway | null, sessionId: string | null): Promise {
+ if (!gateway || !sessionId) {
+ return
+ }
+
+ const rawResult = await gateway.request('approval.pending', {
+ session_id: sessionId
+ })
+
+ const result =
+ rawResult && typeof rawResult === 'object' ? (rawResult as { approvals?: PendingApprovalPayload[] }) : {}
+
+ const pending = Array.isArray(result?.approvals) ? result.approvals[0] : undefined
+
+ if (!pending || typeof pending.request_id !== 'string') {
+ return
+ }
+
+ await receiveApprovalRequest(gateway, {
+ allowPermanent: pending.allow_permanent !== false,
+ choices: Array.isArray(pending.choices) ? pending.choices.filter(choice => typeof choice === 'string') : undefined,
+ command: typeof pending.command === 'string' ? pending.command : '',
+ description: typeof pending.description === 'string' ? pending.description : 'dangerous command',
+ requestId: pending.request_id,
+ sessionId,
+ smartDenied: pending.smart_denied === true
+ })
+}
+
/** The prompt request for one specific session — the tile counterpart of the
* active-session `$*Request` views (same map, fixed key). */
export const sessionApprovalRequest = (sessionId: string | null) =>
diff --git a/apps/desktop/src/store/reasoning-disclosure.ts b/apps/desktop/src/store/reasoning-disclosure.ts
new file mode 100644
index 0000000000..584c00a57a
--- /dev/null
+++ b/apps/desktop/src/store/reasoning-disclosure.ts
@@ -0,0 +1,14 @@
+import { atom } from 'nanostores'
+
+import { persistBoolean, storedBoolean } from '@/lib/storage'
+
+const REASONING_COLLAPSED_BY_DEFAULT_STORAGE_KEY = 'hermes.desktop.reasoning.collapsedByDefault'
+
+/** Desktop-local presentation preference; shared backend config must not be changed by a single window. */
+export const $reasoningCollapsedByDefault = atom(storedBoolean(REASONING_COLLAPSED_BY_DEFAULT_STORAGE_KEY, false))
+
+$reasoningCollapsedByDefault.subscribe(value => persistBoolean(REASONING_COLLAPSED_BY_DEFAULT_STORAGE_KEY, value))
+
+export function setReasoningCollapsedByDefault(value: boolean) {
+ $reasoningCollapsedByDefault.set(value)
+}
diff --git a/apps/desktop/src/store/session-dot-state.test.ts b/apps/desktop/src/store/session-dot-state.test.ts
index 5e81c3201b..1661c3ba09 100644
--- a/apps/desktop/src/store/session-dot-state.test.ts
+++ b/apps/desktop/src/store/session-dot-state.test.ts
@@ -1,6 +1,13 @@
-import { describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { hasLiveTurn, showsRunningArc } from './session-dot-state'
+import { createClientSessionState } from '@/lib/chat-runtime'
+import type { SessionInfo } from '@/types/hermes'
+
+import { $sessions, $unreadFinishedSessionIds, setSessions } from './session'
+import { $delegatingSessionIds, $sessionDotStateById, hasLiveTurn, showsRunningArc } from './session-dot-state'
+import { clearAllSessionStates, publishSessionState } from './session-states'
+import { $unreadWriteGuard } from './session-unread-remote'
+import { $subagentsBySession, type SubagentProgress } from './subagents'
describe('showsRunningArc', () => {
it('keeps the arc when an authoritative turn goes quiet', () => {
@@ -35,3 +42,109 @@ describe('hasLiveTurn', () => {
expect(hasLiveTurn('unread')).toBe(false)
})
})
+
+describe('$delegatingSessionIds', () => {
+ const subagent = (status: SubagentProgress['status']): SubagentProgress => ({
+ id: 'sub-1',
+ parentId: null,
+ goal: 'do a thing',
+ status,
+ taskCount: 1,
+ taskIndex: 0,
+ startedAt: 0,
+ updatedAt: 0,
+ filesRead: [],
+ filesWritten: [],
+ stream: []
+ })
+
+ afterEach(() => {
+ clearAllSessionStates()
+ $subagentsBySession.set({})
+ $sessions.set([])
+ })
+
+ it('claims the stored id while a subagent is running after the parent turn ended', () => {
+ publishSessionState('runtime-1', { ...createClientSessionState('stored-1'), busy: false })
+ $subagentsBySession.set({ 'runtime-1': [subagent('running')] })
+
+ expect($delegatingSessionIds.get()).toContain('stored-1')
+ })
+
+ it('drops the session once every subagent reaches a terminal status', () => {
+ publishSessionState('runtime-1', { ...createClientSessionState('stored-1'), busy: false })
+ $subagentsBySession.set({ 'runtime-1': [subagent('running')] })
+ $subagentsBySession.set({ 'runtime-1': [subagent('completed')] })
+
+ expect($delegatingSessionIds.get()).not.toContain('stored-1')
+ })
+
+ it('falls back to the runtime id for a not-yet-persisted conversation', () => {
+ $subagentsBySession.set({ 'runtime-fresh': [subagent('queued')] })
+
+ expect($delegatingSessionIds.get()).toContain('runtime-fresh')
+ })
+})
+
+const storedRow = (id: string, extra: Partial = {}): SessionInfo =>
+ ({ id, message_count: 1, source: 'cli', started_at: 0, title: id, ...extra }) as SessionInfo
+
+describe('persisted unread (backend watermark)', () => {
+ beforeEach(() => {
+ clearAllSessionStates()
+ $sessions.set([])
+ $unreadFinishedSessionIds.set([])
+ $unreadWriteGuard.set(new Map())
+ })
+
+ afterEach(() => {
+ clearAllSessionStates()
+ $sessions.set([])
+ $unreadFinishedSessionIds.set([])
+ $unreadWriteGuard.set(new Map())
+ })
+
+ it('claims unread for a session whose row carries unread: true', () => {
+ setSessions([storedRow('s1', { unread: true })])
+
+ expect($sessionDotStateById.get()['s1']).toBe('unread')
+ })
+
+ it('keeps draft weaker than persisted unread', () => {
+ // A blank tile (no busy, no messages, message_count 0) is a draft; the
+ // persisted unread claim must speak over it.
+ setSessions([storedRow('s1', { message_count: 0, unread: true })])
+ publishSessionState('rt1', createClientSessionState('s1'))
+
+ expect($sessionDotStateById.get()['s1']).toBe('unread')
+ })
+
+ it('lets working outrank persisted unread', () => {
+ setSessions([storedRow('s1', { unread: true })])
+ publishSessionState('rt1', { ...createClientSessionState('s1'), busy: true })
+
+ expect($sessionDotStateById.get()['s1']).toBe('working')
+ })
+
+ it('fences a stale page with the write guard', () => {
+ const guard = new Map()
+ guard.set('s1', { at: Date.now(), value: true })
+ $unreadWriteGuard.set(guard)
+
+ // A page issued before our PATCH still says read — keep OUR value.
+ setSessions([storedRow('s1', { unread: false })])
+ expect($sessionDotStateById.get()['s1']).toBe('unread')
+
+ // The guard expires: the page wins and the dot drops.
+ const expired = new Map()
+ expired.set('s1', { at: Date.now() - 60_000, value: true })
+ $unreadWriteGuard.set(expired)
+ expect($sessionDotStateById.get()['s1']).not.toBe('unread')
+ })
+
+ it('leaves a row alone when the backend omits the flag (older runtime)', () => {
+ setSessions([storedRow('s1')])
+
+ expect($sessionDotStateById.get()['s1'] ?? 'idle').not.toBe('unread')
+ })
+})
diff --git a/apps/desktop/src/store/session-dot-state.ts b/apps/desktop/src/store/session-dot-state.ts
index bf94a1658e..f6f30169ff 100644
--- a/apps/desktop/src/store/session-dot-state.ts
+++ b/apps/desktop/src/store/session-dot-state.ts
@@ -15,15 +15,57 @@
*
* The inputs are all reference-stable across stream deltas, so this recomputes
* on status edges rather than per token.
+ *
+ * Unread has TWO sources, both claiming the same state: the runtime marker
+ * (a turn finished in the background while this window wasn't looking at it,
+ * $unreadFinishedSessionIds — transient) and the backend's derived read-state
+ * watermark (row.unread — persists across restarts and is visible to every
+ * surface). The write side of the persisted flag lives in session-unread.ts.
*/
import { computed } from 'nanostores'
-import { stableRecord } from '@/lib/stable-array'
+import { stableArray, stableRecord } from '@/lib/stable-array'
import { $backgroundRunningSessionIds } from './composer-status'
import { $sessions, $unreadFinishedSessionIds, lineageAliases } from './session'
-import { $attentionSessionIds, $draftSessionIds, $stalledSessionIds, $workingSessionIds } from './session-states'
+import {
+ $attentionSessionIds,
+ $draftSessionIds,
+ $sessionStates,
+ $stalledSessionIds,
+ $workingSessionIds
+} from './session-states'
+import { $unreadWriteGuard, UNREAD_WRITE_GUARD_MS } from './session-unread-remote'
+import { $subagentsBySession, activeSubagentCount } from './subagents'
+
+// Sessions parked in async delegation: the parent turn has ended (busy=false —
+// delegate_task(background=true) returns its handle the moment the children
+// are spawned) while those subagents keep working for minutes. Without this
+// input the sidebar row dropped to a plain idle dot mid-delegation, reading as
+// "done" while work was still running in child sessions. Same runtime→stored
+// bridge and fresh-chat fallback as $backgroundRunningSessionIds:
+// $subagentsBySession is keyed by runtime id, surfaces key on stored ids, and
+// lineageAliases covers whichever tip of the conversation a surface holds.
+let delegatingIds: readonly string[] = []
+export const $delegatingSessionIds = computed(
+ [$subagentsBySession, $sessionStates, $sessions],
+ (bySession, states, sessions) => {
+ const ids = new Set()
+
+ for (const [runtimeId, items] of Object.entries(bySession)) {
+ if (activeSubagentCount(items) === 0) {
+ continue
+ }
+
+ for (const alias of lineageAliases(states[runtimeId]?.storedSessionId ?? runtimeId, sessions)) {
+ ids.add(alias)
+ }
+ }
+
+ return (delegatingIds = stableArray(delegatingIds, [...ids]))
+ }
+)
export type SessionDotState = 'background' | 'draft' | 'idle' | 'needs-input' | 'stalled' | 'unread' | 'working'
@@ -63,11 +105,13 @@ export const $sessionDotStateById = computed(
$workingSessionIds,
$stalledSessionIds,
$backgroundRunningSessionIds,
+ $delegatingSessionIds,
$unreadFinishedSessionIds,
$draftSessionIds,
- $sessions
+ $sessions,
+ $unreadWriteGuard
],
- (attention, working, stalled, background, unread, draft, sessions) => {
+ (attention, working, stalled, background, delegating, unread, draft, sessions, unreadWriteGuard) => {
const next: Record = {}
const claim = (ids: readonly string[], state: SessionDotState) => {
@@ -86,7 +130,39 @@ export const $sessionDotStateById = computed(
// the first thing that does happen speaks over it.
claim(draft, 'draft')
claim(unread, 'unread')
+
+ // Persisted read state (backend watermark): a row marked unread keeps the
+ // same emerald dot a background finish would paint, and survives
+ // restarts. Same tier as the runtime marker — both mean "there is
+ // something here you haven't opened". A list page that predates one of
+ // our own writes is fenced out by the write guard: keep OUR value until a
+ // page confirms it or the guard expires.
+ const persistedUnread: string[] = []
+
+ for (const s of sessions) {
+ const entry = unreadWriteGuard.get(s.id)
+
+ if (entry && Date.now() - entry.at < UNREAD_WRITE_GUARD_MS) {
+ if (entry.value) {
+ persistedUnread.push(s.id)
+ }
+
+ continue
+ }
+
+ if (s.unread === true) {
+ persistedUnread.push(s.id)
+ }
+ }
+
+ claim(persistedUnread, 'unread')
+
claim(background, 'background')
+ // Async delegation: the parent turn has ended but its subagents are still
+ // running, so the session's work continues in child sessions. Same visual
+ // claim as background processes — and it yields to `working` below the
+ // moment the parent turn itself is live (synchronous orchestrator children).
+ claim(delegating, 'background')
claim(working, 'working')
// Stalled REFINES working rather than rivalling it — the turn is still
diff --git a/apps/desktop/src/store/session-list-density.test.ts b/apps/desktop/src/store/session-list-density.test.ts
new file mode 100644
index 0000000000..bde020789a
--- /dev/null
+++ b/apps/desktop/src/store/session-list-density.test.ts
@@ -0,0 +1,30 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const loadStore = async () => {
+ vi.resetModules()
+
+ return import('./session-list-density')
+}
+
+describe('session list density preference', () => {
+ beforeEach(() => {
+ window.localStorage.clear()
+ })
+
+ it('defaults to compact (pre-density behavior) and persists changes', async () => {
+ const first = await loadStore()
+
+ expect(first.$sessionListDensity.get()).toBe('compact')
+
+ first.setSessionListDensity('detailed')
+
+ expect(window.localStorage.getItem('hermes.desktop.sessionListDensity')).toBe('detailed')
+ expect((await loadStore()).$sessionListDensity.get()).toBe('detailed')
+ })
+
+ it('falls back to compact for an unknown stored value', async () => {
+ window.localStorage.setItem('hermes.desktop.sessionListDensity', 'tiny')
+
+ expect((await loadStore()).$sessionListDensity.get()).toBe('compact')
+ })
+})
diff --git a/apps/desktop/src/store/session-list-density.ts b/apps/desktop/src/store/session-list-density.ts
new file mode 100644
index 0000000000..a2d0b355a4
--- /dev/null
+++ b/apps/desktop/src/store/session-list-density.ts
@@ -0,0 +1,18 @@
+import { type Codec, persistentAtom } from '@/lib/persisted'
+
+export type SessionListDensity = 'compact' | 'comfortable' | 'detailed'
+
+const STORAGE_KEY = 'hermes.desktop.sessionListDensity'
+
+// Compact is the pre-density row exactly as it shipped, so existing users see
+// no change until they opt into a denser-information mode themselves (#68119).
+const densityCodec: Codec = {
+ decode: raw => (raw === 'comfortable' || raw === 'detailed' ? raw : 'compact'),
+ encode: value => value
+}
+
+export const $sessionListDensity = persistentAtom(STORAGE_KEY, 'compact', densityCodec)
+
+export function setSessionListDensity(density: SessionListDensity) {
+ $sessionListDensity.set(density)
+}
diff --git a/apps/desktop/src/store/session-states-eviction.test.ts b/apps/desktop/src/store/session-states-eviction.test.ts
index 8958df05ee..b82aa79756 100644
--- a/apps/desktop/src/store/session-states-eviction.test.ts
+++ b/apps/desktop/src/store/session-states-eviction.test.ts
@@ -8,8 +8,8 @@ import { $sessionStates, $sessionTiles, closeSessionTile, publishSessionState }
* The closed-tile leak: gateway events keep publishing for sessions whose
* surface is gone, and every parked transcript taxes every later publish (map
* spread + the status projections run per entry per message delta). A settled
- * state nothing references must leave the map; everything a surface still
- * needs must stay.
+ * state nothing references must release its transcript; lightweight status
+ * stays so sidebar projections remain available.
*/
const state = (storedId: string, patch: Partial> = {}) => ({
@@ -28,13 +28,14 @@ beforeEach(() => {
})
describe('publish-time eviction', () => {
- it('evicts a settling session no surface references, keeping its unread dot', () => {
+ it('releases an unreferenced settled transcript while keeping status and its unread dot', () => {
publishSessionState('rt-1', state('stored-1', { busy: true }))
expect($sessionStates.get()['rt-1']).toBeDefined()
publishSessionState('rt-1', state('stored-1', { busy: false }))
- expect($sessionStates.get()['rt-1']).toBeUndefined()
+ expect($sessionStates.get()['rt-1']?.messages).toEqual([])
+ expect($sessionStates.get()['rt-1']).toMatchObject({ storedSessionId: 'stored-1', busy: false })
// The settle transition still fired: the sidebar's unread marker landed.
expect($unreadFinishedSessionIds.get()).toContain('stored-1')
})
@@ -100,8 +101,9 @@ describe('closeSessionTile eviction', () => {
expect($sessionStates.get()['rt-1']).toBeDefined()
- // ... and its settle publish is what evicts it.
+ // ... and its settle publish releases only the heavy transcript.
publishSessionState('rt-1', state('stored-1', { busy: false }))
- expect($sessionStates.get()['rt-1']).toBeUndefined()
+ expect($sessionStates.get()['rt-1']?.messages).toEqual([])
+ expect($sessionStates.get()['rt-1']).toMatchObject({ storedSessionId: 'stored-1', busy: false })
})
})
diff --git a/apps/desktop/src/store/session-states.test.ts b/apps/desktop/src/store/session-states.test.ts
index 3bff4ba520..0abc89bfd5 100644
--- a/apps/desktop/src/store/session-states.test.ts
+++ b/apps/desktop/src/store/session-states.test.ts
@@ -6,16 +6,39 @@ import { $layoutTree } from '@/components/pane-shell/tree/store'
import { $selectedStoredSessionId } from '@/store/session'
import type { SessionTile } from '@/store/session-states'
import {
+ $sessionStates,
blankDraftTile,
focusedSessionNeedsRoute,
markSelectionRestore,
orderTilesByTree,
+ releaseSessionTranscript,
selectionHomesToWorkspace
} from '@/store/session-states'
const tile = (storedSessionId: string): SessionTile => ({ storedSessionId })
const tilePane = (id: string) => `session-tile:${id}`
+describe('releaseSessionTranscript', () => {
+ afterEach(() => {
+ $sessionStates.set({})
+ })
+
+ it('normalizes legacy state whose messages field is undefined', () => {
+ const legacy = { busy: false, storedSessionId: 'stored' } as ClientSessionState
+ $sessionStates.set({ runtime: legacy })
+
+ expect(() => releaseSessionTranscript('runtime')).not.toThrow()
+ expect($sessionStates.get().runtime).toEqual({ ...legacy, messages: [] })
+ })
+
+ it('ignores a legacy undefined state without throwing', () => {
+ $sessionStates.set({ runtime: undefined } as unknown as Record)
+
+ expect(() => releaseSessionTranscript('runtime')).not.toThrow()
+ expect($sessionStates.get()).toHaveProperty('runtime', undefined)
+ })
+})
+
describe('orderTilesByTree', () => {
it('no-ops (null) without a tree or below two tiles', () => {
expect(orderTilesByTree(null, [tile('a'), tile('b')])).toBeNull()
diff --git a/apps/desktop/src/store/session-states.ts b/apps/desktop/src/store/session-states.ts
index 1064b90d7a..108b8d761e 100644
--- a/apps/desktop/src/store/session-states.ts
+++ b/apps/desktop/src/store/session-states.ts
@@ -35,14 +35,17 @@ import type { SessionInfo } from '@/types/hermes'
import { $activeGatewayProfile, normalizeProfileKey } from './profile'
import {
$activeSessionId,
+ $lastReadAtBySessionId,
$selectedStoredSessionId,
$sessions,
- $unreadFinishedSessionIds,
+ clearReadBaseline,
lineageAliases,
+ markSessionRead,
sessionMatchesStoredId,
setActiveSessionStoredIdRotation,
setSessions
} from './session'
+import { ackStoredSessionId, markSessionUnreadFinished } from './session-unread'
import { isSecondaryWindow } from './windows'
// ---------------------------------------------------------------------------
@@ -179,14 +182,27 @@ function handleTransition(previous: ClientSessionState | null, next: ClientSessi
if (next.busy && !wasWorking) {
clearSettled(storedId)
+ // A NEW turn is starting: the read baseline guarded the PREVIOUS
+ // completion's re-asserts. Dropping it here means this turn's finish
+ // re-lights even if it lands within the same millisecond as the last
+ // read (same-tick submit → finish in tests and fast local models).
+ clearReadBaseline(storedId)
} else if (!next.busy && wasWorking) {
markSettled(storedId)
- if (storedId !== $selectedStoredSessionId.get()) {
- const cur = $unreadFinishedSessionIds.get()
+ // FOCUSED, not selected: a session finishing in the tile the user is
+ // watching is already seen, and a tile is never the primary selection.
+ if (storedId !== $focusedStoredSessionId.get()) {
+ // Re-light only genuinely new completions: if the user already viewed
+ // this session (or its family) at or after this settle moment, a
+ // re-assert of the same completion must not re-arm the dot. `-1` for
+ // "never read" (not `0`) so fake-timer tests pinned to t=0 still light.
+ const lastReadAt = $lastReadAtBySessionId.get()[storedId] ?? -1
- if (!cur.includes(storedId)) {
- $unreadFinishedSessionIds.set([...cur, storedId])
+ if (Date.now() > lastReadAt) {
+ // Flags the transient atom AND persists a marker, so the green dot
+ // survives an app restart (see session-unread.ts).
+ markSessionUnreadFinished(storedId)
}
}
}
@@ -228,15 +244,13 @@ function evictable(runtimeId: string, state: ClientSessionState): boolean {
* is updated independently by the caller, so the visual path stays live
* without the store churn.
*
- * A settled state nothing references is EVICTED instead of republished:
- * gateway events keep flowing for sessions whose tile was closed mid-turn,
- * and parking each one's full transcript here forever is the leak that made
- * the app crawl after a day of tile use — every entry taxes every later
- * publish (map spread + the status-set projections). Transition side effects
- * still fire, so the closed session's settle keeps its unread dot. Only an
- * entry already in the map is evicted — a FIRST publish always lands, because
- * a resume can publish its idle state a beat before `$activeSessionId` /
- * the tile's runtime binding points at it. */
+ * A settled state nothing references releases its transcript instead of
+ * republishing it. Gateway events keep flowing for sessions whose tile was
+ * closed mid-turn, and parking each one's full transcript here forever is the
+ * leak that made the app crawl after a day of tile use. Transition side
+ * effects still fire, so lightweight status and the unread dot survive. A
+ * FIRST publish always lands in full because a resume can publish its idle
+ * state a beat before `$activeSessionId` / the tile binding points at it. */
export function publishSessionState(runtimeId: string, state: ClientSessionState) {
const current = $sessionStates.get()
const prev = current[runtimeId] ?? null
@@ -247,8 +261,7 @@ export function publishSessionState(runtimeId: string, state: ClientSessionState
if (prev && evictable(runtimeId, state)) {
handleTransition(prev, state, runtimeId)
- const { [runtimeId]: _dropped, ...rest } = current
- $sessionStates.set(rest)
+ releaseSessionTranscript(runtimeId, state)
return
}
@@ -257,6 +270,30 @@ export function publishSessionState(runtimeId: string, state: ClientSessionState
handleTransition(prev, state, runtimeId)
}
+/** Keep the cheap status projection for a cold session while releasing its
+ * transcript. Unread completion is stored separately, so it survives too. */
+export function releaseSessionTranscript(runtimeId: string, state?: ClientSessionState) {
+ const current = $sessionStates.get()
+
+ if (!(runtimeId in current)) {
+ return
+ }
+
+ const retained = state ?? current[runtimeId]
+
+ // Older persisted snapshots can contain an undefined state or omit the
+ // messages field. Treat either shape as already cold instead of throwing
+ // while memory pressure is being relieved.
+ if (!retained) {
+ return
+ }
+
+ const lightweight =
+ Array.isArray(retained.messages) && retained.messages.length === 0 ? retained : { ...retained, messages: [] }
+
+ $sessionStates.set({ ...current, [runtimeId]: lightweight })
+}
+
export function dropSessionState(runtimeId: string) {
// Disarm the watchdog — a dropped runtime must not fire a stale clear later.
// Settle-grace entries are keyed by stored id and self-expire; leave them so
@@ -644,6 +681,14 @@ export function openSessionTile(
) {
const tiles = $sessionTiles.get()
+ // Opening a session in a tab/tile is "reading" it — clear its unread dot
+ // exactly like main-thread resume does. Previously only
+ // setSelectedStoredSessionId cleared unread, so tile-opened sessions kept
+ // their green dot even while the user was reading them. Acks the persisted
+ // watermark/marker too so a later list refresh doesn't repaint it.
+ markSessionRead(storedSessionId)
+ ackStoredSessionId(storedSessionId)
+
if (storedSessionId === $selectedStoredSessionId.get()) {
return
}
@@ -891,6 +936,20 @@ export const $focusedSessionState = computed([$focusedRuntimeId, $sessionStates]
export const selectionHomesToWorkspace = (selected: null | string, tiles: readonly SessionTile[]): boolean =>
!(selected && tiles.some(t => t.storedSessionId === selected))
+// Bringing a finished session to the front clears its green dot. Keyed on the
+// FOCUSED session, not the selected one: a tile is never $selectedStoredSessionId,
+// and a tile tab click goes through activateTreePane rather than focusOpenSession,
+// so this is the one hook that catches every way a tile reaches the front.
+// Clears the whole conversation family (markSessionRead) AND acks the
+// persisted watermark/marker (ackStoredSessionId) so the next list refresh
+// doesn't repaint the dot the user just cleared by looking at it.
+$focusedStoredSessionId.listen(focused => {
+ if (focused) {
+ markSessionRead(focused)
+ ackStoredSessionId(focused)
+ }
+})
+
// Cold-start restore is the one selection change that is NOT a navigation: the
// route already pointed at the primary session before the window loaded, and
// homing on it would front the workspace tab over the PERSISTED active tab —
diff --git a/apps/desktop/src/store/session-unread-remote.test.ts b/apps/desktop/src/store/session-unread-remote.test.ts
new file mode 100644
index 0000000000..1cbc967baa
--- /dev/null
+++ b/apps/desktop/src/store/session-unread-remote.test.ts
@@ -0,0 +1,113 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { SessionInfo } from '@/types/hermes'
+
+const patch = vi.fn<(id: string, unread: boolean, profile?: null | string) => Promise<{ ok: boolean }>>(() =>
+ Promise.resolve({ ok: true })
+)
+
+vi.mock('@/hermes', () => ({
+ // The store only needs the REST mutation; keep the mock minimal.
+ setApiRequestProfile: () => {},
+ setSessionUnreadRemote: (id: string, unread: boolean, profile?: null | string) => patch(id, unread, profile)
+}))
+
+import { $sessions } from '@/store/session'
+
+import { $unreadWriteGuard, clearUnreadOnOpen, markSessionUnread, watchUnreadWriteGuard } from './session-unread-remote'
+
+const row = (id: string, extra: Partial = {}): SessionInfo =>
+ ({ id, message_count: 1, source: 'cli', started_at: 0, title: id, ...extra }) as SessionInfo
+
+beforeEach(() => {
+ $sessions.set([])
+ $unreadWriteGuard.set(new Map())
+ patch.mockClear()
+})
+
+afterEach(() => {
+ $sessions.set([])
+ $unreadWriteGuard.set(new Map())
+})
+
+describe('markSessionUnread', () => {
+ it('optimistically paints the row, then PATCHes with the owning profile', async () => {
+ $sessions.set([row('a', { profile: 'work', unread: false })])
+
+ await markSessionUnread('a', true)
+
+ expect(patch).toHaveBeenCalledWith('a', true, 'work')
+ expect($sessions.get().find(s => s.id === 'a')?.unread).toBe(true)
+ })
+
+ it('no-ops for a runtime-only session with no persisted row', async () => {
+ await markSessionUnread('ghost', true)
+
+ expect(patch).not.toHaveBeenCalled()
+ })
+
+ it('rolls back the row and rethrows when the PATCH fails', async () => {
+ $sessions.set([row('a', { unread: false })])
+ patch.mockImplementationOnce(() => Promise.reject(new Error('offline')))
+
+ await expect(markSessionUnread('a', true)).rejects.toThrow('offline')
+
+ // The backend kept the old value, so the optimistic flip is undone and
+ // the guard is released (nothing to fence a page about).
+ expect($sessions.get().find(s => s.id === 'a')?.unread).toBe(false)
+ expect($unreadWriteGuard.get().has('a')).toBe(false)
+ })
+})
+
+describe('clearUnreadOnOpen', () => {
+ it('no-ops for a session that is already read', async () => {
+ $sessions.set([row('a', { unread: false })])
+
+ await clearUnreadOnOpen('a')
+
+ expect(patch).not.toHaveBeenCalled()
+ })
+
+ it('PATCHes read for an unread session, using its owning profile', async () => {
+ $sessions.set([row('a', { profile: 'p2', unread: true })])
+
+ await clearUnreadOnOpen('a')
+
+ expect(patch).toHaveBeenCalledWith('a', false, 'p2')
+ expect($sessions.get().find(s => s.id === 'a')?.unread).toBe(false)
+ })
+
+ it('swallows a failed PATCH (the next honest refresh heals the dot)', async () => {
+ $sessions.set([row('a', { unread: true })])
+ patch.mockImplementationOnce(() => Promise.reject(new Error('offline')))
+
+ await expect(clearUnreadOnOpen('a')).resolves.toBeUndefined()
+ })
+})
+
+describe('watchUnreadWriteGuard', () => {
+ it('drops a guard entry once a list page confirms the value we wrote', () => {
+ watchUnreadWriteGuard()
+ const guard = new Map()
+ guard.set('a', { at: Date.now(), value: true })
+ $unreadWriteGuard.set(guard)
+
+ // The server caught up and echoes our value back.
+ $sessions.set([row('a', { unread: true })])
+
+ expect($unreadWriteGuard.get().has('a')).toBe(false)
+ })
+
+ it('keeps the guard while a page contradicts a write still in flight', () => {
+ watchUnreadWriteGuard()
+ const guard = new Map()
+ guard.set('a', { at: Date.now(), value: true })
+ $unreadWriteGuard.set(guard)
+
+ // A list request issued before the PATCH still says read. Honouring it
+ // would silently undo the mark the user just made.
+ $sessions.set([row('a', { unread: false })])
+
+ expect($unreadWriteGuard.get().has('a')).toBe(true)
+ })
+})
diff --git a/apps/desktop/src/store/session-unread-remote.ts b/apps/desktop/src/store/session-unread-remote.ts
new file mode 100644
index 0000000000..6200b8b6c9
--- /dev/null
+++ b/apps/desktop/src/store/session-unread-remote.ts
@@ -0,0 +1,101 @@
+/**
+ * Persisted unread flag sync (backend read-state watermark via
+ * PATCH /api/sessions/{id} → SessionDB.set_session_read).
+ *
+ * The sidebar's dot is fed by TWO sources (see session-dot-state.ts): the
+ * runtime "turn finished in background" marker ($unreadFinishedSessionIds,
+ * transient) and the backend's derived `unread` key (last_read_at watermark
+ * vs last_active — survives restarts and is visible to every surface). This
+ * module owns the WRITE side of the persisted flag: the row-level
+ * "Mark as unread"/"Mark as read" toggle and the automatic clear when a
+ * session is opened. The read side lives in session-dot-state.ts.
+ *
+ * Optimistic, then honest (AGENTS.md): paint the row immediately, PATCH the
+ * backend, roll back visibly on failure. A list page already in flight when
+ * we PATCH can land after the ack carrying the OLD value — the write guard
+ * lets our value outrank that stale page briefly (#74570 pattern, same as
+ * session-pin-sync.ts).
+ *
+ * NOTE: import cycle with ./session is inert — both modules only touch each
+ * other's exports inside function bodies, never at module evaluation time.
+ */
+import { atom } from 'nanostores'
+
+import { setSessionUnreadRemote } from '@/hermes'
+
+import { $sessions, setSessions } from './session'
+
+export const UNREAD_WRITE_GUARD_MS = 10_000
+
+/** id -> the value we wrote and when. Guarded rows outrank list pages. */
+export const $unreadWriteGuard = atom>(new Map())
+
+function rowFor(storedId: string) {
+ return $sessions.get().find(row => row.id === storedId)
+}
+
+/** Toggle the persisted unread flag: optimistic row update, then PATCH, then
+ * roll back visibly if the write fails. No-op for runtime-only sessions (a
+ * brand-new chat with no persisted row yet — there is nothing to flag). */
+export async function markSessionUnread(storedId: string, unread: boolean): Promise {
+ const row = rowFor(storedId)
+
+ if (!row) {
+ return
+ }
+
+ const guard = new Map($unreadWriteGuard.get())
+ guard.set(storedId, { at: Date.now(), value: unread })
+ $unreadWriteGuard.set(guard)
+
+ setSessions(rows => rows.map(r => (r.id === storedId ? { ...r, unread } : r)))
+
+ try {
+ await setSessionUnreadRemote(storedId, unread, row.profile)
+ } catch (err) {
+ // Roll back visibly: the backend kept the old value.
+ const guard2 = new Map($unreadWriteGuard.get())
+ guard2.delete(storedId)
+ $unreadWriteGuard.set(guard2)
+ setSessions(rows => rows.map(r => (r.id === storedId ? { ...r, unread: !unread } : r)))
+ throw err
+ }
+}
+
+/** Opening a session clears its persisted unread flag (auto-mark-read).
+ * Best-effort: a failed PATCH is healed by the next honest refresh. */
+export async function clearUnreadOnOpen(storedId: string): Promise {
+ const row = rowFor(storedId)
+
+ if (!row || row.unread !== true) {
+ return
+ }
+
+ try {
+ await markSessionUnread(storedId, false)
+ } catch {
+ // Ignore: the dot simply returns until a refresh reconciles.
+ }
+}
+
+/** Release guard entries once a list page confirms the value we wrote. Call
+ * once at boot, next to watchSessionPins(). */
+export function watchUnreadWriteGuard(): void {
+ $sessions.listen(rows => {
+ const guard = $unreadWriteGuard.get()
+ let changed = false
+
+ for (const [id, entry] of guard) {
+ const row = rows.find(r => r.id === id)
+
+ if (row && row.unread === entry.value) {
+ guard.delete(id)
+ changed = true
+ }
+ }
+
+ if (changed) {
+ $unreadWriteGuard.set(new Map(guard))
+ }
+ })
+}
diff --git a/apps/desktop/src/store/session-unread-tile.test.ts b/apps/desktop/src/store/session-unread-tile.test.ts
new file mode 100644
index 0000000000..c93480dced
--- /dev/null
+++ b/apps/desktop/src/store/session-unread-tile.test.ts
@@ -0,0 +1,84 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// The completed-unread dot is keyed on the FOCUSED session, not the selected
+// one. A tile is never $selectedStoredSessionId, so keying either half on the
+// selection left a tiled session's dot green with no way to clear it.
+
+describe('completed-unread dot follows the focused session', () => {
+ beforeEach(() => {
+ vi.resetModules()
+ })
+
+ afterEach(() => {
+ vi.resetModules()
+ })
+
+ async function setup() {
+ const tree = await import('@/components/pane-shell/tree/store')
+ const model = await import('@/components/pane-shell/tree/model')
+ const { registry } = await import('@/contrib/registry')
+ const { createClientSessionState } = await import('@/lib/chat-runtime')
+ const session = await import('./session')
+ const states = await import('./session-states')
+
+ for (const id of ['workspace', 'session-tile:tiled']) {
+ registry.register({
+ area: 'panes',
+ data: id === 'workspace' ? { placement: 'main', uncloseable: true } : { placement: 'main' },
+ id,
+ render: () => null,
+ title: id
+ })
+ }
+
+ // The workspace holds the primary chat, a second zone holds the tile.
+ tree.declareDefaultTree(
+ model.split('row', [
+ model.group(['workspace'], { active: 'workspace', id: 'grp-main' }),
+ model.group(['session-tile:tiled'], { active: 'session-tile:tiled', id: 'grp-tile' })
+ ])
+ )
+
+ session.$unreadFinishedSessionIds.set([])
+ session.$selectedStoredSessionId.set('primary')
+
+ const finishTurn = (storedSessionId: string) => {
+ const working = { ...createClientSessionState(null), busy: true, storedSessionId }
+ states.publishSessionState(`rt-${storedSessionId}`, working)
+ states.publishSessionState(`rt-${storedSessionId}`, { ...working, busy: false })
+ }
+
+ return { finishTurn, session, tree }
+ }
+
+ it('clears the dot when an already-open tile is fronted', async () => {
+ const { finishTurn, session, tree } = await setup()
+
+ tree.noteActiveTreeGroup('grp-main')
+ finishTurn('tiled')
+ expect(session.$unreadFinishedSessionIds.get()).toEqual(['tiled'])
+
+ // Fronting the tile is what a tab click does. Before the fix nothing on
+ // this path cleared the marker, so the dot stayed green.
+ tree.noteActiveTreeGroup('grp-tile')
+ expect(session.$unreadFinishedSessionIds.get()).toEqual([])
+ })
+
+ it('never marks a tile that finishes while it is the focused one', async () => {
+ const { finishTurn, session, tree } = await setup()
+
+ tree.noteActiveTreeGroup('grp-tile')
+ finishTurn('tiled')
+
+ expect(session.$unreadFinishedSessionIds.get()).toEqual([])
+ })
+
+ it('marks the primary session when a tile has focus', async () => {
+ const { finishTurn, session, tree } = await setup()
+
+ tree.noteActiveTreeGroup('grp-tile')
+ finishTurn('primary')
+
+ expect(session.$unreadFinishedSessionIds.get()).toEqual(['primary'])
+ })
+})
diff --git a/apps/desktop/src/store/session-unread.test.ts b/apps/desktop/src/store/session-unread.test.ts
new file mode 100644
index 0000000000..f1d0224c9b
--- /dev/null
+++ b/apps/desktop/src/store/session-unread.test.ts
@@ -0,0 +1,245 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import type { SessionInfo } from '@/types/hermes'
+
+import { $activeGatewayProfile } from './profile'
+import {
+ $cronSessions,
+ $messagingSessions,
+ $selectedStoredSessionId,
+ $sessions,
+ $unreadFinishedSessionIds,
+ setSelectedStoredSessionId,
+ setSessions
+} from './session'
+import { clearAllSessionStates } from './session-states'
+import {
+ $sessionSeenCounts,
+ $unreadFinishedMarkers,
+ forgetSessionUnread,
+ markSessionUnreadFinished
+} from './session-unread'
+
+const session = (over: Partial): SessionInfo => ({
+ archived: false,
+ cwd: null,
+ ended_at: null,
+ id: 'live',
+ input_tokens: 0,
+ is_active: false,
+ last_active: 0,
+ message_count: 0,
+ model: null,
+ output_tokens: 0,
+ preview: null,
+ source: null,
+ started_at: 0,
+ title: null,
+ tool_call_count: 0,
+ ...over
+})
+
+function resetAll() {
+ clearAllSessionStates()
+ // Lists first: their listeners recompute the unread atom, so wiping the
+ // atom afterwards leaves a genuinely clean slate.
+ $sessions.set([])
+ $cronSessions.set([])
+ $messagingSessions.set([])
+ $selectedStoredSessionId.set(null)
+ $activeGatewayProfile.set('default')
+ $sessionSeenCounts.set({})
+ $unreadFinishedMarkers.set({})
+ $unreadFinishedSessionIds.set([])
+}
+
+describe('persisted unread (session-unread)', () => {
+ beforeEach(resetAll)
+
+ it('reconstructs the green dot from a seen watermark after a cold start', () => {
+ // "Restart": persisted watermark says 3 messages were seen; the freshly
+ // loaded list says the session now has 5 — it finished while we were away.
+ $sessionSeenCounts.set({ default: { s1: 3 } })
+
+ setSessions([session({ id: 's1', message_count: 5 })])
+
+ expect($unreadFinishedSessionIds.get()).toEqual(['s1'])
+ })
+
+ it('seeds the watermark on first sight instead of painting every row green', () => {
+ setSessions([session({ id: 's1', message_count: 5 })])
+
+ expect($unreadFinishedSessionIds.get()).toEqual([])
+ expect($sessionSeenCounts.get()).toEqual({ default: { s1: 5 } })
+ })
+
+ it('keeps a live-edge marker across a transient wipe (gateway/profile switch)', () => {
+ setSessions([session({ id: 's1', message_count: 4 })])
+ markSessionUnreadFinished('s1')
+ expect($unreadFinishedSessionIds.get()).toEqual(['s1'])
+
+ // Gateway switch: transient paint layer wiped, lists drained…
+ setSessions([])
+ $unreadFinishedSessionIds.set([])
+
+ // …then the profile's lists load again: the persisted marker repaints.
+ setSessions([session({ id: 's1', message_count: 4 })])
+
+ expect($unreadFinishedSessionIds.get()).toEqual(['s1'])
+ })
+
+ it('acks watermark + marker when the user opens the session', () => {
+ $sessionSeenCounts.set({ default: { s1: 3 } })
+ setSessions([session({ id: 's1', message_count: 5 })])
+ markSessionUnreadFinished('s1')
+
+ setSelectedStoredSessionId('s1')
+
+ expect($unreadFinishedSessionIds.get()).toEqual([])
+ expect($unreadFinishedMarkers.get()).toEqual({})
+ expect($sessionSeenCounts.get()).toEqual({ default: { s1: 5 } })
+
+ // A later refresh with the same count stays read.
+ setSessions([session({ id: 's1', message_count: 5 })])
+ expect($unreadFinishedSessionIds.get()).toEqual([])
+ })
+
+ it('tracks the selected session’s count so on-screen activity never reads as unread', () => {
+ $selectedStoredSessionId.set('s1')
+ setSessions([session({ id: 's1', message_count: 2 })])
+
+ // The turn completes while the user is looking at it.
+ setSessions([session({ id: 's1', message_count: 7 })])
+
+ expect($unreadFinishedSessionIds.get()).toEqual([])
+ expect($sessionSeenCounts.get()).toEqual({ default: { s1: 7 } })
+
+ // Navigating away must not retroactively flag it.
+ setSelectedStoredSessionId(null)
+ setSessions([session({ id: 's1', message_count: 7 })])
+ expect($unreadFinishedSessionIds.get()).toEqual([])
+ })
+
+ it('follows auto-compression id rotation via the durable lineage id', () => {
+ $sessionSeenCounts.set({ default: { root: 3 } })
+
+ setSessions([session({ _lineage_root_id: 'root', id: 'tip-2', message_count: 6 })])
+
+ expect($unreadFinishedSessionIds.get()).toEqual(['tip-2'])
+
+ // Opening the rotated tip acks the lineage watermark.
+ setSelectedStoredSessionId('tip-2')
+ expect($sessionSeenCounts.get()).toEqual({ default: { root: 6 } })
+ })
+
+ it('reconstructs unread for cron rows too', () => {
+ $sessionSeenCounts.set({ default: { cron1: 1 } })
+
+ $cronSessions.set([session({ id: 'cron1', message_count: 3 })])
+
+ expect($unreadFinishedSessionIds.get()).toEqual(['cron1'])
+ })
+
+ it('never paints messaging rows from count growth, but honors live-edge markers', () => {
+ // First sight seeds…
+ $messagingSessions.set([session({ id: 'tg1', message_count: 10 })])
+ // …then inbound messages bump the count: NOT "finished — unread".
+ $messagingSessions.set([session({ id: 'tg1', message_count: 14 })])
+
+ expect($unreadFinishedSessionIds.get()).toEqual([])
+
+ // A real background turn edge still marks it, durably.
+ markSessionUnreadFinished('tg1')
+ $unreadFinishedSessionIds.set([])
+ $messagingSessions.set([session({ id: 'tg1', message_count: 14 })])
+
+ expect($unreadFinishedSessionIds.get()).toEqual(['tg1'])
+ })
+
+ it('preserves a live-edge id whose row is not in any loaded list yet', () => {
+ // A brand-new session's first turn isn't flushed to the sidebar list until
+ // persisted — the flag must survive list refreshes in the meantime.
+ markSessionUnreadFinished('fresh')
+
+ setSessions([session({ id: 'other', message_count: 2 })])
+
+ expect($unreadFinishedSessionIds.get()).toContain('fresh')
+ })
+
+ it('keeps same-id sessions in different profiles independent', () => {
+ // Session ids are caller-supplied and every profile backend is its own
+ // namespace, so "s1" in alpha and "s1" in beta are different sessions —
+ // and cron/messaging lists always mix profiles into one array.
+ $sessionSeenCounts.set({ alpha: { s1: 3 }, beta: { s1: 5 } })
+ $unreadFinishedMarkers.set({ alpha: ['s1'] })
+
+ setSessions([
+ session({ id: 's1', message_count: 5, profile: 'beta' }),
+ session({ id: 's1', message_count: 5, profile: 'alpha' })
+ ])
+
+ // Only alpha's row is past its watermark; beta's sits exactly on it.
+ expect($unreadFinishedSessionIds.get()).toEqual(['s1'])
+ expect($sessionSeenCounts.get()).toEqual({ alpha: { s1: 3 }, beta: { s1: 5 } })
+
+ // Opening beta's row (the gateway is on beta) acks beta only.
+ $activeGatewayProfile.set('beta')
+ setSelectedStoredSessionId('s1')
+
+ expect($sessionSeenCounts.get()).toEqual({ alpha: { s1: 3 }, beta: { s1: 5 } })
+ // alpha's marker survives an ack of beta's identically-named session.
+ expect($unreadFinishedMarkers.get()).toEqual({ alpha: ['s1'] })
+
+ // A later refresh must not launder alpha's gap through beta's selection.
+ setSessions([
+ session({ id: 's1', message_count: 6, profile: 'beta' }),
+ session({ id: 's1', message_count: 5, profile: 'alpha' })
+ ])
+
+ expect($sessionSeenCounts.get()).toEqual({ alpha: { s1: 3 }, beta: { s1: 6 } })
+ expect($unreadFinishedMarkers.get()).toEqual({ alpha: ['s1'] })
+ })
+
+ it('files a live-edge marker with no loaded row under the active gateway profile', () => {
+ $activeGatewayProfile.set('work')
+
+ markSessionUnreadFinished('fresh')
+
+ expect($unreadFinishedMarkers.get()).toEqual({ work: ['fresh'] })
+ expect($unreadFinishedSessionIds.get()).toEqual(['fresh'])
+ })
+
+ it('forgets a deleted session’s persisted unread, per profile', () => {
+ $sessionSeenCounts.set({ alpha: { root: 3, other: 1 }, beta: { root: 9 } })
+ $unreadFinishedMarkers.set({ alpha: ['root', 'keep'], beta: ['root'] })
+ $unreadFinishedSessionIds.set(['tip-2'])
+
+ forgetSessionUnread(['tip-2', 'root', null, undefined], 'alpha')
+
+ expect($sessionSeenCounts.get()).toEqual({ alpha: { other: 1 }, beta: { root: 9 } })
+ expect($unreadFinishedMarkers.get()).toEqual({ alpha: ['keep'], beta: ['root'] })
+ expect($unreadFinishedSessionIds.get()).toEqual([])
+ })
+
+ it('drops an emptied profile bucket instead of persisting an empty shell', () => {
+ $sessionSeenCounts.set({ alpha: { s1: 3 } })
+ $unreadFinishedMarkers.set({ alpha: ['s1'] })
+
+ forgetSessionUnread(['s1'], 'alpha')
+
+ expect($sessionSeenCounts.get()).toEqual({})
+ expect($unreadFinishedMarkers.get()).toEqual({})
+ })
+
+ it('caps markers per profile, evicting the oldest', () => {
+ for (let i = 0; i < 201; i += 1) {
+ markSessionUnreadFinished(`s${i}`)
+ }
+
+ const markers = $unreadFinishedMarkers.get().default
+
+ expect(markers).toHaveLength(200)
+ expect(markers[0]).toBe('s1')
+ expect(markers.at(-1)).toBe('s200')
+ })
+})
diff --git a/apps/desktop/src/store/session-unread.ts b/apps/desktop/src/store/session-unread.ts
new file mode 100644
index 0000000000..b6afadace0
--- /dev/null
+++ b/apps/desktop/src/store/session-unread.ts
@@ -0,0 +1,565 @@
+import { Codecs, persistentAtom } from '@/lib/persisted'
+import { stableArray } from '@/lib/stable-array'
+import { readKey } from '@/lib/storage'
+import { $activeGatewayProfile, normalizeProfileKey } from '@/store/profile'
+import type { SessionInfo } from '@/types/hermes'
+
+import {
+ $cronSessions,
+ $messagingSessions,
+ $selectedStoredSessionId,
+ $sessions,
+ $unreadFinishedSessionIds,
+ sessionMatchesStoredId,
+ sessionPinId
+} from './session'
+import { isSecondaryWindow } from './windows'
+
+/**
+ * PERSISTED UNREAD ("finished — unread" green dot) — the durable layer under
+ * the transient `$unreadFinishedSessionIds` atom, ported from the webui's
+ * proven design (sessions.js: viewed-count watermarks + completion markers).
+ *
+ * Two persisted records, both bucketed BY PROFILE and then keyed by the
+ * DURABLE lineage id (sessionPinId) so state survives auto-compression's
+ * session-id rotation — same durable-id rule as `$sessionColorOverrides`:
+ *
+ * 1. SEEN WATERMARKS — the message_count last acknowledged for a session
+ * (set when the user opens it, kept current while it stays selected, and
+ * seeded on FIRST SIGHT of an unknown session so a fresh install doesn't
+ * paint every row green). A row whose live `message_count` exceeds its
+ * watermark is unread — this is what reconstructs the green dot for a
+ * session that finished while the app was CLOSED, which the live
+ * busy→idle edge in session-states.ts can never replay after a restart.
+ *
+ * 2. EXPLICIT MARKERS — the live busy→idle edge, persisted. Covers the gap
+ * where a turn finishes in the background but the sidebar list hasn't
+ * refreshed its message_count yet (and any completion that adds no
+ * stored messages), so a restart right after a finish keeps the dot.
+ *
+ * PROFILE SCOPING is not optional: session ids are caller-supplied and each
+ * remote-profile backend is its own namespace, so two profiles can hold the
+ * same id — and the lists routinely mix profiles (cron/messaging are ALWAYS
+ * cross-profile, `$sessions` is too in all-profiles mode). Unscoped keys let
+ * one profile's watermark/marker paint (or silence) another's row. The bucket
+ * is always the ROW's own `profile` (normalizeProfileKey, absent → "default"),
+ * never the live gateway's — except for the live busy→idle edge with no loaded
+ * row, which only ever fires for the ACTIVE gateway's runtimes and therefore
+ * falls back to `$activeGatewayProfile`.
+ *
+ * Both records are BOUNDED: markers cap per profile (oldest evicted),
+ * watermarks cap in total (unlisted, unmarked entries dropped first), and
+ * deleting/archiving a session drops its entries outright via
+ * {@link forgetSessionUnread}.
+ *
+ * Scope of watermark-based unread: chat + cron rows. Messaging rows get their
+ * message_count bumped by inbound human messages, so count-over-watermark
+ * would paint "finished — unread" on every new inbound text; they keep only
+ * the explicit live-edge markers (now persisted across restarts too).
+ */
+
+/** profile key → durable id → last acknowledged message_count. */
+type SeenCounts = Record>
+
+/** profile key → durable ids flagged by the live busy→idle edge. */
+type Markers = Record
+
+export const $sessionSeenCounts = persistentAtom(
+ 'hermes.desktop.sessionSeenCounts',
+ {},
+ Codecs.json(sanitizeSeenCounts)
+)
+
+export const $unreadFinishedMarkers = persistentAtom(
+ 'hermes.desktop.unreadFinishedSessions',
+ {},
+ Codecs.json(sanitizeMarkers)
+)
+
+const isPlainRecord = (value: unknown): value is Record =>
+ Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+
+// Also the migration: a pre-profile-scoping flat record (durable id → number)
+// has non-object values, so it drops wholesale rather than mis-attributing
+// every id to a profile named after it. Dropped watermarks reseed on next
+// sight, which reads as "not unread" — the safe default.
+function sanitizeSeenCounts(value: unknown): SeenCounts {
+ if (!isPlainRecord(value)) {
+ return {}
+ }
+
+ const next: SeenCounts = {}
+
+ for (const [profile, bucket] of Object.entries(value)) {
+ if (!isPlainRecord(bucket)) {
+ continue
+ }
+
+ const counts = Object.fromEntries(
+ Object.entries(bucket).filter(
+ (entry): entry is [string, number] => typeof entry[1] === 'number' && Number.isFinite(entry[1])
+ )
+ )
+
+ if (Object.keys(counts).length) {
+ next[profile] = counts
+ }
+ }
+
+ return next
+}
+
+// Same story for markers: the legacy flat shape was a bare string[], which is
+// not an object of arrays, so it decodes to {}.
+function sanitizeMarkers(value: unknown): Markers {
+ if (!isPlainRecord(value)) {
+ return {}
+ }
+
+ const next: Markers = {}
+
+ for (const [profile, bucket] of Object.entries(value)) {
+ if (!Array.isArray(bucket)) {
+ continue
+ }
+
+ const ids = bucket.filter((id): id is string => typeof id === 'string' && id.length > 0)
+
+ if (ids.length) {
+ next[profile] = ids
+ }
+ }
+
+ return next
+}
+
+// Watermarks accrete one entry per session ever seen; keep the record bounded.
+// Past the cap, entries for sessions no longer in any loaded list (and not
+// explicitly marked) are dropped — a pruned session reseeds on next sight,
+// which reads as "not unread", the safe default.
+const SEEN_COUNTS_CAP = 2000
+
+// Markers only matter while their session still exists, and a marker whose
+// session is gone is invisible (nothing paints it) but immortal — deletes we
+// never observed (another client, a wiped backend) would accrete forever. Cap
+// per profile and evict oldest-first: the freshest finishes are the ones the
+// user still cares about.
+const MARKERS_CAP = 200
+
+const rowsFor = (lists: readonly SessionInfo[][]): SessionInfo[] => lists.flat()
+
+const isSelected = (row: SessionInfo, selected: null | string): boolean =>
+ Boolean(selected && sessionMatchesStoredId(row, selected))
+
+/** The persistence bucket a row belongs to — its OWN profile, never the live
+ * gateway's (the lists are routinely cross-profile). */
+const profileKeyForRow = (row: SessionInfo): string => normalizeProfileKey(row.profile)
+
+/** The row a bare stored id refers to. Ids are caller-supplied and each
+ * profile's backend is its own namespace, so two profiles can hold the same
+ * id; a tie breaks toward the live gateway, since both opening a session and
+ * running one swap the gateway onto that session's profile. */
+function resolveLoadedRow(storedSessionId: string): SessionInfo | undefined {
+ const matches = rowsFor([$sessions.get(), $cronSessions.get(), $messagingSessions.get()]).filter(row =>
+ sessionMatchesStoredId(row, storedSessionId)
+ )
+
+ if (matches.length < 2) {
+ return matches[0]
+ }
+
+ const gateway = normalizeProfileKey($activeGatewayProfile.get())
+
+ return matches.find(row => profileKeyForRow(row) === gateway) ?? matches[0]
+}
+
+/** Bucket for a bare stored id: its row's profile, else the live gateway's. */
+const resolveProfile = (storedSessionId: string): string => {
+ const row = resolveLoadedRow(storedSessionId)
+
+ return row ? profileKeyForRow(row) : normalizeProfileKey($activeGatewayProfile.get())
+}
+
+/** Write a profile's marker bucket, dropping the key when it empties so we
+ * don't persist a graveyard of `[]`. */
+function setMarkerBucket(profile: string, ids: readonly string[]): void {
+ const markers = $unreadFinishedMarkers.get()
+ const next = { ...markers }
+
+ if (ids.length) {
+ next[profile] = [...ids]
+ } else {
+ delete next[profile]
+ }
+
+ $unreadFinishedMarkers.set(next)
+}
+
+/** LIVE-EDGE WRITER — called by session-states.ts on a background busy→idle
+ * transition. Flags the transient atom (immediate paint) AND persists the
+ * marker so the dot survives a restart. The marker lands in the row's own
+ * profile; with no loaded row we use the active gateway's profile, which is
+ * the only place a live edge can come from. */
+export function markSessionUnreadFinished(storedSessionId: string): void {
+ const current = $unreadFinishedSessionIds.get()
+
+ if (!current.includes(storedSessionId)) {
+ $unreadFinishedSessionIds.set([...current, storedSessionId])
+ }
+
+ const row = resolveLoadedRow(storedSessionId)
+ const profile = row ? profileKeyForRow(row) : normalizeProfileKey($activeGatewayProfile.get())
+ const durableId = row ? sessionPinId(row) : storedSessionId
+ const bucket = $unreadFinishedMarkers.get()[profile] ?? []
+
+ if (bucket.includes(durableId)) {
+ return
+ }
+
+ const next = [...bucket, durableId]
+
+ setMarkerBucket(profile, next.length > MARKERS_CAP ? next.slice(next.length - MARKERS_CAP) : next)
+}
+
+/** ACK — the user opened (or is looking at) this session: watermark := its
+ * current message_count, and any explicit marker is retired. */
+function ackSessionRow(row: SessionInfo): void {
+ const profile = profileKeyForRow(row)
+ const durableId = sessionPinId(row)
+
+ if (Number.isFinite(row.message_count)) {
+ const seen = $sessionSeenCounts.get()
+ const bucket = seen[profile]
+
+ if (bucket?.[durableId] !== row.message_count) {
+ $sessionSeenCounts.set({ ...seen, [profile]: { ...bucket, [durableId]: row.message_count } })
+ }
+ }
+
+ const markers = $unreadFinishedMarkers.get()[profile]
+
+ if (!markers) {
+ return
+ }
+
+ const next = markers.filter(id => id !== durableId && !sessionMatchesStoredId(row, id))
+
+ if (next.length !== markers.length) {
+ setMarkerBucket(profile, next)
+ }
+}
+
+/** Clear persisted unread for a stored id even when its row isn't loaded —
+ * the marker alone can be retired; the watermark needs the row's count. With
+ * no row there is no profile to read, so we retire it from the active
+ * gateway's bucket (the profile whose sessions you can actually be opening);
+ * other profiles' identically-named ids stay untouched. */
+export function ackStoredSessionId(storedSessionId: null | string): void {
+ if (!storedSessionId) {
+ return
+ }
+
+ const row = resolveLoadedRow(storedSessionId)
+
+ if (row) {
+ ackSessionRow(row)
+
+ return
+ }
+
+ const profile = normalizeProfileKey($activeGatewayProfile.get())
+ const markers = $unreadFinishedMarkers.get()[profile]
+
+ if (!markers) {
+ return
+ }
+
+ const next = markers.filter(id => id !== storedSessionId)
+
+ if (next.length !== markers.length) {
+ setMarkerBucket(profile, next)
+ }
+}
+
+/** Sidebar "Mark all as read" — ack every LOADED row (watermark := its current
+ * count, markers retired) so the persisted layer doesn't repaint the dots the
+ * user just dismissed on the next list refresh. Rows not loaded keep their
+ * state: an unseen session in a collapsed profile stays honestly unread. */
+export function ackAllSessionsRead(): void {
+ for (const row of rowsFor([$sessions.get(), $cronSessions.get(), $messagingSessions.get()])) {
+ ackSessionRow(row)
+ }
+}
+
+/** DELETE/ARCHIVE CLEANUP — the session is gone from the user's world, so its
+ * watermark and marker are dead weight. Drops every candidate id (stored id,
+ * live id, lineage root) from both persisted records in `profile`'s bucket
+ * and from the transient atom. Same-id sessions in other profiles survive. */
+export function forgetSessionUnread(
+ candidateIds: readonly (null | string | undefined)[],
+ profile?: null | string
+): void {
+ const ids = new Set(candidateIds.filter((id): id is string => Boolean(id)))
+
+ if (!ids.size) {
+ return
+ }
+
+ const key = normalizeProfileKey(profile)
+ const seen = $sessionSeenCounts.get()
+ const counts = seen[key]
+
+ if (counts) {
+ const kept = Object.fromEntries(Object.entries(counts).filter(([id]) => !ids.has(id)))
+
+ if (Object.keys(kept).length !== Object.keys(counts).length) {
+ const next = { ...seen }
+
+ if (Object.keys(kept).length) {
+ next[key] = kept
+ } else {
+ delete next[key]
+ }
+
+ $sessionSeenCounts.set(next)
+ }
+ }
+
+ const markers = $unreadFinishedMarkers.get()[key]
+
+ if (markers) {
+ const kept = markers.filter(id => !ids.has(id))
+
+ if (kept.length !== markers.length) {
+ setMarkerBucket(key, kept)
+ }
+ }
+
+ const current = $unreadFinishedSessionIds.get()
+ const nextIds = current.filter(id => !ids.has(id))
+
+ if (nextIds.length !== current.length) {
+ $unreadFinishedSessionIds.set(nextIds)
+ }
+}
+
+/** Seed/refresh watermarks from freshly loaded lists: the SELECTED session
+ * tracks its live count (it's on screen — nothing there is unread), and a
+ * session never seen before seeds at its current count instead of lighting
+ * up green on first sight. Known, unselected rows are left alone — the gap
+ * between their watermark and live count IS the unread signal. */
+function ingestRows(rows: readonly SessionInfo[]): void {
+ const selected = $selectedStoredSessionId.get()
+ // Only the OWNING profile's row counts as on-screen: a same-id row in
+ // another profile is a different session and keeps its unread gap.
+ const selectedProfile = selected ? resolveProfile(selected) : null
+ const seen = $sessionSeenCounts.get()
+ let next: null | SeenCounts = null
+
+ const write = (profile: string, durableId: string, count: number): void => {
+ next ??= { ...seen }
+ next[profile] = { ...next[profile], [durableId]: count }
+ }
+
+ for (const row of rows) {
+ if (!Number.isFinite(row.message_count)) {
+ continue
+ }
+
+ const profile = profileKeyForRow(row)
+ const durableId = sessionPinId(row)
+ const bucket = next?.[profile] ?? seen[profile]
+
+ if (profile === selectedProfile && isSelected(row, selected)) {
+ if (bucket?.[durableId] !== row.message_count) {
+ write(profile, durableId, row.message_count)
+ }
+
+ // Any lingering explicit marker for the on-screen session is stale.
+ const markers = $unreadFinishedMarkers.get()[profile]
+
+ if (markers) {
+ const kept = markers.filter(id => id !== durableId && !sessionMatchesStoredId(row, id))
+
+ if (kept.length !== markers.length) {
+ setMarkerBucket(profile, kept)
+ }
+ }
+ } else if (!bucket || !(durableId in bucket)) {
+ write(profile, durableId, row.message_count)
+ }
+ }
+
+ if (next) {
+ $sessionSeenCounts.set(pruneSeenCounts(next, rows))
+ }
+}
+
+function pruneSeenCounts(seen: SeenCounts, rows: readonly SessionInfo[]): SeenCounts {
+ const total = Object.values(seen).reduce((sum, bucket) => sum + Object.keys(bucket).length, 0)
+
+ if (total <= SEEN_COUNTS_CAP) {
+ return seen
+ }
+
+ const markers = $unreadFinishedMarkers.get()
+ const keep = new Map>()
+
+ const keepFor = (profile: string): Set => {
+ let ids = keep.get(profile)
+
+ if (!ids) {
+ ids = new Set(markers[profile] ?? [])
+ keep.set(profile, ids)
+ }
+
+ return ids
+ }
+
+ for (const row of rows) {
+ keepFor(profileKeyForRow(row)).add(sessionPinId(row))
+ }
+
+ const next: SeenCounts = {}
+
+ for (const [profile, bucket] of Object.entries(seen)) {
+ const allowed = keepFor(profile)
+ const kept = Object.fromEntries(Object.entries(bucket).filter(([id]) => allowed.has(id)))
+
+ if (Object.keys(kept).length) {
+ next[profile] = kept
+ }
+ }
+
+ return next
+}
+
+/** Recompute the transient unread atom from persisted state + loaded rows.
+ * Runs after every list refresh — including the first one after a cold
+ * start, which is what brings green dots back from a restart. Stored ids
+ * already flagged by the live edge but not (yet) present in any list — a
+ * brand-new session's first turn isn't flushed to the list until persisted —
+ * are preserved, not dropped. */
+function recomputeUnread(): void {
+ const selected = $selectedStoredSessionId.get()
+ const markers = $unreadFinishedMarkers.get()
+ const seen = $sessionSeenCounts.get()
+ const unread: string[] = []
+
+ const isMarked = (row: SessionInfo, durableId: string): boolean => {
+ const bucket = markers[profileKeyForRow(row)]
+
+ return Boolean(bucket?.includes(durableId) || bucket?.includes(row.id))
+ }
+
+ // Watermark + marker unread for chat and cron rows. The selected skip stays
+ // profile-blind here (unlike the persisted writes): the paint layer is keyed
+ // by row id, so dotting a same-id row from another profile would just put a
+ // dot on the session you have open.
+ for (const row of rowsFor([$sessions.get(), $cronSessions.get()])) {
+ if (isSelected(row, selected)) {
+ continue
+ }
+
+ const durableId = sessionPinId(row)
+ const watermark = seen[profileKeyForRow(row)]?.[durableId]
+
+ const exceedsWatermark =
+ typeof watermark === 'number' && Number.isFinite(row.message_count) && row.message_count > watermark
+
+ if (exceedsWatermark || isMarked(row, durableId)) {
+ unread.push(row.id)
+ }
+ }
+
+ // Messaging rows: explicit (live-edge) markers only — see header comment.
+ for (const row of $messagingSessions.get()) {
+ if (!isSelected(row, selected) && isMarked(row, sessionPinId(row))) {
+ unread.push(row.id)
+ }
+ }
+
+ // Preserve live-edge ids whose row isn't loaded yet.
+ const loadedRows = rowsFor([$sessions.get(), $cronSessions.get(), $messagingSessions.get()])
+
+ for (const id of $unreadFinishedSessionIds.get()) {
+ if (id !== selected && !unread.includes(id) && !loadedRows.some(row => sessionMatchesStoredId(row, id))) {
+ unread.push(id)
+ }
+ }
+
+ const current = $unreadFinishedSessionIds.get()
+ const next = stableArray(current, unread)
+
+ if (next !== current) {
+ $unreadFinishedSessionIds.set([...next])
+ }
+}
+
+// COLD-BOOT REHYDRATE — module evaluation can race Chromium's storage-area
+// load: an early read comes back empty, the atoms seed their fallbacks, and
+// the first ingest would then re-seed every row and write that emptiness
+// back over the real record. By the time the first session list arrives
+// (seconds later, over IPC) storage is reliably readable, so re-read both
+// keys once right before the first ingest and adopt the disk state, keeping
+// any entry this window already wrote in the meantime (a live edge or an
+// ack beats the stale disk copy for its own key).
+let rehydratedFromDisk = false
+
+function rehydrateFromDiskOnce(): void {
+ if (rehydratedFromDisk) {
+ return
+ }
+
+ rehydratedFromDisk = true
+
+ try {
+ const rawSeen = readKey('hermes.desktop.sessionSeenCounts')
+ const diskSeen = rawSeen ? sanitizeSeenCounts(JSON.parse(rawSeen) as unknown) : {}
+ const memorySeen = $sessionSeenCounts.get()
+ const mergedSeen: SeenCounts = { ...diskSeen }
+
+ for (const [profile, bucket] of Object.entries(memorySeen)) {
+ mergedSeen[profile] = { ...mergedSeen[profile], ...bucket }
+ }
+
+ $sessionSeenCounts.set(mergedSeen)
+
+ const rawMarkers = readKey('hermes.desktop.unreadFinishedSessions')
+ const diskMarkers = rawMarkers ? sanitizeMarkers(JSON.parse(rawMarkers) as unknown) : {}
+ const memoryMarkers = $unreadFinishedMarkers.get()
+ const merged: Markers = { ...diskMarkers }
+
+ for (const [profile, ids] of Object.entries(memoryMarkers)) {
+ merged[profile] = [...new Set([...(merged[profile] ?? []), ...ids])]
+ }
+
+ $unreadFinishedMarkers.set(merged)
+ } catch {
+ // Unreadable storage: keep the in-memory state — same fallback the
+ // atoms started from.
+ }
+}
+
+function onListChange(): void {
+ rehydrateFromDiskOnce()
+ ingestRows(rowsFor([$sessions.get(), $cronSessions.get(), $messagingSessions.get()]))
+ recomputeUnread()
+}
+
+// Wiring: module-scope listeners, same pattern as session-states.ts's
+// $selectedStoredSessionId listener. Loaded via session-states.ts (the live
+// edge imports markSessionUnreadFinished), so it's active wherever unread is.
+// ONLY the primary window maintains the persisted records: a secondary window
+// (single-chat pop-out, watch window) sees a sliver of the session lists, and
+// letting it seed/ack against that partial view would clobber the primary's
+// whole-record writes — same isolation rule as the persisted session tiles.
+if (!isSecondaryWindow()) {
+ $sessions.listen(onListChange)
+ $cronSessions.listen(onListChange)
+ $messagingSessions.listen(onListChange)
+
+ // Opening a session acks it durably (the transient atom is already cleared
+ // synchronously by setSelectedStoredSessionId — this is the persisted half).
+ $selectedStoredSessionId.listen(ackStoredSessionId)
+}
diff --git a/apps/desktop/src/store/session.test.ts b/apps/desktop/src/store/session.test.ts
index fc2e8967f5..ab7961dc03 100644
--- a/apps/desktop/src/store/session.test.ts
+++ b/apps/desktop/src/store/session.test.ts
@@ -4,6 +4,17 @@ import type { ClientSessionState } from '@/app/types'
import { createClientSessionState } from '@/lib/chat-runtime'
import type { SessionInfo } from '@/types/hermes'
+const setUnreadRemote = vi.fn<(id: string, unread: boolean, profile?: null | string) => Promise<{ ok: boolean }>>(() =>
+ Promise.resolve({ ok: true })
+)
+
+vi.mock('@/hermes', () => ({
+ // Opening a session now PATCHes its persisted unread flag (clearUnreadOnOpen
+ // -> markSessionUnread); keep the REST mutation minimal for the suite.
+ setApiRequestProfile: () => {},
+ setSessionUnreadRemote: (id: string, unread: boolean, profile?: null | string) => setUnreadRemote(id, unread, profile)
+}))
+
import {
$activeSessionId,
$connection,
@@ -267,6 +278,81 @@ describe('mergeSessionPage', () => {
expect(merged.map(s => s.id)).toEqual(['tip-5'])
expect(merged[0]?.last_active).toBe(9_000)
})
+
+ it('sorts survivors by last_active so they interleave with incoming instead of forming a stale block', () => {
+ // Repro of #47203: two survivors (B and C) have different last_active
+ // timestamps. B settled more recently than C. Without sorting, survivors
+ // are prepended in their old order from `previous`, which may be stale.
+ // With sorting, B (more recent) should appear before C.
+ const previous = [
+ session({ id: 'c', last_active: 100 }),
+ session({ id: 'b', last_active: 200 }),
+ session({ id: 'a', last_active: 300 })
+ ]
+
+ // Server returns A (fresh page, order=recent), omits B and C (min_messages=1)
+ const incoming = [session({ id: 'a', last_active: 300, message_count: 2 })]
+
+ const merged = mergeSessionPage(previous, incoming, ['b', 'c'])
+
+ // B (last_active 200) should come before C (last_active 100)
+ expect(merged.map(s => s.id)).toEqual(['a', 'b', 'c'])
+ })
+
+ it('places a very recent survivor in correct position among incoming sessions', () => {
+ // A survivor with last_active between two incoming sessions should be
+ // interleaved, not prepended as a block.
+ const previous = [session({ id: 'survivor', last_active: 150 }), session({ id: 'old', last_active: 50 })]
+
+ const incoming = [session({ id: 'newest', last_active: 200 }), session({ id: 'older', last_active: 100 })]
+
+ const merged = mergeSessionPage(previous, incoming, ['survivor'])
+
+ // survivor (150) should be between newest (200) and older (100)
+ expect(merged.map(s => s.id)).toEqual(['newest', 'survivor', 'older'])
+ })
+
+ it('keeps a survivor whose optimistic last_active outranks the whole page on top', () => {
+ // touchSessionActivity stamps last_active on user-send before the server
+ // sees the message; that bump must place the survivor by its FRESH time.
+ const previous = [session({ id: 'typing', last_active: 900 }), session({ id: 'settled', last_active: 100 })]
+
+ const incoming = [session({ id: 'settled', last_active: 100, message_count: 3 })]
+
+ const merged = mergeSessionPage(previous, incoming, ['typing'])
+
+ expect(merged.map(s => s.id)).toEqual(['typing', 'settled'])
+ })
+
+ it('falls back to started_at for survivors that have no last_active yet', () => {
+ // A brand-new session (no persisted message) carries last_active 0; the
+ // backend's effective-recency key falls back to started_at, so we must
+ // too, or a fresh draft sinks to the very bottom of the sidebar.
+ const previous = [
+ session({ id: 'draft', last_active: 0, started_at: 500 }),
+ session({ id: 'other', last_active: 400 })
+ ]
+
+ const incoming = [session({ id: 'other', last_active: 400, message_count: 2 })]
+
+ const merged = mergeSessionPage(previous, incoming, ['draft'])
+
+ expect(merged.map(s => s.id)).toEqual(['draft', 'other'])
+ })
+
+ it('interleaves against the title-preserving merged rows, not the raw incoming page', () => {
+ // The optimistic last_active carried onto an incoming row must count for
+ // its position in the interleave: previous knows 'bumped' was touched at
+ // 300 even though the server page still reports 100.
+ const previous = [session({ id: 'survivor', last_active: 200 }), session({ id: 'bumped', last_active: 300 })]
+
+ const incoming = [session({ id: 'bumped', last_active: 100, message_count: 2 })]
+
+ const merged = mergeSessionPage(previous, incoming, ['survivor'])
+
+ expect(merged.map(s => s.id)).toEqual(['bumped', 'survivor'])
+ expect(merged[0]?.last_active).toBe(300)
+ })
})
describe('touchSessionActivity', () => {
@@ -476,12 +562,15 @@ describe('unread finished sessions', () => {
clearAllSessionStates()
$unreadFinishedSessionIds.set([])
$selectedStoredSessionId.set(null)
+ $sessions.set([])
+ setUnreadRemote.mockClear()
})
afterEach(() => {
clearAllSessionStates()
$unreadFinishedSessionIds.set([])
$selectedStoredSessionId.set(null)
+ $sessions.set([])
})
it('marks a session unread when its turn finishes in the background', () => {
@@ -531,6 +620,114 @@ describe('unread finished sessions', () => {
setSelectedStoredSessionId('s1')
expect($unreadFinishedSessionIds.get()).toEqual([])
})
+
+ it('clears the whole conversation family when any row is opened', () => {
+ $sessions.set([
+ session({ id: 'parent', _lineage_root_id: null }),
+ session({ id: 'child', _lineage_root_id: 'parent' }),
+ session({ id: 'root', _lineage_root_id: null })
+ ])
+ $selectedStoredSessionId.set('other')
+
+ // Parent and child both finish in the background.
+ for (const storedId of ['parent', 'child']) {
+ const working = makeState({ busy: true, storedSessionId: storedId })
+ publishSessionState(`rt-${storedId}`, working)
+ publishSessionState(`rt-${storedId}`, { ...working, busy: false })
+ }
+
+ expect($unreadFinishedSessionIds.get().sort()).toEqual(['child', 'parent'])
+
+ // Opening the CHILD clears the PARENT's dot too (same family).
+ setSelectedStoredSessionId('child')
+ expect($unreadFinishedSessionIds.get()).toEqual([])
+
+ $sessions.set([])
+ })
+
+ it('does NOT re-light a completion that settled before the user read it', () => {
+ vi.useFakeTimers()
+ vi.setSystemTime(1_000_000)
+ $selectedStoredSessionId.set('other')
+
+ const working = makeState({ busy: true, storedSessionId: 's1' })
+ publishSessionState('rt1', working)
+
+ // User reads the session at t=2s, then the same completion re-asserts at
+ // t=3s — the re-assert is the same settled state, so it must not re-light.
+ vi.setSystemTime(2_000_000)
+ setSelectedStoredSessionId('s1')
+ expect($unreadFinishedSessionIds.get()).toEqual([])
+
+ vi.setSystemTime(3_000_000)
+ publishSessionState('rt1', { ...working, busy: false })
+ expect($unreadFinishedSessionIds.get()).toEqual([])
+
+ vi.useRealTimers()
+ })
+
+ it('re-lights when a NEW turn settles after the read baseline', () => {
+ vi.useFakeTimers()
+ vi.setSystemTime(1_000_000)
+ $selectedStoredSessionId.set('other')
+
+ const working = makeState({ busy: true, storedSessionId: 's1' })
+ publishSessionState('rt1', working)
+
+ // User reads s1 at t=2s, then moves on to another session.
+ vi.setSystemTime(2_000_000)
+ setSelectedStoredSessionId('s1')
+ expect($unreadFinishedSessionIds.get()).toEqual([])
+ setSelectedStoredSessionId('other')
+
+ // A NEW turn starts (busy again) and finishes at t=4s — genuinely new
+ // completion after the read baseline, so it re-lights.
+ vi.setSystemTime(3_000_000)
+ publishSessionState('rt1', { ...working, busy: true })
+
+ vi.setSystemTime(4_000_000)
+ publishSessionState('rt1', { ...working, busy: false })
+ expect($unreadFinishedSessionIds.get()).toEqual(['s1'])
+
+ vi.useRealTimers()
+ })
+
+ it('openSession marks read before any focus short-circuit', async () => {
+ vi.useFakeTimers()
+ vi.setSystemTime(1_000_000)
+ $selectedStoredSessionId.set('s1')
+ $unreadFinishedSessionIds.set(['s1'])
+
+ // A no-op navigate — openSession with 'in-place' against the already
+ // selected session hits focusOpenSession and returns without loading.
+ const { openSession } = await import('@/app/open-session')
+ openSession('s1', () => {}, 'in-place')
+
+ expect($unreadFinishedSessionIds.get()).toEqual([])
+
+ vi.useRealTimers()
+ })
+
+ it('clears a persisted unread row when the session is opened', async () => {
+ $sessions.set([session({ id: 's1', unread: true })])
+
+ setSelectedStoredSessionId('s1')
+
+ // The optimistic flip is synchronous; the PATCH is fire-and-forget.
+ expect($sessions.get().find(s => s.id === 's1')?.unread).toBe(false)
+
+ await Promise.resolve()
+ expect(setUnreadRemote).toHaveBeenCalledWith('s1', false, undefined)
+ })
+
+ it('does not PATCH a read row when it is opened', async () => {
+ $sessions.set([session({ id: 's1', unread: false })])
+
+ setSelectedStoredSessionId('s1')
+
+ await Promise.resolve()
+ expect(setUnreadRemote).not.toHaveBeenCalled()
+ })
})
describe('remembered session id (per profile)', () => {
diff --git a/apps/desktop/src/store/session.ts b/apps/desktop/src/store/session.ts
index c64a194ef5..5b06249951 100644
--- a/apps/desktop/src/store/session.ts
+++ b/apps/desktop/src/store/session.ts
@@ -9,6 +9,8 @@ import { persistBoolean, persistString, storedBoolean, storedString } from '@/li
import { syncCronModelImpactConnection } from '@/store/cron-model-impact-scope'
import type { SessionInfo, UsageStats } from '@/types/hermes'
+import { clearUnreadOnOpen } from './session-unread-remote'
+
type Updater = T | ((current: T) => T)
export type ComposerModelSource = '' | 'default' | 'manual'
@@ -437,7 +439,41 @@ export function mergeSessionPage(
(keep.has(session.id) || (session._lineage_root_id != null && keep.has(session._lineage_root_id)))
)
- return survivors.length ? [...survivors, ...merged] : merged
+ if (!survivors.length) {
+ return merged
+ }
+
+ // Survivors carry their old relative positions from `previous`, which can be
+ // stale — the server page is the fresh `order=recent` truth. Sort survivors
+ // by the same effective-recency key the backend sorts by (last_active with a
+ // started_at fallback) and interleave them into the title-preserving merged
+ // rows so a retained session lands where recency puts it instead of the
+ // whole set forming a stale block at the top of the sidebar (fixes #47203).
+ // Ties keep the survivor first, matching the old prepend behavior.
+ const recency = (session: SessionInfo): number => Math.max(session.last_active || 0, session.started_at || 0)
+
+ const sortedSurvivors = [...survivors].sort((a, b) => recency(b) - recency(a))
+ const interleaved: SessionInfo[] = []
+ let survivorIndex = 0
+ let mergedIndex = 0
+
+ while (survivorIndex < sortedSurvivors.length && mergedIndex < merged.length) {
+ if (recency(sortedSurvivors[survivorIndex]) >= recency(merged[mergedIndex])) {
+ interleaved.push(sortedSurvivors[survivorIndex++])
+ } else {
+ interleaved.push(merged[mergedIndex++])
+ }
+ }
+
+ while (survivorIndex < sortedSurvivors.length) {
+ interleaved.push(sortedSurvivors[survivorIndex++])
+ }
+
+ while (mergedIndex < merged.length) {
+ interleaved.push(merged[mergedIndex++])
+ }
+
+ return interleaved
}
/** Raise a session in recents on user send (before stream / turn resolve). */
@@ -643,24 +679,82 @@ export const setActiveSessionId = (next: Updater) => updateAtom($
export const setActiveSessionStoredIdRotation = (next: Updater) =>
updateAtom($activeSessionStoredIdRotation, next)
-// Transient: a background session finished and the user hasn't opened it since.
-// Written by session-states.ts (handleTransition), cleared here on session open.
+// A background session finished and the user hasn't opened it since. This atom
+// is the transient PAINT layer (what the dots subscribe to); durability lives
+// in session-unread.ts, which persists explicit finish markers + per-session
+// "seen message_count" watermarks and rebuilds this atom from them on every
+// list refresh — so the green dot survives an app restart, and a session that
+// finished while the app was CLOSED still comes up unread. The explicit
+// Mark-as-unread toggle rides the BACKEND watermark instead
+// (SessionDB.set_session_read, session-unread-remote.ts). Written by
+// session-states.ts (live busy→idle edge), cleared here on session open.
export const $unreadFinishedSessionIds = atom([])
-export const markAllSessionsRead = () => {
- if ($unreadFinishedSessionIds.get().length) {
+/** Sidebar "mark all as read" — clears every finished-unread dot. Purely
+ * renderer-local, like the atom itself. */
+export function markAllSessionsRead() {
+ if ($unreadFinishedSessionIds.get().length > 0) {
$unreadFinishedSessionIds.set([])
}
}
+// Last time the user actually viewed a session. A finished turn should only
+// re-arm the unread marker if it settles AFTER this baseline; otherwise an
+// already-viewed completion keeps re-lighting the row.
+export const $lastReadAtBySessionId = atom>({})
+
+/** A new turn started for this session: the read baseline only guarded the
+ * PREVIOUS completion's re-asserts, so drop it — the new turn's finish must
+ * re-light even when it lands in the same millisecond as the last read. */
+export const clearReadBaseline = (storedSessionId: string) => {
+ const map = $lastReadAtBySessionId.get()
+
+ if (storedSessionId in map) {
+ const { [storedSessionId]: _dropped, ...rest } = map
+ $lastReadAtBySessionId.set(rest)
+ }
+}
+
export const setSelectedStoredSessionId = (next: Updater) => {
updateAtom($selectedStoredSessionId, next)
// Opening a session clears its unread state — the user is now looking at it.
+ // Clear the whole conversation family (branch children + compression lineage
+ // root), not just the exact row: the sidebar lights the dot for every alias
+ // of a lineage, so reading any row must clear all of them.
const id = $selectedStoredSessionId.get()
- if (id && $unreadFinishedSessionIds.get().includes(id)) {
- $unreadFinishedSessionIds.set($unreadFinishedSessionIds.get().filter(x => x !== id))
+ if (id) {
+ markSessionRead(id)
}
+
+ // ...and the persisted watermark flag, when the row carried one.
+ if (id) {
+ void clearUnreadOnOpen(id)
+ }
+}
+
+/** Record that the user has seen a session (and its conversation family) at
+ * this moment. Clears the unread set for the family and stores a last-read
+ * baseline so a later completion that settles BEFORE this view is not
+ * re-lit. Must be callable before any focus short-circuit (openSession top)
+ * so re-clicking an already-visible session still clears its dot. */
+export const markSessionRead = (storedSessionId: string | null | undefined) => {
+ if (!storedSessionId) {
+ return
+ }
+
+ const sessions = $sessions.get()
+ const familyIds = new Set(lineageAliases(storedSessionId, sessions))
+
+ const lastReadAt = Date.now()
+ const nextReadMap = { ...$lastReadAtBySessionId.get() }
+
+ for (const id of familyIds) {
+ nextReadMap[id] = lastReadAt
+ }
+
+ $lastReadAtBySessionId.set(nextReadMap)
+ $unreadFinishedSessionIds.set($unreadFinishedSessionIds.get().filter(id => !familyIds.has(id)))
}
export const setMessages = (next: Updater) => updateAtom($messages, next)
diff --git a/apps/desktop/src/store/statusbar-prefs.ts b/apps/desktop/src/store/statusbar-prefs.ts
index 612c9be18e..7318e18d7e 100644
--- a/apps/desktop/src/store/statusbar-prefs.ts
+++ b/apps/desktop/src/store/statusbar-prefs.ts
@@ -51,3 +51,20 @@ export function setStatusbarItemVisible(id: string, visible: boolean) {
$statusbarHiddenIds.set(visible ? hidden.filter(entry => entry !== id) : [...hidden, id])
}
+
+/** Pure so the menu can derive its reset row's disabled state from the hidden
+ * list it already subscribes to, rather than reading the atom out of band.
+ * Set-compared: order is incidental (items are appended as they're hidden) and
+ * a duplicated id shouldn't read as a customization. */
+export function isStatusbarLayoutDefault(hidden: readonly string[]) {
+ const ids = new Set(hidden)
+
+ return ids.size === STATUSBAR_HIDDEN_BY_DEFAULT.length && STATUSBAR_HIDDEN_BY_DEFAULT.every(id => ids.has(id))
+}
+
+/** Put the show/hide set back to what ships. Only touches item layout — whole-bar
+ * visibility is a separate preference, and resetting from the bar's own menu
+ * shouldn't make the bar the user is right-clicking disappear. */
+export function resetStatusbarLayout() {
+ $statusbarHiddenIds.set([...STATUSBAR_HIDDEN_BY_DEFAULT])
+}
diff --git a/apps/desktop/src/store/subagents.test.ts b/apps/desktop/src/store/subagents.test.ts
index 254a7a22f4..74a604a026 100644
--- a/apps/desktop/src/store/subagents.test.ts
+++ b/apps/desktop/src/store/subagents.test.ts
@@ -190,4 +190,148 @@ describe('subagent store', () => {
.sort()
).toEqual(['c', 'd'])
})
+
+ // Regression test for #73728: backend terminal statuses like `timeout` and
+ // `error` were normalised to `running`, making timed-out subagents immortal
+ // in the active status stack. `cancelled`/`canceled` must also map to
+ // `interrupted`.
+ it('normalises backend terminal statuses to recognised SubagentStatus values', () => {
+ upsertSubagent('s1', { goal: 'a', status: 'running', subagent_id: 'a', task_index: 0 })
+ upsertSubagent('s1', { goal: 'b', status: 'running', subagent_id: 'b', task_index: 1 })
+ upsertSubagent('s1', { goal: 'c', status: 'running', subagent_id: 'c', task_index: 2 })
+ upsertSubagent('s1', { goal: 'd', status: 'running', subagent_id: 'd', task_index: 3 })
+
+ // Emit terminal events with backend-native status strings
+ upsertSubagent(
+ 's1',
+ { status: 'timeout', subagent_id: 'a', task_index: 0, summary: 'timed out' },
+ false,
+ 'subagent.complete'
+ )
+ upsertSubagent(
+ 's1',
+ { status: 'error', subagent_id: 'b', task_index: 1, summary: 'errored' },
+ false,
+ 'subagent.complete'
+ )
+ upsertSubagent('s1', { status: 'cancelled', subagent_id: 'c', task_index: 2 }, false, 'subagent.complete')
+ upsertSubagent('s1', { status: 'canceled', subagent_id: 'd', task_index: 3 }, false, 'subagent.complete')
+
+ const items = listFor('s1')
+ const byId = Object.fromEntries(items.map(i => [i.id, i]))
+
+ // timeout → failed
+ expect(byId['a']?.status).toBe('failed')
+ expect(byId['a']?.currentTool).toBeUndefined()
+
+ // error → failed
+ expect(byId['b']?.status).toBe('failed')
+
+ // cancelled → interrupted
+ expect(byId['c']?.status).toBe('interrupted')
+
+ // canceled → interrupted
+ expect(byId['d']?.status).toBe('interrupted')
+
+ // All four are terminal — prune should remove them all
+ pruneFinishedSessionSubagents('s1')
+ expect(listFor('s1')).toHaveLength(0)
+ })
+
+ // The backend completes subagents with status "timeout" (hard child timeout,
+ // delegation.child_timeout_seconds) and no summary — synthesize the reason
+ // so the failed row explains itself instead of rendering as a bare failure.
+ it('maps backend timeout status to a terminal failure with a synthesized reason', () => {
+ upsertSubagent('s1', { goal: 'scan files', status: 'running', subagent_id: 't1', task_index: 0 })
+ upsertSubagent(
+ 's1',
+ { status: 'timeout', subagent_id: 't1', task_index: 0, duration_seconds: 612.3 },
+ false,
+ 'subagent.complete'
+ )
+
+ const item = listFor('s1')[0]
+ expect(item?.status).toBe('failed')
+ expect(item?.durationSeconds).toBe(612.3)
+ expect(item?.summary).toBe('Timed out after 612.3s')
+
+ // A timed-out row must be pruned at the next message.start boundary like
+ // any other finished row — it must not linger as a live spinner.
+ pruneFinishedSessionSubagents('s1')
+ expect(listFor('s1')).toHaveLength(0)
+ })
+
+ it('falls back to a placeholder when timeout duration is missing', () => {
+ upsertSubagent('s1', { goal: 'scan files', status: 'running', subagent_id: 't2', task_index: 0 })
+ upsertSubagent('s1', { status: 'timeout', subagent_id: 't2', task_index: 0 }, false, 'subagent.complete')
+
+ expect(listFor('s1')[0]?.summary).toBe('Timed out after ?s')
+ })
+
+ // Fail-closed guard: subagent.complete is terminal by definition, so an
+ // unrecognized status on it must not resurrect a row as 'running'. Live
+ // events keep the lenient fallback (a status we don't know is still active).
+ it('fails closed on unrecognized completion statuses but stays lenient for live events', () => {
+ upsertSubagent('s1', { goal: 'scan files', status: 'running', subagent_id: 'u1', task_index: 0 })
+ upsertSubagent(
+ 's1',
+ { status: 'some_future_terminal_status', subagent_id: 'u1', task_index: 0 },
+ false,
+ 'subagent.complete'
+ )
+ expect(listFor('s1')[0]?.status).toBe('failed')
+ expect(activeSubagentCount(listFor('s1'))).toBe(0)
+
+ upsertSubagent('s1', { goal: 'scan files', status: 'running', subagent_id: 'u2', task_index: 1 })
+ upsertSubagent(
+ 's1',
+ { status: 'some_future_live_status', subagent_id: 'u2', task_index: 1, text: 'still working' },
+ false,
+ 'subagent.progress'
+ )
+ expect(listFor('s1')[1]?.status).toBe('running')
+ expect(activeSubagentCount(listFor('s1'))).toBe(1)
+ })
+
+ // Folded in from PR #85995: a subagent.complete carrying a still-active
+ // payload status ('running'/'queued') must also settle as failed — the
+ // event itself is the source of truth that the child is done.
+ it.each(['running', 'queued'] as const)(
+ 'treats a completion event with %s payload status as terminal failure',
+ status => {
+ upsertSubagent(
+ 's1',
+ {
+ goal: 'inconsistent completion',
+ status: 'running',
+ subagent_id: 'ic1',
+ task_index: 0,
+ tool_name: 'search_files'
+ },
+ true,
+ 'subagent.start'
+ )
+ upsertSubagent('s1', { status, subagent_id: 'ic1', task_index: 0 }, false, 'subagent.complete')
+
+ const items = listFor('s1')
+ expect(items[0]?.status).toBe('failed')
+ expect(items[0]?.currentTool).toBeUndefined()
+ expect(activeSubagentCount(items)).toBe(0)
+ }
+ )
+
+ // Folded in from PR #80045 (#80018): a late progress event must not revive
+ // the spinner after a terminal completion — the row stays settled.
+ it('does not regress to running when a late running event arrives after timeout', () => {
+ upsertSubagent('s1', { goal: 'task', status: 'running', subagent_id: 'late1', task_index: 0 })
+ upsertSubagent(
+ 's1',
+ { goal: 'task', status: 'timeout', subagent_id: 'late1', summary: 'Timed out', task_index: 0 },
+ true,
+ 'subagent.complete'
+ )
+ upsertSubagent('s1', { goal: 'task', status: 'running', subagent_id: 'late1', task_index: 0, text: 'late' })
+
+ expect(listFor('s1')[0]?.status).toBe('failed')
+ })
})
diff --git a/apps/desktop/src/store/subagents.ts b/apps/desktop/src/store/subagents.ts
index 6127b15183..7196f14a47 100644
--- a/apps/desktop/src/store/subagents.ts
+++ b/apps/desktop/src/store/subagents.ts
@@ -55,8 +55,29 @@ const str = (v: unknown) => (isStr(v) ? v : '')
const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined)
const strList = (v: unknown) => (Array.isArray(v) ? v.filter(isStr) : [])
-const asStatus = (v: unknown): SubagentStatus =>
- v === 'completed' || v === 'failed' || v === 'interrupted' || v === 'queued' ? v : 'running'
+const asStatus = (v: unknown, terminalEvent = false): SubagentStatus => {
+ if (v === 'completed' || v === 'failed' || v === 'interrupted') {
+ return v
+ }
+
+ if (v === 'timeout' || v === 'error') {
+ return 'failed'
+ }
+
+ if (v === 'cancelled' || v === 'canceled') {
+ return 'interrupted'
+ }
+
+ // Fail closed on completion: a subagent.complete event is terminal by
+ // definition, so an unrecognized (or still-active 'queued'/'running')
+ // status must render as a failure rather than leave a dead row spinning
+ // as 'running' forever. Live events keep the lenient fallback.
+ if (terminalEvent) {
+ return 'failed'
+ }
+
+ return v === 'queued' ? v : 'running'
+}
const compact = (text: string, max = PREVIEW_MAX) => {
const line = text.replace(/\s+/g, ' ').trim()
@@ -106,6 +127,15 @@ const appendStream = (stream: SubagentStreamEntry[], entry: SubagentStreamEntry)
return [...stream, entry].slice(-MAX_STREAM)
}
+// The backend sends no summary on a hard child timeout (only a preview like
+// "Timed out after 612.3s" + duration_seconds). Synthesize it so the terminal
+// row explains why it failed instead of rendering as a bare failure.
+const timeoutSummary = (payload: SubagentPayload): string => {
+ const seconds = num(payload.duration_seconds)
+
+ return str(payload.status) === 'timeout' ? `Timed out after ${seconds ?? '?'}s` : ''
+}
+
function streamFromPayload(
payload: SubagentPayload,
status: SubagentStatus,
@@ -137,7 +167,7 @@ function streamFromPayload(
out.push({ at, kind: 'thinking', text })
}
- const summary = compact(str(payload.summary) || str(payload.text))
+ const summary = compact(str(payload.summary) || str(payload.text) || timeoutSummary(payload))
if (TERMINAL.has(status) && summary) {
out.push({ at, isError: status === 'failed', kind: 'summary', text: summary })
@@ -148,7 +178,7 @@ function streamFromPayload(
function toProgress(payload: SubagentPayload, prev: SubagentProgress | undefined, eventType = ''): SubagentProgress {
const at = Date.now()
- const status = asStatus(payload.status)
+ const status = asStatus(payload.status, eventType === 'subagent.complete')
const tool = str(payload.tool_name)
const stream = streamFromPayload(payload, status, eventType, at).reduce(appendStream, prev?.stream ?? [])
const filesRead = strList(payload.files_read)
@@ -173,7 +203,7 @@ function toProgress(payload: SubagentPayload, prev: SubagentProgress | undefined
filesRead: filesRead.length ? filesRead : (prev?.filesRead ?? []),
filesWritten: filesWritten.length ? filesWritten : (prev?.filesWritten ?? []),
stream,
- summary: str(payload.summary) || prev?.summary,
+ summary: str(payload.summary) || timeoutSummary(payload) || prev?.summary || undefined,
currentTool: TERMINAL.has(status) ? undefined : tool || prev?.currentTool
}
}
diff --git a/apps/desktop/src/store/suggestion-providers/github.test.ts b/apps/desktop/src/store/suggestion-providers/github.test.ts
new file mode 100644
index 0000000000..654db5d139
--- /dev/null
+++ b/apps/desktop/src/store/suggestion-providers/github.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+
+import { githubHit } from './github'
+
+describe('githubHit', () => {
+ it('matches a completed whole-word github mention', () => {
+ expect(githubHit('open a github issue for this')).toBe(true)
+ expect(githubHit('check GitHub please')).toBe(true)
+ })
+
+ it('does not fire while the word is still under the caret', () => {
+ expect(githubHit('let me check github')).toBe(false)
+ })
+
+ it('does not match inside other words', () => {
+ expect(githubHit('mygithubby thing here')).toBe(false)
+ })
+
+ it('matches a pasted github.com link immediately', () => {
+ expect(githubHit('review https://github.com/NousResearch/hermes-agent/pull/1')).toBe(true)
+ expect(githubHit('see https://gist.github.com/foo/abc')).toBe(true)
+ })
+
+ it('does not match lookalike domains', () => {
+ expect(githubHit('see https://notgithub.com/x more')).toBe(false)
+ expect(githubHit('see https://github.com.evil.example/x more')).toBe(false)
+ })
+})
diff --git a/apps/desktop/src/store/suggestion-providers/github.ts b/apps/desktop/src/store/suggestion-providers/github.ts
new file mode 100644
index 0000000000..934f54a863
--- /dev/null
+++ b/apps/desktop/src/store/suggestion-providers/github.ts
@@ -0,0 +1,116 @@
+import { requestComposerFocus, requestComposerInsert } from '@/app/chat/composer/focus'
+import { getGhAuthStatus } from '@/hermes'
+import { translateNow } from '@/i18n'
+import { type ComposerSuggestion, registerDraftProvider } from '@/store/composer-suggestions'
+
+/**
+ * GitHub draft provider — the deliberate NON-MCP integration path.
+ *
+ * GitHub has no entry in the MCP catalog and never gets a connect pill: its
+ * hosted MCP requires a per-host OAuth app (generic Dynamic Client
+ * Registration 404s at /register), and more importantly the bundled
+ * github/* skills driving the `gh` CLI are a strictly more capable
+ * integration (PRs, reviews, issues, releases, workflows) than the remote
+ * MCP's tool surface. So when the draft signals GitHub intent, the right
+ * offer is onboarding onto the skills:
+ *
+ * - `gh` already authenticated → no pill. The skills just work; suggesting
+ * setup at an already-set-up user is noise.
+ * - not authenticated (or gh missing) → offer the `github-auth` skill. The
+ * invoke prefixes the draft with `/github-auth` (same reversible,
+ * never-sends-on-your-behalf contract as the skill provider) and the
+ * agent walks the user through `gh auth login` / install.
+ *
+ * The auth probe is served by `GET /api/git/gh-auth` (cached backend-side);
+ * a probe failure (older backend, transient error) suggests nothing rather
+ * than nagging.
+ */
+
+const AUTH_TTL_MS = 5 * 60_000
+const SKILL_NAME = 'github-auth'
+
+let needsSetup: boolean | null = null
+let checkedAt = 0
+
+/** Drop the cached gh-auth probe (e.g. after the setup flow completes). */
+export function invalidateGithubSuggestionIndex(): void {
+ needsSetup = null
+ checkedAt = 0
+}
+
+// Whole-word "github" mention or a pasted github.com link. Same completed-
+// word discipline as the MCP provider: a keyword still under the caret is a
+// word in progress, not intent — but a pasted host counts immediately.
+const KEYWORD_RE = /(?]*@)?([\w.-]*\.)?github\.com(?=[/\s:,)\]}"'<>]|$)/i
+
+/** Pure matcher, exported for tests. */
+export function githubHit(text: string): boolean {
+ if (HOST_RE.test(text)) {
+ return true
+ }
+
+ // Keyword matching runs with URLs removed: "github" inside a pasted
+ // lookalike domain (notgithub.com, github.com.evil.example) is the URL's
+ // business, and the host matcher above already rejected it.
+ const withoutUrls = text.replace(/https?:\/\/[^\s]+/gi, ' ')
+ const match = KEYWORD_RE.exec(withoutUrls.toLowerCase())
+
+ // Completed word: at least one character follows the mention.
+ return match !== null && match.index + 'github'.length < withoutUrls.length
+}
+
+async function loadNeedsSetup(): Promise {
+ if (needsSetup !== null && Date.now() - checkedAt < AUTH_TTL_MS) {
+ return needsSetup
+ }
+
+ const status = await getGhAuthStatus()
+
+ needsSetup = !status.authenticated
+ checkedAt = Date.now()
+
+ return needsSetup
+}
+
+function toSuggestion(): ComposerSuggestion {
+ const copy = (key: string, ...args: unknown[]) => translateNow(`composer.githubSuggestions.${key}`, ...args)
+
+ return {
+ brand: 'github',
+ doneLabel: copy('done'),
+ doneTip: copy('doneTip'),
+ id: SKILL_NAME,
+ invoke: async () => {
+ // Prefix, don't replace — and never send. The agent takes over when
+ // the user sends: the github-auth skill installs gh if needed and
+ // runs the device-code OAuth flow.
+ requestComposerInsert(`/${SKILL_NAME} `, { mode: 'prefix' })
+ requestComposerFocus()
+ },
+ label: copy('label'),
+ provider: 'github',
+ tip: copy('tip'),
+ workingLabel: copy('label'),
+ workingTip: copy('tip')
+ }
+}
+
+registerDraftProvider('github', async ({ text }) => {
+ const trimmed = text.trimStart()
+
+ // Already a slash command (possibly ours from a previous click).
+ if (trimmed.startsWith('/')) {
+ return []
+ }
+
+ if (!githubHit(text)) {
+ return []
+ }
+
+ if (!(await loadNeedsSetup())) {
+ return []
+ }
+
+ return [toSuggestion()]
+})
diff --git a/apps/desktop/src/store/suggestion-providers/mcp.test.ts b/apps/desktop/src/store/suggestion-providers/mcp.test.ts
index 9de2ad08b0..f83a5b2c4b 100644
--- a/apps/desktop/src/store/suggestion-providers/mcp.test.ts
+++ b/apps/desktop/src/store/suggestion-providers/mcp.test.ts
@@ -1,5 +1,7 @@
import { describe, expect, it } from 'vitest'
+import { MCP_DIRECTORY } from '@/lib/mcp-directory'
+
import { matchSuggestions } from './mcp'
const INDEX = [
@@ -75,4 +77,27 @@ describe('matchSuggestions', () => {
{ keyword: 'sentry.io', server: 'sentry' }
])
})
+
+ it('a keyword still under the caret does not fire yet', () => {
+ // The debounce elapses mid-thought; the word is only intent once
+ // something follows it.
+ expect(matchSuggestions('can you check linear', INDEX)).toEqual([])
+ expect(matchSuggestions('can you check linear ', INDEX)).toEqual([{ keyword: 'linear', server: 'linear' }])
+ expect(matchSuggestions('can you check linear?', INDEX)).toEqual([{ keyword: 'linear', server: 'linear' }])
+ })
+
+ it('a pasted URL fires even as the last thing in the draft', () => {
+ // Pasting is a deliberate act — the completed-word guard is keyword-only.
+ const index = [{ hosts: ['linear.app'], keywords: ['linear'], server: 'linear' }]
+
+ expect(matchSuggestions('look at https://linear.app/team/issue/ABC-1', index)).toEqual([
+ { keyword: 'linear.app', server: 'linear' }
+ ])
+ })
+
+ it('does not offer GitHub through the generic OAuth registration path', () => {
+ const index = MCP_DIRECTORY.map(entry => ({ hosts: entry.hosts, keywords: entry.keywords, server: entry.name }))
+
+ expect(matchSuggestions('connect github', index)).toEqual([])
+ })
})
diff --git a/apps/desktop/src/store/suggestion-providers/mcp.ts b/apps/desktop/src/store/suggestion-providers/mcp.ts
index 7048aed84f..4cdc535066 100644
--- a/apps/desktop/src/store/suggestion-providers/mcp.ts
+++ b/apps/desktop/src/store/suggestion-providers/mcp.ts
@@ -2,13 +2,14 @@ import {
addMcpServer,
authMcpServer,
cancelMcpOAuthFlow,
+ getMcpCatalog,
getMcpOAuthFlow,
listMcpServers,
removeMcpServer
} from '@/hermes'
import { translateNow } from '@/i18n'
import { completeMcpDesktopOAuth, McpOAuthCancelled } from '@/lib/mcp-dashboard-oauth'
-import { directoryEntry, MCP_DIRECTORY } from '@/lib/mcp-directory'
+import { MCP_DIRECTORY } from '@/lib/mcp-directory'
import { prettyName } from '@/lib/text'
import { type ComposerSuggestion, registerDraftProvider } from '@/store/composer-suggestions'
import { $gateway } from '@/store/gateway'
@@ -17,15 +18,20 @@ import { notifyError } from '@/store/notifications'
/**
* The MCP draft provider — the suggestion bus's founding member (PR #85036).
*
- * Matches the draft against the desktop's directory of official hosted MCP
- * remotes (`lib/mcp-directory.ts` — deliberately NOT the reviewed install
- * catalog) by whole-word keyword and pasted-link host suffix, excluding
- * servers already configured. A suggestion's invoke runs the whole connect:
- * validated config write → browser OAuth → live tool reload, with rollback
- * on cancel/failure so a decline never strands a half-configured server.
+ * Matches the draft against the Nous-approved MCP catalog's `suggest`
+ * metadata (`GET /api/mcp/catalog` — the same reviewed manifests behind
+ * `hermes mcp catalog`), by whole-word keyword and pasted-link host suffix,
+ * excluding servers already configured. The catalog is the single source of
+ * truth for suggestible servers; the renderer-local `lib/mcp-directory.ts`
+ * remains only as a compatibility rung for older backends whose catalog
+ * entries carry no `suggest` field. A suggestion's invoke runs the whole
+ * connect: validated config write → browser OAuth → live tool reload, with
+ * rollback on cancel/failure so a decline never strands a half-configured
+ * server.
*/
const CONFIGURED_TTL_MS = 5 * 60_000
+const CATALOG_TTL_MS = 5 * 60_000
// Names already present in mcp_servers config (enabled or not) — those need a
// toggle/auth at most, not an "add this server" pill. Cached briefly; a miss
@@ -33,10 +39,25 @@ const CONFIGURED_TTL_MS = 5 * 60_000
let configuredNames: Set | null = null
let configuredAt = 0
-/** Drop the configured-servers cache (profile switch / after an install). */
+interface SuggestibleServer {
+ server: string
+ keywords: string[]
+ hosts?: string[]
+ /** Streamable-HTTP/SSE endpoint written to config on invoke. */
+ url: string
+}
+
+// Suggestible servers from the catalog (entries with `suggest` + an http
+// url), or the static directory on backends that predate `suggest`.
+let suggestible: SuggestibleServer[] | null = null
+let suggestibleAt = 0
+
+/** Drop the caches (profile switch / after an install). */
export function invalidateMcpSuggestionIndex(): void {
configuredNames = null
configuredAt = 0
+ suggestible = null
+ suggestibleAt = 0
}
async function loadConfiguredNames(): Promise> {
@@ -52,6 +73,39 @@ async function loadConfiguredNames(): Promise> {
return configuredNames
}
+async function loadSuggestible(): Promise {
+ if (suggestible && Date.now() - suggestibleAt < CATALOG_TTL_MS) {
+ return suggestible
+ }
+
+ const { entries } = await getMcpCatalog()
+
+ const fromCatalog: SuggestibleServer[] = entries
+ .filter(entry => entry.suggest && entry.url && (entry.suggest.keywords.length > 0 || entry.suggest.hosts.length > 0))
+ .map(entry => ({
+ hosts: entry.suggest!.hosts,
+ keywords: entry.suggest!.keywords,
+ server: entry.name,
+ url: entry.url!
+ }))
+
+ // Compatibility rung: an older backend serves the catalog without any
+ // `suggest` metadata. Fall back to the static directory rather than
+ // silently losing the feature (remove once the backend contract bumps).
+ suggestible =
+ fromCatalog.length > 0
+ ? fromCatalog
+ : MCP_DIRECTORY.map(entry => ({
+ hosts: entry.hosts,
+ keywords: entry.keywords,
+ server: entry.name,
+ url: entry.url
+ }))
+ suggestibleAt = Date.now()
+
+ return suggestible
+}
+
interface KeywordEntry {
server: string
keywords: string[]
@@ -84,11 +138,32 @@ export interface McpMatch {
const MAX_MATCHES = 2
+// Whole-word (unicode-aware) keyword hit that the user has FINISHED typing:
+// at least one character must follow the match (the lookahead already
+// guarantees it's a boundary). A hit still under the caret — "figma" as the
+// last thing typed, debounce elapsed mid-thought — is not intent yet, it's
+// eavesdropping on a word in progress; the pill waits for the space/period.
+const keywordHit = (haystack: string, candidate: string): boolean => {
+ const pattern = new RegExp(
+ `(? hosts.some(candidate => hostMatches(candidate, suffix)))
- // Whole-word match so "linearly" doesn't suggest Linear. Directory
+ // Whole-word match so "linearly" doesn't suggest Linear. Suggest
// keywords are lowercase; multi-word keywords match as phrases.
- const keyword =
- host ??
- entry.keywords.find(candidate =>
- new RegExp(
- `(? keywordHit(haystack, candidate))
if (keyword) {
matches.push({ keyword, server: entry.server })
@@ -119,19 +187,13 @@ export function matchSuggestions(text: string, index: KeywordEntry[]): McpMatch[
return matches
}
-async function connect(server: string, sessionId: string | null, cancelled: () => boolean): Promise {
- const known = directoryEntry(server)
-
- if (!known) {
- return
- }
-
+async function connect(known: SuggestibleServer, sessionId: string | null, cancelled: () => boolean): Promise {
try {
- await addMcpServer({ name: known.name, url: known.url })
+ await addMcpServer({ name: known.server, url: known.url })
try {
await completeMcpDesktopOAuth({
- serverName: known.name,
+ serverName: known.server,
start: authMcpServer,
status: getMcpOAuthFlow,
cancelled,
@@ -142,7 +204,7 @@ async function connect(server: string, sessionId: string | null, cancelled: () =
// Decline/failure means "no server" — roll back the config write
// rather than stranding an unauthorized entry (authoritative-write
// rule). Best-effort; the primary error wins.
- await removeMcpServer(known.name).catch(() => {})
+ await removeMcpServer(known.server).catch(() => {})
throw error
}
@@ -156,14 +218,14 @@ async function connect(server: string, sessionId: string | null, cancelled: () =
invalidateMcpSuggestionIndex()
} catch (error) {
if (!(error instanceof McpOAuthCancelled)) {
- notifyError(error, translateNow('composer.mcpSuggestions.connectFailed', prettyName(server)))
+ notifyError(error, translateNow('composer.mcpSuggestions.connectFailed', prettyName(known.server)))
}
throw error
}
}
-function toSuggestion(match: McpMatch, sessionId: string | null): ComposerSuggestion {
+function toSuggestion(match: McpMatch, known: SuggestibleServer, sessionId: string | null): ComposerSuggestion {
const name = prettyName(match.server)
const copy = (key: string, ...args: unknown[]) => translateNow(`composer.mcpSuggestions.${key}`, ...args)
@@ -172,7 +234,9 @@ function toSuggestion(match: McpMatch, sessionId: string | null): ComposerSugges
doneLabel: copy('added', name),
doneTip: copy('addedTip'),
id: match.server,
- invoke: context => connect(match.server, sessionId, context.cancelled),
+ // The pill's session wins over the one captured at sample time: the reload
+ // has to reach the session the user is actually looking at.
+ invoke: context => connect(known, context.sessionId ?? sessionId, context.cancelled),
label: copy('label', name),
provider: 'mcp',
tip: copy('tip', match.keyword),
@@ -182,16 +246,19 @@ function toSuggestion(match: McpMatch, sessionId: string | null): ComposerSugges
}
registerDraftProvider('mcp', async ({ sessionId, text }) => {
- const index = MCP_DIRECTORY.map(entry => ({ hosts: entry.hosts, keywords: entry.keywords, server: entry.name }))
+ // Catalog unreachable — suggest nothing rather than mis-suggest.
+ const index = await loadSuggestible()
const candidates = matchSuggestions(text, index)
- // Fast path: no keyword hit at all → nothing, without touching the network.
+ // Fast path: no keyword hit at all → skip the servers fetch.
if (candidates.length === 0) {
return []
}
- // Server list unreachable — suggest nothing rather than mis-suggest.
const configured = await loadConfiguredNames()
+ const byName = new Map(index.map(entry => [entry.server, entry]))
- return candidates.filter(candidate => !configured.has(candidate.server)).map(match => toSuggestion(match, sessionId))
+ return candidates
+ .filter(candidate => !configured.has(candidate.server))
+ .map(match => toSuggestion(match, byName.get(match.server)!, sessionId))
})
diff --git a/apps/desktop/src/store/suggestion-providers/repair.ts b/apps/desktop/src/store/suggestion-providers/repair.ts
index f0ee2265c0..159348d486 100644
--- a/apps/desktop/src/store/suggestion-providers/repair.ts
+++ b/apps/desktop/src/store/suggestion-providers/repair.ts
@@ -73,7 +73,7 @@ function toSuggestion(server: string, sessionId: string | null): ComposerSuggest
doneTip: copy('doneTip'),
icon: 'plug',
id: server,
- invoke: context => reconnect(server, sessionId, context.cancelled),
+ invoke: context => reconnect(server, context.sessionId ?? sessionId, context.cancelled),
label: copy('label', name),
provider: 'repair',
tip: copy('tip', name),
diff --git a/apps/desktop/src/store/suggestion-providers/skill.test.ts b/apps/desktop/src/store/suggestion-providers/skill.test.ts
index 67eef945d3..f85c29675b 100644
--- a/apps/desktop/src/store/suggestion-providers/skill.test.ts
+++ b/apps/desktop/src/store/suggestion-providers/skill.test.ts
@@ -1,28 +1,127 @@
import { describe, expect, it } from 'vitest'
-import { skillPattern } from './skill'
+import type { ChatMessage } from '@/lib/chat-messages'
-describe('skillPattern', () => {
- it('matches the exact name as a whole word', () => {
- expect(skillPattern('perf').test('run the perf loop')).toBe(true)
- expect(skillPattern('perf').test('performance is bad')).toBe(false)
+import { collidesWithWorkspace, skillHit, skillPattern, skillTouchedInMessages } from './skill'
+
+// skillHit is the provider's real predicate: a whole-word match that the user
+// has finished typing (at least one character follows it).
+const hits = (name: string, draft: string) => skillHit(skillPattern(name), draft.toLowerCase())
+
+describe('skillPattern + skillHit', () => {
+ it('matches the exact name as a completed whole word', () => {
+ expect(hits('perf', 'run the perf loop')).toBe(true)
+ expect(hits('perf', 'performance is bad')).toBe(false)
})
it('hyphenated names also match spaced phrasing', () => {
- expect(skillPattern('pr-ready').test('make this pr ready')).toBe(true)
- expect(skillPattern('pr-ready').test('run pr-ready on it')).toBe(true)
- expect(skillPattern('pr_ready').test('pr ready please')).toBe(true)
+ expect(hits('pr-ready', 'make this pr ready pls')).toBe(true)
+ expect(hits('pr-ready', 'run pr-ready on it')).toBe(true)
+ expect(hits('pr_ready', 'pr ready please')).toBe(true)
})
it('never matches inside other words', () => {
- expect(skillPattern('read').test('i already did')).toBe(false)
- expect(skillPattern('work').test('reworked the layout')).toBe(false)
+ expect(hits('read', 'i already did')).toBe(false)
+ expect(hits('work', 'reworked the layout')).toBe(false)
// Suffix boundary includes hyphen: "clean" must not fire inside "clean-up"
// (a different skill may own that name).
- expect(skillPattern('clean').test('do a clean-up pass')).toBe(false)
+ expect(hits('clean', 'do a clean-up pass')).toBe(false)
})
it('is case-insensitive via lowercased input', () => {
- expect(skillPattern('Clean').test('please clean this diff')).toBe(true)
+ expect(hits('Clean', 'please clean this diff')).toBe(true)
+ })
+
+ it('a name still under the caret is not a hit yet', () => {
+ // The debounce fires while the word is the last thing typed — wait for
+ // the next keystroke to call it intent.
+ expect(hits('perf', 'run perf')).toBe(false)
+ expect(hits('perf', 'run perf ')).toBe(true)
+ expect(hits('perf', 'run perf.')).toBe(true)
+ })
+
+ it('an earlier completed occurrence still counts', () => {
+ expect(hits('perf', 'perf first, then more perf')).toBe(true)
+ })
+})
+
+describe('collidesWithWorkspace', () => {
+ it('suppresses a skill named exactly like the cwd folder', () => {
+ expect(collidesWithWorkspace('hermes-agent', '/Users/b/www/hermes-agent')).toBe(true)
+ })
+
+ it('suppresses inside worktree-suffixed folders too', () => {
+ expect(collidesWithWorkspace('hermes-agent', '/Users/b/www/hermes-agent-suggest')).toBe(true)
+ })
+
+ it('does not suppress on substring-only overlap', () => {
+ // "perf" inside "perfect-app" is not a homonym of the project.
+ expect(collidesWithWorkspace('perf', '/Users/b/www/perfect-app')).toBe(false)
+ expect(collidesWithWorkspace('clean', '/Users/b/www/hermes-agent')).toBe(false)
+ })
+
+ it('never collides when detached (empty cwd)', () => {
+ expect(collidesWithWorkspace('hermes-agent', '')).toBe(false)
+ })
+})
+
+// -- skillTouchedInMessages ---------------------------------------------------
+
+const toolCall = (toolName: string, args?: unknown, argsText = ''): ChatMessage => ({
+ id: 't',
+ role: 'assistant',
+ parts: [{ args: args as never, argsText, toolCallId: 'x', toolName, type: 'tool-call' }]
+})
+
+const userText = (text: string): ChatMessage => ({
+ id: 'u',
+ role: 'user',
+ parts: [{ text, type: 'text' }]
+})
+
+describe('skillTouchedInMessages', () => {
+ it('detects a skill_view load of the skill', () => {
+ expect(skillTouchedInMessages('pr-ready', [toolCall('skill_view', { name: 'pr-ready' })])).toBe(true)
+ })
+
+ it('detects a skill_manage touch of the skill', () => {
+ expect(skillTouchedInMessages('pr-ready', [toolCall('skill_manage', { action: 'patch', name: 'pr-ready' })])).toBe(
+ true
+ )
+ })
+
+ it('matches qualified skill names (category/name, plugin:name)', () => {
+ expect(
+ skillTouchedInMessages('hermes-agent-dev', [toolCall('skill_view', { name: 'github/hermes-agent-dev' })])
+ ).toBe(true)
+ expect(
+ skillTouchedInMessages('writing-plans', [toolCall('skill_view', { name: 'superpowers:writing-plans' })])
+ ).toBe(true)
+ })
+
+ it('falls back to argsText when args were not parsed', () => {
+ expect(skillTouchedInMessages('pr-ready', [toolCall('skill_view', undefined, '{"name":"pr-ready"}')])).toBe(true)
+ })
+
+ it('detects the user loading the skill via its slash command', () => {
+ expect(skillTouchedInMessages('pr-ready', [userText('/pr-ready check this branch')])).toBe(true)
+ expect(skillTouchedInMessages('pr-ready', [userText('/pr-ready')])).toBe(true)
+ })
+
+ it('ignores touches of OTHER skills and non-skill tools', () => {
+ expect(skillTouchedInMessages('pr-ready', [toolCall('skill_view', { name: 'clean' })])).toBe(false)
+ expect(skillTouchedInMessages('pr-ready', [toolCall('read_file', { path: 'pr-ready' })])).toBe(false)
+ // Slash prefix must be exact — /pr-ready-extra is a different command.
+ expect(skillTouchedInMessages('pr-ready', [userText('/pr-ready-extra go')])).toBe(false)
+ // Merely mentioning the name in prose is not a load.
+ expect(skillTouchedInMessages('pr-ready', [userText('is pr-ready any good?')])).toBe(false)
+ })
+
+ it('is case-insensitive on the stored arg', () => {
+ expect(skillTouchedInMessages('pr-ready', [toolCall('skill_view', { name: 'PR-Ready' })])).toBe(true)
+ })
+
+ it('empty transcript touches nothing', () => {
+ expect(skillTouchedInMessages('pr-ready', [])).toBe(false)
})
})
diff --git a/apps/desktop/src/store/suggestion-providers/skill.ts b/apps/desktop/src/store/suggestion-providers/skill.ts
index 94b84f8885..6b203aad55 100644
--- a/apps/desktop/src/store/suggestion-providers/skill.ts
+++ b/apps/desktop/src/store/suggestion-providers/skill.ts
@@ -1,7 +1,10 @@
import { requestComposerFocus, requestComposerInsert } from '@/app/chat/composer/focus'
import { getSkills } from '@/hermes'
import { translateNow } from '@/i18n'
+import type { ChatMessage } from '@/lib/chat-messages'
import { type ComposerSuggestion, registerDraftProvider } from '@/store/composer-suggestions'
+import { $activeSessionId, $currentCwd, $messages } from '@/store/session'
+import { $sessionStates } from '@/store/session-states'
/**
* Skill-match draft provider: the draft names a skill the user has, so offer
@@ -41,7 +44,34 @@ const escape = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
export function skillPattern(name: string): RegExp {
const flexible = name.toLowerCase().split(/[-_]/).map(escape).join('[-_ ]')
- return new RegExp(`(? {
@@ -62,6 +92,102 @@ async function loadIndex(): Promise {
return index
}
+// ---------------------------------------------------------------------------
+// Already-in-context guard: a skill the session has engaged with must not be
+// re-offered. skill_view loads the whole SKILL.md into the conversation and
+// skill_manage implies the agent is already working with it — clicking the
+// pill would just re-inject content the context already carries (the reported
+// annoyance: a "Use skill" pill for a skill loaded at session start).
+// ---------------------------------------------------------------------------
+
+const SKILL_TOOL_NAMES = new Set(['skill_manage', 'skill_view'])
+
+/** The `name` argument of a skill tool call, however the transcript stored
+ * it: live rows carry a parsed `args` object, hydrated rows may only have
+ * the JSON `argsText`. */
+function skillArgName(part: { args?: unknown; argsText?: unknown }): string {
+ const record = part.args && typeof part.args === 'object' ? (part.args as Record) : null
+
+ if (record && typeof record.name === 'string') {
+ return record.name
+ }
+
+ if (typeof part.argsText === 'string' && part.argsText) {
+ try {
+ const parsed: unknown = JSON.parse(part.argsText)
+
+ if (parsed && typeof parsed === 'object' && typeof (parsed as { name?: unknown }).name === 'string') {
+ return (parsed as { name: string }).name
+ }
+ } catch {
+ // Non-JSON argsText carries no name.
+ }
+ }
+
+ return ''
+}
+
+/** True when the tool-call arg names this skill — exactly, or as the final
+ * segment of a qualified form (`github/hermes-agent-dev`, `plugin:skill`). */
+function argNamesSkill(arg: string, skillName: string): boolean {
+ const value = arg.trim().toLowerCase()
+
+ if (!value) {
+ return false
+ }
+
+ const target = skillName.toLowerCase()
+
+ return value === target || (value.split(/[/:]/).pop() ?? '') === target
+}
+
+/** Session already touched this skill: the agent loaded it (`skill_view`),
+ * edited it (`skill_manage`), or the user sent its `/name` command.
+ * Exported for tests. */
+export function skillTouchedInMessages(skillName: string, messages: readonly ChatMessage[]): boolean {
+ const slash = new RegExp(`^/${escape(skillName.toLowerCase())}(?:\\s|$)`)
+
+ for (const message of messages) {
+ for (const part of message.parts) {
+ if (
+ part.type === 'tool-call' &&
+ SKILL_TOOL_NAMES.has(part.toolName) &&
+ argNamesSkill(skillArgName(part), skillName)
+ ) {
+ return true
+ }
+
+ if (
+ message.role === 'user' &&
+ part.type === 'text' &&
+ typeof part.text === 'string' &&
+ slash.test(part.text.trimStart().toLowerCase())
+ ) {
+ return true
+ }
+ }
+ }
+
+ return false
+}
+
+/** This session's transcript, wherever it currently lives: the per-runtime
+ * mirror ($sessionStates) for any session, falling back to the active view
+ * ($messages) for a session whose mirror hasn't populated yet. */
+function sessionTranscript(sessionId: string | null): readonly ChatMessage[] {
+ const cached = sessionId ? $sessionStates.get()[sessionId]?.messages : undefined
+
+ if (cached?.length) {
+ return cached
+ }
+
+ if (sessionId && sessionId === $activeSessionId.get()) {
+ return $messages.get()
+ }
+
+ return cached ?? []
+}
+
function toSuggestion(name: string): ComposerSuggestion {
const copy = (key: string, ...args: unknown[]) => translateNow(`composer.skillSuggestions.${key}`, ...args)
@@ -84,7 +210,7 @@ function toSuggestion(name: string): ComposerSuggestion {
}
}
-registerDraftProvider('skill', async ({ text }) => {
+registerDraftProvider('skill', async ({ sessionId, text }) => {
const trimmed = text.trimStart()
// Already a slash command (possibly ours from a previous click) — stand
@@ -94,7 +220,17 @@ registerDraftProvider('skill', async ({ text }) => {
}
const haystack = text.toLowerCase()
+ const cwd = $currentCwd.get()
const skills = await loadIndex()
+ const matched = skills.filter(skill => skillHit(skill.pattern, haystack) && !collidesWithWorkspace(skill.name, cwd))
- return skills.filter(skill => skill.pattern.test(haystack)).map(skill => toSuggestion(skill.name))
+ if (matched.length === 0) {
+ return []
+ }
+
+ // Transcript scan only for actual matches — the common no-match sample
+ // never pays for it.
+ const transcript = sessionTranscript(sessionId)
+
+ return matched.filter(skill => !skillTouchedInMessages(skill.name, transcript)).map(skill => toSuggestion(skill.name))
})
diff --git a/apps/desktop/src/store/updates.test.ts b/apps/desktop/src/store/updates.test.ts
index 7507a2f53c..55a9391a1a 100644
--- a/apps/desktop/src/store/updates.test.ts
+++ b/apps/desktop/src/store/updates.test.ts
@@ -123,6 +123,15 @@ describe('maybeNotifyUpdateAvailable', () => {
maybeNotifyUpdateAvailable(status({ behind: 0 }))
expect(notifySpy).not.toHaveBeenCalled()
})
+
+ // FAIL-BEFORE: a shallow installer clone reports behind:null + updateAvailable
+ // (exact count unknowable without a merge-base). The guard treated null as 0
+ // and silently swallowed the notification entirely.
+ it('still notifies with generic copy when the exact behind count is unknown', () => {
+ maybeNotifyUpdateAvailable(status({ behind: null, updateAvailable: true }))
+ expect(notifySpy).toHaveBeenCalledTimes(1)
+ expect(notifySpy.mock.calls[0]?.[0]).toMatchObject({ message: 'A new update is available.' })
+ })
})
describe('reportBackendContract', () => {
diff --git a/apps/desktop/src/store/updates.ts b/apps/desktop/src/store/updates.ts
index 19739a977e..3d234e0d4f 100644
--- a/apps/desktop/src/store/updates.ts
+++ b/apps/desktop/src/store/updates.ts
@@ -206,7 +206,11 @@ export function maybeNotifyUpdateAvailable(status: DesktopUpdateStatus | null) {
return
}
- if ((status.behind ?? 0) <= 0) {
+ const behind = typeof status.behind === 'number' ? status.behind : null
+
+ // behind === null means "update available, exact count unknown" (shallow
+ // clone). That still deserves the toast — just with count-free copy.
+ if ((behind ?? 0) <= 0 && !status.updateAvailable) {
return
}
@@ -218,8 +222,6 @@ export function maybeNotifyUpdateAvailable(status: DesktopUpdateStatus | null) {
return
}
- const behind = status.behind ?? 0
-
notify({
action: {
label: translateNow('notifications.seeWhatsNew'),
@@ -232,7 +234,10 @@ export function maybeNotifyUpdateAvailable(status: DesktopUpdateStatus | null) {
icon: 'gift',
id: UPDATE_TOAST_ID,
kind: 'info',
- message: translateNow('notifications.updateReadyMessage', behind),
+ message:
+ behind !== null && behind > 0
+ ? translateNow('notifications.updateReadyMessage', behind)
+ : translateNow('notifications.updateReadyMessageUnknown'),
onDismiss: () => snoozeUpdateToast(),
title: translateNow('notifications.updateReadyTitle')
})
diff --git a/apps/desktop/src/store/windows.ts b/apps/desktop/src/store/windows.ts
index 7f23c1cdea..3549ce4186 100644
--- a/apps/desktop/src/store/windows.ts
+++ b/apps/desktop/src/store/windows.ts
@@ -110,6 +110,13 @@ export function canOpenNewWindow(): boolean {
return typeof window !== 'undefined' && typeof window.hermesDesktop?.openWindow === 'function'
}
+// True when the shell can hand a session to the user's own terminal emulator.
+// Desktop-only, and a REMOTE connection is excluded by the caller: the terminal
+// we'd open is on this machine, but the session lives on the remote host.
+export function canOpenSessionInTerminal(): boolean {
+ return typeof window !== 'undefined' && typeof window.hermesDesktop?.openSessionInTerminal === 'function'
+}
+
type WindowOpenResult = { ok: boolean; error?: string } | undefined
// Run a window-open bridge call, surfacing any failure as a toast. Shared by the
@@ -149,3 +156,20 @@ export async function openNewWindow(): Promise {
await runWindowOpen(() => window.hermesDesktop.openWindow(), 'Could not open a new window')
}
+
+// Resume a session in the user's own terminal emulator, running the TUI there.
+// `cwd` starts the shell in the session's workspace; `profile` pins the runtime
+// to the profile that owns the session. No-ops gracefully outside Electron.
+export async function openSessionInTerminal(
+ sessionId: string,
+ opts?: { cwd?: string; profile?: string }
+): Promise {
+ if (!sessionId || !canOpenSessionInTerminal()) {
+ return
+ }
+
+ await runWindowOpen(
+ () => window.hermesDesktop.openSessionInTerminal(sessionId, opts),
+ 'Could not open chat in a terminal'
+ )
+}
diff --git a/apps/desktop/src/styles.css b/apps/desktop/src/styles.css
index 3fc1f06996..8d3591e3f8 100644
--- a/apps/desktop/src/styles.css
+++ b/apps/desktop/src/styles.css
@@ -28,6 +28,27 @@
}
}
+/* Continuous decorative animations otherwise keep Chromium's renderer awake
+ behind another app. main.tsx owns this attribute only for the primary
+ window; wake/pet overlays retain their purpose-built visibility behavior. */
+:root[data-renderer-animations-paused] :is(
+ .shimmer,
+ .quest-glow,
+ .pet-egg,
+ .pet-egg__glow,
+ .pet-egg-shadow,
+ .pet-wobble,
+ .progress-slide,
+ .kanban-arc
+ ),
+:root[data-renderer-animations-paused] .arc-border::before,
+:root[data-renderer-animations-paused]
+ [data-slot='aui_assistant-message-content']
+ .aui-md
+ [data-slot='code-card'][data-streaming='true'] {
+ animation-play-state: paused !important;
+}
+
/* Sidebar sections: tall viewports give each its own scroller; compact ones
(this variant) flatten everything into one shared scroll. See ChatSidebar. */
@custom-variant compact (@media (max-height: 768px));
@@ -451,7 +472,7 @@
--sticky-human-top: 0.23rem;
--file-tree-row-height: 1.375rem;
- --composer-width: 48.75rem;
+ --composer-width: 100%;
--composer-control-size: 1.5rem;
--composer-control-primary-size: 1.625rem;
--composer-control-gap: 0.25rem;
@@ -1403,7 +1424,7 @@ body.guest-pointer-lock :is(webview, iframe) {
}
[data-slot='aui_intro'] > div {
- max-width: min(var(--composer-width), 82vw);
+ max-width: var(--composer-width);
}
[data-slot='aui_intro'] p:last-child {
@@ -2344,6 +2365,10 @@ button[data-slot='aui_msg-reactions'] svg {
--hud-band-inset: 0.5rem;
/* Clear space above the composer for the exit chip. */
--hud-chip-strip: 1.625rem;
+ /* How long the exit chip stays after you stop pointing at the HUD. Long
+ enough to cross the gap between the bar and the chip without it
+ evaporating, short enough that it isn't furniture. */
+ --hud-exit-hold: 600ms;
}
/* Chat surface carries nothing in HUD mode — the visual is the BAND below. */
@@ -2865,11 +2890,42 @@ button[data-slot='aui_msg-reactions'] svg {
}
/* The exit button. HUD mode has no titlebar, so this is the only visible way
- back; it lives in the open space off the bar's outer edge, at the right.
+ back; it rides the bar's outer edge at the right.
- A bare themed glyph rather than a chip: it sits over whatever the user is
- really working in, and a card floating there is a stray fragment of app on
- their screen.
+ It wears the BAR'S material, not the desktop's. Every shipped control that
+ floats over content the app does not own resolves this the same way — give
+ the control its own substrate and let the glyph read against that, never
+ against the backdrop:
+
+ - Apple HIG, Materials: "Materials help visually separate foreground
+ elements, such as text and controls, from background elements." Controls
+ sit ON a material, never directly on content; even `clear` Liquid Glass
+ is specced with a 35%-opacity dimming layer behind it over bright
+ content.
+ https://developer.apple.com/design/human-interface-guidelines/materials
+ - Firefox picture-in-picture, the closest analogue we have (a small
+ always-on-top window over arbitrary content): the close/unpip buttons
+ are `background-color: rgba(255,255,255,.8)` with a `#000` glyph — an
+ opaque chip, not a bare icon.
+ toolkit/themes/shared/pictureinpicture/player.css
+ - Discord's overlay redesign: "This layer provided contrast against the
+ game making the UI easier to see."
+ https://discord.com/blog/redesigning-the-discord-overlay
+
+ Anything that instead tries to derive contrast from the backdrop is a dead
+ end here. mix-blend-difference composites against the PAGE behind the
+ element, and behind a transparent Electron window that is nothing — the
+ desktop is composited by WindowServer after Chromium has finished drawing
+ the frame (the same reason backdrop-filter can't frost the HUD). A glyph
+ halo has the same flaw from the other side: it guesses one backdrop
+ luminance and is grime over everything else.
+
+ So: the composer bar's exact tokens — same fill, same hairline, same bottom
+ shadow. The bar is the HUD's solved case for "our surface, over an unknown
+ desktop, in either appearance", and theme plus OS light/dark (mode 'system')
+ come free with it, because --dt-card and --ui-text-primary are the pair the
+ whole app is built on. The chip inverts with the appearance instead of
+ betting on one.
Placed from --hud-bar-height rather than CSS anchor(). Lightning CSS drops a
whole rule containing an `anchor()` on the vertical axis, so the flipped-edge
@@ -2879,22 +2935,42 @@ button[data-slot='aui_msg-reactions'] svg {
top: auto;
right: 0.375rem;
bottom: calc(var(--hud-bar-height, var(--composer-fallback-height)) + 0.375rem);
- aspect-ratio: 1;
+ /* Square. `size="icon-titlebar"` sizes width and height from two DIFFERENT
+ vars (--titlebar-control-size / --titlebar-control-height, 20x22 today),
+ which is right in a titlebar row and reads as a dent on a lone floating
+ chip — so height comes off the width instead. */
+ aspect-ratio: 1 / 1;
height: auto;
- background: transparent !important;
- border: 0;
+ background: var(--dt-card) !important;
+ border: 1px solid var(--ui-stroke-secondary) !important;
+ border-radius: 0.5rem;
+ box-shadow: 0 2px 2px -1px rgb(0 0 0 / 0.12);
color: var(--ui-text-primary) !important;
- /* Always clickable, dim at rest. Gating the CLICKS on composer `:focus` made
- the only visible way out of HUD mode depend on the thing most likely to be
- broken when someone wants out: if focus never lands (#81893) you can't type
- AND the chip silently swallows clicks, leaving a transparent always-on-top
- rectangle over the desktop with no in-app way to dismiss it.
+ /* Gone until you reach for the HUD. A permanent chip is a fragment of Hermes
+ parked on top of whatever you are really working in; reaching for the bar
+ is the motion that means "I want the app", so that is what brings the way
+ out with it. Hover, not focus — the gate #81893 warned about made the
+ escape hatch depend on the caret landing in the composer, broken exactly
+ when you most want out, whereas pointing at the bar needs nothing to be
+ working.
- Dim rather than invisible keeps the original intent — this shouldn't be a
- loud chip floating over whatever you're actually working in — without
- making the escape hatch conditional on the failure it exists for. */
- opacity: 0.45;
- transition: opacity var(--hud-fade) var(--hud-ease-exit);
+ `visibility`, not opacity alone: an always-on-top window eats clicks
+ wherever the page hands the hit test something real, so a 0-opacity chip
+ with `pointer-events: auto` would be an invisible button in the corner
+ that drops you out of HUD mode when you click the app behind it.
+ `visibility: hidden` takes it out of `elementFromPoint` as well as off the
+ screen, and it transitions discretely, so it flips in step with the fade
+ rather than needing a second mechanism. */
+ opacity: 0;
+ visibility: hidden;
+ /* Leaving holds first. The chip sits 0.375rem clear of the bar, so the
+ cursor crosses shell dead space on its way up from the bar to the chip and
+ both hover triggers are false for that moment — without the hold it would
+ fade out from under a hand that is on its way to press it. */
+ transition:
+ opacity var(--hud-fade) var(--hud-ease-exit) var(--hud-exit-hold),
+ visibility 0s linear calc(var(--hud-exit-hold) + var(--hud-fade)),
+ background-color var(--hud-reveal) var(--hud-ease-enter);
pointer-events: auto;
}
@@ -2905,18 +2981,36 @@ button[data-slot='aui_msg-reactions'] svg {
top: 0;
}
-/* Hover and focus-visible brighten it too, so pointing at the chip confirms it
- is a control before you commit the click. */
-[data-hud-shell]:has([data-slot='composer-rich-input']:focus) [data-hud-exit],
+/* What counts as reaching for it: the bar, the transcript band, or the chip
+ itself. The band only answers `:hover` while it is on screen (faded out it
+ is `pointer-events: none`), so this can't reveal the chip over a HUD that
+ isn't there. The chip's own hover is in the set so arriving re-asserts the
+ reveal that the hold above was covering for.
+
+ Hovering the shell at large is deliberately NOT a trigger — most of the
+ HUD's rectangle is empty window over someone else's app, and it is
+ `pointer-events: none` precisely so the cursor passing through means
+ nothing. */
+[data-hud-shell]:has([data-slot='composer-dock']:hover) [data-hud-exit],
+[data-hud-shell]:has([data-slot='composer-bounds']:hover) [data-hud-exit],
[data-hud-shell] [data-hud-exit]:hover,
[data-hud-shell] [data-hud-exit]:focus-visible {
- opacity: 0.9;
- transition-duration: var(--hud-reveal);
+ opacity: 1;
+ visibility: visible;
+ transition-duration: var(--hud-reveal), 0s, var(--hud-reveal);
transition-delay: 0s;
}
-[data-hud-shell]:has([data-slot='composer-rich-input']:focus) [data-hud-exit]:hover {
- opacity: 1;
+/* Hover and focus-visible: the app's own control-hover tint, so pointing at it
+ confirms it is a button with the same feedback every other icon button in
+ Hermes gives. Layered OVER the card rather than replacing it —
+ --ui-control-hover-background is a translucent color-mix meant to sit on an
+ opaque titlebar, and here the button IS the opaque surface, so assigning it
+ directly would make the chip see-through on hover. */
+[data-hud-shell] [data-hud-exit]:hover,
+[data-hud-shell] [data-hud-exit]:focus-visible {
+ background:
+ linear-gradient(var(--ui-control-hover-background), var(--ui-control-hover-background)), var(--dt-card) !important;
}
/* The corner resize handle — a hot corner, not a button. The window is created
diff --git a/apps/desktop/src/types/hermes.ts b/apps/desktop/src/types/hermes.ts
index 2afe4e44a7..97b0039ec5 100644
--- a/apps/desktop/src/types/hermes.ts
+++ b/apps/desktop/src/types/hermes.ts
@@ -331,6 +331,7 @@ export interface HermesConfig {
personality?: string
skin?: string
interim_assistant_messages?: boolean
+ timestamps?: boolean
}
desktop?: {
repo_scan_enabled?: boolean
@@ -501,6 +502,11 @@ export interface SessionInfo {
* elsewhere. Undefined against a backend predating the flag; treat that as
* "no opinion" and leave the local pin set alone. */
pinned?: boolean
+ /** Derived read state (backend watermark: `last_read_at` vs `last_active`,
+ * see `SessionDB.session_unread`). True when the conversation was
+ * explicitly marked unread or a response arrived after it was last read.
+ * Undefined against a backend predating the flag; treat as read. */
+ unread?: boolean
preview: null | string
source: null | string
started_at: number
@@ -605,6 +611,12 @@ export interface SessionResumeResponse {
/** Mid-turn redirect corrections, oldest first. The turn's original prompt
* stays in `user`; these are the follow-ups typed while it ran. */
corrections?: string[]
+ /** Parallel to `corrections`: the length of `assistant` already streamed
+ * when each correction was accepted. Lets a resume rebuild arrival order —
+ * the correction bubble lands after the output the user had already seen
+ * and before the output it redirected (#73793). Omitted by older
+ * gateways. */
+ correction_offsets?: number[]
/** Retained failed turn: the error the terminal frame carried (the frame
* itself may have been lost to a disconnect). */
error?: string
@@ -616,6 +628,26 @@ export interface SessionResumeResponse {
queued?: null | {
user?: string
}
+ // The oldest gateway approval still waiting for a response. This is returned
+ // on resume so a reconnect can restore a prompt whose original event was
+ // emitted while the client transport was detached.
+ pending_approval?: {
+ allow_permanent?: boolean
+ choices?: string[]
+ command?: string
+ description?: string
+ request_id?: string
+ smart_denied?: boolean
+ }
+ // The clarify question still blocking this session, if any. Same replay
+ // class as pending_approval: emitted-while-detached prompts are restored
+ // from the resume snapshot instead of being lost until server-side timeout.
+ pending_clarify?: {
+ choices?: null | string[]
+ multi_select?: boolean
+ question?: string
+ request_id?: string
+ }
info?: SessionRuntimeInfo
message_count: number
messages: SessionMessage[]
@@ -1395,6 +1427,10 @@ export interface McpCatalogEntry {
bootstrap: string[]
default_enabled: string[] | null
post_install: string
+ /** Composer-suggestion triggers (present when the manifest declares a
+ * `suggest` block; null/absent on entries without one and on older
+ * backends that predate the field). */
+ suggest?: { keywords: string[]; hosts: string[] } | null
needs_install: boolean
installed: boolean
enabled: boolean
diff --git a/apps/desktop/vite.config.ts b/apps/desktop/vite.config.ts
index 971ea8bd60..46d5bea536 100644
--- a/apps/desktop/vite.config.ts
+++ b/apps/desktop/vite.config.ts
@@ -3,6 +3,7 @@ import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'
import fs from 'fs'
+import { createRequire } from 'module'
// `hgui` symlinks a worktree's node_modules to the main checkout. Vite realpaths
// those before enforcing server.fs.allow, so codicon/font assets resolve outside
@@ -25,6 +26,20 @@ const fsAllow = [
)
]
+// React refuses to run when `react` and `react-dom` come from two different
+// installed copies ("Minified React error #527" — a blank window, since it
+// throws before the first paint). Both packages are pinned to one version in
+// this workspace's package.json, but npm hoists whatever *it* considers
+// compatible to the monorepo root: a root dependency whose react peer is a
+// loose range (e.g. `^18 || ^19`) pulls the newest react up there, while
+// react-dom stays at the pinned one. `^19.2.7` accepts `19.2.8`, so npm never
+// warns. Resolving from this workspace instead of a hardcoded root path yields
+// the versions declared here — npm nests a copy under the workspace exactly
+// when the hoisted one differs, so the pair can only ever match.
+const requireFromApp = createRequire(path.join(__dirname, 'vite.config.ts'))
+const reactDir = path.dirname(requireFromApp.resolve('react/package.json'))
+const reactDomDir = path.dirname(requireFromApp.resolve('react-dom/package.json'))
+
// The dev-only render/state churn counters (src/debug) must be imported
// STATICALLY above react-dom — react-dom captures the devtools hook at module
// init, so a dynamic import lands too late and observes zero commits. A static
@@ -147,10 +162,10 @@ export default defineConfig(({ command }) => ({
'@hermes/plugin-sdk': path.resolve(__dirname, './src/sdk/index.ts'),
'@hermes/shared/billing': path.resolve(__dirname, '../shared/src/billing-types.ts'),
'@hermes/shared': path.resolve(__dirname, '../shared/src'),
- react: path.resolve(__dirname, '../../node_modules/react'),
- 'react-dom': path.resolve(__dirname, '../../node_modules/react-dom'),
- 'react/jsx-dev-runtime': path.resolve(__dirname, '../../node_modules/react/jsx-dev-runtime.js'),
- 'react/jsx-runtime': path.resolve(__dirname, '../../node_modules/react/jsx-runtime.js')
+ react: reactDir,
+ 'react-dom': reactDomDir,
+ 'react/jsx-dev-runtime': path.join(reactDir, 'jsx-dev-runtime.js'),
+ 'react/jsx-runtime': path.join(reactDir, 'jsx-runtime.js')
},
dedupe: ['react', 'react-dom', 'react-router']
},
diff --git a/apps/desktop/vitest.config.ts b/apps/desktop/vitest.config.ts
index dd2f38ff31..70835d91f0 100644
--- a/apps/desktop/vitest.config.ts
+++ b/apps/desktop/vitest.config.ts
@@ -1,4 +1,4 @@
-import type { TestProjectConfiguration } from 'vitest/config';
+import type { TestProjectConfiguration } from 'vitest/config'
import { defineConfig } from 'vitest/config'
const reactUi: TestProjectConfiguration = {
@@ -20,7 +20,8 @@ const electronNative: TestProjectConfiguration = {
test: {
name: 'electron',
environment: 'node',
- include: ['electron/**/*.test.ts', 'scripts/**.test.{ts,mjs}']
+ include: ['electron/**/*.test.ts', 'scripts/**.test.{ts,mjs}'],
+ exclude: ['scripts/run-short-session-hang-repro.test.mjs']
}
}
diff --git a/apps/shared/src/cron-trigger-controller.ts b/apps/shared/src/cron-trigger-controller.ts
new file mode 100644
index 0000000000..032231bd38
--- /dev/null
+++ b/apps/shared/src/cron-trigger-controller.ts
@@ -0,0 +1,40 @@
+export interface CronTriggerRunResult {
+ started: boolean
+ value: T | null
+}
+
+export interface CronTriggerController {
+ isRunning(key: string): boolean
+ run(key: string, action: () => Promise, onStarted?: () => void): Promise>
+}
+
+// This is an interaction guard for one mounted UI surface. Cross-window and
+// cross-process exclusion remains the backend's responsibility via its durable
+// cron claim; a renderer-local Set must never be treated as the execution lock.
+export function createCronTriggerController(
+ onRunningChange: (key: string, running: boolean) => void = () => undefined
+): CronTriggerController {
+ const running = new Set()
+
+ return {
+ isRunning: key => running.has(key),
+ async run(key: string, action: () => Promise, onStarted?: () => void) {
+ if (running.has(key)) {
+ return { started: false, value: null }
+ }
+
+ running.add(key)
+
+ try {
+ onRunningChange(key, true)
+
+ onStarted?.()
+
+ return { started: true, value: await action() }
+ } finally {
+ running.delete(key)
+ onRunningChange(key, false)
+ }
+ }
+ }
+}
diff --git a/apps/shared/src/index.ts b/apps/shared/src/index.ts
index 391a3715bd..8a17342961 100644
--- a/apps/shared/src/index.ts
+++ b/apps/shared/src/index.ts
@@ -34,6 +34,11 @@ export {
type SettlementDeps,
type SettlementOutcome
} from './charge-settlement'
+export {
+ createCronTriggerController,
+ type CronTriggerController,
+ type CronTriggerRunResult
+} from './cron-trigger-controller'
export {
type ConnectionState,
type GatewayClientOptions,
diff --git a/apps/shared/src/json-rpc-gateway.ts b/apps/shared/src/json-rpc-gateway.ts
index 4f24737ed7..acde83e96c 100644
--- a/apps/shared/src/json-rpc-gateway.ts
+++ b/apps/shared/src/json-rpc-gateway.ts
@@ -1,6 +1,7 @@
export type GatewayEventName =
| 'gateway.ready'
| 'session.info'
+ | 'session.usage'
| 'message.start'
| 'message.delta'
| 'message.interim'
diff --git a/cli-config.yaml.example b/cli-config.yaml.example
index 4ec0a24a40..4dee7a61f3 100644
--- a/cli-config.yaml.example
+++ b/cli-config.yaml.example
@@ -166,6 +166,26 @@ model:
# gpt-5.4:
# stale_timeout_seconds: 1800 # Longer non-stream stale timeout for slow large-context turns
+# =============================================================================
+# Unified Timeouts (operation deadlines)
+# =============================================================================
+# One place to override Hermes's internal operation deadlines (seconds).
+# Keys are dotted paths resolved by agent/deadline.py:resolve_timeout().
+# Precedence: this section > legacy HERMES_* env var (back-compat) > built-in
+# default. 0 or a negative value disables the bound (unbounded); very large
+# values are clamped to a platform-safe maximum automatically.
+#
+# Currently resolved keys (more paths migrate here over time — see issue #85125):
+#
+# timeouts:
+# tools:
+# concurrent_batch: 420 # Deadline for a parallel tool-call batch
+# # (legacy env: HERMES_CONCURRENT_TOOL_TIMEOUT_S)
+# sequential_call: 420 # Deadline for one sequentially-executed tool call.
+# # Defaults to concurrent_batch's value so the two
+# # executor paths stay in sync; human waits
+# # (approval prompts, clarify) never count against it.
+
# =============================================================================
# OpenRouter Provider Routing (only applies when using OpenRouter)
# =============================================================================
@@ -893,6 +913,19 @@ agent:
# window on /restart, and keep it well under systemd's TimeoutStopSec.
# restart_drain_timeout: 0
+ # Cron-only floor under the same drain (seconds). Default 30.
+ # restart_drain_timeout above is written for chat turns, which are cheap to
+ # interrupt: the user is told the gateway is restarting and the session
+ # resumes on their next message. A cron run has no such safety net — it is
+ # recorded in jobs.json as a permanent failure, nobody is waiting on it, and
+ # a recurring job simply skips to its next schedule. So in-flight cron work
+ # gets its own grace window instead of inheriting the 0 above.
+ # Clamped at runtime to the shutdown-watchdog leash (restart_drain_timeout
+ # + 60s) minus teardown headroom, so values past ~50s need a matching
+ # TimeoutStopSec bump to take effect. Set 0 to opt out and drain cron on
+ # restart_drain_timeout like before.
+ # cron_drain_timeout: 30
+
# Upper bound (seconds) a submitted prompt waits for the deferred agent
# build (MCP discovery, model metadata, skills scan) before failing with a
# visible error. The wait is patient — the message is delivered as soon as
@@ -1362,8 +1395,8 @@ code_execution:
# The delegate_task tool spawns child agents with isolated context.
# Supports single tasks and batch mode (default 3 parallel, configurable).
delegation:
- max_iterations: 50 # Max tool-calling turns per child (default: 50)
- # max_concurrent_children: 3 # Max parallel child agents per batch (default: 3, floor: 1, no ceiling).
+ max_iterations: 250 # Max tool-calling turns per child (default: 250)
+ # max_concurrent_children: 10 # Max parallel child agents per batch (default: 10, floor: 1, no ceiling).
# WARNING: values above 10 multiply API cost linearly.
# max_spawn_depth: 1 # Delegation tree depth cap (range: 1-3, default: 1 = flat).
# Raise to 2 to allow workers to spawn their own subagents.
@@ -1480,11 +1513,13 @@ display:
# Background process notifications (gateway/messaging only).
# Controls how chatty the process watcher is when you use
# terminal(background=true, notify_on_complete=true) from Telegram/Discord/etc.
+ # concise: One-line status message on completion; failures include a short
+ # output tail (default)
# off: No watcher messages at all
- # result: Only the final completion message
- # error: Only the final message when exit code != 0
- # all: Running output updates + final message (default)
- background_process_notifications: all
+ # result: Only the final raw-output completion message
+ # error: Only the final raw-output message when exit code != 0
+ # all: Running output updates + final raw-output message
+ background_process_notifications: concise
# Play terminal bell when agent finishes a response.
diff --git a/cli.py b/cli.py
index cd218ab1c8..1eea326a5b 100644
--- a/cli.py
+++ b/cli.py
@@ -43,7 +43,7 @@ from urllib.parse import unquote, urlparse
from contextlib import contextmanager
from pathlib import Path
from datetime import datetime
-from typing import List, Dict, Any, Optional
+from typing import List, Dict, Any, Optional, Mapping
logger = logging.getLogger(__name__)
@@ -224,7 +224,7 @@ from hermes_cli.browser_connect import (
try_launch_chrome_debug,
)
from hermes_cli.env_loader import load_hermes_dotenv
-from utils import base_url_host_matches, fast_safe_load
+from utils import base_url_host_matches, base_url_hostname, fast_safe_load
_hermes_home = get_hermes_home()
_project_env = Path(__file__).parent / '.env'
@@ -501,6 +501,12 @@ def load_cli_config() -> Dict[str, Any]:
"busy_input_mode": "interrupt",
"persistent_output": True,
"persistent_output_max_lines": 200,
+ # Clear terminal scrollback as well as the visible viewport when the
+ # classic CLI performs a full redraw/resize recovery. Disabled by
+ # default because some users prefer preserving terminal history;
+ # enable when a terminal/tmux stack stamps stale prompt chrome into
+ # scrollback during fullscreen/restore resizes.
+ "cli_rebuild_scrollback_on_redraw": False,
# Print a one-line summary of resolved modal prompts (approval /
# clarify) into scrollback so the decision survives the repaint.
"persist_prompts": True,
@@ -2689,6 +2695,63 @@ def _query_osc11_background() -> str | None:
pass
+def _heal_cooked_mode_drift(fd: int) -> bool:
+ """Detect and heal cooked-mode termios drift on *fd* while prompt_toolkit
+ expects raw mode.
+
+ prompt_toolkit's ``run_in_terminal`` / ``in_terminal`` wraps every
+ "print above the prompt" in a ``cooked_mode()`` context: it flips the
+ tty back to cooked (ICANON/ECHO/ISIG), runs the function, then restores
+ raw mode. Hermes schedules those windows cross-thread constantly — the
+ background self-review's ``💾`` summary, background process notification
+ drains, curses pickers — and if a restore is ever lost (coroutine
+ cancelled mid-window, racing chains, an external writer touching the
+ shared tty), the terminal is left in cooked mode while the Application
+ still believes it owns raw mode. The kernel line-buffers every
+ keystroke and the CLI appears to "stop taking input" even though the
+ process is perfectly healthy (observed live: pts in ``icanon echo``
+ while the event loop idled normally in ``ep_poll``).
+
+ This helper is the last line of defense for that whole class: when the
+ lflag has drifted back to cooked, re-apply prompt_toolkit's own raw-mode
+ flag surgery (mirrors ``prompt_toolkit.input.vt100.raw_mode``) in place.
+ Returns True when drift was detected and healed, False when the tty was
+ already raw (or could not be inspected).
+
+ POSIX-only by construction — callers must not invoke this on Windows
+ (no termios; prompt_toolkit uses the win32 console API there instead).
+ """
+ try:
+ import termios
+ attrs = termios.tcgetattr(fd)
+ except Exception:
+ return False
+ lflag = attrs[3]
+ if not (lflag & (termios.ICANON | termios.ECHO)):
+ return False # still raw — nothing to do
+ # Same surgery as prompt_toolkit.input.vt100.raw_mode._patch_lflag /
+ # _patch_iflag, applied to the *current* attrs so any user settings
+ # (speed, size-independent flags) are preserved.
+ attrs[3] = lflag & ~(
+ termios.ECHO | termios.ICANON | termios.IEXTEN | termios.ISIG
+ )
+ attrs[0] = attrs[0] & ~(
+ termios.IXON
+ | termios.IXOFF
+ | termios.ICRNL
+ | termios.INLCR
+ | termios.IGNCR
+ )
+ # VMIN=1 so reads return per-byte (Solaris-derived systems default to 4;
+ # prompt_toolkit sets this explicitly in raw_mode.__enter__).
+ attrs[6][termios.VMIN] = 1
+ try:
+ termios.tcsetattr(fd, termios.TCSANOW, attrs)
+ except Exception:
+ return False
+ return True
+
+
def _detect_light_mode() -> bool:
global _LIGHT_MODE_CACHE
if _LIGHT_MODE_CACHE is not None:
@@ -3551,6 +3614,58 @@ def _strip_leaked_bracketed_paste_wrappers(text: str) -> str:
return strip_leaked_bracketed_paste_wrappers(text)
+def _hermes_call_output_screen_diff(
+ orig_osd,
+ app,
+ output,
+ screen,
+ current_pos,
+ color_depth,
+ previous_screen,
+ last_style,
+ is_done,
+ full_screen,
+ attrs_for_style_string,
+ style_string_has_style,
+ size,
+ previous_width,
+):
+ """Call prompt_toolkit ``_output_screen_diff`` with Hermes resize guards.
+
+ 1. Inflate ``previous_screen.height`` when the new screen is taller so pt
+ skips the reserve-vertical-space cursor move that stamps chrome into
+ scrollback (pt #29 / Hermes #26137).
+ 2. On AttributeError/TypeError from a corrupt previous paint buffer
+ (classic after tmux attach with same width), retry once with
+ ``previous_screen=None`` so pt first-paints cleanly instead of crashing
+ the event loop with ``'cell' object has no attribute 'char'``.
+ """
+ try:
+ if previous_screen is not None and hasattr(previous_screen, "height"):
+ if previous_screen.height < screen.height:
+ previous_screen.height = screen.height
+ except Exception:
+ pass
+
+ try:
+ return orig_osd(
+ app, output, screen, current_pos, color_depth,
+ previous_screen, last_style, is_done, full_screen,
+ attrs_for_style_string, style_string_has_style,
+ size, previous_width,
+ )
+ except (AttributeError, TypeError):
+ # Corrupt previous_screen / row cells after client reattach.
+ return orig_osd(
+ app, output, screen, current_pos, color_depth,
+ None, # previous_screen → first-paint erase path
+ None, # last_style
+ is_done, full_screen,
+ attrs_for_style_string, style_string_has_style,
+ size, 0, # previous_width → treat as changed
+ )
+
+
def _apply_bracketed_paste_timeout_patch() -> None:
"""Patch prompt_toolkit to recover from torn bracketed-paste sequences.
@@ -3662,6 +3777,97 @@ _TERMINAL_INPUT_MODE_RESET_SEQ = (
"\x1b[0m" # reset text attributes
"\x1b[?25h" # ensure cursor visible
)
+_EXTENDED_ENTER_KEYS_SEQ = "\x1b[>1u\x1b[>4;2m"
+
+
+_BACKSLASH_LINE_CONTINUATION_RE = re.compile(r"\\[ \t]*$")
+
+
+def _terminal_supports_extended_enter_keys(env: Optional[Mapping[str, str]] = None) -> bool:
+ """Whether it is safe/useful to request modified Enter key reporting.
+
+ The classic CLI already maps Kitty CSI-u / xterm modifyOtherKeys Shift+Enter
+ byte sequences to the newline handler. Some terminals (notably iTerm2) only
+ emit those distinct sequences after the application asks for extended key
+ mode. Keep this allowlist aligned with the Ink TUI, which enables the same
+ modes for these terminals.
+ """
+ if env is None:
+ env = os.environ
+ term_program = (env.get("TERM_PROGRAM") or "").strip()
+ term = (env.get("TERM") or "").strip().lower()
+ if env.get("WT_SESSION"):
+ return True
+ if term_program in {"iTerm.app", "WezTerm", "ghostty", "vscode"}:
+ return True
+ if env.get("KITTY_WINDOW_ID") or "kitty" in term:
+ return True
+ if term == "xterm-ghostty":
+ return True
+ if term.startswith("tmux") or term_program.lower() == "tmux":
+ return True
+ return False
+
+
+def _enable_extended_enter_keys(output=None, env: Optional[Mapping[str, str]] = None) -> bool:
+ """Ask allowlisted terminals to report Shift+Enter distinctly.
+
+ Writes both the Kitty keyboard protocol push (CSI >1u) and xterm
+ modifyOtherKeys level 2 (CSI >4;2m), mirroring the Ink TUI. The exit reset
+ sequence already pops/resets both modes, so this is safe across normal
+ exits, Ctrl+C, and SIGTERM cleanup.
+ """
+ if not _terminal_supports_extended_enter_keys(env):
+ return False
+ try:
+ target = output
+ if target is not None and hasattr(target, "write_raw"):
+ target.write_raw(_EXTENDED_ENTER_KEYS_SEQ)
+ target.flush()
+ return True
+ stream = sys.stdout
+ if stream is not None and stream.isatty():
+ stream.write(_EXTENDED_ENTER_KEYS_SEQ)
+ stream.flush()
+ return True
+ except Exception:
+ return False
+ return False
+
+
+def _cli_multiline_shortcuts_enabled(config: Optional[Dict[str, Any]] = None) -> bool:
+ """Return whether classic CLI harness-standard multiline fallbacks are on.
+
+ Default is on to match the norm in adjacent agent harnesses: Ctrl+J is a
+ documented no-setup newline shortcut in Claude Code, OpenCode defaults
+ ``input_newline`` to include ``ctrl+j``, and Codex exposes Ctrl+J/keymap
+ newline behavior. Users on unusual POSIX PTYs that send bare LF for plain
+ Enter can set ``display.cli_multiline_shortcuts: false`` to restore the
+ legacy c-j submit fallback.
+ """
+ if config is None:
+ config = CLI_CONFIG
+ display = config.get("display") if isinstance(config, dict) else None
+ value = display.get("cli_multiline_shortcuts", True) if isinstance(display, dict) else True
+ if isinstance(value, bool):
+ return value
+ if isinstance(value, str):
+ normalized = value.strip().lower()
+ if normalized in {"1", "true", "yes", "on", "enabled"}:
+ return True
+ if normalized in {"0", "false", "no", "off", "disabled"}:
+ return False
+ return True
+
+
+def _is_backslash_line_continuation(text: str) -> bool:
+ """True when Enter should turn a trailing backslash into a newline."""
+ return bool(_BACKSLASH_LINE_CONTINUATION_RE.search(text or ""))
+
+
+def _apply_backslash_line_continuation(text: str) -> str:
+ """Replace a trailing ``\\`` marker with an actual newline."""
+ return _BACKSLASH_LINE_CONTINUATION_RE.sub("", text or "") + "\n"
def _preserve_ctrl_enter_newline() -> bool:
@@ -3672,8 +3878,8 @@ def _preserve_ctrl_enter_newline() -> bool:
NOT be bound to submit;
binding it to submit makes Ctrl+Enter (intended as 'newline like Alt+Enter')
submit instead. Local POSIX TTYs that deliver Enter as LF (docker exec,
- some thin PTYs without SSH) still need c-j bound to submit, so we keep
- that binding for those.
+ some thin PTYs without SSH) still need c-j bound to submit when
+ display.cli_multiline_shortcuts is disabled, so we keep that legacy opt-out.
See issue #22379.
"""
@@ -3702,22 +3908,33 @@ def _preserve_ctrl_enter_newline() -> bool:
return False
-def _bind_prompt_submit_keys(kb, handler) -> None:
+def _bind_prompt_submit_keys(
+ kb,
+ handler,
+ *,
+ multiline_shortcuts_enabled: Optional[bool] = None,
+) -> None:
"""Bind terminal Enter forms to the submit handler.
- Enter is always submit. On POSIX we also bind c-j (LF) to submit because
- some thin PTYs (docker exec, certain SSH flavors) deliver Enter as LF
- instead of CR — without this, Enter appears dead on those terminals.
+ Enter is always submit. By default, c-j (Ctrl+J/LF) is left for the
+ multiline newline handler because that is the common agent-harness UX.
+ Users can set ``display.cli_multiline_shortcuts: false`` to restore the
+ legacy POSIX fallback that binds c-j to submit on local thin PTYs whose
+ plain Enter arrives as LF instead of CR.
- Exception: on Windows, WSL, SSH sessions, Windows Terminal, and Ghostty,
- c-j is the wire encoding of Ctrl+Enter (a distinct keystroke from
- plain Enter / c-m). We leave c-j unbound there so the c-j newline
- handler registered separately can fire — giving the user an
- Enter-involving newline keystroke without terminal settings changes.
+ Even when the setting is disabled, environments where Ctrl+Enter is known
+ to arrive as c-j (Windows, WSL, SSH, Windows Terminal, Ghostty) keep c-j
+ reserved for newline; otherwise Ctrl+Enter submits instead of composing.
See _preserve_ctrl_enter_newline() and issue #22379.
"""
+ if multiline_shortcuts_enabled is None:
+ multiline_shortcuts_enabled = _cli_multiline_shortcuts_enabled()
kb.add("enter")(handler)
- if sys.platform != "win32" and not _preserve_ctrl_enter_newline():
+ if (
+ sys.platform != "win32"
+ and not multiline_shortcuts_enabled
+ and not _preserve_ctrl_enter_newline()
+ ):
kb.add("c-j")(handler)
@@ -3897,6 +4114,26 @@ def _estimate_tui_input_height(
return min(max(visual_lines, 1), max(1, int(max_height or 1)))
+def _status_bar_visible_from_display_config(display_config: object) -> bool:
+ """Return the initial classic-CLI status-bar visibility from display config.
+
+ ``display.tui_statusbar`` is the persisted user-facing setting toggled by
+ the TUI/statusbar controls. YAML parses bare ``off`` as ``False``, while
+ older config snapshots or hand edits may use strings such as ``"off"`` or
+ ``"hidden"``. Treat those values consistently so a new CLI process does not
+ re-enable a status bar that the user deliberately disabled.
+ """
+ if not isinstance(display_config, dict):
+ display_config = {}
+ statusbar_config = display_config.get(
+ "statusbar",
+ display_config.get("tui_statusbar", "top"),
+ )
+ if isinstance(statusbar_config, str):
+ return statusbar_config.strip().lower() not in {"0", "false", "hidden", "no", "off"}
+ return statusbar_config is not False
+
+
def _collect_query_images(query: str | None, image_arg: str | None = None) -> tuple[str, list[Path]]:
"""Collect local image attachments for single-query CLI flows."""
message = query or ""
@@ -4246,6 +4483,12 @@ def _normalize_moa_model(model: Optional[str]) -> tuple[Optional[str], Optional[
return "moa", preset
return None, model
+def _split_model_config_default(raw_default: Any) -> tuple[str, str]:
+ # Thin wrapper around the shared helper in config.py — kept for
+ # backward compat with existing call sites in this module.
+ from hermes_cli.config import split_model_config_default
+ return split_model_config_default(raw_default)
+
class _VoiceInputMessage:
"""Sentinel wrapper for voice-transcribed messages in ``_pending_input``.
@@ -4421,6 +4664,8 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
self._pending_edit_snapshots = {}
self._last_input_mode_recovery = 0.0
self._input_mode_recovery_notice_shown = False
+ self._last_termios_drift_check = 0.0
+ self._termios_drift_notice_shown = False
# Configuration - priority: CLI args > env vars > config file
# Model comes from: CLI arg or config.yaml (single source of truth).
@@ -4428,8 +4673,17 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
# authoritative. This avoids conflicts in multi-agent setups where
# env vars would stomp each other.
_model_config = CLI_CONFIG.get("model", {})
- _config_model = (_model_config.get("default") or _model_config.get("model") or "") if isinstance(_model_config, dict) else (_model_config or "")
+ _raw_default = (_model_config.get("default") or _model_config.get("model") or "") if isinstance(_model_config, dict) else (_model_config or "")
+ # A dict-valued default (``model.default: {provider: ..., model: ...}``)
+ # carries its own provider; flatten it here so the nested provider is
+ # available when ``requested_provider`` is constructed below instead of
+ # being discarded and replaced by the outer merged ``model.provider``
+ # (typically ``"auto"``, which is authoritative at runtime resolution).
+ _config_model, _nested_provider = _split_model_config_default(_raw_default)
_DEFAULT_CONFIG_MODEL = ""
+ # Track whether the user passed -m / --model so resume knows not to
+ # clobber an explicit override with the session's stored model.
+ self._explicit_model_override = bool(model)
self.model = model or _config_model or _DEFAULT_CONFIG_MODEL
# A ``moa:`` model string selects the MoA virtual provider in
# one shot (parity with interactive ``/moa`` and the model picker). Do
@@ -4452,7 +4706,7 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
# Auto-detect model from local server if still on default
if self.model == _DEFAULT_CONFIG_MODEL:
_base_url = (_model_config.get("base_url") or "") if isinstance(_model_config, dict) else ""
- if "localhost" in _base_url or "127.0.0.1" in _base_url:
+ if base_url_hostname(_base_url) in ("localhost", "127.0.0.1"):
from hermes_cli.runtime_provider import _auto_detect_local_model
_detected = _auto_detect_local_model(_base_url)
if _detected:
@@ -4474,6 +4728,7 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
self.requested_provider = (
_moa_provider_override
or provider
+ or _nested_provider
or CLI_CONFIG["model"].get("provider")
or os.getenv("HERMES_INFERENCE_PROVIDER")
or "auto"
@@ -4706,6 +4961,10 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
# don't auto-queue another continuation on top of a user-cancelled
# turn (which would make Ctrl+C feel like it did nothing).
self._last_turn_interrupted = False
+ # When stdout/PTY raises EIO (broken pipe after a stream-stall
+ # interrupt), freeze further UI paints so we don't spin the main
+ # thread at hundreds of escape-sequence writes/sec (#81521).
+ self._terminal_io_broken = False
self._should_exit = False
# /exit --delete: when True, the current session's SQLite history and
# on-disk transcripts are deleted during shutdown. Set by
@@ -4803,7 +5062,9 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
self._voice_barge_phase = None # "generation" or "playback" phase of the last barge trip
# Status bar visibility (toggled via /statusbar)
- self._status_bar_visible = True
+ self._status_bar_visible = _status_bar_visible_from_display_config(
+ CLI_CONFIG.get("display") if isinstance(CLI_CONFIG, dict) else None
+ )
# Battery read-out in the status bar (toggled via /battery, off by
# default). Persisted to display.battery so it survives restarts.
self._battery_visible = bool(CLI_CONFIG["display"].get("battery", False))
@@ -4869,6 +5130,20 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
finally:
self._active_session_lease = None
+ def _mark_terminal_io_broken(self, reason: str = "") -> None:
+ """Stop UI paints after the PTY/stdout becomes unusable (#81521)."""
+ if getattr(self, "_terminal_io_broken", False):
+ return
+ self._terminal_io_broken = True
+ try:
+ self._pet_stop_anim()
+ except Exception:
+ pass
+ logger.warning(
+ "Terminal I/O broken%s — freezing UI paints to avoid redraw storm (#81521)",
+ f" ({reason})" if reason else "",
+ )
+
def _invalidate(self, min_interval: float = 0.25) -> None:
"""Throttled UI repaint for high-frequency background updates.
@@ -4886,12 +5161,20 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
within the 250ms window — or an in-flight resize — silently drop it, so
the prompt never renders and times out unseen (#41098).
"""
+ if getattr(self, "_terminal_io_broken", False):
+ return
if getattr(self, "_resize_recovery_pending", False):
return
now = time.monotonic()
if hasattr(self, "_app") and self._app and (now - getattr(self, "_last_invalidate", 0.0)) >= min_interval:
self._last_invalidate = now
- self._app.invalidate()
+ try:
+ self._app.invalidate()
+ except OSError as exc:
+ if getattr(exc, "errno", None) == errno.EIO:
+ self._mark_terminal_io_broken("invalidate")
+ return
+ raise
def _paint_now(self) -> None:
"""Immediate, unthrottled repaint for user-blocking modal prompts.
@@ -4904,10 +5187,17 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
already use. See ``_invalidate`` for why the throttle must not gate
these paints (#41098).
"""
+ if getattr(self, "_terminal_io_broken", False):
+ return
app = getattr(self, "_app", None)
if app is not None:
try:
app.invalidate()
+ except OSError as exc:
+ if getattr(exc, "errno", None) == errno.EIO:
+ self._mark_terminal_io_broken("paint_now")
+ return
+ raise
except Exception:
pass
@@ -4926,16 +5216,72 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
matching the standard terminal-UX convention (bash, zsh, fish,
vim, htop).
"""
+ if getattr(self, "_terminal_io_broken", False):
+ return
app = getattr(self, "_app", None)
if not app:
return
- self._clear_prompt_toolkit_screen(app)
+ self._clear_prompt_toolkit_screen(
+ app,
+ rebuild_scrollback=self._redraw_rebuilds_scrollback(),
+ )
+ if getattr(self, "_terminal_io_broken", False):
+ return
_replay_output_history()
try:
app.invalidate()
+ except OSError as exc:
+ if getattr(exc, "errno", None) == errno.EIO:
+ self._mark_terminal_io_broken("force_full_redraw")
+ return
+ raise
except Exception:
pass
+ def _schedule_focus_regain_redraw(self, min_interval: float = 1.0) -> None:
+ """Repaint after a terminal focus-in report (``CSI I``), rate-limited.
+
+ Terminals with focus tracking active (Ghostty, iTerm2, xterm builds,
+ multiplexers that toggle DECSET 1004 upstream) emit ``\\x1b[I`` when
+ the Hermes tab/window becomes visible again. Emulators can coalesce
+ or drop hidden-tab output and repaint the surface while we're
+ invisible, so on regain prompt_toolkit's incremental diff stacks on
+ stale content — a second copy of the composer/prompt chrome next to
+ the ghost of the old one (#60920 focus-regain variant, #25337).
+
+ The stock handling maps ``CSI I``/``CSI O`` to ``Keys.Ignore`` so the
+ bytes never pollute the input buffer; this hook additionally routes
+ focus-in through the same recovery as Ctrl+L / ``/redraw``. It is
+ self-gating: terminals that never enable focus tracking never emit
+ the sequence, so nothing changes for them. Rate-limited so a burst of
+ focus reports (rapid Alt+Tab, mux pane hops) repaints at most once
+ per ``min_interval`` seconds.
+ """
+ now = time.monotonic()
+ last = getattr(self, "_last_focus_regain_redraw", 0.0)
+ if now - last < min_interval:
+ return
+ self._last_focus_regain_redraw = now
+ self._force_full_redraw()
+
+ @staticmethod
+ def _redraw_rebuilds_scrollback() -> bool:
+ """Return whether CLI redraw/resize recovery should clear scrollback.
+
+ Some terminal/tmux stacks move prompt_toolkit's non-fullscreen bottom
+ chrome into scrollback when the window is maximized/restored. A normal
+ CSI 2J viewport clear cannot remove those stale prompt/input-rule rows,
+ so users who hit that class of bug need CSI 3J as well, followed by the
+ existing bounded output-history replay.
+ """
+ display_config = CLI_CONFIG.get("display") if isinstance(CLI_CONFIG, dict) else {}
+ if not isinstance(display_config, dict):
+ display_config = {}
+ raw = display_config.get("cli_rebuild_scrollback_on_redraw", False)
+ if isinstance(raw, str):
+ return raw.strip().lower() in {"1", "true", "yes", "on", "always"}
+ return bool(raw)
+
def _recover_terminal_after_interrupt(self) -> None:
"""Recover the terminal after an interrupted agent turn (#33271).
@@ -4953,17 +5299,29 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
screen/cursor state and forces a clean repaint.
Both steps are independently safe and self-guard, so a failure of one
- never prevents the other.
+ never prevents the other. If the PTY is already dead (EIO), skip the
+ redraw entirely — painting a broken fd is the #81521 redraw storm.
"""
+ if getattr(self, "_terminal_io_broken", False):
+ return
try:
from hermes_cli.curses_ui import flush_stdin
flush_stdin()
except Exception:
pass
+ # #60920: The interruption marker is now printed with
+ # _suspend_output_history in chat(), so _OUTPUT_HISTORY only
+ # contains the normal response text (no marker text). Do NOT
+ # clear history here — _force_full_redraw → _replay_output_history
+ # replays the response correctly without duplicating the marker.
+ # The /redraw + Ctrl+L paths also preserve replay for scrollback
+ # recovery as intended.
self._force_full_redraw()
def _clear_prompt_toolkit_screen(self, app, *, rebuild_scrollback: bool = False) -> None:
"""Clear the terminal and reset prompt_toolkit renderer state."""
+ if getattr(self, "_terminal_io_broken", False):
+ return
try:
renderer = app.renderer
out = renderer.output
@@ -4980,6 +5338,11 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
# next _redraw() starts from a known (0, 0) origin and
# re-renders every cell rather than diffing against stale.
renderer.reset(leave_alternate_screen=False)
+ except OSError as exc:
+ if getattr(exc, "errno", None) == errno.EIO:
+ self._mark_terminal_io_broken("clear_screen")
+ return
+ pass
except Exception:
pass
@@ -5044,20 +5407,40 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
# reach, leaving a duplicated status bar stranded above the live origin.
# Ctrl+L / /redraw clears it cleanly, so route the resize path through
# the SAME recovery: wipe the visible viewport (banner-safe — CSI 2J
- # only, never CSI 3J) and replay the transcript so nothing is lost.
- # Row-count-only changes skip this (no reflow → no ghost) to avoid an
- # unnecessary full repaint.
+ # by default; CSI 3J only when display.cli_rebuild_scrollback_on_redraw
+ # is enabled) and replay the transcript so nothing is lost.
+ # Same-width SIGWINCH (tmux attach, benign focus/tab signals) is left
+ # untouched — no clear, no replay — because a 2J without replay erases
+ # the visible transcript and a replay against preserved scrollback
+ # duplicates it (#65293). The stale-previous_screen crash tmux attach
+ # used to trigger is handled by _hermes_call_output_screen_diff's
+ # retry-with-first-paint instead (#83874).
try:
new_width = self._get_tui_terminal_width()
except Exception:
new_width = None
prev_width = getattr(self, "_last_resize_width", None)
- # First resize of the session has no prior width to compare against;
- # treat it as a change so an initial maximize/restore is covered too.
- width_changed = new_width is not None and new_width != prev_width
+ # Replay only on an OBSERVED width change. The first signal of a
+ # session must not count as one (#65293): GNOME Terminal and friends
+ # deliver benign SIGWINCHes (tab bar appearing, monitor-scale change,
+ # focus events), and a 2J+replay against preserved scrollback
+ # duplicates everything ``_OUTPUT_HISTORY`` holds — after a resume
+ # that is the entire "Previous Conversation" recap plus the first
+ # live exchange. ``_install_resize_recovery`` seeds the baseline at
+ # startup, so an initial maximize/restore still differs from it and
+ # is still recovered; with no baseline (width probe failed) this
+ # signal just records one for the next comparison.
+ width_changed = (
+ new_width is not None
+ and prev_width is not None
+ and new_width != prev_width
+ )
if width_changed:
try:
- self._clear_prompt_toolkit_screen(app, rebuild_scrollback=False)
+ self._clear_prompt_toolkit_screen(
+ app,
+ rebuild_scrollback=self._redraw_rebuilds_scrollback(),
+ )
_replay_output_history()
except Exception:
pass
@@ -5153,6 +5536,45 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
self._resize_recovery_pending = False
self._recover_after_resize(app, original_on_resize)
+ def _install_resize_recovery(self, app) -> None:
+ """Route prompt_toolkit's ``_on_resize`` through the debounced
+ ghost-clearing recovery (#5474/#49120) and record the current terminal
+ width as the baseline for width-change detection.
+
+ Seeding the baseline here is what keeps the session's FIRST SIGWINCH
+ honest (#65293): ``_recover_after_resize`` replays the transcript only
+ on an observed width change, and without a startup baseline it could
+ not tell a benign signal (GNOME Terminal tab bar, monitor-scale
+ change) from a real one. An initial maximize/restore still differs
+ from the seeded width, so it is still recovered.
+
+ The probe reads ``app.output`` directly — NOT
+ ``_get_tui_terminal_width`` — because this runs before ``app.run()``,
+ when ``get_app()`` still returns prompt_toolkit's DummyApplication
+ whose DummyOutput reports a hardcoded 80 columns; seeding that fake
+ width would make the first real signal look like a width change and
+ resurrect the duplicate-replay bug this exists to fix.
+ ``app.output`` is the same object the running app's resize handler
+ measures, so install-time and signal-time widths are comparable.
+ """
+ width = None
+ try:
+ width = app.output.get_size().columns
+ except Exception:
+ width = None
+ if not width or width <= 0:
+ try:
+ width = shutil.get_terminal_size((80, 24)).columns
+ except Exception:
+ width = None
+ self._last_resize_width = width
+ original_on_resize = app._on_resize
+
+ def _resize_clear_ghosts():
+ self._schedule_resize_recovery(app, original_on_resize)
+
+ app._on_resize = _resize_clear_ghosts
+
def _status_bar_context_style(self, percent_used: Optional[int]) -> str:
if percent_used is None:
return "class:status-bar-dim"
@@ -5795,7 +6217,9 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
display = cfg.get("display", {}) if isinstance(cfg.get("display"), dict) else {}
pet_cfg = display.get("pet", {}) if isinstance(display.get("pet"), dict) else {}
- enabled = bool(pet_cfg.get("enabled"))
+ from utils import is_truthy_value
+
+ enabled = is_truthy_value(pet_cfg.get("enabled"), default=False)
slug = str(pet_cfg.get("slug", "") or "")
scale = float(pet_cfg.get("scale", constants.DEFAULT_SCALE) or constants.DEFAULT_SCALE)
cols = constants.resolve_cols(scale, pet_cfg.get("unicode_cols", 0))
@@ -5956,6 +6380,9 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
"""Advance the frame + invalidate on a timer while a pet is enabled."""
while self._pet_anim_running:
time.sleep(self._PET_FRAME_INTERVAL)
+ if getattr(self, "_terminal_io_broken", False):
+ self._pet_anim_running = False
+ break
now = time.monotonic()
if now - self._pet_cfg_checked >= self._PET_CFG_INTERVAL:
self._pet_cfg_checked = now
@@ -5968,6 +6395,10 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
if app is not None:
try:
app.invalidate()
+ except OSError as exc:
+ if getattr(exc, "errno", None) == errno.EIO:
+ self._mark_terminal_io_broken("pet_anim")
+ break
except Exception:
pass
@@ -6404,7 +6835,10 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
def _normalize_model_for_provider(self, resolved_provider: str) -> bool:
"""Normalize provider-specific model IDs and routing."""
- current_model = (self.model or "").strip()
+ current_model = str(self.model or "").strip()
+ if isinstance(self.model, dict):
+ _m, _ = _split_model_config_default(self.model)
+ current_model = _m
changed = False
try:
@@ -7563,11 +7997,18 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
f"[dim] Hermes needs at least {MINIMUM_CONTEXT_LENGTH:,} tokens. Tool schemas + system prompt use a large fixed prefix.[/]"
)
base_url = getattr(self, "base_url", "") or ""
- if "11434" in base_url or "ollama" in base_url.lower():
+ from urllib.parse import urlparse as _urlparse
+ try:
+ _parsed = _urlparse(base_url if "://" in base_url else f"//{base_url}")
+ _port = _parsed.port
+ except ValueError:
+ _port = None
+ _host = base_url_hostname(base_url)
+ if _port == 11434 or "ollama" in _host:
self._console_print(
f"[dim] Ollama fix: OLLAMA_CONTEXT_LENGTH={MINIMUM_CONTEXT_LENGTH} ollama serve[/]"
)
- elif "1234" in base_url:
+ elif _port == 1234:
self._console_print(
"[dim] LM Studio fix: Set context length in model settings → reload model[/]"
)
@@ -7687,6 +8128,179 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
else:
self._console_print(f"[dim]{_escape(msg)}[/dim]")
+ def _persist_model_switch_to_session(self, result) -> None:
+ """Persist a session-scoped /model switch to the session DB row.
+
+ Writes the model column plus the runtime route so ``--resume``
+ (CLI, reads ``gateway_runtime``) and ``session.resume`` (TUI/desktop,
+ reads top-level ``model_config`` keys via
+ ``_stored_session_runtime_overrides``) both restore the switched
+ provider instead of recombining the model with the ambient default
+ (#79536). Mirrors the gateway's ``update_session_model()`` call.
+ getattr: tests drive the switch paths with ``object.__new__`` stubs.
+ """
+ db = getattr(self, "_session_db", None)
+ sid = getattr(self, "session_id", None)
+ if not db or not sid:
+ return
+ provider = result.target_provider
+ # Bare "custom" is the resolved billing class, not a routable
+ # identity — persisting it verbatim makes a later resume hard-fail
+ # when the config default has moved off the custom endpoint
+ # (resolve_runtime_provider only trusts config base_url for bare
+ # custom while the config provider is still custom-ish). Heal to
+ # the durable custom: