@arach/lattices 0.2.0 → 0.6.1

package/docs/tiling-reference.md

@@ -0,0 +1,224 @@
+# Tiling Reference
+
+Complete reference for Lattices window tiling — positions, grids, execution paths, and voice interpretation.
+
+## Position System
+
+Every tile position is a cell in a **cols × rows** grid, expressed as fractional `(x, y, w, h)` of the screen's visible area (excluding menu bar and dock).
+
+### Named Positions
+
+All valid position strings that `TilePosition` accepts:
+
+| Position string | Grid | Cell (col, row) | Description |
+|---|---|---|---|
+| `maximize` | 1×1 | full | Full screen (100% × 100%) |
+| `center` | — | — | Centered floating (70% × 80%, offset 15%/10%) |
+| **Halves (2×1, full height)** | | | |
+| `left` | 2×1 | 0,0 | Left 50% |
+| `right` | 2×1 | 1,0 | Right 50% |
+| **Halves (1×2, full width)** | | | |
+| `top` | 1×2 | 0,0 | Top 50% |
+| `bottom` | 1×2 | 0,1 | Bottom 50% |
+| **Quarters (2×2)** | | | |
+| `top-left` | 2×2 | 0,0 | Top-left 25% |
+| `top-right` | 2×2 | 1,0 | Top-right 25% |
+| `bottom-left` | 2×2 | 0,1 | Bottom-left 25% |
+| `bottom-right` | 2×2 | 1,1 | Bottom-right 25% |
+| **Thirds (3×1, full height)** | | | |
+| `left-third` | 3×1 | 0,0 | Left 33% column |
+| `center-third` | 3×1 | 1,0 | Center 33% column |
+| `right-third` | 3×1 | 2,0 | Right 33% column |
+| **Sixths (3×2)** | | | |
+| `top-left-third` | 3×2 | 0,0 | Top-left sixth |
+| `top-center-third` | 3×2 | 1,0 | Top-center sixth |
+| `top-right-third` | 3×2 | 2,0 | Top-right sixth |
+| `bottom-left-third` | 3×2 | 0,1 | Bottom-left sixth |
+| `bottom-center-third` | 3×2 | 1,1 | Bottom-center sixth |
+| `bottom-right-third` | 3×2 | 2,1 | Bottom-right sixth |
+| **Fourths (4×1, full height)** | | | |
+| `first-fourth` | 4×1 | 0,0 | Leftmost 25% column |
+| `second-fourth` | 4×1 | 1,0 | Second 25% column |
+| `third-fourth` | 4×1 | 2,0 | Third 25% column |
+| `last-fourth` | 4×1 | 3,0 | Rightmost 25% column |
+| **Eighths (4×2)** | | | |
+| `top-first-fourth` | 4×2 | 0,0 | Top row, 1st column |
+| `top-second-fourth` | 4×2 | 1,0 | Top row, 2nd column |
+| `top-third-fourth` | 4×2 | 2,0 | Top row, 3rd column |
+| `top-last-fourth` | 4×2 | 3,0 | Top row, 4th column |
+| `bottom-first-fourth` | 4×2 | 0,1 | Bottom row, 1st column |
+| `bottom-second-fourth` | 4×2 | 1,1 | Bottom row, 2nd column |
+| `bottom-third-fourth` | 4×2 | 2,1 | Bottom row, 3rd column |
+| `bottom-last-fourth` | 4×2 | 3,1 | Bottom row, 4th column |
+| **Horizontal thirds (1×3)** | | | |
+| `top-third` | 1×3 | 0,0 | Top 33% row |
+| `middle-third` | 1×3 | 0,1 | Middle 33% row |
+| `bottom-third` | 1×3 | 0,2 | Bottom 33% row |
+| **Edge quarters** | | | |
+| `left-quarter` | 4×1 | 0,0 | Leftmost 25% column |
+| `right-quarter` | 4×1 | 3,0 | Rightmost 25% column |
+| `top-quarter` | 1×4 | 0,0 | Top 25% row |
+| `bottom-quarter` | 1×4 | 0,3 | Bottom 25% row |
+
+### Custom Grid Syntax
+
+For arbitrary grids: compact `CxR:C,R` or canonical `grid:CxR:C,R`
+
+- `C` = total columns, `R` = total rows
+- Compact `CxR:C,R` starts at 1 from the top-left
+- Canonical `grid:CxR:C,R` starts at 0 for API/wire compatibility
+- Example: `5x3:3,2` or `grid:5x3:2,1` = center cell of a 5×3 grid
+- Spans can use two inclusive corners, such as `4x4:1,1-2,2`
+
+Parsed by `PlacementSpec` / `parseGridString()` into fractional `(x, y, w, h)`.
+
+### Placement Contract
+
+Placement strings are convenient at the boundary, but the daemon uses a
+typed placement model internally:
+
+- named tile positions
+- arbitrary grid cells
+- raw fractional rectangles
+
+That is what keeps CLI, daemon, voice, and hands-off execution aligned.
+
+## Drag Snap Zones
+
+The menu bar app can also use placement specs as drag-to-snap targets.
+When you drag a window, Lattices shows faint landing zones plus a live
+preview of the resulting frame. Releasing over a zone tiles the dragged
+window to that placement. Hold `Command` while dragging to reveal snap
+mode, and release `Command` to drop back to a normal free drag without
+ending the gesture.
+
+The recommended agent-owned config lives in `~/.lattices/snap-zones.json`:
+
+```json
+{
+  "enabled": true,
+  "modifier": "command",
+  "zoneOpacity": 0.08,
+  "highlightOpacity": 0.18,
+  "previewOpacity": 0.14,
+  "rules": [
+    {
+      "id": "left-edge",
+      "label": "Left",
+      "placement": "left",
+      "trigger": { "x": 0.0, "y": 0.18, "w": 0.12, "h": 0.64 },
+      "priority": 10
+    },
+    {
+      "id": "notes-rail",
+      "label": "Notes",
+      "placement": { "x": 0.68, "y": 0.0, "w": 0.32, "h": 1.0 },
+      "trigger": { "x": 0.88, "y": 0.18, "w": 0.12, "h": 0.64 },
+      "priority": 30
+    }
+  ]
+}
+```
+
+Notes:
+
+- `rules` is the preferred list key. `zones` is still accepted for backward compatibility.
+- `modifier` accepts `command`, `option`, `control`, or `shift`.
+- `placement` can be a named placement/preset string or raw fractions.
+- `trigger` uses normalized `(x, y, w, h)` fractions of the screen's
+  visible area, with `y = 0` at the top.
+- `priority` breaks ties when trigger regions overlap.
+- `trigger` can also be a named placement or preset string if you want
+  the trigger region itself to reuse an existing tile definition.
+- The older `~/.lattices/grid.json` `snapZones` section still works, but
+  `~/.lattices/snap-zones.json` is the cleaner file for agents to edit.
+
+## Execution Paths
+
+The old split-brain tiling logic has been collapsed toward a shared path.
+The canonical mutation is now:
+
+```json
+{ "method": "window.place", "params": { "placement": "left" } }
+```
+
+All higher-level surfaces should compile into the same placement model:
+
+- **Daemon / CLI**: `window.place` is the canonical mutation
+- **Compatibility**: `window.tile` maps to `window.place`
+- **Voice / hands-off**: parse natural language, then emit a placement spec
+- **HUD**: still exposes a smaller shortcut set, but should target the same placement executor
+
+The important change is that placement resolution now happens through
+`PlacementSpec`, not through separate ad hoc parsers per surface.
+
+## Frame Calculation
+
+All paths eventually call one of:
+
+1. **`WindowTiler.tileFrame(for:on:)`** — takes a `TilePosition` + `NSScreen`, returns a `CGRect` in AX coordinates (origin = top-left of primary display)
+2. **`WindowTiler.tileFrame(fractions:inDisplay:)`** — takes raw `(x, y, w, h)` fractions + display rect
+
+The math:
+```
+visible = screen.visibleFrame  (excludes menu bar + dock)
+primaryH = primary screen height
+axTop = primaryH - visible.maxY  (flip from AppKit bottom-left to AX top-left)
+
+frame.x = visible.x + visible.width × fx
+frame.y = axTop + visible.height × fy
+frame.w = visible.width × fw
+frame.h = visible.height × fh
+```
+
+## Window Targeting
+
+The `tile_window` intent resolves the target window in this priority:
+
+1. **`session`** slot → `LatticesApi.window.place` / `window.tile` compatibility wrapper
+2. **`wid`** slot → `DesktopModel.shared.windows[wid]` (direct window ID lookup)
+3. **`app`** slot → first matching window by `localizedCaseInsensitiveContains`, excluding recently-tiled windows (prevents double-matching in batch commands like "Chrome left, Chrome right")
+4. **No target** → tiles the frontmost window
+
+### HandsOff-specific targeting
+
+The system prompt instructs the LLM to always use `wid` from the desktop snapshot, never `app`. This avoids ambiguity when multiple windows of the same app exist. In speech, the LLM says the app name; in the JSON action, it uses the wid.
+
+## Common Layouts (multi-action)
+
+These are composed from multiple `tile_window` actions:
+
+| Layout | Actions |
+|---|---|
+| Split screen | left + right |
+| Stack | top + bottom |
+| Thirds | left-third + center-third + right-third |
+| Quadrants | top-left + top-right + bottom-left + bottom-right |
+| Six-up (3×2) | All six `*-*-third` positions |
+| Eight-up (4×2) | All eight `*-*-fourth` positions |
+| Distribute | Single `distribute` intent (auto-grid) |
+
+CLI shortcuts compile into the same distributor:
+
+- `lattices tile family` → smart-grid the frontmost app's visible windows
+- `lattices distribute iTerm2 right` → smart-grid visible iTerm windows inside the right half
+
+## HandsOff Smart Distribution
+
+When the LLM sends multiple `tile_window` actions targeting the **same position**, `HandsOffSession.distributeTileActions()` subdivides:
+
+- 2+ windows → "left" becomes top-left, left, bottom-left
+- 2+ windows → "right" becomes top-right, right, bottom-right
+- 2+ windows → "maximize" fans out to quadrants then halves
+
+## Guardrails
+
+- **Typed placement validation**: invalid placement strings or objects are rejected at the daemon boundary.
+- **Recently-tiled dedup**: `IntentEngine.recentlyTiledWids` prevents the same window from being matched twice within 2 seconds during batch operations.
+- **Compatibility wrappers**: `window.tile` still works, but routes through the same placement machinery.
+
+## Current Gaps
+
+1. **Voice extraction still needs to catch up**: the canonical executor understands horizontal thirds and edge quarters, but the local voice resolver still needs broader phrase coverage.
+2. **HUD coverage is narrower than the executor**: keyboard tiling exposes a small subset of the full placement vocabulary.
+3. **Optimization and layer actions are still wrapper-level**: `space.optimize` and `layer.activate` are now stable action IDs, but they currently wrap existing distributor and layer-switching behavior rather than a full planner.

package/docs/twins.md

@@ -0,0 +1,138 @@
+---
+title: Project Twins
+description: Pi-backed project twins for mediated, persistent agent execution
+order: 3
+---
+
+A project twin is a persistent software counterpart to a codebase.
+
+It is not the primary agent. It is the project-native runtime that sits
+between a general-purpose caller and the project's execution protocol.
+
+## Why a twin exists
+
+General-purpose agents are interchangeable. Project protocols are not.
+
+If every primary agent has to learn the project's tool surface, memory
+policy, protocol semantics, and context conventions from scratch, the
+integration becomes brittle. A twin fixes that by becoming the stable
+project-facing runtime:
+
+- The **primary agent** asks for work
+- The **twin** resumes with the right context and memory
+- The **protocol** stays behind the twin boundary
+
+```text
+primary agent -> project twin -> project protocol / harness
+```
+
+The twin is the client of record for the project.
+
+## Responsibilities
+
+A project twin owns:
+
+- Project-scoped identity
+- Persistent session continuity
+- Memory compaction and continuation
+- Tool policy and allowed capabilities
+- Protocol knowledge
+- Project context assembly
+- Caller-facing summaries and handoffs
+
+A primary agent should not speak the project protocol directly. It should
+invoke the twin.
+
+## Pi-backed runtime
+
+Pi is a good fit for the twin runtime because it already provides:
+
+- Persistent sessions
+- RPC mode for long-running subprocess integration
+- Tool calling with an explicit harness
+- Compaction and summarization hooks
+- Context files, prompt templates, and extension loading
+
+That makes the split:
+
+- **Twin**: product concept and policy boundary
+- **Pi**: reasoning and session runtime
+- **Host system**: orchestration, durable memory, and protocol adapters
+
+Pi powers the twin. It does not define the twin.
+
+## Invocation model
+
+The primary agent makes a single mediated call into the twin:
+
+1. Resume the twin session
+2. Inject caller context, project memory, and protocol state
+3. Let the twin do project-local work inside the harness
+4. Return a concise result to the caller
+
+The caller should see a stable capability surface such as:
+
+- `status`
+- `inspect`
+- `plan`
+- `execute`
+- `summarize`
+- `handoff`
+
+It should not see raw protocol-shaped operations unless that protocol is
+itself the public product surface.
+
+## Implementation in this repo
+
+This repo now includes a Pi-backed runtime in
+[`bin/project-twin.ts`](/Users/arach/dev/lattices/bin/project-twin.ts).
+
+The runtime:
+
+- Spawns `pi --mode rpc` as a persistent subprocess
+- Stores project-local session state under `.openscout/twins/<name>/sessions`
+- Exposes a stable `invoke()` API for callers
+- Optionally injects OpenScout relay context if `.openscout/relay*` exists
+
+The default harness is intentionally narrow:
+
+- Built-in Pi tools are explicitly pinned to `read,bash,edit,write`
+- Extension, skill, and prompt-template discovery are disabled by default
+- Project instructions still come from `AGENTS.md` and related context files
+
+This keeps the twin deterministic unless the host explicitly widens the
+surface.
+
+## Example
+
+```ts
+import { ProjectTwin } from "@lattices/cli"
+
+const twin = new ProjectTwin({
+  cwd: "/Users/you/dev/my-project",
+  name: "my-project",
+  model: "anthropic/claude-sonnet-4-5",
+})
+
+await twin.start()
+
+const result = await twin.invoke({
+  caller: "primary-agent",
+  protocol: "openscout-relay",
+  memory: "The caller is debugging relay enrollment and wants the next safe action.",
+  task: "Inspect the available project context and summarize what the caller should do next.",
+})
+
+console.log(result.text)
+
+await twin.stop()
+```
+
+## Design rule
+
+All project-specific protocol semantics should live behind the twin
+boundary.
+
+The primary agent should invoke the twin as a skill-like capability.
+The twin should own context assembly, protocol interaction, and the final
+handoff back to the caller.

package/docs/voice-command-protocol.md

@@ -0,0 +1,278 @@
+# Voice Command Protocol — Lattices ↔ Vox
+
+## Overview
+
+Lattices delegates all audio capture and transcription to Vox via WebSocket JSON-RPC. Lattices never accesses the microphone directly — it borrows Vox's mic and transcription pipeline, receives English text back, and routes it through its own intent engine.
+
+These dictations are **ephemeral** — Vox does not persist them as memos, sync them, or add them to Vox's history. Lattices is just using Vox as a transcription pipe.
+
+## Vox Process Model
+
+Vox consists of three independent processes:
+
+| Process | Role | Relevance to Lattices |
+|---|---|---|
+| **Vox.app** | Main UI — menu bar, notch visualization, memo history | None |
+| **Vox** | Background service — mic access, recording, hotkeys, orchestrates transcription, state notifications | **This is what Lattices connects to** |
+| **VoxEngine** | Transcription engine — runs Whisper models, called by Vox internally | Indirect — Vox delegates to it |
+
+Vox is the right target because:
+- It owns the mic and recording lifecycle
+- It's the long-running background process (always up when Vox is installed)
+- It already orchestrates the record → transcribe → result pipeline
+- It's easy to discover via its existing DistributedNotification
+
+## Service Discovery
+
+Lattices never hardcodes ports. Discovery uses two mechanisms:
+
+### 1. Well-known file (at rest)
+
+Vox writes its service configuration on startup:
+
+```
+~/.vox/services.json
+```
+
+```json
+{
+  "agent": {"port": 19823, "pid": 48209},
+  "engine": {"port": 19821, "pid": 48210},
+  "sync": {"port": 19820, "pid": 48208},
+  "inference": {"port": 19822, "pid": 48212}
+}
+```
+
+Lattices reads `agent.port` from this file. If the file doesn't exist, Vox isn't installed.
+
+### 2. DistributedNotification (live discovery)
+
+Vox posts when it comes online:
+
+```
+Notification: com.jdi.vox.agent.live.ready
+UserInfo:     {"agentPort": 19823, "pid": 48209}
+```
+
+Lattices subscribes to this on startup. Handles:
+- **Vox launches after Lattices** — Lattices picks up the port dynamically
+- **Vox restarts** — Lattices reconnects with the new port
+- **Port changes** — no stale config
+
+### 3. Health check
+
+After discovering a port, Lattices confirms Vox is alive:
+
+```json
+→ {"id": "hc", "method": "ping"}
+← {"id": "hc", "result": {"pong": true}}
+```
+
+If ping fails, Lattices marks voice as unavailable and retries on the next `live.ready` or after ~30 seconds.
+
+### When Vox is not running
+
+Three possible states:
+
+| State | How detected | Lattices behavior |
+|---|---|---|
+| **Not installed** | `/Applications/Vox.app` doesn't exist and no `~/.vox/` dir | Footer: `[Space] Voice (unavailable)` — no recovery action |
+| **Installed but not running** | App bundle exists, but `services.json` missing/stale or ping fails | Footer: `[Space] Voice (start Vox)` — pressing Space runs `open /Applications/Vox.app`, which brings up Vox as a side effect |
+| **Running** | Ping succeeds | Normal operation |
+
+Launch-on-demand flow:
+1. User presses Space while Vox is down but Vox is installed
+2. Lattices runs `NSWorkspace.shared.open(URL(fileURLWithPath: "/Applications/Vox.app"))`
+3. Feedback strip shows "Starting Vox..."
+4. Lattices waits for `live.ready` notification (timeout: 10s)
+5. On `live.ready`, connects and proceeds with `startDictation`
+6. On timeout, shows "Couldn't reach Vox — try opening it manually"
+
+Passive behavior (no user action):
+- No log spam — just a quiet unavailable state
+- Lattices keeps listening for `live.ready` and re-checks `services.json` periodically (~30s)
+- The moment Vox comes online, voice becomes available — no restart needed
+
+## Protocol
+
+### Wire Format
+
+Uses Vox's JSON-RPC format over WebSocket:
+
+```
+Request:  {"id": "...", "method": "...", "params": {...}}
+Response: {"id": "...", "result": {...}}  or  {"id": "...", "error": "..."}
+Event:    {"event": "...", "data": {...}}   (server push, no id)
+```
+
+### Methods (Lattices → Vox)
+
+**`startDictation`** — Start recording from the mic.
+
+```json
+{"id": "1", "method": "startDictation", "params": {
+  "source": "lattices",
+  "persist": false
+}}
+```
+
+- `source` — identifies the caller (for Vox's logging/UI)
+- `persist: false` — do not save as a memo, do not sync, do not show in Vox history
+
+Response (immediate ack):
+```json
+{"id": "1", "result": {"ok": true}}
+```
+
+Error responses:
+```json
+{"id": "1", "error": "Microphone access denied"}
+{"id": "1", "error": "No model loaded"}
+{"id": "1", "error": "mic_busy", "owner": "vox"}
+```
+
+The `mic_busy` error means another consumer (Vox's own memo recording, or another client) already has an active dictation. The `owner` field identifies who holds the mic. Lattices shows: "Mic in use by Vox — finish your memo first".
+
+The reverse case (user hits Vox hotkey while Lattices has the mic) is handled on Vox's side — it should reject its own recording with an equivalent busy state. Vox is the single owner of mic arbitration.
+
+**`stopDictation`** — Stop recording and return the transcript.
+
+```json
+{"id": "2", "method": "stopDictation"}
+```
+
+Response (after transcription completes):
+```json
+{"id": "2", "result": {
+  "transcript": "tile this left",
+  "confidence": 0.94,
+  "durationMs": 1820
+}}
+```
+
+**`cancelDictation`** — Abort without transcribing.
+
+```json
+{"id": "3", "method": "cancelDictation"}
+```
+
+```json
+{"id": "3", "result": {"ok": true}}
+```
+
+### Events (Vox → Lattices)
+
+Pushed over the WebSocket connection during an active dictation.
+
+| Event | When | Data |
+|---|---|---|
+| `dictation.started` | Mic is hot, recording has begun | `{"source": "lattices"}` |
+| `dictation.transcribing` | Recording stopped, model is running | `{}` |
+| `dictation.result` | Transcription complete | `{"transcript": "...", "confidence": 0.94, "durationMs": 1820}` |
+| `dictation.error` | Something failed during recording or transcription | `{"message": "..."}` |
+
+## Disconnect Contract
+
+If the WebSocket connection drops mid-dictation (Lattices crashes, user quits, network hiccup), Vox **must** auto-cancel the in-flight dictation:
+
+1. Stop recording immediately
+2. Discard any captured audio — do not transcribe
+3. Release the mic so Vox's own UI or a reconnecting client can use it
+4. Log the orphaned dictation for diagnostics: `[dictation] orphaned session from lattices — connection dropped, auto-cancelled`
+
+Vox treats a closed WebSocket as an implicit `cancelDictation`. No grace period, no buffering — if the consumer is gone, the recording is worthless.
+
+On the Lattices side, if the connection drops while in `listening` or `transcribing` state:
+- Feedback strip: "Connection lost" (red)
+- Attempt reconnect via normal discovery (ping → `services.json` → wait for `live.ready`)
+- Do not auto-retry the dictation — the user needs to press Space again
+
+## End-to-End Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant L as Lattices UI
+    participant TA as Vox
+    participant IE as Intent Engine
+
+    U->>L: Press Space (in cheat sheet)
+    L->>TA: startDictation (persist: false)
+
+    alt Error
+        TA-->>L: error (mic denied / no model)
+        L->>U: Red text in feedback strip
+    else OK
+        TA-->>L: {ok: true}
+        TA-->>L: dictation.started
+        L->>U: Green dot (pulsing) + "Listening..."
+
+        Note over U,TA: User speaks...
+
+        U->>L: Press Space again
+        L->>TA: stopDictation
+        TA-->>L: dictation.transcribing
+        L->>U: "Transcribing..."
+
+        TA-->>L: {transcript: "tile this left", confidence: 0.94}
+        L->>U: Show transcript
+    end
+
+    L->>IE: Classify via NLEmbedding
+    IE-->>L: intent: tile_window, slots: {position: left}, confidence: 0.95
+    L->>U: Show intent + slots
+
+    L->>IE: Execute
+    IE-->>L: result
+    L->>U: "Done" or error
+
+    Note over L: Log entry written
+```
+
+## UI States
+
+| State | Feedback strip | Footer |
+|---|---|---|
+| **Idle** | Hidden | `[Space] Voice  [ESC] Dismiss` |
+| **Not installed** | Hidden | `[Space] Voice (unavailable)  [ESC] Dismiss` |
+| **Installed, not running** | Hidden | `[Space] Voice (start Vox)  [ESC] Dismiss` |
+| **Starting** | "Starting Vox..." | `[ESC] Cancel` |
+| **Error** | Red: "Mic access denied" or "Mic in use by Vox" | `[ESC] Dismiss` |
+| **Disconnected** | Red: "Connection lost" | `[ESC] Dismiss` |
+| **Listening** | Green dot + "Listening..." | `[Space] Stop  [ESC] Cancel` |
+| **Transcribing** | "Transcribing..." | `[ESC] Cancel` |
+| **Result** | `"tile this left"` → `tile window · position: left` → `Done` | `[Space] New  [ESC] Dismiss` |
+
+## Logging
+
+Every voice command produces a diagnostic log entry:
+
+```
+[voice] "tile this left" → tile_window(position: left) → ok (conf=0.95, 1820ms)
+[voice] "organize my stuff" → distribute() → ok (conf=0.79, 2100ms)
+[voice] "do something weird" → (no match, conf=0.41, 900ms)
+[voice] error: Vox not running
+[voice] error: mic_busy (owner: vox)
+[voice] error: connection dropped mid-dictation
+[voice] launched Vox, connected in 2.1s
+```
+
+## Implementation Scope
+
+### Lattices side
+- Use `@vox/client` SDK (`VoxClient` with `service: "agent"`, `clientId: "lattices"`, `capabilities: ["dictation"]`) — see `vox/sdk/SDK.md` for full reference
+- Replace `AVAudioRecorder` in `VoxAudioProvider` with `createDictationSession().start({ persist: false })`
+- Remove mic entitlement and `NSMicrophoneUsageDescription` (Lattices never touches the mic)
+- Service discovery, auto-reconnect, and auth are handled by the SDK
+- Map `DictationSession` events (`stateChange`, `partialTranscript`, `finalTranscript`, `error`) to cheat sheet UI states
+- Handle `MicBusyError` — show `"Mic in use by ${error.owner}"`
+
+### Vox side (separate repo)
+- Expose a WebSocket bridge (or add methods to existing bridge)
+- Add `startDictation`, `stopDictation`, `cancelDictation` handlers
+- Emit `dictation.started`, `dictation.transcribing`, `dictation.result`, `dictation.error` events
+- Honor `persist: false` — skip memo creation and sync
+- Write `~/.vox/services.json` on startup (all service ports)
+- Include `agentPort` in `live.ready` notification userInfo
+- Return `mic_busy` error with `owner` field when another consumer holds the mic
+- Auto-cancel dictation on WebSocket disconnect (closed socket = implicit cancel)