feat: Reginald is real — model router + agent loop + query_project (P4)

The fixture chat panel is now a working agent. Ask Reginald a question and it
consults the real project through a tool loop, then answers in grounded prose.
Read-only v0 — writes still go through the propose-approve controls.

core (@commitea/core/agent):
- chat-client: OpenAI-wire chat completions over an injected fetch (same seam as
  gitea). Points at any OpenAI-compatible endpoint (LM Studio/Ollama/OpenAI).
- model-router: small model for prose + the read tool; big model reserved for
  later decomposition (pickModel).
- agent-loop: runAgentTurn drives call→tool→result→call until prose (or a step
  budget), recording each tool step. Injected complete + execute → fully testable.
- query-project: the single read tool's engine — compact focus/board/calibration/
  issue/search views built from scheduler + lifecycle + calibration; unbuilt views
  return a notImplemented marker (never fabricated). The model reports, never computes.
- agent-tools: query_project declaration + Reginald's system prompt.

app:
- main model bridge (model:status, model:chat) runs the loop; query_project
  reconciles the repo and builds the view. Model traffic stays in main (token/CSP).
  gitea.ts refactored to share getGiteaClient + reconcileSnapshot.
- preload + global.d.ts expose the model bridge; useChat drives the panel — real
  agent turn when a model is configured, scripted fixture reply otherwise (so
  fixture e2e is unchanged). A subtle "consulted the project" activity line.

Model config (env, defaults to LM Studio on :1234): COMMITEA_MODEL_URL /
_SMALL (google/gemma-4-e4b) / _BIG (qwen/qwen3.6-35b-a3b). COMMITEA_E2E=1 keeps
it unconfigured so the panel stays scripted.

Verified: 88 core tests green (14 agent: client parse, loop tool/error/budget,
all views) + a gated live integration test. Desktop typecheck clean, 14 fixture
e2e green. Gated live e2e drives the real app against gitea + gemma-4-e4b: asked
"what now?", Reginald called query_project and answered "focus is on issue #2"
(the real scheduler pick).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/desktop/e2e/live-reginald.spec.ts

@@ -0,0 +1,33 @@
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { _electron as electron, expect, test } from '@playwright/test'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const MAIN = join(here, '..', 'out', 'main', 'index.js')
+
+// Opt-in (GITEA_LIVE=1 + COMMITEA_MODEL_LIVE=1 + a local model on :1234). Launches
+// WITHOUT COMMITEA_E2E so Reginald runs the real agent loop against the real repo.
+test.describe('live Reginald', () => {
+  test('answers a question by consulting the real project', async () => {
+    test.skip(!process.env.GITEA_LIVE || !process.env.COMMITEA_MODEL_LIVE, 'live model test — opt-in')
+    test.setTimeout(120_000)
+    const app = await electron.launch({ args: [MAIN], env: { ...process.env } })
+    const win = await app.firstWindow()
+    await win.waitForLoadState('domcontentloaded')
+
+    // model configured → the live greeting + header, not the scripted demo
+    await expect(win.getByText('gemma-4 · local')).toBeVisible({ timeout: 20000 })
+    await expect(win.getByText(/I check the real board before I answer/)).toBeVisible()
+
+    const composer = win.getByPlaceholder(/Tell me what to do/)
+    await composer.fill('What should I work on right now?')
+    await composer.press('Enter')
+
+    // the agent loop ran end-to-end: it consulted the project, then answered
+    await expect(win.getByText(/consulted the project/)).toBeVisible({ timeout: 90_000 })
+    await win.screenshot({ path: join(here, '.artifacts', 'screens', 'live-reginald.png'), fullPage: true, animations: 'disabled' })
+
+    await app.close()
+  })
+})

apps/desktop/src/main/gitea.ts

@@ -9,7 +9,13 @@
 import { readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
-import { createGiteaClient, type GiteaConfig, type LifecycleEvent } from '@commitea/core'
+import {
+  createGiteaClient,
+  type GiteaClient,
+  type GiteaConfig,
+  type LifecycleEvent,
+  type ProjectSnapshot,
+} from '@commitea/core'
 import { ipcMain } from 'electron'
 
 /** Walk up from cwd looking for a .env.local with a GITEA_TOKEN (dev convenience). */
@@ -43,28 +49,45 @@ function resolveConfig(): GiteaConfig | null {
   }
 }
 
-export function registerGiteaIpc(): void {
-  const config = resolveConfig()
-  const client = config ? createGiteaClient(config, fetch) : null
-  const repo = config ? `${config.owner}/${config.repo}` : null
+// Memoized client so both the gitea and model bridges share one instance.
+let sharedClient: GiteaClient | null | undefined
+export function getGiteaClient(): GiteaClient | null {
+  if (sharedClient === undefined) {
+    const config = resolveConfig()
+    sharedClient = config ? createGiteaClient(config, fetch) : null
+  }
+  return sharedClient
+}
 
-  ipcMain.handle('gitea:status', () => ({ configured: !!config, repo }))
+/** Full reconcile: issues + milestones + native deps + lifecycle timelines. */
+export async function reconcileSnapshot(
+  client: GiteaClient,
+): Promise<ProjectSnapshot & { milestones: Awaited<ReturnType<GiteaClient['listMilestones']>> }> {
+  const [issues, milestones] = await Promise.all([client.listIssues(), client.listMilestones()])
+  // dependency edges among the open scope (the scheduler only plans what's left)
+  const open = issues.filter((i) => i.state === 'open')
+  const perIssue = await Promise.all(
+    open.map(async (i) => ({ issue: i.number, dependsOn: await client.getIssueDependencies(i.number) })),
+  )
+  const deps = perIssue.flatMap(({ issue, dependsOn }) => dependsOn.map((d) => ({ issue, dependsOn: d })))
+  // lifecycle timelines for every issue (open → columns/badges, closed → calibration actuals)
+  const timelineEntries = await Promise.all(
+    issues.map(async (i) => [i.number, await client.getIssueTimeline(i.number)] as const),
+  )
+  const timelines: Record<number, LifecycleEvent[]> = Object.fromEntries(timelineEntries)
+  return { issues, milestones, deps, timelines }
+}
+
+export function registerGiteaIpc(): void {
+  const client = getGiteaClient()
+  const repo = client ? `${process.env.GITEA_OWNER ?? 'christian'}/${process.env.GITEA_REPO ?? 'commitea'}` : null
+
+  ipcMain.handle('gitea:status', () => ({ configured: !!client, repo }))
 
   ipcMain.handle('gitea:reconcile', async () => {
     if (!client) return { configured: false, issues: [], milestones: [], deps: [], timelines: {} }
-    const [issues, milestones] = await Promise.all([client.listIssues(), client.listMilestones()])
-    // dependency edges among the open scope (the scheduler only plans what's left)
-    const open = issues.filter((i) => i.state === 'open')
-    const perIssue = await Promise.all(
-      open.map(async (i) => ({ issue: i.number, dependsOn: await client.getIssueDependencies(i.number) })),
-    )
-    const deps = perIssue.flatMap(({ issue, dependsOn }) => dependsOn.map((d) => ({ issue, dependsOn: d })))
-    // lifecycle timelines for every issue (open → columns/badges, closed → calibration actuals)
-    const timelineEntries = await Promise.all(
-      issues.map(async (i) => [i.number, await client.getIssueTimeline(i.number)] as const),
-    )
-    const timelines: Record<number, LifecycleEvent[]> = Object.fromEntries(timelineEntries)
-    return { configured: true, issues, milestones, deps, timelines }
+    const snap = await reconcileSnapshot(client)
+    return { configured: true, ...snap }
   })
 
   ipcMain.handle('gitea:getIssue', async (_event, index: number) => {

apps/desktop/src/main/index.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 import { BrowserWindow, app, shell } from 'electron'
 
 import { registerGiteaIpc } from './gitea.js'
+import { registerModelIpc } from './model.js'
 
 function createWindow(): void {
   const win = new BrowserWindow({
@@ -35,6 +36,7 @@ function createWindow(): void {
 
 void app.whenReady().then(() => {
   registerGiteaIpc()
+  registerModelIpc()
   createWindow()
 
   app.on('activate', () => {

apps/desktop/src/main/model.ts

@@ -0,0 +1,69 @@
+/**
+ * Main-process model bridge — Reginald's brain runs here. Model traffic (like
+ * gitea's) stays in main: the renderer is CSP-locked and never talks to the
+ * LLM directly. On `model:chat` it drives the agent loop against the configured
+ * OpenAI-compatible endpoint, executing `query_project` by reconciling the repo
+ * and building the requested view. v0 is read-only — writes still go through the
+ * propose-approve controls.
+ */
+
+import {
+  buildProjectView,
+  type ChatMessage,
+  createChatClient,
+  type ModelRouter,
+  type ProjectView,
+  type QueryFilters,
+  REGINALD_SYSTEM,
+  REGINALD_TOOLS,
+  runAgentTurn,
+} from '@commitea/core'
+import { ipcMain } from 'electron'
+
+import { getGiteaClient, reconcileSnapshot } from './gitea.js'
+
+/** Small local model for prose + the read tool; big model reserved for later decomposition. */
+function resolveModelRouter(): ModelRouter | null {
+  if (process.env.COMMITEA_E2E === '1') return null // e2e uses the scripted fixture Reginald
+  const baseUrl = process.env.COMMITEA_MODEL_URL ?? 'http://localhost:1234/v1'
+  if (!baseUrl) return null
+  return {
+    small: { baseUrl, model: process.env.COMMITEA_MODEL_SMALL ?? 'google/gemma-4-e4b' },
+    big: { baseUrl, model: process.env.COMMITEA_MODEL_BIG ?? 'qwen/qwen3.6-35b-a3b' },
+  }
+}
+
+export function registerModelIpc(): void {
+  const router = resolveModelRouter()
+
+  ipcMain.handle('model:status', () => ({
+    configured: !!router,
+    model: router?.small.model ?? null,
+  }))
+
+  ipcMain.handle('model:chat', async (_event, messages: ChatMessage[]) => {
+    if (!router) return { ok: false as const, reason: 'unconfigured' as const }
+    const client = getGiteaClient()
+    const chat = createChatClient(router.small, fetch)
+
+    const execute = async (name: string, args: unknown) => {
+      if (name !== 'query_project') return { error: `unknown tool: ${name}` }
+      if (!client) return { error: 'gitea is not configured' }
+      const snap = await reconcileSnapshot(client)
+      const a = (args ?? {}) as { view: ProjectView; filters?: QueryFilters }
+      return buildProjectView(a.view, a.filters, snap, new Date())
+    }
+
+    try {
+      const turn = await runAgentTurn({
+        complete: (m, t) => chat.complete(m, t),
+        messages: [{ role: 'system', content: REGINALD_SYSTEM }, ...messages],
+        tools: REGINALD_TOOLS,
+        execute,
+      })
+      return { ok: true as const, content: turn.content, steps: turn.steps }
+    } catch (e) {
+      return { ok: false as const, reason: 'error' as const, message: e instanceof Error ? e.message : String(e) }
+    }
+  })
+}

apps/desktop/src/preload/index.ts

@@ -10,6 +10,12 @@ const api = {
     /** One issue by index, normalized (or null if unconfigured). */
     getIssue: (index: number) => ipcRenderer.invoke('gitea:getIssue', index),
   },
+  model: {
+    /** Whether a model endpoint is configured (else the UI keeps the scripted Reginald). */
+    status: () => ipcRenderer.invoke('model:status'),
+    /** One agent turn: messages in, Reginald's prose + the tools it consulted out. */
+    chat: (messages: unknown) => ipcRenderer.invoke('model:chat', messages),
+  },
 }
 
 export type CommiteaApi = typeof api

apps/desktop/src/renderer/src/components/shell/chat-panel.tsx

@@ -1,12 +1,13 @@
 import React, { useEffect, useRef, useState } from 'react'
 
-import { CANNED_REPLY, CHAT, type ChatMessage } from '../../data/fixtures.js'
+import { useChat } from '../../lib/use-chat.js'
 import { Icon, IconButton } from '../ui/index.js'
 
 /**
- * Reginald's panel — chat is the write-path (decisions.md D1). This is the P3-2
- * fixture shell: it echoes a canned reply so the layout + interactions are real,
- * but no model is wired. P4 replaces `send` with the model router + tools.
+ * Reginald's panel — chat is the write-path (decisions.md D1). Wired to the
+ * model bridge via `useChat`: when a model is configured, sending drives a real
+ * agent turn (query_project + prose); otherwise it echoes the scripted fixture
+ * reply so the layout stays real. Writes still go through propose-approve.
  */
 export interface ChatPanelProps {
   onOpenDirectives?: () => void
@@ -14,9 +15,8 @@ export interface ChatPanelProps {
 }
 
 export function ChatPanel({ onOpenDirectives, offline }: ChatPanelProps) {
-  const [msgs, setMsgs] = useState<ChatMessage[]>(CHAT)
+  const { msgs, thinking, live, steps, send: sendChat } = useChat()
   const [text, setText] = useState('')
-  const [thinking, setThinking] = useState(false)
   const scrollRef = useRef<HTMLDivElement>(null)
 
   useEffect(() => {
@@ -27,13 +27,8 @@ export function ChatPanel({ onOpenDirectives, offline }: ChatPanelProps) {
   const send = () => {
     const t = text.trim()
     if (!t) return
-    setMsgs((m) => [...m, { from: 'user', text: t }])
     setText('')
-    setThinking(true)
-    setTimeout(() => {
-      setThinking(false)
-      setMsgs((m) => [...m, { from: 'agent', text: CANNED_REPLY }])
-    }, 900)
+    sendChat(t)
   }
 
   return (
@@ -61,7 +56,7 @@ export function ChatPanel({ onOpenDirectives, offline }: ChatPanelProps) {
         <Icon name="sparkles" size={16} style={{ color: offline ? 'var(--ink-3)' : 'var(--jade)' }} />
         <span style={{ font: 'var(--text-body-strong)', color: 'var(--ink-1)' }}>Reginald</span>
         <span style={{ font: '400 11px var(--font-mono)', color: 'var(--ink-3)', marginLeft: 'auto' }}>
-          {offline ? 'offline · queueing' : 'gemma-4b · local'}
+          {offline ? 'offline · queueing' : live ? 'gemma-4 · local' : 'demo · scripted'}
         </span>
         <IconButton icon="history" label="Directive log" size="sm" onClick={onOpenDirectives} />
       </header>
@@ -98,6 +93,11 @@ export function ChatPanel({ onOpenDirectives, offline }: ChatPanelProps) {
           </div>
         ) : null}
         {thinking ? <div style={{ font: 'var(--text-agent)', color: 'var(--ink-3)' }}>considering…</div> : null}
+        {!thinking && steps.length ? (
+          <div style={{ font: 'var(--text-caption)', color: 'var(--ink-3)', display: 'flex', alignItems: 'center', gap: 5 }}>
+            <Icon name="eye" size={11} /> consulted {Array.from(new Set(steps.map((s) => s.replace('query_project', 'the project')))).join(', ')}
+          </div>
+        ) : null}
       </div>
 
       <div style={{ padding: 14, borderTop: '1px solid var(--line-1)', flexShrink: 0 }}>

apps/desktop/src/renderer/src/global.d.ts

@@ -1,4 +1,11 @@
-import type { DependencyEdge, GiteaIssue, GiteaMilestone, LifecycleEvent } from '@commitea/core'
+import type {
+  AgentStep,
+  ChatMessage,
+  DependencyEdge,
+  GiteaIssue,
+  GiteaMilestone,
+  LifecycleEvent,
+} from '@commitea/core'
 
 /** The gitea bridge exposed by the preload over IPC (main-process backed). */
 export interface GiteaBridge {
@@ -14,11 +21,23 @@ export interface GiteaBridge {
   getIssue(index: number): Promise<GiteaIssue | null>
 }
 
+/** One agent turn's result. */
+export type ChatResult =
+  | { ok: false; reason: 'unconfigured' | 'error'; message?: string }
+  | { ok: true; content: string; steps: AgentStep[] }
+
+/** The model bridge (Reginald) exposed by the preload over IPC. */
+export interface ModelBridge {
+  status(): Promise<{ configured: boolean; model: string | null }>
+  chat(messages: ChatMessage[]): Promise<ChatResult>
+}
+
 declare global {
   interface Window {
     commitea: {
       platform: string
       gitea: GiteaBridge
+      model: ModelBridge
     }
   }
 }

apps/desktop/src/renderer/src/lib/use-chat.ts

@@ -0,0 +1,101 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import type { ChatMessage as WireMessage } from '@commitea/core'
+
+import { CANNED_REPLY, CHAT, type ChatMessage } from '../data/fixtures.js'
+
+const LIVE_GREETING: ChatMessage = {
+  from: 'agent',
+  text: 'Morning. Ask me anything about the project — I check the real board before I answer.',
+}
+
+export interface ChatState {
+  msgs: ChatMessage[]
+  thinking: boolean
+  /** true once a model endpoint is confirmed; otherwise the panel echoes the demo reply. */
+  live: boolean
+  /** Tools Reginald consulted on the last turn (for a subtle activity line). */
+  steps: string[]
+  send: (text: string) => void
+}
+
+/**
+ * Reginald's conversation. When a model is configured, `send` drives one agent
+ * turn through the main-process bridge (which runs the tool loop). Otherwise it
+ * echoes the scripted fixture reply, so the layout stays real with no model and
+ * fixture e2e is unaffected. The fixture greeting is display-only — only real
+ * turns (`convo`) are sent to the model as history.
+ */
+export function useChat(): ChatState {
+  const [seed, setSeed] = useState<ChatMessage[]>(CHAT)
+  const [convo, setConvo] = useState<ChatMessage[]>([])
+  const [thinking, setThinking] = useState(false)
+  const [live, setLive] = useState(false)
+  const [steps, setSteps] = useState<string[]>([])
+  const convoRef = useRef(convo)
+  convoRef.current = convo
+
+  useEffect(() => {
+    let alive = true
+    window.commitea.model
+      .status()
+      .then((s) => {
+        if (alive && s.configured) {
+          setLive(true)
+          setSeed([LIVE_GREETING])
+        }
+      })
+      .catch(() => {})
+    return () => {
+      alive = false
+    }
+  }, [])
+
+  const send = useCallback(
+    (raw: string) => {
+      const text = raw.trim()
+      if (!text) return
+      const nextConvo: ChatMessage[] = [...convoRef.current, { from: 'user', text }]
+      setConvo(nextConvo)
+      setThinking(true)
+      setSteps([])
+
+      if (!live) {
+        window.setTimeout(() => {
+          setThinking(false)
+          setConvo((c) => [...c, { from: 'agent', text: CANNED_REPLY }])
+        }, 900)
+        return
+      }
+
+      const wire: WireMessage[] = nextConvo.map((m) => ({
+        role: m.from === 'user' ? 'user' : 'assistant',
+        content: m.text,
+      }))
+      window.commitea.model
+        .chat(wire)
+        .then((res) => {
+          setThinking(false)
+          if (res.ok) {
+            setSteps(res.steps.map((s) => s.tool))
+            setConvo((c) => [...c, { from: 'agent', text: res.content || '…' }])
+          } else {
+            setConvo((c) => [
+              ...c,
+              {
+                from: 'agent',
+                text: res.reason === 'error' ? `I hit a snag: ${res.message ?? 'unknown error'}` : 'No model is configured.',
+              },
+            ])
+          }
+        })
+        .catch(() => {
+          setThinking(false)
+          setConvo((c) => [...c, { from: 'agent', text: 'I could not reach the model.' }])
+        })
+    },
+    [live],
+  )
+
+  return { msgs: [...seed, ...convo], thinking, live, steps, send }
+}