fix(native-chat): each chat failure says why in plain words, on the thing that failed

src/main/native-chat/agent-session-journal/journal-open-failure.test.ts

@@ -1,9 +1,14 @@
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { agentSessionRefusalError } from '../../../shared/agent-session-wire-refusals'
 import { openJournalDatabase } from './journal-database'
-import { classifyJournalOpenFailure } from './journal-open-failure'
+import {
+  classifyJournalOpenFailure,
+  createJournalOpenReadRefusals,
+  journalOpenReadRefusal
+} from './journal-open-failure'
 import { loadJournal } from './journal-open'
 import { journalDatabaseFile } from './journal-paths'
 
@@ -104,3 +109,51 @@ describe('classifyJournalOpenFailure', () => {
     expect(classifyJournalOpenFailure(first)).toBe('journalUnavailable')
   })
 })
+
+describe('journalOpenReadRefusal', () => {
+  it('names the reason, keeps the message the code and the storage text only as the cause', () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const storage = nodeSqliteError(26)
+    const refusal = journalOpenReadRefusal(storage)
+    expect(refusal.message).toBe('agent_session_journal_unreadable')
+    expect(refusal.refusal).toMatchObject({
+      code: 'agent_session_journal_unreadable',
+      details: { reason: 'journalCorrupt' }
+    })
+    expect(refusal.cause).toBe(storage)
+    vi.restoreAllMocks()
+  })
+
+  it('passes a refusal the open already raised through unchanged', () => {
+    const raised = agentSessionRefusalError('agent_session_identity_required', {
+      reason: 'recordMissing'
+    })
+    expect(journalOpenReadRefusal(raised)).toBe(raised)
+  })
+})
+
+describe('createJournalOpenReadRefusals', () => {
+  it('logs a session once per failure until it opens, and each session on its own', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const refusals = createJournalOpenReadRefusals()
+    const denied = systemError('EACCES', -13)
+    const corrupt = nodeSqliteError(26)
+
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const refusal = refusals.refusal('session-1', denied)
+      expect(refusal.refusal).toMatchObject({ details: { reason: 'journalUnavailable' } })
+      expect(refusal.cause).toBe(denied)
+    }
+    expect(warn).toHaveBeenCalledTimes(1)
+    refusals.refusal('session-2', denied)
+    expect(warn).toHaveBeenCalledTimes(2)
+    expect(refusals.refusal('session-1', corrupt).refusal).toMatchObject({
+      details: { reason: 'journalCorrupt' }
+    })
+    expect(warn).toHaveBeenCalledTimes(3)
+    refusals.forget('session-1')
+    refusals.refusal('session-1', corrupt)
+    expect(warn).toHaveBeenCalledTimes(4)
+    vi.restoreAllMocks()
+  })
+})

src/main/native-chat/agent-session-journal/journal-open-failure.ts

@@ -2,6 +2,11 @@
 // past, or the open failed in a way that can clear (a lock, permissions, too many open files).
 
 import type { AgentSessionRefusalReason } from '../../../shared/agent-session-refusal-details'
+import {
+  AgentSessionRefusalError,
+  isAgentSessionRefusalError,
+  refuse
+} from '../../../shared/agent-session-wire-refusals'
 import { isSqliteCorruption } from '../../sqlite/sqlite-read-failure'
 
 export type JournalOpenFailure = AgentSessionRefusalReason<'agent_session_journal_unreadable'>
@@ -20,3 +25,56 @@ export function classifyJournalOpenFailure(error: unknown): JournalOpenFailure {
   }
   return 'journalUnavailable'
 }
+
+/**
+ * What a read throws when the conversation it reaches cannot be opened. The storage's own text
+ * (a path, "file is not a database") goes to the log only; the reader gets the classified refusal,
+ * whose message stays the bare code.
+ */
+export function journalOpenReadRefusal(error: unknown): AgentSessionRefusalError {
+  if (isAgentSessionRefusalError(error)) {
+    return error
+  }
+  return unreadableRefusal(error, classifyJournalOpenFailure(error), true)
+}
+
+const MAX_LOGGED_SESSIONS = 256
+
+/**
+ * The read door's refusals for one host. A reader reconnects on a timer while an open can clear,
+ * so a session's failure is logged once until that session opens or the failure changes.
+ */
+export function createJournalOpenReadRefusals() {
+  const logged = new Map<string, string>()
+  return {
+    refusal: (sessionId: string, error: unknown): AgentSessionRefusalError => {
+      if (isAgentSessionRefusalError(error)) {
+        return error
+      }
+      const reason = classifyJournalOpenFailure(error)
+      const failure = `${reason}:${error instanceof Error ? error.message : String(error)}`
+      const repeat = logged.get(sessionId) === failure
+      // Past the cap a new session logs every failure rather than evict another's.
+      if (!repeat && (logged.has(sessionId) || logged.size < MAX_LOGGED_SESSIONS)) {
+        logged.set(sessionId, failure)
+      }
+      return unreadableRefusal(error, reason, !repeat)
+    },
+    /** The session opened or closed: its next failure is news. */
+    forget: (sessionId: string): void => {
+      logged.delete(sessionId)
+    }
+  }
+}
+
+function unreadableRefusal(
+  error: unknown,
+  reason: JournalOpenFailure,
+  log: boolean
+): AgentSessionRefusalError {
+  if (log) {
+    console.warn('[agent-session] opening the conversation for a read failed:', error)
+  }
+  const code = 'agent_session_journal_unreadable'
+  return new AgentSessionRefusalError(refuse(code, { reason }, code), { cause: error })
+}

src/main/native-chat/agent-session-wire/structured-agent-session-conversation-lifetime.ts

@@ -5,11 +5,11 @@
 // public entry point here takes the session's serialize once and calls the under-serialize forms,
 // because the queue is not reentrant.
 
-import { TUI_AGENT_DISPLAY_NAMES } from '../../../shared/tui-agent-display-names'
 import {
   AgentSessionRefusalError,
   agentSessionRefusalError
 } from '../../../shared/agent-session-wire-refusals'
+import { createJournalOpenReadRefusals } from '../agent-session-journal/journal-open-failure'
 import type { StructuredAgentSessionConversations } from './structured-agent-session-conversations'
 import {
   abandonQueuedStructuredAgentSessionMessages,
@@ -40,6 +40,7 @@ export function createStructuredAgentSessionConversationLifetime(host: {
   let disposed = false
   const { sessions, serialize } = host
   const deps = () => host.context().deps
+  const readRefusals = createJournalOpenReadRefusals()
   // The sweep's stop puts an idle agent to rest: nothing is queued, so no loop reads its cause.
   const stopAgent = (sessionId: string) =>
     stopStructuredAgentSessionAgentUnderSerialize(host.context(), sessionId)
@@ -69,12 +70,11 @@ export function createStructuredAgentSessionConversationLifetime(host: {
       return record !== null && deps().hasOpenDispatch?.(record) === true
     },
     stopAgent,
-    // A host stop with its reason: the delivery loop waiting on this child writes the one error
-    // row and rejects what is queued with it.
+    // A host stop: the delivery loop waiting on this child writes the one error row and rejects
+    // what is queued with it, both worded from the hostStopped fact.
     stopStartingAgent: (sessionId) =>
       stopStructuredAgentSessionAgentUnderSerialize(host.context(), sessionId, {
-        cause: 'host-stop',
-        reason: `${TUI_AGENT_DISPLAY_NAMES[sessions.get(sessionId)?.params.provider ?? 'claude']} never finished starting, so Orca stopped it.`
+        cause: 'host-stop'
       }),
     closeConversation,
     onError: (sessionId, error) => deps().onEventSinkError?.({ sessionId, error }),
@@ -98,6 +98,7 @@ export function createStructuredAgentSessionConversationLifetime(host: {
     conversation: async (sessionId: string): Promise<StructuredAgentSessionHostSession> => {
       const open = sessions.get(sessionId)
       if (open) {
+        readRefusals.forget(sessionId)
         return open
       }
       const record = deps().store.getRecord(sessionId)
@@ -116,19 +117,23 @@ export function createStructuredAgentSessionConversationLifetime(host: {
         if (disposed) {
           throw new AgentSessionRefusalError(AGENT_SESSION_NOT_ATTACHED)
         }
-        const session = await host.open(sessionId)
+        const session = await host.open(sessionId).catch((error: unknown) => {
+          throw readRefusals.refusal(sessionId, error)
+        })
         if (!session) {
           throw agentSessionRefusalError('agent_session_identity_required', {
             reason: 'recordMissing'
           })
         }
+        readRefusals.forget(sessionId)
         return session
       })
     },
     /** Ends a chat's resources, not the chat: its record and journal stay on disk, and what is
      *  still queued will not be sent. */
     close: (sessionId: string): Promise<void> =>
       serialize(sessionId, async () => {
+        readRefusals.forget(sessionId)
         const session = sessions.get(sessionId)
         if (session) {
           // Abandoned before the stop, so no start delivers it.

src/main/native-chat/agent-session-wire/structured-agent-session-options-read.ts

@@ -12,6 +12,7 @@ import {
 } from '../../../shared/agent-session-wire'
 import { decodeStructuredAgentSessionOptionValue } from '../../../shared/structured-agent-session-option-codec'
 import type { AgentSessionRecordStore } from '../../runtime/agent-session-record-store'
+import { journalOpenReadRefusal } from '../agent-session-journal/journal-open-failure'
 import { isClaudeStructuredOptionKey } from '../../claude/claude-structured-options'
 import { isCodexTurnOptionKey } from '../../codex/codex-structured-turn-start'
 import type { StructuredAgentSessionHostDeps } from './structured-agent-session-host-types'
@@ -88,7 +89,9 @@ export async function readStructuredAgentSessionOptions(
 ): Promise<AgentSessionOptionsResult> {
   const { adapter, store } = context.deps
   const live = await context.serialize(sessionId, async () => {
-    const session = await context.openConversation(sessionId)
+    const session = await context.openConversation(sessionId).catch((error: unknown) => {
+      throw journalOpenReadRefusal(error)
+    })
     const child = session?.child
     if (!child) {
       return null

src/main/native-chat/agent-session-wire/structured-agent-session-start-failure-row.ts

@@ -1,5 +1,6 @@
 import { agentJournalItemKey } from '../../../shared/agent-session-journal-item-key'
 import { isQueuedAgentJournalSubmission } from '../../../shared/agent-session-queued-submission'
+import { structuredAgentSessionStartFailureRowIdentity } from '../../../shared/structured-agent-session-start-failure-row-key'
 import type { JournalLifecycleMutationInput } from '../agent-session-journal/journal-row-builders'
 import type { StructuredAgentSessionHostSession } from './structured-agent-session-host-types'
 import type { StructuredAgentSessionStartFailureWords } from './structured-agent-session-failure-text'
@@ -21,7 +22,7 @@ export function structuredAgentSessionStartFailureRow(
 ): JournalLifecycleMutationInput {
   return {
     kind: 'item',
-    identity: startFailureRowIdentity(startKey),
+    identity: structuredAgentSessionStartFailureRowIdentity(startKey),
     // The row repeats the sentence the start's rejected messages carry.
     body: { kind: 'status', text: words.reason, tone: 'error', failure: words.rejection }
   }
@@ -33,14 +34,10 @@ export function hasStructuredAgentSessionStartFailureRow(
   items: readonly { itemId: string }[],
   startKey: string
 ): boolean {
-  const itemId = agentJournalItemKey(startFailureRowIdentity(startKey))
+  const itemId = agentJournalItemKey(structuredAgentSessionStartFailureRowIdentity(startKey))
   return items.some((item) => item.itemId === itemId)
 }
 
-function startFailureRowIdentity(startKey: string) {
-  return { provider: 'orca' as const, clientMessageId: `start-failure:${startKey}` }
-}
-
 /**
  * A start the delivery loop needed and did not get: the start's row, and every queued message
  * rejected with the same words. Writes nothing when nothing is still queued: a start whose

src/main/runtime/rpc/methods/structured-agent-session-at-rest.test.ts

@@ -236,6 +236,78 @@ describe('the accessor', () => {
     })
   })
 
+  it('refuses a read whose journal will not open with the classified reason, never the storage text', async () => {
+    await restingChat()
+    const open = vi.spyOn(rig.host.collaboratorsForTests().conversationDelivery, 'open')
+    vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const storagePath = '/Users/someone/.orca/journals/session-1/journal.sqlite'
+    const failWith = (error: Error): void => {
+      open.mockRejectedValue(error)
+    }
+    const failures = async (): Promise<RpcResponse[]> =>
+      [
+        ...(await call('agentSession.history', { sessionId: SESSION, direction: 'tail' })),
+        ...(await call('agentSession.subscribe', { sessionId: SESSION })),
+        ...(await call('agentSession.options', { sessionId: SESSION }))
+      ].filter((reply) => !reply.ok)
+
+    failWith(
+      Object.assign(new Error(`file is not a database: ${storagePath}`), {
+        code: 'ERR_SQLITE_ERROR',
+        errcode: 26
+      })
+    )
+    const corrupt = await failures()
+    failWith(Object.assign(new Error(`EACCES: permission denied, open '${storagePath}'`), {}))
+    const unavailable = await failures()
+
+    for (const [replies, reason] of [
+      [corrupt, 'journalCorrupt'],
+      [unavailable, 'journalUnavailable']
+    ] as const) {
+      expect(replies).toHaveLength(3)
+      for (const reply of replies) {
+        expect(reply).toMatchObject({
+          ok: false,
+          error: {
+            // Not a passthrough code: released clients read the message, which stays the code.
+            code: 'runtime_error',
+            message: 'agent_session_journal_unreadable',
+            data: { refusal: { code: 'agent_session_journal_unreadable', details: { reason } } }
+          }
+        })
+        expect(JSON.stringify(reply)).not.toContain(storagePath)
+      }
+    }
+  })
+
+  it('logs a reader reconnecting to a journal that will not open once per failure', async () => {
+    await restingChat()
+    const open = vi.spyOn(rig.host.collaboratorsForTests().conversationDelivery, 'open')
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const logged = (): unknown[] =>
+      warn.mock.calls
+        .filter(([line]) => line === '[agent-session] opening the conversation for a read failed:')
+        .map(([, error]) => error)
+    const reconnect = async (): Promise<RpcResponse[]> => [
+      ...(await call('agentSession.subscribe', { sessionId: SESSION })),
+      ...(await call('agentSession.history', { sessionId: SESSION, direction: 'tail' }))
+    ]
+    const denied = new Error('EACCES: permission denied')
+    const exhausted = new Error('EMFILE: too many open files')
+
+    open.mockRejectedValue(denied)
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+      // Every attempt is still refused with its reason; only the log is quiet.
+      expect((await reconnect()).filter((reply) => !reply.ok)).toHaveLength(2)
+    }
+    expect(logged()).toEqual([denied])
+    open.mockRejectedValue(exhausted)
+    await reconnect()
+    await reconnect()
+    expect(logged()).toEqual([denied, exhausted])
+  })
+
   it('opens a corrupt journal through the recovering open and still accepts a send (P2-03)', async () => {
     await foundRestTestChat(rig)
     await rig.host.flushAllStreamedEvents()