chore(ci): add and apply fmt:check script (#779)

* Add formatting conventions
* Add a fmt lint check
* rely on defaults
---------
Co-authored-by: Julius Marminge <julius0216@outlook.com>

Author: jasonLaster

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.