# Architecture

## Recommended shape

Lumbridge should be two cooperating Rust processes:

```text
native desktop UI
      | local authenticated IPC
Lumbridge session runtime
      |-- PTYs and process trees
      |-- ACP clients and adapters
      |-- repositories and worktrees
      |-- usage/event ledger
      `-- secret-store handles
```

Separating the UI from the session runtime lets terminals survive renderer
restarts, permits a future headless/SSH mode, and gives persistence one owner.
The first development build may run both in one process, but boundaries and IPC
messages should be real from the beginning.

## Planned crates

- `lumbridge-core`: IDs, commands, events, errors, capability and usage types.
- `lumbridge-runtime`: session ownership, supervision, recovery, IPC server.
- `lumbridge-pty`: portable PTY and process-tree adapters.
- `lumbridge-terminal`: VT parsing, scrollback, selection, search, render model.
- `lumbridge-acp`: ACP client, capability negotiation, transcript normalization.
- `lumbridge-harness`: manifests, launch profiles, hooks, PTY fallback adapters.
- `lumbridge-provider`: BYOK providers and provider-neutral usage records.
- `lumbridge-storage`: SQLite migrations, event log, snapshots, retention.
- `lumbridge-secrets`: Keychain/libsecret adapters and redaction.
- `lumbridge-git`: repositories, worktrees, diffs, status, conflict state.
- `lumbridge-ui`: native desktop state and rendering.
- `lumbridge`: installable application entry point.

Only `lumbridge-core` and the entry point exist in the scaffold. New crates are
added after their architecture spike passes.

## Terminal path

The runtime owns PTYs, child process groups, resize signals, input ordering, and
raw output. The terminal engine turns output into immutable render snapshots and
bounded deltas for the UI. Scrollback is chunked and persisted separately from
the live screen to prevent large agent transcripts from blocking input.

We should evaluate, not blindly copy, WezTerm, Zellij, RMUX, tmux, and cmux. The
first spike must compare a reusable terminal crate with a small first-party layer.
Correctness cases include alternate screen, bracketed paste, OSC 8 links, Kitty
keyboard/graphics negotiation, Unicode width, IME, mouse modes, shell integration,
and simultaneous automation plus human input.

## UI decision gate

Do not lock the project to a webview or to Zed's private implementation details
before a measured spike. Compare:

1. GPUI for a Zed-like native model and excellent text-heavy interaction.
2. Iced/wgpu plus a dedicated terminal renderer for stable Rust portability.
3. Tauri only as a delivery-speed baseline, not the assumed winner.

The winner must render six busy panes smoothly, keep input latency low, support
IME/accessibility, package on macOS and both Linux targets, and avoid a license
or upstream-stability trap.

## Harness integration

Each harness is described by a versioned manifest: executable discovery, launch
arguments, environment allowlist, resume semantics, status/usage probes, ACP
command when available, and hook installation rules.

ACP is preferred because it provides structured prompts, plans, tool calls,
permissions, content blocks, and session lifecycle. A supervised PTY is always
available because terminal fidelity and arbitrary CLI compatibility are product
requirements. Harness-specific adapters translate both paths into the same event
model without pretending a PTY has capabilities it cannot prove.

## Usage model

Usage is an append-only observation stream, not a mutable percentage field.
Observations include account profile, provider, harness, model, units, time
window, reset time, provenance, confidence, and source timestamp. Projections are
derived views that can be recomputed as forecasting improves.

Subscription balance is provider-specific and sometimes unavailable. BYOK calls
usually expose token counts but cost still depends on cached tokens, reasoning,
tool calls, and current pricing. Adapters normalize facts without erasing their
source or uncertainty.

## Persistence

SQLite in WAL mode stores metadata, commands/events, normalized usage, and small
snapshots. Large scrollback chunks and binary attachments use content-addressed
files. A write-ahead event is committed before an external mutation is reported
as accepted. Startup replays incomplete operations and reconciles live children.

## Security

- macOS secrets: Keychain; Linux secrets: Secret Service/libsecret, with an
  explicit encrypted-file fallback only if the user enables it.
- Never pass keys in process arguments. Prefer inherited file descriptors or a
  minimal child environment when a harness requires environment variables.
- IPC is local, authenticated, permission-restricted, and version-negotiated.
- Transcript and crash-report redaction happens before persistence or export.
- Repository trust, harness approval mode, and sandbox mode are visible per pane.
- Remote control and plugins are out of scope until a capability/permission model
  exists.

## Platform adapters

Shared contracts cover PTY, process tree, notifications, secret store, paths,
autostart, updater, and packaging. macOS uses `forkpty`/process groups and native
Keychain. Ubuntu and Omarchy use Unix PTYs, cgroups/systemd scopes when available,
and Secret Service. Omarchy is treated as Arch Linux, not as a separate kernel.