mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/002-event-bus-system.rispec.md

@@ -0,0 +1,125 @@
+# RISE-002: Event Bus System
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/002-event-bus-system.rispec.md
+
+## Creative Intent
+
+mia-code enables modules to communicate without knowing each other exist. A session module publishes that a session was created; the UI module, the persistence module, and the logging module each react independently. The event bus is the nervous system — it carries signals between organs that never need to touch.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Modules in mia-code call each other directly: `commands.ts` imports `sessionStore.ts`, calls `formatting.ts`, invokes `geminiHeadless.ts`
+- Adding a new consumer of session events (e.g., analytics, sharing, web UI) requires modifying the producer
+- The unifier in `unifier.ts` is tightly coupled to the agent execution flow — it must be called explicitly after each agent response
+- There is no way for an external plugin or module to observe internal events without code changes
+- Cross-cutting concerns (logging every tool execution, timing every agent call) require threading logic through every call site
+
+**Desired State:**
+- Any module can publish a typed event without knowing who listens
+- Any module can subscribe to events without modifying the publisher
+- Events carry structured, validated payloads (via Zod schemas)
+- Events are scoped to an instance (project directory) — events from project A never trigger handlers in project B
+- Subscription cleanup happens automatically when an instance is disposed
+- The event catalog is discoverable: a developer can list all event types and their payload shapes
+
+## Desired Outcome Definition
+
+A centralized `Bus` module that provides `publish()` and `subscribe()` functions. Events are defined as typed constants with Zod-validated payloads. The bus is instance-scoped, meaning each project directory gets its own isolated event channel.
+
+## Natural Language Functional Description
+
+### Event Definition
+
+Each event type is defined as a constant using a factory function:
+
+```
+BusEvent.define("session.created", z.object({
+  sessionId: z.string(),
+  projectRoot: z.string(),
+  engine: z.enum(["gemini", "claude"]),
+  timestamp: z.number()
+}))
+```
+
+This returns an event descriptor object containing the event name string, the Zod schema for its payload, and TypeScript type inference. The descriptor is used for both publishing and subscribing — ensuring type safety at both ends.
+
+### Publishing Events
+
+Any module publishes an event by calling:
+
+```
+Bus.publish(Session.Event.Created, {
+  sessionId: "abc-123",
+  projectRoot: "/home/dev/myproject",
+  engine: "gemini",
+  timestamp: Date.now()
+})
+```
+
+The bus validates the payload against the event's Zod schema at publish time. If validation fails, it throws a `NamedError("bus.invalid_payload", ...)` with details about which fields failed. In production, invalid payloads are logged and dropped rather than crashing.
+
+### Subscribing to Events
+
+Modules subscribe by providing a handler function:
+
+```
+const unsubscribe = Bus.subscribe(Session.Event.Created, (payload) => {
+  // payload is fully typed as { sessionId: string, projectRoot: string, ... }
+  log.info("session created", { sessionId: payload.sessionId });
+});
+```
+
+The returned `unsubscribe` function removes the handler when called. Handlers execute synchronously in subscription order. If a handler throws, the error is caught and logged — it does not prevent other handlers from running.
+
+### Instance Scoping
+
+The bus is scoped to an instance (see RISE-003). When `Bus.publish()` is called, only subscribers within the same instance context receive the event. This prevents a session created in `/project-a` from triggering handlers registered by `/project-b`.
+
+Implementation: the bus stores handlers in a `Map<instanceId, Map<eventName, Set<handler>>>`. Instance ID is derived from the project root directory.
+
+### Event Catalog
+
+The standard event types for mia-code include:
+
+- `session.created` — new session started
+- `session.resumed` — existing session resumed
+- `session.ended` — session explicitly ended
+- `message.sent` — user sent a prompt
+- `message.received` — agent produced a response
+- `message.chunk` — streaming chunk received from agent
+- `tool.started` — agent began executing a tool
+- `tool.completed` — tool execution finished
+- `tool.failed` — tool execution errored
+- `config.changed` — configuration value updated
+- `ceremonial.output` — Mia/Miette interpretation produced
+- `error.occurred` — unhandled error captured
+
+Each event lives as a constant in the namespace of its domain module (e.g., `Session.Event.Created`, `Tool.Event.Started`).
+
+### Cleanup
+
+When an instance is disposed (project context ends), all subscriptions for that instance are removed. The `Bus.disposeInstance(instanceId)` function clears all handlers for that instance. This prevents memory leaks from accumulated handlers across long-running server processes.
+
+## Supporting Structures
+
+- **Instance State (RISE-003)** provides the scoping mechanism — the bus uses instance IDs to isolate events
+- **Namespace Module Pattern (RISE-004)** organizes event constants within domain namespaces
+- **Zod Schema Validation (RISE-005)** validates every event payload at publish time
+- **Named Error System (RISE-006)** provides typed errors for invalid payloads
+- **Structured Logging (RISE-007)** logs event publication and handler errors
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Decoupled Session Persistence:**
+The `sessionStore` module subscribes to `Session.Event.Created`. When a new session starts, the store persists it — without the session creation code ever importing or calling the store. If the store module is removed, sessions still work; they just aren't saved.
+
+**Scenario 2 — Real-Time UI Updates:**
+The TUI subscribes to `Message.Event.Chunk`. As streaming chunks arrive from the agent, the UI renders them immediately. The agent execution code in `geminiHeadless.ts` publishes chunks without knowing whether a TUI, a web client, or nothing at all is listening.
+
+**Scenario 3 — Metrics Collection:**
+A lightweight metrics module subscribes to `Tool.Event.Completed`. It records tool execution durations, success rates, and frequency. No existing code is modified — the metrics module is a pure subscriber.
+
+**Scenario 4 — Plugin System Foundation:**
+A user-authored plugin subscribes to `Message.Event.Received`. After every agent response, the plugin automatically saves a summary to a project journal file. The plugin is loaded dynamically and communicates entirely through the event bus.

package/rispecs/borrowed_from_opencode/003-instance-state-pattern.rispec.md

@@ -0,0 +1,136 @@
+# RISE-003: Instance State Pattern
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/003-instance-state-pattern.rispec.md
+
+## Creative Intent
+
+mia-code enables clean isolation between project contexts. When a developer works on two projects simultaneously, each project's agent sessions, configuration overrides, tool state, and event subscriptions remain completely separate. The instance state pattern makes "per-project singleton" a first-class primitive — initialize once per directory, share within that directory, clean up when done.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code uses global singletons: one `~/.mia-code-sessions.json` file, one `~/.mia-code.json` config
+- The `sessionStore.ts` module reads/writes a global file — if two mia-code processes run for different projects, they race on the same file
+- There is no concept of "project scope" for runtime state — all state is either global (config files) or local (function variables)
+- Agent process handles (the spawned Gemini/Claude CLI) are held in closure variables, not in a managed state container
+- Cleanup of resources (killing agent subprocesses, closing file handles) depends on process exit handlers, not structured disposal
+
+**Desired State:**
+- Each project directory gets an isolated state container that holds all runtime state for that context
+- State is lazily initialized: the container is created on first access, not at startup
+- State is a singleton per directory: multiple calls to `state()` within the same project return the same instance
+- Disposal runs cleanup functions in reverse initialization order
+- Parallel project operation is safe — project A's state never leaks into project B
+- The pattern is generic: any module can declare its own instance-scoped state
+
+## Desired Outcome Definition
+
+A generic `Instance.state<T>(initFn, cleanupFn)` function that returns a lazy accessor. The accessor initializes state on first call, returns the cached value on subsequent calls, and runs cleanup when the instance is disposed.
+
+## Natural Language Functional Description
+
+### State Declaration
+
+A module declares instance-scoped state by calling:
+
+```
+const sessionState = Instance.state(
+  async () => {
+    // init: runs once per project directory
+    const store = await loadSessionIndex(projectRoot);
+    return { store, activeSessions: new Map() };
+  },
+  async (state) => {
+    // cleanup: runs when instance is disposed
+    await saveSessionIndex(state.store);
+    for (const session of state.activeSessions.values()) {
+      await session.kill();
+    }
+  }
+);
+```
+
+This returns a `StateAccessor<T>` — a callable that resolves to the state value.
+
+### State Access
+
+Any code within the same instance context accesses the state by awaiting the accessor:
+
+```
+const { store, activeSessions } = await sessionState();
+activeSessions.set(id, newSession);
+```
+
+The first call triggers the init function. Subsequent calls return the cached result immediately (resolved promise). The accessor is typed — TypeScript infers the return type from the init function.
+
+### Concurrent First Access
+
+If two code paths call `await sessionState()` simultaneously before initialization completes, only one init function executes. The second caller awaits the same initialization promise. This prevents double-initialization bugs.
+
+### Instance Identity
+
+The instance is identified by the project root directory (resolved to an absolute path). When `Instance.state()` is called, it captures the current project context from the call stack or an explicit context parameter:
+
+```
+const state = Instance.state(initFn, cleanupFn, { scope: "/home/dev/myproject" });
+```
+
+If no scope is provided, it defaults to `process.cwd()` resolved to the nearest git root (or cwd if no git root exists).
+
+### Instance Lifecycle
+
+- **Creation**: Implicit on first `state()` access within a project directory
+- **Active**: State is cached and returned on every subsequent access
+- **Disposal**: Explicit via `Instance.dispose(projectRoot)` or automatic on process exit
+
+Disposal runs all cleanup functions registered for that project root, in reverse order of registration (LIFO). After disposal, accessing state for that project root re-triggers initialization (the instance is "reset").
+
+### Multiple State Declarations
+
+Different modules declare their own state independently:
+
+```
+// In session module
+const sessionState = Instance.state(async () => ({ sessions: new Map() }));
+
+// In config module
+const configState = Instance.state(async () => await loadConfig(projectRoot));
+
+// In agent module
+const agentState = Instance.state(async () => ({ processes: [] }), async (s) => {
+  for (const p of s.processes) p.kill();
+});
+```
+
+All three are scoped to the same instance (project root) but initialized independently, on demand.
+
+### Instance Registry
+
+Internally, a global registry maps project roots to their state containers:
+
+```
+Map<projectRoot, Map<stateKey, { value: T, cleanup: (v: T) => Promise<void> }>>
+```
+
+Each `Instance.state()` call generates a unique `stateKey` (via symbol or auto-incrementing ID) to distinguish different state declarations within the same instance.
+
+## Supporting Structures
+
+- **Event Bus (RISE-002)** is instance-scoped — it uses the same project root identity to isolate events
+- **Namespace Module Pattern (RISE-004)** co-locates state declarations with their domain modules
+- **Lazy Initialization (RISE-008)** is the underlying mechanism — `Instance.state()` is a specialized lazy with scope and cleanup
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Multi-Project Server:**
+The mia-code server (RISE-001) handles requests for `/project-a` and `/project-b` simultaneously. Each project's session state, agent processes, and event subscriptions are isolated. A request to `/project-a/sessions` never sees `/project-b`'s sessions.
+
+**Scenario 2 — Safe Agent Process Management:**
+The agent module declares instance state that tracks spawned Gemini/Claude CLI processes. When the instance is disposed (server shutdown, project close), the cleanup function kills all agent processes for that project. No orphan processes.
+
+**Scenario 3 — Test Isolation:**
+Tests create instances with temporary directories as project roots. Each test gets pristine state. After the test, `Instance.dispose(tempDir)` runs cleanup. Tests run in parallel without interference.
+
+**Scenario 4 — Config Hot Reload:**
+When a project's `.mia-code.json` changes, the config module disposes and re-initializes its instance state. The new config is picked up on the next `configState()` access. Other modules' state (sessions, agents) is unaffected.

package/rispecs/borrowed_from_opencode/004-namespace-module-pattern.rispec.md

@@ -0,0 +1,151 @@
+# RISE-004: Namespace Module Pattern
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/004-namespace-module-pattern.rispec.md
+
+## Creative Intent
+
+mia-code enables clean, discoverable module APIs through TypeScript namespaces. Each domain concept — Session, Tool, Config, Permission — is a namespace that co-locates its functions, types, events, and constants. A developer types `Session.` and immediately sees everything the session domain offers: `Session.create()`, `Session.Info`, `Session.Event.Created`. No barrel files, no scattered imports, no guessing where things live.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code modules export loose functions and types from individual files (`sessionStore.ts` exports `rememberSession`, `findSession`, etc.)
+- Types are defined in a separate `types.ts` file, divorced from the modules that use them
+- There is no single entry point for a domain concept — understanding "sessions" requires reading `sessionStore.ts`, parts of `commands.ts`, parts of `types.ts`, and parts of `cli.ts`
+- Adding a new domain concept (e.g., permissions, tools) means creating multiple files and wiring imports across the codebase
+- IDE autocomplete shows a flat list of imported functions with no grouping by domain
+
+**Desired State:**
+- Each domain concept is a TypeScript namespace exported from a single file
+- The namespace contains all public API: functions, types (as Zod schemas with inferred types), events, and constants
+- Internal implementation details are private to the file — not exported from the namespace
+- Consumers import one namespace and access everything through it
+- Adding a new domain means creating one file with one namespace
+
+## Desired Outcome Definition
+
+A convention where each major module exports a TypeScript `namespace` containing its complete public API, organized by kind (functions, types, events, constants).
+
+## Natural Language Functional Description
+
+### Namespace Structure
+
+Each domain module follows this pattern:
+
+```typescript
+// src/session.ts
+import { z } from "zod";
+import { Bus, BusEvent } from "./bus";
+
+// Private implementation
+async function loadFromDisk(path: string) { /* ... */ }
+function generateId(): string { /* ... */ }
+
+// Public namespace
+export namespace Session {
+  // --- Types (Zod schemas + inferred types) ---
+  export const Info = z.object({
+    id: z.string(),
+    projectRoot: z.string(),
+    engine: z.enum(["gemini", "claude"]),
+    createdAt: z.number(),
+    lastActiveAt: z.number(),
+  });
+  export type Info = z.infer<typeof Info>;
+
+  export const CreateInput = z.object({
+    projectRoot: z.string(),
+    engine: z.enum(["gemini", "claude"]).default("gemini"),
+  });
+  export type CreateInput = z.infer<typeof CreateInput>;
+
+  // --- Events ---
+  export const Event = {
+    Created: BusEvent.define("session.created", Info),
+    Resumed: BusEvent.define("session.resumed", Info),
+    Ended: BusEvent.define("session.ended", z.object({ id: z.string() })),
+  } as const;
+
+  // --- Functions ---
+  export async function create(input: CreateInput): Promise<Info> {
+    const validated = CreateInput.parse(input);
+    const id = generateId();
+    const session: Info = {
+      id,
+      projectRoot: validated.projectRoot,
+      engine: validated.engine,
+      createdAt: Date.now(),
+      lastActiveAt: Date.now(),
+    };
+    await loadFromDisk(validated.projectRoot); // private fn
+    Bus.publish(Event.Created, session);
+    return session;
+  }
+
+  export async function resume(id: string): Promise<Info> { /* ... */ }
+  export async function list(): Promise<Info[]> { /* ... */ }
+  export async function end(id: string): Promise<void> { /* ... */ }
+
+  // --- Constants ---
+  export const MAX_IDLE_TIME_MS = 30 * 60 * 1000;
+}
+```
+
+### Consumption Pattern
+
+Consumers import the namespace and access everything through it:
+
+```typescript
+import { Session } from "./session";
+
+const session = await Session.create({
+  projectRoot: "/home/dev/myproject",
+  engine: "gemini",
+});
+
+// Type usage
+function displaySession(info: Session.Info) {
+  console.log(info.id, info.projectRoot);
+}
+
+// Event subscription
+Bus.subscribe(Session.Event.Created, (payload) => {
+  log.info("new session", { id: payload.id });
+});
+
+// Schema validation
+const parsed = Session.Info.parse(untrustedData);
+```
+
+### Naming Conventions
+
+- **Namespace name**: PascalCase singular noun (`Session`, `Tool`, `Config`, `Permission`)
+- **Functions**: camelCase verbs (`create`, `resume`, `list`, `validate`)
+- **Type schemas**: PascalCase nouns (`Info`, `CreateInput`, `ListOutput`)
+- **Event objects**: nested under `Event` constant (`Event.Created`, `Event.Failed`)
+- **Constants**: UPPER_SNAKE_CASE (`MAX_IDLE_TIME_MS`, `DEFAULT_ENGINE`)
+
+### What Lives Outside the Namespace
+
+Private implementation functions and third-party imports live outside the namespace at module scope. They are not exported. The namespace is the only export. Exception: cross-cutting utility modules (like `formatting.ts`) may export plain functions. Each namespace lives in one file named after the domain concept (`session.ts`, `tool.ts`, `config.ts`). No barrel files needed.
+
+## Supporting Structures
+
+- **Zod Schema Validation (RISE-005)** provides the schema objects that live inside namespaces as types
+- **Event Bus (RISE-002)** provides the event definitions that live inside namespaces under `Event`
+- **Named Error System (RISE-006)** provides error types that can be co-located in namespaces
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — IDE Discovery:**
+A new contributor types `Session.` in their editor. Autocomplete shows: `create`, `resume`, `list`, `end`, `Info`, `CreateInput`, `Event`, `MAX_IDLE_TIME_MS`. They understand the entire session API without reading documentation.
+
+**Scenario 2 — Adding a New Domain:**
+To add a "Permission" domain, a developer creates `src/permission.ts`, defines `export namespace Permission { ... }` with types, events, and functions. No barrel file updates, no scattered type definitions, no import rewiring. The domain is self-contained.
+
+**Scenario 3 — Refactoring Without Breaking:**
+Renaming an internal helper function inside `session.ts` (outside the namespace) requires zero changes to consumers. The namespace boundary protects the public API from implementation changes.
+
+**Scenario 4 — Type and Validator Colocation:**
+When adding a new field to `Session.Info`, the developer updates the Zod schema in one place. The TypeScript type updates automatically via `z.infer`. Runtime validation updates automatically because the schema IS the validator. One change, three effects.

package/rispecs/borrowed_from_opencode/005-zod-schema-validation.rispec.md

@@ -0,0 +1,139 @@
+# RISE-005: Zod Schema Validation
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/005-zod-schema-validation.rispec.md
+
+## Creative Intent
+
+mia-code enables a single source of truth for every data shape in the system. A Zod schema defines a session object once — TypeScript infers the static type, runtime validation catches malformed data at boundaries, and API documentation generates automatically. No more drift between what the type says, what the validator checks, and what the docs describe. The schema is the contract.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Data shapes in mia-code are defined as TypeScript interfaces in `types.ts` — they exist only at compile time and vanish at runtime
+- The `~/.mia-code-sessions.json` file is read with `JSON.parse()` and cast to a type — if the file is corrupted or has unexpected fields, the error surfaces far from the parse site
+- Configuration from `~/.mia-code.json` is loaded with no validation — missing fields cause undefined access errors deep in business logic
+- Agent CLI output is parsed with ad-hoc string matching — there is no schema for what a valid agent event looks like
+- API inputs (when RISE-001 adds the HTTP server) have no validation layer — any JSON is accepted and trusted
+
+**Desired State:**
+- Every data structure has a Zod schema that serves as type definition, runtime validator, and documentation source
+- Data is validated at system boundaries: file I/O, user input, API requests, agent output parsing
+- Invalid data is caught early with clear, actionable error messages
+- TypeScript types are derived from schemas — never manually duplicated
+- Schemas compose naturally — a `Session.Info` schema reuses `Config.Engine` schema
+- Adding a field to a schema automatically updates the type, the validator, and the API docs
+
+## Desired Outcome Definition
+
+All data models, configuration structures, API inputs/outputs, event payloads, and tool parameters are defined as Zod schemas. Types are inferred. Validation happens at every boundary.
+
+## Natural Language Functional Description
+
+### Schema Definition Pattern
+
+Every data structure is defined schema-first:
+
+```typescript
+import { z } from "zod";
+
+export const SessionInfo = z.object({
+  id: z.string().uuid(),
+  projectRoot: z.string().min(1),
+  engine: z.enum(["gemini", "claude"]),
+  createdAt: z.number().int().positive(),
+  lastActiveAt: z.number().int().positive(),
+  messageCount: z.number().int().nonneg().default(0),
+});
+
+export type SessionInfo = z.infer<typeof SessionInfo>;
+```
+
+The `z.infer<typeof SessionInfo>` extracts the TypeScript type automatically. The schema and the type share the same name — TypeScript's declaration merging allows a value and a type with the same name to coexist.
+
+### Boundary Validation
+
+Validation occurs at every point where data enters or leaves the system:
+
+**File I/O boundary:**
+```typescript
+async function loadSessions(path: string): Promise<SessionIndex> {
+  const raw = JSON.parse(await readFile(path, "utf-8"));
+  return SessionIndex.parse(raw); // throws ZodError if invalid
+}
+```
+
+**API request boundary:**
+```typescript
+app.post("/sessions", (req, res) => {
+  const input = Session.CreateInput.safeParse(req.body);
+  if (!input.success) {
+    return res.status(400).json({ error: input.error.format() });
+  }
+  // input.data is fully typed and validated
+});
+```
+
+**Configuration boundary:**
+```typescript
+const ConfigSchema = z.object({
+  defaultEngine: z.enum(["gemini", "claude"]).default("gemini"),
+  unifierEnabled: z.boolean().default(true),
+  maxSessionAge: z.number().positive().default(86400),
+  geminiModel: z.string().default("gemini-2.5-pro"),
+  claudeModel: z.string().default("claude-sonnet-4-20250514"),
+});
+
+function loadConfig(path: string): Config {
+  const raw = existsSync(path) ? JSON.parse(readFileSync(path, "utf-8")) : {};
+  return ConfigSchema.parse(raw); // defaults fill in missing fields
+}
+```
+
+**Agent output boundary:**
+```typescript
+const AgentEvent = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("text"), content: z.string() }),
+  z.object({ type: z.literal("tool_use"), name: z.string(), input: z.record(z.unknown()) }),
+  z.object({ type: z.literal("error"), message: z.string() }),
+]);
+```
+
+### Schema Composition
+
+Schemas compose by reference — define `const Engine = z.enum(["gemini", "claude"])` once, reuse in `SessionInfo`, `ConfigSchema`, and anywhere else. Changes propagate automatically.
+
+### Custom Error Messages
+
+User-facing schemas include helpful error messages: `.min(1, "Prompt cannot be empty")`, `.uuid("Invalid session ID format")`. These surface directly in API error responses and CLI output.
+```
+
+### Safe vs. Strict Parsing
+
+- `Schema.parse(data)` — throws `ZodError` on failure. Use at internal boundaries where invalid data is a bug.
+- `Schema.safeParse(data)` — returns `{ success, data, error }`. Use at external boundaries (API, file I/O) where invalid data is expected and must be handled gracefully.
+
+### Schema as Documentation
+
+Schemas generate JSON Schema via `zodToJsonSchema(SessionInfo)` for OpenAPI/Swagger docs. The event bus (RISE-002) uses Zod schemas to validate every event payload at publish time.
+
+## Supporting Structures
+
+- **Event Bus (RISE-002)** validates event payloads using Zod schemas
+- **Namespace Module Pattern (RISE-004)** co-locates schemas inside domain namespaces
+- **Named Error System (RISE-006)** wraps ZodErrors into NamedErrors for consistent error handling
+- **Client-Server Architecture (RISE-001)** uses schemas for API request/response validation
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Corrupted Session File:**
+A user manually edits `~/.mia-code-sessions.json` and introduces a typo in a session ID field. On next load, `SessionIndex.parse()` throws a clear error: `"sessions.0.id: Expected string matching UUID format, received '123'"`. The user knows exactly what to fix.
+
+**Scenario 2 — Config Migration:**
+A new version of mia-code adds a `maxSessionAge` config field with a default. Existing users' config files lack this field. `ConfigSchema.parse()` fills in the default automatically — no migration script needed.
+
+**Scenario 3 — API Input Validation:**
+A client sends `POST /sessions` with `{ "engine": "gpt4" }`. The schema rejects it: `"engine: Expected 'gemini' | 'claude', received 'gpt4'"`. The API returns a 400 with a structured error. No unvalidated data reaches business logic.
+
+**Scenario 4 — Agent Output Parsing:**
+The Gemini CLI emits a JSON event with an unexpected structure. The `AgentEvent` discriminated union rejects it cleanly. The agent module logs the raw event for debugging and skips it, rather than crashing on an undefined property access.