feat: add interactive VT and workspace command plane

docs/ARCHITECTURE.md

@@ -41,8 +41,10 @@ messages should be real from the beginning.
 - `lumbridge`: installable application entry point.
 
 The scaffold currently contains `lumbridge-core`, `lumbridge-storage`,
-`lumbridge-buzz`, `lumbridge-pty`, `lumbridge-runtime`, and the entry point.
-Larger runtime crates are added after their architecture spikes pass.
+`lumbridge-buzz`, `lumbridge-pty`, `lumbridge-runtime`, `lumbridge-terminal`, and
+the entry point. `lumbridge-core` also contains the first typed workspace
+command reducer. Larger runtime crates are added after their architecture spikes
+pass.
 
 ## Terminal path
 
@@ -55,19 +57,41 @@ scrollback. 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.
 
+The first `lumbridge-terminal` implementation wraps `alacritty_terminal` behind
+a Lumbridge-owned input and immutable snapshot contract. It parses styled cells,
+cursor state, alternate screen, terminal modes, title events, keyboard input,
+bracketed paste, resize, and terminal-generated protocol replies. OSC 52
+clipboard writes are disabled by default. The renderer never imports the
+upstream terminal type, and protocol replies return through the same actor input
+queue as human input. See decision 0005.
+
 The first `lumbridge-runtime` actor now owns one `PtySession` on a dedicated
 thread. Bounded command and event queues serialize input, resize, close, and
-shutdown against ordered raw-byte output. The GPUI slice consumes one actor
-session while five surfaces retain deterministic comparison output. This actor
-still runs in-process; moving the same framework-neutral contract behind local
-authenticated IPC is the next durability step. See decision 0004.
+shutdown against ordered raw-byte output. The GPUI slice feeds one actor session
+through the terminal engine while five surfaces retain deterministic comparison
+output. Its current text adapter intentionally renders plain rows and does not
+yet paint cell styles, selection, or the cursor; the next rendering slice owns
+that work. This actor still runs in-process; moving the same framework-neutral
+contract behind local authenticated IPC is the next durability step. See
+decisions 0004 and 0005.
 
 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
+Remaining correctness cases include OSC 8 links, Kitty
 keyboard/graphics negotiation, Unicode width, IME, mouse modes, shell integration,
 and simultaneous automation plus human input.
 
+## Workspace command plane
+
+Human UI, local automation, remote clients, and agents reduce the same typed
+workspace commands. Stable request IDs make retries idempotent; validated pane
+IDs, split ratios, launch intents, and close dispositions prevent untyped JSON
+from becoming the product API. A multi-command setup plan is reduced atomically.
+Observe, Configure, and Execute capabilities are checked before mutation, and a
+layout-only agent cannot smuggle an executable or arbitrary arguments into a
+split request. Current code is an in-process reducer; serialization, durable
+events, and authenticated IPC are subsequent layers. See decision 0006.
+
 ## UI decision gate
 
 Do not lock the project to a webview or to Zed's application implementation
@@ -129,6 +153,19 @@ 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.
 
+Lumbridge Harness is a separate optional orchestrator, not a UI framework. The
+DeepSeek Harness snapshot is a useful MIT-licensed reference for plugin seams,
+durable session events, approvals, ACP, and agent lifecycle, but its developer-
+preview Node/TypeScript/web composition is not embedded into the Rust desktop
+process. If we maintain a fork, it lives in its own repository and communicates
+through a versioned, capability-scoped protocol. A first-party Rust service may
+later replace that implementation without changing the desktop contract.
+
+The Harness can consume redacted workspace projections and emit suggestions or
+typed command plans. Suggestions have no authority. Plan execution is routed
+through the same command plane as human actions, and trace export to a hosted
+model requires explicit scope and destination consent. See decision 0007.
+
 ## Usage model
 
 Usage is an append-only observation stream, not a mutable percentage field.

docs/BRAND.md

@@ -0,0 +1,92 @@
+# Lumbridge brand mark
+
+## Concept
+
+Lumbridge's symbol is an original ember-flame wrapped around a bridge arch. The
+diagonal negative space also reads as a terminal chevron or an open gateway.
+Together, those shapes express a fast native workspace where engineers cross
+between terminals, tools, hosts, and agents.
+
+The mark is symbol-only. Do not ship a Unicode fire emoji as the application
+icon, add pseudo-medieval ornament, or attach generated lettering to the mark.
+
+## Color
+
+| Role | Hex | Intended surface |
+| --- | --- | --- |
+| Ember | `#FF6B35` | Canonical application icon and neutral contexts |
+| Ember, light UI | `#D94824` | Light surfaces around `#F6F3EE` |
+| Ember, dark UI | `#FF8A5B` | Dark surfaces around `#0B0F14` |
+
+All files have transparent backgrounds. The surface colors above are usage
+guidance and are not baked into the assets. Do not add gradients, drop shadows,
+outlines, or extra flame colors.
+
+## Assets
+
+The 1024 px master is
+`assets/brand/master/lumbridge-mark-master-1024.png`. Use it as the source for
+new platform exports.
+
+- `assets/brand/app-icons/lumbridge-app-{size}.png` contains the canonical Ember
+  icon at 16, 32, 48, 64, 128, 256, 512, and 1024 px.
+- `assets/brand/light/lumbridge-mark-light-{size}.png` contains the light-UI
+  colorway at the same sizes.
+- `assets/brand/dark/lumbridge-mark-dark-{size}.png` contains the dark-UI
+  colorway at the same sizes.
+
+The existing PNGs are RGBA and square. Packaging may derive platform-native
+containers such as macOS `.icns` later, but those derived files should preserve
+the supplied canvas and must not stretch or crop the symbol.
+
+## Placement
+
+- Preserve the mark's aspect ratio and transparent canvas.
+- Outside an application-icon tile, keep clear space equal to at least one
+  eighth of the rendered mark height on every side.
+- Prefer the prepared export nearest the requested display size. Do not scale a
+  16 px export upward.
+- At 16–24 px, use the canonical app-icon export without a wordmark, badge, or
+  status dot. The flame and gateway are the intended small-size reading; the
+  terminal chevron becomes secondary.
+- Do not place detailed artwork or low-contrast orange immediately behind the
+  transparent mark.
+
+## Generation and production record
+
+The concept was generated once with the built-in `image_gen` mode using this
+prompt:
+
+> Use case: logo-brand. Asset type: native desktop application icon master for
+> Lumbridge, a very high-performance Rust terminal multiplexer and AI-agent
+> workspace. Create one original symbol-only brand mark that expresses
+> firemaking energy, a bridge or gateway, and a terminal prompt through a single
+> strong silhouette. Use a compact upright ember-flame whose interior negative
+> space forms a clean bridge arch or open gateway; incorporate one extremely
+> subtle angular terminal chevron idea into the geometry without adding a
+> separate floating glyph. Use a vector-friendly, flat, minimal geometric mark
+> with precise edges, centered on a square transparent canvas. Use warm ember
+> orange. Exactly one symbol; no text, letters, wordmark, emoji glyph, gradient,
+> shadow, 3D, mockup, border tile, or watermark. Avoid RuneScape imagery or
+> style, game trademarks, medieval crests, literal campfires, logs, swords,
+> shields, runes, detailed sparks, characters, mascots, and decorative
+> flourishes.
+
+The selected output's geometry was retained. Production exports were then made
+deterministically: low-alpha detached pixels were removed, the mark was inset
+onto a 1024 px transparent canvas, its generated shading was replaced with the
+three exact flat colors above, and Lanczos downscales were produced. No
+third-party artwork, typeface, or game asset is included.
+
+## Originality and release constraints
+
+This identity deliberately uses only generic fire, bridge, gateway, and terminal
+ideas. Do not adapt or add artwork, interfaces, names, symbols, screenshots, or
+other assets from RuneScape or another game.
+
+Generation and internal review are not a trademark search or legal clearance.
+Before a public release, perform a similarity search for the symbol and obtain
+product-name/trademark review; the original mark does not by itself clear the
+name `Lumbridge`. Keep the prompt and this production record with the assets for
+provenance, and review the image-generation provider's then-current output terms
+before redistribution.

docs/DISTRIBUTION.md

@@ -11,10 +11,16 @@ Initial release artifacts:
 - Omarchy/Arch x86_64: signed package archive and an AUR recipe that downloads
   the matching release artifact.
 
+Every package installs the canonical Lumbridge application icon into the native
+platform location: the macOS asset catalog/`.icns`, Linux hicolor PNG sizes and
+`.desktop` entry, and any package-manager metadata. Derived files come from the
+transparent masters in `assets/brand/`; light and dark variants are for product
+surfaces, while launchers use the canonical app icon unless a platform has a
+documented adaptive-icon contract.
+
 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

@@ -25,6 +25,10 @@ The product should feel faster and calmer as concurrency rises.
    user-owned machine reached through SSH or Tailscale.
 9. Follow a project's Buzz channel and intentionally share a redacted pane image
    without leaving the workspace.
+10. Inspect terminal, browser, tools, context, goal, and review views without
+    losing the pane's process identity or execution target.
+11. Ask a local or selected-provider analyst for a small set of next actions,
+    then choose, edit, dismiss, or explicitly authorize one.
 
 ## Local and remote workspaces
 
@@ -54,6 +58,39 @@ devices.
 
 An arbitrary command remains a supported harness through the generic PTY adapter.
 
+## Pane surfaces and decision shelf
+
+A pane is the durable unit of work; its surface is a view over that work. The
+first surface set is Terminal, Browser, Tools, Context, Goal, and Review. A
+surface change never silently launches a process, moves the pane to another
+host, or changes which agent owns the session. Unsupported surfaces are shown as
+unavailable rather than simulated.
+
+An optional decision shelf sits below the active work surface. It may show an
+answer draft, two or three concrete choices, why each was suggested, and the
+capability each choice would need. Suggestions are inert data. Choosing one may
+prepare a typed workspace plan, but any command, file mutation, credential use,
+or external message still passes through the normal approval and command plane.
+
+## Lumbridge Harness
+
+Lumbridge Harness is an optional orchestrator distributed as a separately
+versioned component. It can analyze explicitly shared workspace state, refine
+prompts, recommend next steps, and coordinate supported agents. It does not own
+the desktop shell and is not required for terminal multiplexing.
+
+Its model boundary is provider-neutral. Initial development targets an
+OpenAI-compatible API so the same contract can use a local Spark/Qwen endpoint,
+Cerebras, or another user-selected provider. Credentials stay in the OS
+credential store and are resolved by opaque handle. Endpoint profiles must not
+embed secrets in workspace layouts, command arguments, or traces.
+
+Trace analysis is off until the user enables it for a workspace and selects the
+fields or sessions to share. Local analysis remains local. Sending trace data to
+a hosted provider requires a destination preview and a separate consent. The
+Harness receives only the Observe, Configure, or Execute capability granted for
+that run; autopilot cannot manufacture a broader grant.
+
 ## Provider modes
 
 Subscription mode delegates authentication to the installed upstream harness.
@@ -95,6 +132,7 @@ in the operating-system credential store.
 - 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.
+- Making Lumbridge Harness, trace analysis, or autopilot mandatory.
 - Windows support.
 - Mobile control or collaborative hosted sessions.
 - Arbitrary third-party remote compute provisioning; the first release connects

docs/RESEARCH.md

@@ -48,6 +48,16 @@ They are shallow snapshots for study, not dependencies or vendored source.
 - `openclaw/openclaw`
 - `anomalyco/opencode`
 
+DeepSeek Harness at the captured revision is MIT-licensed experimental software,
+but it is a large Node/TypeScript workspace with a React web client, Cordis
+plugin tree, native/platform payloads, and a broad third-party closure. Its own
+safety notice says it is unaudited and can access processes, files, credentials,
+and the network exposed to it. We will study its service seams, durable event
+log, approval flow, ACP profile, and agent lifecycle. We will not embed its web
+shell into Lumbridge or treat its sandbox as a security boundary. Any branded
+fork is a separate repository/process with preserved notices and an explicit
+dependency and payload review.
+
 ## Research questions
 
 1. Which terminal core gives us correctness without inheriting a product-shaped
@@ -60,4 +70,3 @@ They are shallow snapshots for study, not dependencies or vendored source.
    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/RESEARCH_SNAPSHOTS.md

@@ -39,5 +39,9 @@ only when a question genuinely requires upstream history.
   crate before adapting anything.
 - The captured BBARIT Terminal root did not contain a top-level license file.
   Treat its implementation as unlicensed unless upstream clarifies otherwise.
+- DeepSeek Harness is MIT at the captured root, but it is an unaudited
+  developer preview with Node/TypeScript, React, native payloads, and packages
+  carrying their own terms. Preserve its license/notices and review the complete
+  shipped dependency closure before maintaining or distributing a fork.
 - Every other source still requires a file-level and dependency-level review
   before reuse; a top-level license filename is not sufficient clearance.

docs/ROADMAP.md

@@ -12,6 +12,8 @@
 - Prove Buzz SDK message, attachment, cursor, reconnect, and duplicate-delivery
   behavior against a disposable local relay.
 - Decide terminal core, UI stack, IPC transport, and schema evolution policy.
+- Define the Lumbridge Harness process boundary, trace-consent model, provider-
+  neutral endpoint profile, and upstream-fork maintenance policy.
 
 Exit: recorded decisions with working spikes and measured results.
 
@@ -21,6 +23,8 @@ Exit: recorded decisions with working spikes and measured results.
 - Saved SSH/Tailscale hosts and durable remote panes through a per-user remote
   runtime; reconnect from a second Lumbridge installation.
 - Session restore, crash recovery, command palette, keybindings, notifications.
+- Per-pane Terminal, Browser, Tools, Context, Goal, and Review surface tabs, plus
+  an inert decision shelf that can render typed suggestions without executing.
 - Repository/worktree creation and basic Git status/diff.
 - Optional Buzz collaboration pane, workspace channel binding, and confirmed
   redacted pane-image sharing.
@@ -34,6 +38,9 @@ Exit: Lumbridge is worth using as a terminal multiplexer without AI features.
 - 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.
+- Separately versioned Lumbridge Harness with local/self-hosted OpenAI-compatible
+  model support, prompt refinement, trace projections, and capability-gated
+  workspace plans.
 
 Exit: daily multi-agent work is reliable and observable.
 

docs/TESTING.md

@@ -111,9 +111,16 @@ who already have the final cargo-watch release installed.
   dimensions, and exclusion of provider credentials from the child environment.
 - `lumbridge-runtime` tests ordered actor output, serialized input and resize,
   event polling, invalid configuration, and bounded-time cleanup of a hung PTY.
-- The GPUI slice tests byte line-framing across CRLF, chunk boundaries, split
-  UTF-8, and invalid bytes. It renders one real actor-owned PTY and keeps five
-  surfaces deterministic; line framing is explicitly not VT emulation.
+  A cross-crate integration test drives a real synthetic shell through actor
+  output, VT parsing, terminal key encoding, and a 41×101 resize.
+- `lumbridge-terminal` fixtures cover styled Unicode, cursor/title state,
+  alternate screen, bracketed paste, protocol replies, sanitized title and
+  blocked OSC 52 behavior, key encoding, application-cursor mode, and resize.
+- `lumbridge-core` tests capability-gated split/select/rename/close commands,
+  idempotent request IDs, close-tree promotion, and atomic agentic setup plans.
+- The GPUI slice tests its key-event adapter. It renders one real actor-owned VT
+  session as plain snapshot rows and keeps five surfaces deterministic; styled
+  cell/cursor rendering remains a separate gate.
 - The current-GPUI probe compile-checks real AccessKit element wiring and real
   platform input-handler installation. Unit tests cover its semantic tree and
   UTF-16/UTF-8 composed-text mutations. OS screen readers, IME candidate windows,

docs/UI_SPIKE_SCORECARD.md

@@ -21,9 +21,11 @@ from macOS and Linux and the hard gates pass.
 | Native menu/window/clipboard/drag-and-drop | review | pending | pending |
 | API clarity and maintenance burden | review | pending | pending |
 
-The current programs establish dependency, build, launch, and static layout
-baselines. The next iteration adds deterministic streaming, input timestamps,
-accessibility identifiers, a native Markdown editor, and one Wry browser child.
+The current programs establish dependency, build, launch, and interaction
+baselines. GPUI now routes a real PTY through a VT engine and keyboard encoder;
+its renderer still flattens the immutable screen snapshot to plain rows. The
+next iteration adds styled cells/cursor/selection, measured pane-driven resize,
+a native Markdown editor, and one isolated browser child.
 
 ## Ubuntu baseline — metal, 2026-08-31
 
@@ -85,7 +87,7 @@ fallback.
 
 Both renderers retain the same all-deterministic six-surface action stream for
 comparison. The GPUI integration mode replaces one terminal fixture with a real
-actor-owned PTY and leaves five deterministic surfaces running. Counters
+actor-owned VT session and leaves five deterministic surfaces running. Counters
 separate external PTY batches/lines from total model updates. The GPUI footer
 reports dispatch-to-element-build p50/p95 over a bounded 256-sample window. It
 is deliberately not called key-to-present or frame-present latency: neither

docs/UX_VERTICAL_SLICE.md

@@ -67,11 +67,18 @@ surface rather than a hosted Lumbridge control plane.
    in a stable order.
 6. The footer groups connection state, selected-harness identity, usage-window
    provenance, and burn forecast into readable regions.
+7. The selected pane has a quiet surface strip for Terminal, Browser, Tools,
+   Context, Goal, and Review. Switching surfaces keeps one pane identity.
+8. A compact decision shelf may show local-analyst choices below the work
+   surface. It labels its model/provider, trace scope, and whether suggestions
+   are inert; no choice is visually conflated with an approved action.
 
 ## Keyboard task flow
 
-- Arrow keys or `h/j/k/l`: move focus through the 2×3 pane grid.
-- `1` through `6`: focus a pane directly.
+- `Alt+Arrow` or `Alt+h/j/k/l`: move focus through the 2×3 pane grid while
+  leaving ordinary terminal arrows and text available to the PTY.
+- `Alt+1` through `Alt+6`: focus a pane directly while leaving terminal digits
+  available to the PTY.
 - `Cmd+K` on macOS or `Ctrl+K` on Linux: open the command palette.
 - Typing while the palette is open changes its query; arrows change the result;
   `Enter` runs it; `Escape` closes it and restores pane focus.

docs/decisions/0004-runtime-actor-owns-each-pty.md

@@ -16,9 +16,10 @@ arrives. Process-local session IDs are correlation IDs only; durable IDs are
 assigned by the persisted runtime protocol later.
 
 Runtime events contain ordered raw PTY bytes. The UI spike may line-frame plain
-fixture output for display, but ANSI/VT parsing, screen state, cursor behavior,
-scrollback, and terminal input modes belong to `lumbridge-terminal`. The UI must
-not infer terminal semantics from raw strings.
+fixture output for deterministic surfaces, but the live pane sends bytes through
+`lumbridge-terminal`. ANSI/VT parsing, screen state, cursor behavior, scrollback,
+and terminal input modes never belong to the runtime actor or UI. The UI must not
+infer terminal semantics from raw strings.
 
 Dropping the UI-side actor disconnects its bounded channels, releases an actor
 blocked by event backpressure, terminates the process group through

docs/decisions/0005-terminal-engine-boundary.md

@@ -0,0 +1,24 @@
+# 0005: Terminal semantics stay behind a Lumbridge-owned contract
+
+Status: accepted for the first terminal slice.
+
+Lumbridge uses `alacritty_terminal` with default features disabled as its first
+VT state engine. The dependency is mature enough to cover substantially more
+terminal behavior than a new parser, but its types do not cross into runtime,
+storage, IPC, or UI APIs.
+
+`lumbridge-terminal` accepts ordered raw PTY bytes and exposes immutable
+Lumbridge snapshots containing cells, styles, colors, cursor, terminal modes,
+and sanitized title state. It owns terminal key and paste encoding. Protocol
+replies such as device-status responses return as bytes and enter the same
+bounded actor queue as all other PTY input, preserving ordering.
+
+Clipboard writes such as OSC 52 are disabled by default. Transcript-bearing
+snapshots deliberately omit `Debug`, and terminal titles are bounded and stripped
+of controls. A renderer may derive plain rows for a spike, but that is not the
+terminal model and must not become the persistence or automation contract.
+
+Adopting this engine is reversible: conformance fixtures target the Lumbridge
+contract, and no upstream application code is copied into this repository.
+Kitty keyboard/graphics behavior, OSC 8 links, mouse modes, IME, selection, and
+platform rendering remain explicit qualification work.

docs/decisions/0006-workspace-command-plane.md

@@ -0,0 +1,20 @@
+# 0006: Every workspace controller uses one typed command plane
+
+Status: accepted for implementation.
+
+Human UI, CLI automation, remote clients, and agents submit the same typed
+workspace commands. Stable request IDs make retries idempotent. Pane IDs, split
+ratios, surfaces, launch intents, and close dispositions are validated before
+state changes, and a multi-command setup plan is applied atomically. Reusing an
+ID with a different origin or command is a conflict, not a silent duplicate.
+
+Each request has an origin and an explicit Observe, Configure, or Execute grant.
+The command declares the minimum capability it needs. Creating or terminating a
+process requires Execute; layout-only changes require Configure. Launch intents
+refer to a user shell or an approved harness profile and working directory, not
+arbitrary executable arguments or secret values.
+
+This reducer is not an authorization bypass. The future IPC layer authenticates
+the caller and supplies its granted capability; the reducer rechecks it before
+mutation. Durable audit events record request and object identities, never
+terminal input, transcript content, provider keys, or pane titles by default.

docs/decisions/0007-optional-lumbridge-harness.md

@@ -0,0 +1,27 @@
+# 0007: Lumbridge Harness is optional, separate, and capability-scoped
+
+Status: accepted for architecture; implementation and fork policy pending.
+
+Lumbridge may distribute a separately versioned Lumbridge Harness for prompt
+refinement, trace analysis, recommendations, and agent coordination. The native
+Rust terminal workspace remains complete without it, and the Harness does not
+run inside the UI process.
+
+The captured DeepSeek Harness is an MIT-licensed and architecturally useful
+reference, but it is also an unaudited Node/TypeScript developer preview with a
+web client and broad native dependency closure. A maintained fork, if selected,
+lives in its own repository/process, preserves required notices, and exposes a
+small versioned protocol. Its React UI is not embedded in Lumbridge. We can later
+replace the implementation with a first-party Rust service without changing the
+desktop contract.
+
+Model access is provider-neutral and begins with OpenAI-compatible endpoints so
+development can use a self-hosted Spark/Qwen model or a user-selected service
+such as Cerebras. Endpoint credentials are opaque secret-store handles.
+
+Trace analysis is opt-in per workspace. The user chooses the trace projection
+and destination; local processing stays local, while hosted processing requires
+an explicit preview and consent. Suggestions and decision-shelf choices carry no
+authority. Any setup, launch, mutation, or autopilot action becomes a typed
+workspace plan and can use only the Observe, Configure, or Execute capability
+granted to that run.