Merge upstream/main: performance, PR workflows, and UI improvements

.github/workflows/ci.yml

@@ -8,7 +8,7 @@ on:
 
 jobs:
   quality:
-    name: Lint, Typecheck, Test, Browser Test, Build
+    name: Format, Lint, Typecheck, Test, Browser Test, Build
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
       - name: Checkout
@@ -45,6 +45,9 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
+      - name: Format
+        run: bun run fmt:check
+
       - name: Lint
         run: bun run lint
 

.oxfmtrc.json

@@ -7,7 +7,8 @@
     "node_modules",
     "bun.lock",
     "*.tsbuildinfo",
-    "**/routeTree.gen.ts"
+    "**/routeTree.gen.ts",
+    "apps/web/public/mockServiceWorker.js"
   ],
-  "experimentalSortPackageJson": {}
+  "sortPackageJson": {}
 }

.plans/01-shared-model-normalization.md

@@ -1,20 +1,24 @@
 # Plan: Centralize Model Normalization in Contracts
 
 ## Summary
+
 Move model alias/default normalization into `packages/contracts` so desktop and renderer use one shared source of truth.
 
 ## Motivation
+
 - Removes duplicated logic between:
   - `apps/desktop/src/codexAppServerManager.ts`
   - `apps/renderer/src/model-logic.ts`
 - Prevents behavior drift when model aliases/defaults are updated.
 
 ## Scope
+
 - Add shared model utilities to contracts.
 - Update desktop and renderer to consume shared utilities.
 - Keep renderer-specific display options in renderer.
 
 ## Proposed Changes
+
 1. Add `packages/contracts/src/model.ts` with:
    - Canonical model list
    - Alias map
@@ -29,14 +33,17 @@ Move model alias/default normalization into `packages/contracts` so desktop and
    - Keep renderer tests focused on renderer-only behavior.
 
 ## Risks
+
 - Desktop/renderer may currently rely on slightly different fallback behavior.
 - Import graph must avoid bundling issues for Electron main/preload.
 
 ## Validation
+
 - `bun run test`
 - `bun run typecheck`
 - Manual check that model selection and session start still send expected model slug.
 
 ## Done Criteria
+
 - No duplicated alias/default map in desktop and renderer.
 - Shared model utilities are contract-tested.

.plans/02-typed-ipc-boundaries.md

@@ -1,17 +1,21 @@
 # Plan: Strengthen Typed IPC Boundaries in Main Process
 
 ## Summary
+
 Replace loose payload casting in IPC handlers with strict schema parsing and typed helper wrappers.
 
 ## Motivation
+
 - `apps/desktop/src/main.ts` currently uses casts like `payload as Parameters<...>`.
 - Casts can hide contract breakages until runtime.
 
 ## Scope
+
 - Desktop main process IPC registration.
 - Optional shared helper for handler registration.
 
 ## Proposed Changes
+
 1. Add IPC helper utility (e.g. `apps/desktop/src/ipcHelpers.ts`) to:
    - Parse payload(s) with Zod schemas
    - Standardize typed handler signatures
@@ -24,14 +28,17 @@ Replace loose payload casting in IPC handlers with strict schema parsing and typ
 4. Add tests for handler parsing failure paths (invalid payloads).
 
 ## Risks
+
 - Refactor can subtly change IPC error shape/messages.
 - Helper abstraction should stay simple and not obscure control flow.
 
 ## Validation
+
 - `bun run test`
 - `bun run typecheck`
 - Manual invalid payload check from renderer/devtools to confirm fast failure.
 
 ## Done Criteria
+
 - No provider handler uses `payload as Parameters<...>`.
 - All IPC entrypoints parse unknown payloads at boundary.

.plans/03-split-codex-app-server-manager.md

@@ -1,9 +1,11 @@
 # Plan: Decompose CodexAppServerManager
 
 ## Summary
+
 Split `CodexAppServerManager` into smaller modules with clear responsibilities.
 
 ## Motivation
+
 - `apps/desktop/src/codexAppServerManager.ts` is large and mixes:
   - Process lifecycle
   - JSON-RPC parsing/routing
@@ -12,10 +14,12 @@ Split `CodexAppServerManager` into smaller modules with clear responsibilities.
 - This increases regression risk and slows changes.
 
 ## Scope
+
 - Desktop provider internals only.
 - Keep external behavior/API stable.
 
 ## Proposed Changes
+
 1. Extract modules:
    - `codex/processLifecycle.ts`
    - `codex/jsonrpcRouter.ts`
@@ -29,13 +33,16 @@ Split `CodexAppServerManager` into smaller modules with clear responsibilities.
    - Session state transitions
 
 ## Risks
+
 - Reordering event handling can change behavior.
 - Must preserve pending request timeout/cancellation semantics.
 
 ## Validation
+
 - Existing tests pass.
 - Add module-level tests for parsing and transition logic.
 
 ## Done Criteria
+
 - Main manager file materially smaller and orchestration-focused.
 - Core protocol/state logic covered by focused tests.

.plans/04-split-chatview-component.md

@@ -1,9 +1,11 @@
 # Plan: Split ChatView into Smaller UI/Logic Units
 
 ## Summary
+
 Refactor `ChatView.tsx` into composable pieces with isolated responsibilities.
 
 ## Motivation
+
 - `apps/renderer/src/components/ChatView.tsx` is large and handles:
   - Session orchestration
   - Send/interrupt actions
@@ -13,10 +15,12 @@ Refactor `ChatView.tsx` into composable pieces with isolated responsibilities.
 - Hard to test and maintain as one component.
 
 ## Scope
+
 - Renderer component boundaries and hooks.
 - Keep visual behavior unchanged.
 
 ## Proposed Changes
+
 1. Create hook: `apps/renderer/src/hooks/useChatSession.ts`
    - `ensureSession`
    - `sendTurn`
@@ -29,12 +33,15 @@ Refactor `ChatView.tsx` into composable pieces with isolated responsibilities.
 4. Add focused tests for hook behavior (error handling, session reuse).
 
 ## Risks
+
 - Refactor can break subtle UI interactions (auto-scroll, menu close, keyboard send).
 
 ## Validation
+
 - `bun run test`
 - Manual smoke: send, stream, interrupt, model switch.
 
 ## Done Criteria
+
 - `ChatView.tsx` significantly reduced and easier to scan.
 - Session logic isolated from rendering.

.plans/05-zod-persisted-state-validation.md

@@ -1,17 +1,21 @@
 # Plan: Move Renderer Persisted-State Validation to Zod
 
 ## Summary
+
 Use explicit Zod schemas for localStorage state parsing and migration.
 
 ## Motivation
+
 - `apps/renderer/src/store.ts` has large manual sanitize functions.
 - Manual type guards are verbose and easier to get wrong during schema evolution.
 
 ## Scope
+
 - Renderer state hydration/persistence path.
 - No backend/protocol changes.
 
 ## Proposed Changes
+
 1. Add schema module: `apps/renderer/src/persistenceSchema.ts`
    - Persisted payload versions (`v1`, `v2`)
    - Thread/message/project schemas
@@ -23,12 +27,15 @@ Use explicit Zod schemas for localStorage state parsing and migration.
    - Unknown thread/project references filtered
 
 ## Risks
+
 - Overly strict schemas could drop valid historical data unexpectedly.
 
 ## Validation
+
 - Unit tests for migration/hydration.
 - Manual reload test with existing localStorage data.
 
 ## Done Criteria
+
 - Store hydration logic is schema-driven.
 - Migration behavior is tested and documented.

.plans/06-provider-logstream-lifecycle.md

@@ -1,17 +1,21 @@
 # Plan: Add Provider Log Stream Lifecycle Management
 
 ## Summary
+
 Ensure `ProviderManager` logging stream is initialized, rotated/structured, and closed safely.
 
 ## Motivation
+
 - `apps/desktop/src/providerManager.ts` opens a write stream in constructor.
 - Stream lifecycle is not explicit on shutdown.
 
 ## Scope
+
 - Desktop provider logging behavior.
 - App shutdown integration.
 
 ## Proposed Changes
+
 1. Add explicit `dispose()` on `ProviderManager`:
    - Remove event listeners
    - End/close log stream
@@ -20,12 +24,15 @@ Ensure `ProviderManager` logging stream is initialized, rotated/structured, and
 4. Optional: per-session log files under `.logs/providers/`.
 
 ## Risks
+
 - Improper close sequencing may lose final log lines.
 
 ## Validation
+
 - Manual run/quit cycle to ensure no open handle warnings.
 - Confirm logs flush on quit and file descriptors are not leaked.
 
 ## Done Criteria
+
 - ProviderManager owns complete log stream lifecycle.
 - Shutdown path explicitly disposes provider resources.

.plans/07-ci-quality-gates.md

@@ -1,17 +1,21 @@
 # Plan: Add CI Workflow for Core Quality Gates
 
 ## Summary
+
 Add GitHub Actions workflow to run lint/typecheck/test (and optionally smoke-test) on pushes and PRs.
 
 ## Motivation
+
 - Repository currently has no CI workflow files.
 - Quality checks are only local/manual.
 
 ## Scope
+
 - `.github/workflows/ci.yml`
 - Bun + Turbo setup in CI.
 
 ## Proposed Changes
+
 1. Add `ci.yml` with jobs:
    - Setup Bun and Node environment
    - Install deps
@@ -22,13 +26,16 @@ Add GitHub Actions workflow to run lint/typecheck/test (and optionally smoke-tes
 3. Configure caching for Bun/Turbo as appropriate.
 
 ## Risks
+
 - Smoke test may be flaky in headless CI environments.
 - CI runtime can grow if caching is misconfigured.
 
 ## Validation
+
 - Verify workflow runs on a branch PR.
 - Ensure failures surface clearly by job name.
 
 ## Done Criteria
+
 - CI blocks regressions in lint/typecheck/test.
 - Workflow docs added to README.

.plans/08-precommit-format-and-lint.md

@@ -1,17 +1,21 @@
 # Plan: Add Pre-Commit Formatting/Lint Hooks
 
 ## Summary
+
 Introduce pre-commit automation so formatting and basic lint checks happen before commits.
 
 ## Motivation
+
 - Current lint failures include formatting-only issues.
 - Shift-left feedback reduces noisy CI failures and cleanup churn.
 
 ## Scope
+
 - Root tooling config and package scripts.
 - No runtime code changes.
 
 ## Proposed Changes
+
 1. Add hook tooling (e.g. Husky + lint-staged or Lefthook).
 2. Configure staged-file tasks:
    - `biome format --write`
@@ -20,13 +24,16 @@ Introduce pre-commit automation so formatting and basic lint checks happen befor
 4. Keep checks fast to avoid developer friction.
 
 ## Risks
+
 - Slow hooks can frustrate contributors and be bypassed.
 - Need to ensure compatibility with Bun workspace setup.
 
 ## Validation
+
 - Create sample staged changes and verify hook behavior.
 - Confirm formatting fixes are applied automatically.
 
 ## Done Criteria
+
 - Pre-commit hook installed and documented.
 - Formatting-only lint failures drop significantly.

.plans/09-event-state-test-expansion.md

@@ -1,17 +1,21 @@
 # Plan: Expand Event/State Transition Test Coverage
 
 ## Summary
+
 Add focused tests for renderer event handling and session evolution logic.
 
 ## Motivation
+
 - Core behavior is event-driven and stateful.
 - Existing renderer tests cover only a subset of timeline/model behavior.
 
 ## Scope
+
 - `apps/renderer/src/session-logic.test.ts`
 - Optional reducer tests for `apps/renderer/src/store.ts`.
 
 ## Proposed Changes
+
 1. Add tests for `evolveSession`:
    - `thread/started`
    - `turn/started`
@@ -24,12 +28,15 @@ Add focused tests for renderer event handling and session evolution logic.
 3. Add reducer integration tests for `APPLY_EVENT`.
 
 ## Risks
+
 - Tests may be brittle if event payload fixtures are too coupled to implementation details.
 
 ## Validation
+
 - `bun run test`
 - Ensure new tests remain deterministic and fast.
 
 ## Done Criteria
+
 - High-risk event transitions are covered by unit tests.
 - Regressions in stream assembly/session status are caught quickly.