0
Fork 0
mirror of https://github.com/zeronsh/comet.git synced 2026-11-16 18:57:19 +00:00
comet/ARCHITECTURE.md
Wing a8d1dc6ecd
Updates that can't strand a device, on every platform, from any device (#1241)
* update: say how a device is installed and whether it can update from afar

UpdateStatus now carries `install`, `canApplyRemotely`, `cannotApplyReason`
and `manualCommand`, so a client no longer has to guess by platform. Older
engines omit them; a method this build doesn't know reads as Unknown rather
than losing the report. `update-ability-v1` advertises it.

ApplyUpdate refuses with the same reason the report gives. That includes a
managed install started by hand, which used to swap `current` and then fail
to restart a service it isn't running under.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* providers: decide what to run at the last moment, and only claim what happened

An update judged its plan before the wait for idle and never looked again, so
a CLI reinstalled meanwhile got the old owner's updater. Under the lease and
owner gate it now re-reads the executable and what's installed and rebuilds the
plan, refusing and checking again if that isn't what the check offered.

With no target version (Hermes, Cursor), exit 0 used to report Updated. It now
takes a moved version, a rewritten executable, or Hermes's own check no longer
finding commits. Otherwise the row stays where it was, with the reason.

Homebrew:
- Only Homebrew's published version is offered. A release Homebrew doesn't have
  yet was an Update button that always failed, and would have failed Update all.
- A formula keeping an npm CLI in its keg is Homebrew's, not npm's. `npm install
  --prefix` was changing the keg behind brew's back. A Node keg's globals stay npm's.
- A Cellar or Caskroom path with no brew at that prefix can't apply, and the
  manual step names brew rather than a self-updater that writes a second copy.

Also: a Chocolatey Claude stays manual, and updaters get 30 minutes rather than
15, since stopping a silent download can leave a truncated CLI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* update: Linux updates that can't strand a box

`app/current` now moves exactly once, when a new version has proved it's ready.
Until then every start of the service runs the old version, so if the new binary
exits, hangs, or the power goes, the next start lands on a binary that works and
knows how to put things back.

- Refuses before stopping anything if the release and a copy of the databases
  won't fit.
- Records the update durably before answering, with an id; `UpdateStatus.update`
  says how it went (inProgress, updated, rolledBack, failed), since reconnecting
  can't tell an update from a rollback.
- The old version copies the SQLite stores once nothing has them open, leaves a
  watchdog behind, and replaces itself with the new binary. It's the same process,
  so the service manager sees nothing change.
- The new version holds back work it can't take back (resuming chats, queued
  messages), proves it reads its data, serves its port and, when signed in, reaches
  Zeron's servers, then commits and only then resumes chats.
- A failed or timed-out trial goes back: the old version restores the databases
  before anything opens them. An interrupted restore finishes first.

`zeron update` on a box with a running service takes the same path and reports the
outcome. Automatic updates don't retry a release that went back; a person can.
ZERON_SERVICE_UNIT names another unit, so a test install can never restart a real
one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* providers: an update someone asks for doesn't wait for running chats

It used to wait behind an exclusive lease with no bound, which with agents always
running can look stuck for ever. Where the installer keeps the old version's files,
it now goes ahead: running chats keep the version they started on, new ones get
the new one, and nothing is drained or held up. That's Claude's native install,
Codex standalone, Grok standalone, Cursor (chats use its SDK, not this CLI),
Antigravity and agents from the ACP registry.

Installers that replace or delete files keep waiting, because a chat's process
lives for its whole session and goes on loading files from where it started: npm
and the other package managers, Homebrew, Muse, OpenCode, Pi and Hermes. Their row
says why, in the new `waitReason`. Automatic updates still wait for a quiet moment.

The registry's cleanup used to delete any version older than the last, now that
updates don't wait for chats it keeps a version something is running from.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* update: Mac and Windows devices can update from afar

The same rule as Linux, with the engine doing all of it, so the app doesn't have
to be open: the installed app changes only at the commit, and anything before that
lands back on the old version.

macOS: the new bundle is copied beside the installed one before anything stops, so
what can fail, fails with Zeron still running. The engine drains, backs up and
replaces itself in place, the same process, so it never starts a successor. Once
proved, one atomic swap makes the new bundle the app. An app still open carries on
from the retired bundle until it restarts.

Windows: the old process can't be replaced, so it starts the new exe from a folder
inside the installation and stays on as the watchdog. A running exe can be renamed,
so moving it into place is the commit.

A bundle something runs from is no longer deleted, for updates from the app too:
that's #1037. Retired bundles and old stages go once a process scan finds nothing
running from them.

A second start during a trial (the app's reconnect seeing the port go quiet) now
bows out rather than rolling back a trial that's still running, and zombies no
longer count as running on macOS. The failure tests give each fake install its own
copy of the binary: hard links made the process checks see through to other
installs, which was the cause of their intermittent failures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* update: nothing but the trial opens the databases mid-update

An app that can't start its helper embeds the engine, which skips the update's
start-up step, and could have opened databases a trial had changed or a restore
was part way through. It now refuses until the update has settled. The app's own
install on quit also refuses during an update: going back from a trial needs the
installed app to stay as it was.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* update: compile on Windows

The watchdog's environment variables are only read on Unix, the test's
version lookup no longer ends in a Unix-only expression, and the Grok CLI
fixture and the test that uses it are Unix-only like their callers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* update: check free disk space on Windows

Without it every Windows update refused with "couldn't check the free disk
space". The store-list test compares paths with forward slashes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* update: a brief reader can't fail the update record on Windows

Replacing a file fails with "Access is denied" while anything has it open
without delete sharing (antivirus, an indexer, a script). Seen once on a real
trial: the watchdog couldn't record the trial's pid. Retry the rename for up
to a second.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* update: give the second-start test a deadline a slow machine can't miss

It failed once in 80 runs on a loaded box, when the second start landed after a
3-second trial deadline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* update: another device's status follows it through its restart

One device asking another's `UpdateStatus` got a subscription that ended the moment
the update restarted the engine, so whoever asked had to know to ask again. It now
carries on until the subscriber goes, asking again if nothing has come for a while,
which also covers a device that died without a word.

Asking a device that can't be reached now says that plainly, and that the update
didn't start, rather than `transport: peer …: readiness check failed`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* update: a beta Mac stays on beta, and says what's on offer

Tested with a bundle shaped like a beta: a beta interface carrying stable's engine.

An update asked from another device already followed the app's recorded channel,
but with no record, as when the app hasn't run since it was installed, the default
was stable: it installed the stable app and left beta. An app with no recorded
choice now stays on the channel it was built for. A choice someone made at that Mac
still stands.

The engine's report compared releases with its own version, which on a beta is
stable's, so a newer beta read as nothing new and no update was offered. On a macOS
app install it now compares with the app's version, and says what that is in
`appVersion`. It looks again once a commit has changed the answer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>
2026-11-05 16:59:05 -07:00

28 KiB

zeron — Architecture

A ground-up native rewrite of zeron — a multi-device controller for coding agents (Claude Code / Codex) — in Rust, with a gpui UI. Fresh app; no backwards compatibility required.

Pillars (from the goal):

  • Optional sync uses Loro CRDT docs (loro-mirror model) through Cloudflare Durable Objects; the same docs persist locally when sync is disabled.
  • Durable Objects stay TypeScript (decision + evidence: docs/research/durable-objects-language.md). Everything device-side is Rust.
  • Feature parity with zeron except token-usage display (poor fit for CRDTs; excluded).
  • Frontend is gpui (pinned Zed rev). Virtualization + markdown techniques ported from mugen + pretext (docs/research/mugen-pretext.md).
  • One binary, headed or headless. Smooth transitions/animations matching the original (catalog in docs/research/feature-inventory.md §1.12).

1. Topology (unchanged shape, new materials)

gpui UI ─ in-proc/localhost RPC ─ engine A ══ DeviceRoom DO relay ══ engine B ─ RPC ─ gpui UI
                    │       optional edge Worker: auth, rooms, R2        │
                    └── optional chat2 sync ──  ChatRoom DO (per chat) ──┘
                                          └─ Workspace registry room ────┘
  • Engine = backend (was @zeron/backend): runs agents, owns auth, terminals, repos/worktrees, diff sync, doc hosting. Pure Rust daemon, fully functional headless.
  • UI = viewport (was Electron): gpui app rendering engine state. Talks the same typed RPC whether the engine is in-process or a separate daemon. Organized around spaces — (device, folder) pairs, local or synced according to the active profile. The sidebar is the data: an attention-sorted Sessions list, filtered by a searchable spaces dropdown ("All spaces" included) that also hosts space management. The horizontal tabs are a device-local viewport onto that list (ui-settings.json openTabs, cross-space): closing a tab is local-only — archiving is an explicit sidebar action — and a sidebar click (re)opens a session as a tab. The new-session canvas carries a space picker (defaulting to the sidebar filter, else the last selected space); new sessions are minted onto the picked space's device via relay-forwardable RPCs.
  • Edge (TypeScript, ported from zeron apps/edge): Worker + ChatRoom DO (per chat, the chat2 row protocol; the legacy SessionRoom DO remains deployed only for pre-cutover clients — no current client dials it) + DeviceRoom DO (per device) + R2 attachments + WorkOS JWKS auth. Absorbs the old apps/server responsibilities (WorkOS code exchange/refresh, orgs) so Postgres, the Hono server, and the WebRTC/signaling stack are all gone.
  • Cloud (docs/design/cloud-device.md): a checkout option — a session in any project whose GitHub repository the Zeron GitHub App reaches can run on its own hosted sandbox, with Cloud's own providers — an ordinary headless engine provisioned per session by the edge's CloudAccount DO + Workflows behind a provider-neutral sandbox interface, sleeping when idle, authenticated with its own device key (runner tokens scoped to that one session's device), and fed provider credentials by the separate service-binding-only zeron-vault Worker (one Durable Object per account serializes refreshes, so parallel sessions never race a refresh token).

Headed / headless

Binaries zeron (app + CLI) and zeron-engine (the app's background engine, no UI linked):

  • zeron — headed. If an engine is already listening on the IPC port, connect to it. Otherwise start the background engine (crates/engine/src/managed.rs) — zeron-engine beside the app ("Zeron Engine" inside the macOS bundle), or zeron engine where no separate executable ships (Windows, which updates as a single zeron.exe) — and attach to it. It is spawned detached from the app (own session/process group, no inherited pipes), not through a service manager, so on macOS privacy permissions stay attributed to the app and no background-item approval is needed. Closing or quitting the app leaves it running with every session; it shows up as its own process. The app reconnects when the connection drops (starting it again if it is gone) without resetting what's on screen, and stops it itself only to replace the runtime (sign-out, the local→synced switch). After an app update it restarts into the new version once no run or terminal is live. If it can't start — or the port is 0, or something else holds the port — the app embeds the engine in-process as before (RPC over an in-memory duplex — same protocol — and serving that engine on the IPC port); ZERON_EMBED_ENGINE=1 forces it. An engine that went away unasked is started again after 1, 2, 5 and 15 s; a fifth loss within five minutes stops and shows the failure (with Retry) rather than embedding — an engine bug would crash an in-process engine too. The engine stops by itself once idle if its app is moved to the Trash or uninstalled, and its log (like every long-running mode's) moves to .old past 64 MB rather than growing for weeks.
  • Updates from another device are transactions (crates/update/src/transaction.rs, crates/engine/src/update_trial.rs). The installed version changes in one step, only once a new version has proved it's ready: app/current on Linux, an atomic bundle swap on macOS, a rename on Windows. Until then every start runs the old version, which is how a new binary that exits, hangs or loses power gets undone. The old version copies the SQLite stores, leaves a watchdog and hands over; the new one holds back what it can't take back (resuming chats, queued messages) until it has committed. A failed trial restores the stores, and UpdateStatus.update says which happened under the id ApplyUpdate answered with. Only the SQLite stores roll back. Provider CLIs update under running chats where their installer keeps old files (UpdatePlan::while_chats_run), and wait otherwise.
  • Desktop banners are the engine's (desktop_notify.rs, advertised as desktop-notifications-v1): finished runs, questions, failures, connection loss and agent updates keep arriving with the app closed. Preferences come from the app's ui-settings.json; "only in the background" uses window focus the app reports (SetViewportFocus). The app keeps the chimes, decided by the same baselines.
  • zeron headless — engine only. A clean installation immediately serves its local profile over localhost IPC; when a saved account selects the synced profile at startup and a bearer is available, it also hosts its DeviceRoom for remote control. A VPS can run this while a laptop's UI drives it.

Local-first workspace profiles

Authentication and workspace selection are deliberately separate state machines:

  • AuthState is live credential state: SignedOut, NeedsOrganization, or SignedIn. It may change after login, refresh, revocation, or logout.
  • WorkspaceScope is the immutable storage and transport boundary captured once at engine startup: Local, Synced, or explicit Development.

The engine never re-resolves an open store because AuthState changed. This prevents a sign-in, token refresh, or revocation from silently swapping databases or attaching online transports to a runtime that started local-only.

Startup condition WorkspaceScope Online transports
WorkOS enabled, no parseable saved session.json Local Disabled
Parseable saved WorkOS session Synced Enabled when a bearer is available; organization onboarding completes before opening the store when needed
WorkOS disabled without a dev bearer Development Disabled
Explicit non-empty dev bearer Development Enabled

zeron login and zeron logout operate on session.json while the engine is stopped. Login selects Synced for the next start; logout selects Local for the next start. The UI may update live authentication status, but the active WorkspaceScope still changes only after restart.

The resolved profile selects the session snapshots, registry snapshot, run journals, and attachment cache that may contain workspace data:

Scope Store and journals Uploads
Local {data_dir}/profiles/local/ {data_dir}/profiles/local/uploads/
Synced {data_dir}/orgs/{org_id}/{user_id}/ {data_dir}/orgs/{org_id}/{user_id}/uploads/
Development {data_dir}/orgs/{org_id}/{user_id}/ {data_dir}/orgs/{org_id}/{user_id}/uploads/

The synced and development store roots preserve the historical cloud layout while their attachment caches are account-scoped. Local identity lives in {data_dir}/local-profile.json; its UUID is stable across restarts and is not an account or development identity.

Older releases wrote every synced and development attachment to {data_dir}/uploads/, and persisted those absolute paths in transcripts. On upgrade, the first synced or development account that opens this legacy cache claims it in {data_dir}/legacy-uploads-owner.json. That account may read the cache as a compatibility fallback, but all new staging and commits use its account-scoped uploads root; other accounts cannot read or write the legacy cache.

Device identity and machine resources remain device-scoped under the common data directory: device-id, repository registration, managed worktrees, agent credentials/accounts, and UI settings. They are available across profiles, but they do not contain or expose another profile's transcripts or attachments.

Privacy boundary and follow-ups

This first local-first change does not upload, import, link, or delete local sessions when a user signs in. Local attachments remain jailed under the local upload root and are not readable through the synced attachment cache. Returning to local-only mode reopens the same local identity and data.

Remote workspace file trust boundary

Devices authenticated to the same synced account are trusted peers for remote workspace control. A peer may send relay-forwarded workspace file requests to the device that owns a checkout; the owning engine resolves the target and enforces workspace-relative path, containment, symlink, and write-conflict checks before touching its filesystem.

Ignored-file visibility is not an authorization boundary. A remote peer may request ignored entries and then read or write them, including potentially sensitive files such as .env, when includeIgnored is enabled. .git remains unavailable regardless of that option. Zeron intentionally does not maintain a filename denylist because it would be incomplete and could imply a security guarantee it cannot provide.

If authenticated devices must no longer trust one another with the full workspace, that policy must be enforced by the owning engine for remote requests. Hiding entries only in the UI is not a security control.

The following product work is intentionally deferred:

  1. Explicit session selection and copy between local and synced profiles, including attachment copying, provenance, and conflict behavior.
  2. Browsing both scopes simultaneously or switching the visible scope without restarting the engine.
  3. A supported self-hosted backend contract covering authentication modes, room APIs, authorization, persistence, and blob storage. Current endpoint and bearer overrides remain development/deployment seams, not a promised compatibility surface.

2. Data model — all Loro

Two persistent doc kinds. When sync is enabled, session docs ride the chat2 row protocol (loro updates as append-only rows + Range-resumable checkpoints, ChatRoom DO) and the registry rides its own row-frame protocol; local-only profiles persist the same docs without joining rooms:

  1. Session doc (per chat) — the transcript + durable command queue. Schema is a Rust port of packages/session-doc (same container names/shapes so the edge's tail materializer keeps working): meta map, messages list (parts as list-of-maps with LoroText bodies — the measured 1.03× oplog shape; never LWW value rewrites), commands list with ledger rules 1–3 (append-only per-device entries; host-only outcomes; dedupe/TTL/supersede evaluation). Continuation splitting at 256KB, render-only tool parts (full inputs stay in the host's local run journal), tail/diff sidecars. Constants carried over (STREAM_COMMIT_MS=120, DO_FLUSH_MS=5s, compaction at 8MB, retain 30d, tail 64).

  2. Workspace registry doc (per profile) — the registry1 snapshot stores spaces (id, deviceId, path, name?, gitDetected, checkoutId, repositoryId), the chats index (id, deviceId, title, archived, cwd, branch, checkoutId, spaceId, lastSeenAt, lastMessagePreview/At, config), devices, session-status rows, and checkout-diff summary pointers. A space is a device+folder pair in the active profile; the owning device's SpacesSync stamps git presence so branch pickers and the diff sidebar can gate without another RPC, plus a repository identity (the trunk's root commit, so renames, transfers and remote spellings don't split a repository; a shallow or empty history falls back to the normalized origin remote, then a device-scoped common-git-dir hash) that groups clones and worktrees of one repository in the sidebar's project mode. Local scope keeps the registry entirely in its profile store. Synced and development scopes join /registry/{orgId}/ws, backed by the private per-user room reg1/{orgId}/{userId}; rows are never visible to every member of an organization.

    Writer discipline: each device writes its own device and session-status rows, rows for chats it hosts, and git stamps for spaces it owns. Creates, renames, archives, and seen marks are LWW sets accepted from any device. deleteSpace tombstones the space and every chat/session row in it in one commit. Presence uses ephemeral room frames rather than durable heartbeat writes.

    Why one registry and not N tiny docs: the sidebar needs one subscription for the whole list (grouping, resort animations, unseen markers). Its rows contain indexes rather than transcripts, so one local snapshot and, when enabled, one room connection remain bounded and cheap.

  3. Mirror layer (zeron-doc crate) — Rust equivalent of loro-mirror: typed structs for the schema, incremental application of doc.subscribe diffs into cached state (no full re-hydration per change — this is also what fixes zeron's known O(transcript) re-projection inefficiency, remaining-work item 1a), and a diff-reconcile write path (evaluate lorosurgeon 0.2.x as a dep; our schema is small enough to hand-roll if it doesn't fit). The UI renders mirror state directly with per-entry change notifications — the "endgame" the TS implementation documented but never reached.

Command plane

Send/steer/interrupt/respondInput = durable command entries in the session doc (QueueCommand), executed by the chat's host device (executor gated on chat ownership; mark-processed BEFORE execute; steer with no live run dispatches as the next turn). Offline sends queue in the doc. This is zeron's proven design, kept verbatim.

3. Cargo workspace

zeron/
  Cargo.toml                 # workspace
  crates/
    proto/        zeron-proto    # wire types: AgentEvent, ToolCall, RunRequest, Model,
                                 # entities, RPC envelopes (serde; ndjson framing);
                                 # `view` = the pure derivations both frontends share
                                 # (sort orders, staleness gating, grouping, boot gate)
    doc/          zeron-doc      # session-doc + workspace-registry schemas, mirror layer,
                                 # parts fold, continuations, command ledger, sidecars
    sync/         zeron-sync     # loro room client (join/VV backfill/fragments/backoff),
                                 # ephemeral presence, DocsStore (SQLite snapshots +
                                 # processed-command ledger)
    harness/      zeron-harness  # Harness trait + claude-code (stream-json subprocess),
                                 # codex (app-server JSON-RPC), mock; steering mailbox,
                                 # requestInput, models/reasoning/options catalogs
    engine/       zeron-engine   # sessions engine (pub/sub, run journal, recovery, stall
                                 # watchdog), doc host + command executor, repos/worktrees,
                                 # checkout-diff sync, terminals (portable-pty), uploads,
                                 # agent accounts (cred swap), auth (WorkOS via edge),
                                 # device-room host/peers, identity
    rpc/          zeron-rpc      # UiRpc/ControlRpc: typed req/resp/stream over WS (tokio-
                                 # tungstenite) + in-memory transport; device-room virtual
                                 # sockets ({s,k,to,from} frames)
    theme/        zeron-theme    # source-neutral theme schema + built-in/custom registry,
                                 # validation, provenance, and local VS Code compiler
    voice/        zeron-voice    # desktop-local optional Parakeet model, capture and inference; no RPC/sync
    ui/           zeron-ui       # gpui app: shell, sidebar, conversation, composer,
                                 # terminal view, diff pane, settings, animation kit
  apps/
    zeron/                       # the binary (headed default, `headless` subcommand)
  edge/                          # TypeScript Worker + DOs (ported from zeron/apps/edge,
                                 # + auth-exchange routes absorbed from apps/server)
  docs/                          # this file + research reports

Engine async runtime: tokio throughout; the UI bridges via gpui_tokio (Tokio::spawn futures surfaced as gpui Tasks). In-process mode runs the engine on its own tokio runtime thread; the UI never blocks on it.

4. UI plan (gpui) — parity + smoothness

Reference: docs/research/gpui.md, docs/research/mugen-pretext.md, feature spec docs/research/feature-inventory.md §1.

  • Deps: gpui + gpui_platform pinned to one Zed rev (Apache-2.0). We do not use Zed's GPL crates (markdown, ui, theme, editor) — markdown, components, and theme are ours.
  • Transcript: gpui list() + ListState::new(n, ListAlignment::Bottom, overdraw) (sum-tree offsets, follow-tail). On top of it, port the mugen behaviors that gpui doesn't give us:
    • stick-to-bottom spring with feed-forward tracking of streaming growth; interrupt from user input (wheel-up / drag), re-engage within a 70px band; own-send re-engages + smooth scrolls;
    • block-granularity rows (one row = one markdown block / tool group, not one message) with stable ids msgId#blockId; live turn stays unsplit, re-splits on persist; optimistic echo rows share the client-minted id so persistence never flickers;
    • row height memoization keyed by (row id, content length, width) so a streamed token re-measures one row;
    • scroll-anchor absorption for above-viewport height changes.
  • Markdown (zeron-ui::markdown): pulldown-cmark parsing on background_spawn with coalescing (Zed's proven pattern), block-level incremental re-parse of the streaming tail (incremark's O(delta) idea: only re-parse from the last stable block boundary), monochrome theme where numbers drive layout, colors are paint. Code blocks: monospace, no wrap ⇒ height = lines × line-height (layout independent of highlight); syntax highlighting via synoptic/syntect-class tokenizer run time-sliced in the background, colors applied as text runs (paint-only). Streaming fade-in veil on newly appended text via with_animation opacity (paint-layer, never affects layout). prefers-reduced-motion honored.
  • Composer: hand-rolled gpui text input (start from Zed's examples/input.rs: IME, selection, clipboard, key actions), compact↔expanded auto-flip by measured text width, auto-grow 76–260px, Enter/Shift+Enter, Send→Steer→Stop morph, drafts + attachments per chat, drag-drop/paste images, QuestionPanel (paged, 1-9 keys, 220ms auto-advance, a corner close / Escape that answers nothing) replacing the composer while input is requested. Pickers (harness/model, traits, repo w/ folder browser, branch w/ worktree toggle) as gpui popovers with menu-in scale/fade.
  • Terminal: alacritty_terminal (vte state machine, MIT/Apache) + portable-pty on the engine side; custom gpui grid element; tabs w/ drag-reorder (150ms sliding transforms), height drag 160px–55vh, 80ms resize debounce, 1MB replay, detach ≠ close. No artificial latency: keys are written the moment they land (one write in flight per tab keeps them ordered) and output after a quiet spell is sent the moment it is read (only floods are paced, 4ms). Typed text goes through the platform text input (IME, dead keys, layout symbols); mouse/focus reporting, DECSCUSR cursors with a typing-aware blink, synchronized output, a contrast floor for program colors. A terminal on another device streams over a direct WebRTC link (engine/src/terminals/link.rs, remote_terminals.rs), falling back to the device-room relay only when the devices can't reach each other and moving back mid-session without a gap (input is numbered and acknowledged, so a path change neither drops nor repeats a keystroke); on slow links the viewer predicts the echo of typed text (ui/src/terminal/predict.rs).
  • Diff pane: unified-patch parser → virtualized file/hunk/line rows, per-file collapse (180ms height tween), time-sliced highlight, 200ms width transition on the pane itself.
  • Animation kit (zeron-ui::motion): small helpers over gpui Animation reproducing the zeron catalog — fade-in (0.5s, cubic-bezier(0.16,1,0.3,1), translateY 4→0), splash-out, zeron-pulse staggered cell wave (boot splash + loaders), gradient-spin-pulse matrix spinner (WorkingIndicator + rotating flavour word), menu-in/dialog-in scale-fades, 200ms ease-out width/height transitions for sidebar/panes, sidebar-resort slide animation (we own the list, so animate row positions directly — the View Transitions equivalent, 260ms cubic-bezier(0.22,1,0.36,1)), reduced-motion switch.
  • Theme: independent light/dark resolved variants, theme-owned semantic/syntax/terminal palettes, optional interaction-accent overlays, and a device-local surface preference that resolves each variant's recommended frost/opaque treatment without changing theme selection. Forced frost derives contrast-checked tints from mapped theme surfaces. Local VS Code file/package compilation and imported/linked custom families retain last-known-good persistence. Colors remain paint-only; hairline borders and bundled Geist/Geist Mono remain shared presentation foundations.

5. Engine plan

Direct ports of zeron behaviors (spec: feature-inventory §3):

  • Sessions engine: per-session broadcast hub; on-disk run journal (resumable seq replay, crash auto-resume); persistent steerable sessions (steering mailbox at step/turn boundary; idle reaper; 10min stall watchdog); recovery stamps aborted.
  • Doc host: per-chat handle (join room, VV backfill, write user entries + stream assistant segments at 120ms commits, drain commands host-only with processed-ledger idempotence, publish diff sidecar, presence); warm-open recent chats (14d/cap 30); nudge-driven cold open; SQLite snapshot store.
  • Harness (research pending — docs/research/harness.md): trait mirroring zeron's HarnessShape; Claude Code via claude CLI stream-json in/out (control protocol for permissions/AskUserQuestion→requestInput, resume, steering); Codex via app-server JSON-RPC or codex exec --json; model/reasoning/option catalogs ported from packages/harness.
  • Repos/diffs: git2 or git subprocess (subprocess — matches zeron, avoids libgit2 edge cases); worktrees under ~/.zeron/worktrees; fs watchers (notify) + 2min repair; diff capture (patch + numstat + untracked, 3MiB cap, sha256) → workspace registry summary + DO diff sidecar.
  • Agent accounts: credential-slot swap (macOS Keychain via security-framework, files elsewhere), plan labels, usage probes, paste-code/browser-poll OAuth flows.
  • Auth: WorkOS through edge routes (/auth/exchange, /auth/refresh, orgs); loopback callback server headed, paste-code headless; dev mode (no key ⇒ bearer = configured user id).

6. Edge plan (TypeScript, edge/)

Port zeron/apps/edge nearly verbatim (it is already Loro-native and smoke-tested: session room w/ hibernation + two-level compaction + daily alarm backups, device room byte relay + nudges + sidecar slots, R2 attachments, JWKS auth). Additions:

  1. Private per-user registry rooms (/registry/{orgId}/ws → reg1/{orgId}/{userId}) with authenticated row sync and ephemeral device presence.
  2. /auth/* routes absorbed from apps/server (WorkOS API key in Worker secret).
  3. Drop /seed migration path and legacy sync anything (fresh app). Hibernation hygiene: no idle timers (flush timer only while dirty), auto-response ping/pong — per docs/research/durable-objects-language.md.

7. Parity exclusions & deliberate changes

  • Excluded: token-usage display (profile heatmap, lifetime stats, per-message token columns, WatchUsage). Rate-limit meters on agent accounts are kept (separate concern; probed from CLIs, not CRDT-synced).
  • Changed: Postgres entity sync/server → workspace registry + edge; Electron/React/mugen → gpui with ported techniques; Node harness SDKs → subprocess protocols; WebRTC → device-room relay (zeron had already made this move); mobile app → out of scope for this repo.
  • Kept verbatim: session-doc schema shape + constants, command ledger rules, edge DO design, render-parts privacy policy, UX behaviors and animation timings.

8. Milestones

Status legend: ✅ shipped · 🟡 shipped with named gaps (see docs/PARITY.md).

  • ✅ M0 Scaffold — workspace builds; proto/doc crates with ledger + parts + continuation unit tests; gpui hello-window runs.
  • ✅ M1 Doc + sync core — zeron-doc mirror over loro 1.13; room client syncs with the edge running under wrangler dev; Rust⇄edge⇄Rust convergence test (M1 exit: two Rust peers converge through a real SessionRoom DO, tail endpoint serves).
  • ✅ M2 Engine core — Claude harness end-to-end headless: zeron headless + dev auth runs a turn, journal + doc writes, recovery test.
  • ✅ M3 UI core — shell (sidebar/panes/header), transcript (virtualized, markdown, streaming, stick-to-bottom), composer (send/steer/stop, question panel); local chat fully usable headed.
  • ✅ M4 Multi-device — device-room host/client virtual sockets, remote device control, workspace registry sync, WorkOS auth + org gate, presence. Proven live by scripts/e2e-smoke.sh: two headless engines against a real edge — B queues a run into the chat doc, the durable nudge wakes host A, A executes (mock harness), transcript + session status sync back to B.
  • 🟡 M5 Full surface — terminals, diff pane, repo/branch/folder pickers + worktrees, agent accounts UI, settings (devices/shortcuts/archived), Codex harness. Gaps: composer attachment UI (engine upload RPCs exist), Cursor harness.
  • 🟡 M6 Polish — wire reconciliation (proto AuthState on the wire, LocalDevice), two-device e2e smoke, keyboard map, clippy/fmt sweep, Linux packaging (scripts/package-linux.sh + release profile), macOS bundling config (dist/macos/, not executed — needs a Mac). Gaps: prefers-reduced-motion, engine hardening (instance lock, watchdogs), edge production deploy.

9. Open questions (tracked, non-blocking)

  1. loro-protocol Rust client ⇄ TS edge interop — verify at M1; fallback is a ~300-line hand-rolled client (the frame protocol is small and we control both ends).
  2. lorosurgeon fit for the mirror write path vs hand-rolled reconcile.
  3. Cursor harness (zeron has it; CLI surface for Rust TBD) — parity item, scheduled after Codex.
  4. Text shaping performance for analytic row heights: gpui measures shaped text natively (Rust ⇒ cheap), so we start with gpui list() measurement + memoization rather than porting pretext's full analytic kernel; revisit only if cold-open of huge transcripts measures slow.