feat(approval-gate): state-as-truth refactor — direct policy consult + reactive turn_state event + reload recovery

console/web/src/components/chat/ChatView.tsx

@@ -92,8 +92,6 @@ export function ChatView({
       let thoughtId: string | null = null
       let thoughtBuffer = ''
       let fcallId: string | null = null
-      // PR #150: same iii function_call_id can fire fcall-start twice
-      // (once for function_execution_start, once for approval_requested).
       // Map UI message id → iii function_call_id so dedupe is reliable.
       const fcallMap = new Map<string, string>()
       let assistantId: string | null = null

console/web/src/lib/backend/pending-approvals-store.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+import {
+  diffPending,
+  type PendingApproval,
+} from './pending-approvals-store'
+
+describe('diffPending', () => {
+  it('returns all entries as added when previous list is empty', () => {
+    const next: PendingApproval[] = [
+      { function_call_id: 'fc-1', function_id: 'shell::fs::write', args: { path: '/tmp/x' } },
+    ]
+    expect(diffPending([], next)).toEqual({
+      added: next,
+      removed: [],
+    })
+  })
+
+  it('returns all entries as removed when next list is empty', () => {
+    const prev: PendingApproval[] = [
+      { function_call_id: 'fc-1', function_id: 'shell::fs::write', args: { path: '/tmp/x' } },
+    ]
+    expect(diffPending(prev, [])).toEqual({
+      added: [],
+      removed: prev,
+    })
+  })
+
+  it('detects a single addition', () => {
+    const prev: PendingApproval[] = [
+      { function_call_id: 'fc-1', function_id: 'shell::fs::write', args: {} },
+    ]
+    const next: PendingApproval[] = [
+      ...prev,
+      { function_call_id: 'fc-2', function_id: 'shell::shell', args: {} },
+    ]
+    expect(diffPending(prev, next)).toEqual({
+      added: [next[1]],
+      removed: [],
+    })
+  })
+
+  it('detects a single removal', () => {
+    const prev: PendingApproval[] = [
+      { function_call_id: 'fc-1', function_id: 'shell::fs::write', args: {} },
+      { function_call_id: 'fc-2', function_id: 'shell::shell', args: {} },
+    ]
+    const next: PendingApproval[] = [prev[0]!]
+    expect(diffPending(prev, next)).toEqual({
+      added: [],
+      removed: [prev[1]],
+    })
+  })
+
+  it('is keyed by function_call_id (treats objects with same id as same entry)', () => {
+    const prev: PendingApproval[] = [
+      { function_call_id: 'fc-1', function_id: 'shell::shell', args: { command: 'ls' } },
+    ]
+    const next: PendingApproval[] = [
+      { function_call_id: 'fc-1', function_id: 'shell::shell', args: { command: 'rm' } },
+    ]
+    expect(diffPending(prev, next)).toEqual({ added: [], removed: [] })
+  })
+})

console/web/src/lib/backend/pending-approvals-store.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure helpers for diffing two pending-approval lists by function_call_id.
+ * Used by the translate layer to derive synthetic `fcall-start` /
+ * `fcall-end` events from successive `turn_state_changed` updates.
+ *
+ * No state lives here — the per-session list lives in the closure of
+ * `realStream` (one chat = one mirror) and is passed in/out as plain
+ * arrays. Keeping this file framework-free makes it unit-testable in
+ * isolation.
+ */
+
+export interface PendingApproval {
+  function_call_id: string
+  function_id: string
+  args: unknown
+}
+
+export interface PendingDiff {
+  added: PendingApproval[]
+  removed: PendingApproval[]
+}
+
+export function diffPending(
+  prev: PendingApproval[],
+  next: PendingApproval[],
+): PendingDiff {
+  const prevIds = new Set(prev.map((e) => e.function_call_id))
+  const nextIds = new Set(next.map((e) => e.function_call_id))
+  return {
+    added: next.filter((e) => !prevIds.has(e.function_call_id)),
+    removed: prev.filter((e) => !nextIds.has(e.function_call_id)),
+  }
+}

console/web/src/lib/backend/real.ts

@@ -43,7 +43,7 @@ import { getIiiClient } from '@/lib/iii-client'
 import { newMessageId } from '@/lib/session-id'
 import type { Mode, ModelId } from '@/types/chat'
 import type { AgentEvent, SessionEventEnvelope } from '@/types/iii-agent-event'
-import { translateAgentEvent } from './translate'
+import { createTurnStateTranslator, translateAgentEvent } from './translate'
 import type { ChatBackend, ChatStreamOptions, StreamEvent } from './types'
 
 interface RunParams {
@@ -112,6 +112,41 @@ async function* realStream(
     })
     subscribed = true
 
+    const turnStateTranslator = createTurnStateTranslator()
+
+    // Recover any pending approvals after a reload — the orchestrator only
+    // re-broadcasts turn_state on the next write, so without this we'd never
+    // surface a modal for an approval that was already parked when the page
+    // loaded.
+    client
+      .call<Record<string, unknown> | null>('state::get', {
+        scope: 'agent',
+        key: `session/${sessionId}/turn_state`,
+      })
+      .then((record) => {
+        if (!record) return
+        // Push (not unshift): the persisted state is always older than the
+        // freshly-subscribed live stream. If live turn_state events already
+        // arrived, the recovery should be processed after them so the
+        // translator's mirror reflects the freshest server state. If no live
+        // events have arrived yet, the recovery is the first event in the
+        // queue and is processed in natural order.
+        queue.push({
+          type: 'turn_state_changed',
+          event_type: 'state:created',
+          new_value: record,
+        })
+        wake()
+      })
+      .catch((err) => {
+        if (import.meta.env.DEV) {
+          console.warn(
+            '[real-backend] state::get turn_state recovery failed',
+            err,
+          )
+        }
+      })
+
     const { provider, model: modelId } = resolveRunParams(model)
 
     // Route the turn-orchestrator kick-off through `harness::call` so the
@@ -178,7 +213,11 @@ async function* realStream(
       if (kickoffError) continue
       const event = queue.shift()
       if (!event) continue
-      for (const streamEvent of translateAgentEvent(event, sessionId)) {
+      const streamEvents =
+        event.type === 'turn_state_changed'
+          ? turnStateTranslator(event, sessionId)
+          : translateAgentEvent(event, sessionId)
+      for (const streamEvent of streamEvents) {
         yield streamEvent
       }
       if (event.type === 'agent_end') return

console/web/src/lib/backend/translate.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest'
+import type { AgentEvent } from '@/types/iii-agent-event'
+import { createTurnStateTranslator } from './translate'
+
+describe('createTurnStateTranslator', () => {
+  it('emits fcall-start { pendingApproval: true } when a new entry appears', () => {
+    const translate = createTurnStateTranslator()
+    const event: AgentEvent = {
+      type: 'turn_state_changed',
+      event_type: 'state:updated',
+      new_value: {
+        state: 'function_awaiting_approval',
+        awaiting_approval: [
+          {
+            function_call_id: 'fc-1',
+            function_id: 'shell::fs::write',
+            args: { path: '/tmp/x' },
+          },
+        ],
+      },
+      old_value: {
+        state: 'function_execute',
+        awaiting_approval: [],
+      },
+    }
+    expect(translate(event, 'sess-a')).toEqual([
+      {
+        kind: 'fcall-start',
+        functionId: 'shell::fs::write',
+        input: { path: '/tmp/x' },
+        pendingApproval: true,
+        functionCallId: 'fc-1',
+        sessionId: 'sess-a',
+      },
+    ])
+  })
+
+  it('emits nothing when the awaiting_approval list is unchanged', () => {
+    const translate = createTurnStateTranslator()
+    const same = {
+      state: 'function_awaiting_approval',
+      awaiting_approval: [
+        { function_call_id: 'fc-1', function_id: 'shell::shell', args: {} },
+      ],
+    }
+    translate(
+      {
+        type: 'turn_state_changed',
+        event_type: 'state:created',
+        new_value: same,
+      },
+      'sess-a',
+    )
+    expect(
+      translate(
+        {
+          type: 'turn_state_changed',
+          event_type: 'state:updated',
+          new_value: same,
+          old_value: same,
+        },
+        'sess-a',
+      ),
+    ).toEqual([])
+  })
+
+  it('emits nothing when state leaves function_awaiting_approval (the orchestrator emits the matching function_execution_end)', () => {
+    const translate = createTurnStateTranslator()
+    translate(
+      {
+        type: 'turn_state_changed',
+        event_type: 'state:created',
+        new_value: {
+          state: 'function_awaiting_approval',
+          awaiting_approval: [
+            { function_call_id: 'fc-1', function_id: 'shell::shell', args: {} },
+          ],
+        },
+      },
+      'sess-a',
+    )
+    expect(
+      translate(
+        {
+          type: 'turn_state_changed',
+          event_type: 'state:updated',
+          new_value: { state: 'function_execute', awaiting_approval: [] },
+          old_value: {
+            state: 'function_awaiting_approval',
+            awaiting_approval: [
+              { function_call_id: 'fc-1', function_id: 'shell::shell', args: {} },
+            ],
+          },
+        },
+        'sess-a',
+      ),
+    ).toEqual([])
+  })
+
+  it('partitions mirrors by sessionId so two chats do not interfere', () => {
+    const translate = createTurnStateTranslator()
+    const pending = {
+      state: 'function_awaiting_approval',
+      awaiting_approval: [
+        { function_call_id: 'fc-1', function_id: 'shell::shell', args: {} },
+      ],
+    }
+    translate(
+      { type: 'turn_state_changed', event_type: 'state:created', new_value: pending },
+      'sess-a',
+    )
+    expect(
+      translate(
+        { type: 'turn_state_changed', event_type: 'state:created', new_value: pending },
+        'sess-b',
+      ),
+    ).toHaveLength(1)
+  })
+})