fix(cli): preserve truthful runtime failure diagnostics

src/cli/runtime-client.test.ts

@@ -1,4 +1,4 @@
-import { mkdtempSync, writeFileSync } from 'node:fs'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { createServer, type Socket } from 'node:net'
@@ -332,6 +332,22 @@ describe.skipIf(process.platform === 'win32')('RuntimeClient', () => {
     })
   })
 
+  it('openOrca keeps the last unreachable reason when later polls have no metadata', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-client-'))
+    writeMetadata(userDataPath, join(userDataPath, 'never-listened.sock'), 'token', process.pid)
+    vi.mocked(launchOrcaApp).mockImplementationOnce(() => {
+      rmSync(join(userDataPath, 'orca-runtime.json'))
+    })
+
+    const client = new RuntimeClient(userDataPath, 100)
+
+    await expect(client.openOrca(100)).rejects.toMatchObject({
+      code: 'runtime_open_timeout',
+      message: expect.stringContaining('never-listened.sock'),
+      data: { unreachableReason: { code: 'endpoint_missing' } }
+    })
+  })
+
   it('openOrca waits for a reachable headless runtime to expose a desktop window', async () => {
     const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-client-'))
     const endpoint = join(userDataPath, 'runtime.sock')

src/cli/runtime/client.ts

@@ -272,7 +272,7 @@ export class RuntimeClient {
       if (status.result.app.desktopWindowStatus === 'available') {
         return status
       }
-      lastReason = status.result.runtime.unreachableReason
+      lastReason = status.result.runtime.unreachableReason ?? lastReason
       await delay(250)
     }
 

src/cli/runtime/local-runtime-unreachable-reason.test.ts

@@ -92,6 +92,13 @@ describe('classifyLocalRuntimeUnreachable', () => {
     )
   })
 
+  it('does not claim a permission-denied endpoint exists', () => {
+    const reason = classifyLocalRuntimeUnreachable(connectError('EACCES'), PIPE, 1000)
+
+    expect(reason.message).not.toMatch(/\bexists\b/i)
+    expect(reason.message).toContain('OS denied')
+  })
+
   // The reported Windows 10 incident: the app process is alive, the pipe is not
   // openable from this process. The guidance must name the isolation possibilities
   // rather than telling the user to keep waiting.

src/cli/runtime/local-runtime-unreachable-reason.ts

@@ -83,7 +83,7 @@ function describe(
     case 'endpoint_missing':
       return `Orca published the ${noun} ${endpoint}, but it does not exist for this process. Either the runtime shut its endpoint down, or this process cannot see it — a sandbox, container, or different user session each hide it this way. Run the CLI as the same user and outside any sandbox, or restart Orca.`
     case 'endpoint_permission_denied':
-      return `The ${noun} ${endpoint} exists but this process is not permitted to open it. Run the CLI as the same user that runs Orca, outside any sandbox that restricts ${noun} access.`
+      return `The OS denied this process access to the ${noun} ${endpoint}. Run the CLI as the same user that runs Orca, outside any sandbox that restricts ${noun} access.`
     case 'connection_refused':
       return `The ${noun} ${endpoint} refused the connection. Orca's runtime is most likely shutting down; restart Orca.`
     case 'connection_closed':