Scaffold Lumbridge architecture and research plan

docs/ARCHITECTURE.md

@@ -0,0 +1,116 @@
+# 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.
+

docs/DISTRIBUTION.md

@@ -0,0 +1,20 @@
+# Distribution plan
+
+Lumbridge source and release metadata live in the public Gitea repository. Users
+should not need a Rust toolchain.
+
+Initial release artifacts:
+
+- macOS arm64: signed and notarized `.dmg` plus a tar archive.
+- macOS x86_64: added when a maintained Intel runner is available.
+- Ubuntu x86_64: `.deb` and AppImage.
+- Omarchy/Arch x86_64: signed package archive and an AUR recipe that downloads
+  the matching release artifact.
+
+Each release includes SHA-256 checksums, a signed update manifest, SBOM, license
+notices, and the exact source commit. Reproducibility is a goal, but a release is
+not called reproducible until two clean builders produce matching artifacts.
+
+The updater must verify signatures before replacing binaries, retain the prior
+version for rollback, and never update a running session runtime in place.
+

docs/PRODUCT_SPEC.md

@@ -0,0 +1,84 @@
+# Product specification
+
+## One sentence
+
+Lumbridge is a high-performance, local-first terminal and workspace multiplexer
+that lets engineers run, steer, compare, and understand many coding agents
+without surrendering control of their accounts, keys, repositories, or shells.
+
+## Primary user
+
+An engineer who works across several repositories and routinely keeps multiple
+coding agents, shells, test watchers, servers, and review surfaces alive at once.
+The product should feel faster and calmer as concurrency rises.
+
+## Core jobs
+
+1. Open a repository and create a durable workspace with terminals and panes.
+2. Launch a supported harness through its subscription login or a BYOK profile.
+3. See whether each agent is working, waiting, blocked, complete, or disconnected.
+4. Steer work without losing terminal fidelity or bypassing approval prompts.
+5. Review file and Git changes by workspace or worktree.
+6. Understand usage, rate-limit windows, burn rate, and likely exhaustion time.
+7. Resume the entire workspace after the UI or machine restarts.
+
+## Initial harnesses
+
+- Claude Code
+- OpenAI Codex
+- DeepSeek Harness
+- Pi and compatible Pi distributions
+- Hermes Agent
+- OpenClaw
+- Goose
+- Gemini CLI
+- OpenCode
+
+An arbitrary command remains a supported harness through the generic PTY adapter.
+
+## Provider modes
+
+Subscription mode delegates authentication to the installed upstream harness.
+Lumbridge observes only documented status, usage, and protocol surfaces.
+
+BYOK mode supports OpenAI, Anthropic, Google Gemini, Groq, Cerebras, DeepSeek,
+and OpenAI-compatible endpoints. Keys live in the operating-system credential
+store. A provider adapter receives an opaque secret handle, never a value stored
+in project state.
+
+Provider and harness selection are independent. For example, a generic harness
+may use Cerebras by API key while Codex uses a ChatGPT subscription.
+
+## Usage footer
+
+The footer answers five questions in a glance:
+
+- Which harness, provider, model, and account profile is active?
+- How much of the current usage window has been consumed?
+- When does the window reset?
+- What is the recent and projected burn rate?
+- How trustworthy is the number?
+
+Every value is labeled internally and in detail views as provider-reported,
+harness-reported, locally measured, estimated, or unavailable. Lumbridge must
+not scrape browser cookies or reverse-engineer private account APIs to manufacture
+an exact remaining balance. When only local observations exist, the UI says so.
+
+## Non-goals for the first release
+
+- A new foundation-model training or inference service.
+- A hosted account or mandatory Lumbridge cloud.
+- Replacing every coding harness with one Lumbridge-owned agent loop.
+- Windows support.
+- Mobile control, collaborative cloud sessions, or remote execution.
+- Bundling third-party subscriptions or reselling model tokens.
+
+## Experience principles
+
+- Terminal truth first: no hidden process state and no fake terminal emulation.
+- Keyboard fast, mouse understandable.
+- Dense information with a quiet default presentation.
+- Approval and security boundaries stay visible.
+- Local and offline workflows remain useful.
+- Estimates are useful only when their uncertainty is honest.
+

docs/RESEARCH.md

@@ -0,0 +1,63 @@
+# Research map
+
+The working checkouts live outside this repository at:
+
+```text
+Desktop/Lumbridge Code/Research/
+```
+
+They are shallow snapshots for study, not dependencies or vendored source.
+
+## Multiplexers and terminal engines
+
+- `manaflow-ai/cmux`: the current cmux product; native workspace/pane model,
+  automation socket, embedded browser, agent hooks, and terminal UX.
+- `Helvesec/rmux`: Rust multiplexer engine, daemon, typed SDKs, tmux surface.
+- `tmux/tmux`: the durable client/server and command model to remain compatible
+  with where useful.
+- `zellij-org/zellij`: Rust workspace, layouts, plugins, collaboration, web client.
+- `wez/wezterm`: mature Rust terminal emulator, multiplexer, rendering, and PTY
+  portability reference.
+
+## Agent IDEs and orchestration products
+
+- `stablyai/orca`: parallel worktrees, many harnesses, terminals, usage tracking,
+  remote execution, and review surfaces.
+- `get-bb/bb`: self-drivable agent IDE with desktop, web, CLI, and API surfaces.
+- `coder/xum`: isolated parallel agent workspaces, remote execution, review, and
+  cost/context UX; AGPL, so treat implementation as study-only.
+- `zed-industries/zed`: high-performance Rust editor, GPUI, terminal, and ACP
+  client. Review the dual-license boundary file by file.
+- `aaif-goose/goose`: Rust desktop/CLI/API agent, many providers, MCP, and ACP.
+- `block/buzz`: Rust human/agent collaboration plus production ACP harness design.
+- `bbarit/terminal`: Rust agent terminal/IDE ideas. No top-level license file was
+  present in the captured snapshot, so do not reuse implementation code.
+
+## Protocols
+
+- `agentclientprotocol/agent-client-protocol`: canonical ACP schema and spec.
+- `agentclientprotocol/rust-sdk`: official high-level Rust client/agent runtime.
+
+## Harnesses
+
+- `openai/codex`
+- `deepseek-ai/deepseek-harness`
+- `google-gemini/gemini-cli`
+- `badlogic/pi-mono`
+- `NousResearch/hermes-agent`
+- `openclaw/openclaw`
+- `anomalyco/opencode`
+
+## Research questions
+
+1. Which terminal core gives us correctness without inheriting a product-shaped
+   dependency or incompatible license?
+2. Can the runtime maintain smooth human input while agents read/write other
+   panes through automation?
+3. Which UI stack meets latency, IME, accessibility, and packaging requirements?
+4. What is the smallest honest common denominator across ACP harnesses?
+5. Which official provider/harness surfaces expose subscription quota, and what
+   must remain measured or unavailable?
+6. Can one event model cover PTY, ACP, Git, usage, permissions, and recovery
+   without turning into untyped JSON everywhere?
+

docs/ROADMAP.md

@@ -0,0 +1,47 @@
+# Roadmap
+
+## Phase 0 — research and decisions
+
+- Capture upstream snapshots, licenses, relevant modules, and architectural notes.
+- Benchmark UI candidates with six animated terminal panes.
+- Spike PTY correctness and process-tree cleanup on macOS, Ubuntu, and Omarchy.
+- Connect the official ACP Rust SDK to two contrasting harnesses.
+- Audit actual usage/quota surfaces for every launch provider.
+- Decide terminal core, UI stack, IPC transport, and schema evolution policy.
+
+Exit: recorded decisions with working spikes and measured results.
+
+## Phase 1 — terminal workspace alpha
+
+- Durable runtime, local IPC, workspaces, tabs, splits, shells, scrollback.
+- Session restore, crash recovery, command palette, keybindings, notifications.
+- Repository/worktree creation and basic Git status/diff.
+- macOS, Ubuntu, and Omarchy development packages.
+
+Exit: Lumbridge is worth using as a terminal multiplexer without AI features.
+
+## Phase 2 — agent alpha
+
+- Generic harness manifest and PTY adapter.
+- ACP client with capability negotiation and permission rendering.
+- Codex, Claude Code, DeepSeek Harness, Pi, and Hermes adapters.
+- Agent status, unread/needs-input state, resume, and transcript navigation.
+
+Exit: daily multi-agent work is reliable and observable.
+
+## Phase 3 — providers and usage
+
+- Subscription profile discovery without credential extraction.
+- BYOK profiles for OpenAI, Anthropic, Gemini, Groq, Cerebras, and DeepSeek.
+- OS credential storage, redaction, provider/model catalog.
+- Usage ledger, reset windows, burn charts, forecasts, export, and footer.
+
+Exit: usage displays are useful, auditable, and honest about uncertainty.
+
+## Phase 4 — public beta
+
+- Goose, Gemini CLI, OpenClaw, and OpenCode adapters.
+- Signed/notarized macOS releases, `.deb`, AppImage, and Arch package.
+- Delta updater with signed manifests and rollback.
+- Accessibility, performance, soak, migration, and recovery qualification.
+

docs/decisions/0001-product-boundary.md

@@ -0,0 +1,15 @@
+# 0001: Lumbridge is the workspace, not one more mandatory agent
+
+Status: accepted for the architecture phase.
+
+Lumbridge owns terminals, workspaces, session durability, integration, review,
+and usage observability. Existing coding harnesses remain first-class processes.
+ACP provides rich structure and PTYs provide universal compatibility.
+
+This boundary preserves user subscriptions, harness-native capabilities, and
+choice. It also prevents an early attempt to build a terminal, IDE, multiplexer,
+provider SDK, and universal agent loop as one inseparable component.
+
+We may later ship an optional Lumbridge-native harness, but the application must
+remain valuable without it.
+

docs/decisions/0002-usage-provenance.md

@@ -0,0 +1,15 @@
+# 0002: Usage data always carries provenance
+
+Status: accepted for the architecture phase.
+
+Provider quotas and subscription windows do not share a stable universal API.
+Lumbridge therefore stores observations with their source and derives forecasts
+without overwriting the facts.
+
+Allowed provenance values begin as provider-reported, harness-reported, locally
+measured, estimated, and unavailable. The UI may simplify these labels in compact
+views, but the detail view and export retain them.
+
+Lumbridge will not scrape browser cookies, copy upstream OAuth tokens, or label a
+local estimate as an exact remaining subscription balance.
+