docs(atlas): a from-scratch design for remote terminals#1398
Draft
srid wants to merge 2 commits into
Draft
Conversation
A clean-slate design for kolu remote terminals, written after rejecting PR #1385 (the "kolu dials remotes" work) as a single 133-file PR. Instead of finishing that design in layers, it redesigns from the goal: - the HOST is the sole source of truth for its own live terminals; kolu persists only a dial-list (Set<hostId>), never a remote-terminal record; - endpoint/location is first-class and non-optional (local is a real value); - awareness is split honestly — PTY-tap signals (cwd/title/foreground) run in-server off kaval's taps, but git/PR/agent awareness MUST run host-side (its providers read the host's fs/home), which is exactly why the watcher exists; - the four #1385 bug classes (cold-boot re-adoption race, env leak, remote-repo prune, restore-to-wrong-endpoint) are dissolved by construction, not patched. Ships as ten thin, independently-mergeable vertical slices; the first remote PR puts a durable shell on the canvas with no host agent. Sibling of the kaval-sessions plan-of-record; status: proposed.
…nest cost Fold the design refinements debated on the PR, verified against the real kolu-watcher code: - "thin slices" → "risk-isolated slices" + an honest cost scorecard; the watcher (P4w) is the fat cost centre, not a thin slice. - Split the old fat P4b into P4w (harden packages/kolu-watcher + its Nix closure; parallel with P4a — it imports nothing from the PTY endpoint), P4c (consume over a net-new loopback harness), P4d (over ssh). - Honest loopback framing: the harness is ssh-free but NOT Nix-free (getHostSession always nix-realises, even for localhost); the swap point is net-new (remote.ts hardwires getHostSession); the consumption logic already ships against a mock. Going remote keeps real risk (cross-arch .drv, reconnect/recheck/ControlMaster, nix copy over ssh-ng) loopback can't prove. - Existence comes from kaval's atomic terminal.list, never the watcher's incremental mirror — that removes the settle window's cause, not re-times it. - P1 reverses #1385's shipped optional location (a change + migration). - Caveat: P1–P4d are commits on the still-open PR #1385, not merged trunk. Twelve phases now; DAG + claims adversarially verified.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A clean-slate design for kolu remote terminals, written after rejecting #1385 — the "kolu dials remotes" work — as a single 133-file PR. Rather than finish that design in safe layers, this note redesigns from the goal and dissolves #1385's bug classes by construction instead of patching them. A plan-of-record Atlas note (
status: proposed), sibling of kaval-sessions — no code changes.The core model
One thesis: the host is the sole source of truth for its own live terminals, and kolu persists only a dial-list (
Set<hostId>), never a remote-terminal record. A remote tile is a localTerminalEndpointbound to ssh — local vs remote is only the transport.awaitkaval's atomicterminal.list(never the watcher's incremental mirror) → synchronously seedterminalMetadata→ project.locationnon-optional; a dropped host is a compile error.The honest correction (what the adversarial review caught)
"The first slice needs no host agent; the DAG just runs in kolu-server" is provably wrong — the git/PR/agent providers read kolu-server's own
fs/os.homedir(), so in-server they inspect the wrong machine. Awareness is split: PTY-tap signals (cwd/title/foreground) run in-server; git/PR/agent run host-side — exactly why the watcher exists (renamed the "host agent", minus PTY-forwarding).Four bug classes, dissolved by construction
terminal.list+ sync seed; persist only a dial-listendpointFor(record.hostId).fs, tolerant of a down hostlocationnon-optional; restore = dial + adopt, never read-record-and-spawnTwelve risk-isolated slices (honest about cost, not "thin")
P1location non-optional ·P2dial-list ·P2bhost-aware feed — cheap local-only bug-proofing, do first →P4akaval-direct shell (ssh, no watcher) →P4whardenkolu-watcher+ its Nix closure — the FAT cost centre, parallel to P4a →P3boot via kaval's atomic list →P4cconsume the watcher over a net-new loopback harness →P4dwatcher over ssh →P5health ·P6host picker ·P7Code-tab fs/git ·P9multiplex.Preview
Self-contained Atlas page (Code tab:
docs/atlas/dist/remote-terminals-from-scratch.html):Generated by Claude Code (model
claude-opus-4-8).