LIMITATIONS.md

Preview limits and next milestones

Implemented features are documented in the README. This file names the gaps so a roadmap item cannot be mistaken for tested behavior.

A prioritized, higher-level roadmap lives in ROADMAP.md.

Limits in 0.20

• macOS/Linux only. WSL can run the Linux terminal build. A native Windows client is not planned.
• Reboots, daemon crashes and service termination lose live PTYs. Layouts recreate new shells. No process-memory checkpointing or transparent shell restoration is implemented.
• No QUIC, Mosh-compatible roaming protocol, predictive echo, automatic public relay, NAT traversal or zero-latency guarantee. OpenSSH reconnects after transport failure.
• A dead controller is released on EOF or the daemon's idle read timeout (45 seconds). During unusual half-open failures another controller no longer has to wait: the desktop app's "Take control" action takes the seat at once and the old controller keeps watching, read-only. The takeover is not authenticated beyond the connection itself, so anyone who can attach to the daemon can take the seat.
• Over SSH the desktop app receives screen diffs (a scroll plus the changed rows, checked by a checksum, with a full snapshot on any mismatch, after a resize, and every 500 updates); other clients and local sockets still get full changed-screen snapshots. A diff client is sent screen bytes as base64 text; everything else, including input and every other client, still uses JSON number arrays, and pane details (title, directory, foreground command) are sent once and then only when they change. Each poll still costs a few hundred bytes of framing even when nothing changed, and request/response polling still adds latency: over an emulated 300 ms link a typed character appears after about 1.2 round trips (tmux: about 1.05) and a pasted 20-byte command after about 3 (tmux: 1), see BENCHMARKS.md. In one scrolling-output test the screen bytes were about 17 times smaller than whole screens and the whole reply stream about 7 times smaller; no benchmark proves this faster than Zellij, WezTerm, tmux or Mosh.
• Layouts are single, columns, rows or a grid with draggable dividers, plus a free-form pane tree (palette: "Split pane right / below (pane tree)"). The tree is client-side. Its shape is saved with the automatic per-workspace layout and re-applied when you accept "Restore" (only for an untouched workspace; panes are matched by order, and a pane that never appears leaves the grid layout in place). There is no cross-window tab dragging or multi-monitor workspace layout, and the tree has no default key binding.
• The desktop app forwards mouse reports to programs that ask for them and draws iTerm2-protocol and Kitty-graphics inline images (PNG and JPEG; Kitty graphics is a subset, see DESKTOP.md: no files, shared memory, zlib, animation or Unicode placeholders). The Kitty keyboard protocol covers only its disambiguate flag. There is no Sixel and no complete modern terminal query support, and universal TUI compatibility is not claimed: validate your editor and shell. The TUI supports cell styling; desktop italic styling and complete font fallback remain limited.
• Remote files are transferred through CLI commands. There is no continuous bidirectional editor sync and no built-in editor: Quick Look is read-only and "Edit in $EDITOR" only types a command. Quick Look colors with syntect's bundled grammars (no Markdown rendering, no per-theme grammar tweaks). Listening ports are detected and can be opened or forwarded one by one from the Ports window, but are never forwarded automatically; a tunnel needs the same port free on this Mac and is keyed by port only, so two hosts using one port clash.
• Output search covers the retained terminal buffer, not an unlimited historical command database. No semantic command blocks, completion engine of its own (the zsh Tab menu uses zsh's completion), per-command telemetry or permanent encrypted transcript store. Secret redaction is pattern-based and best-effort: known key shapes, NAME=value for secret-looking names, --password/--token style flags, user:password@ URLs and Authorization headers are caught; a secret typed as a bare argument (mysql -phunter2) or in free text is not. Commands it catches are not written to the command history (teryon hist scrub removes older ones), and are hidden from the assistant. Another host's history is a snapshot copied with teryon hist pull HOST (newest 5000 commands); nothing syncs in the background, and the ghost suggestions use only this machine's history.
• Offline drafts are memory-only. Closing the client loses unsent drafts. A saved draft can contain multiple commands; review it before submission.
• Notifications: the daemon can push agent and long-command events to ntfy or a webhook ([notify]), and the desktop app does the same from the background, and each sink that refuses a notification or cannot be reached is tried again after 5 s, 30 s, 2 min, 10 min and 30 min before it is dropped (each sink on its own, so one that is down does not hold up or repeat the others). That is at-least-once, not exactly-once: a timeout after a sink did accept it can deliver it twice. Retries live in memory, so they are lost if the daemon restarts, at most 32 wait at once (more are dropped), and teryon doctor shows how many are waiting and how many were dropped since the daemon started (notify_waiting, notify_dropped), but not which. You can answer an agent's approval prompt from an ntfy push (reply = true, see docs/DESKTOP.md), but only Approve and Deny, only through ntfy, and anyone who can read the topic can tap the buttons; the buttons are not per-device. The screen is read to decide whether the agent still asks, so an agent whose prompt we do not recognise gets no buttons that work. There is no mobile app of our own. They need curl.
• Device handoff means detach one controller and attach another. No invitation links, separate-user RBAC, hosted collaboration, screen broadcasting or organization administration.
• The top bar shows load, memory and a heat warning for the daemon's host, with an opt-in caffeinate keep-awake and teryon wake. The Host health window graphs load and memory for the last ~30 minutes, in memory only (lost on restart). There is no per-process view, Apple GPU scheduling or GPU workload control, and wake-on-LAN only works over Ethernet to a host that is asleep, not off.
• SSH requires existing noninteractive key/agent authentication. Password onboarding and first-use host-key enrollment remain ordinary OpenSSH tasks.
• Signed and notarized .dmg/.pkg are built by hand on a Mac with scripts/release-macos.sh and attached to the GitHub Release (the signing certificates live only on that Mac). CI builds the unsigned TERYON.app (the macos-app job in release.yml, uploaded as a workflow artifact, never attached to a Release); signing and notarizing it is still done by hand. App Store submission and automatic installation of updates are not included: teryon update and the palette's "Check for updates" only say whether a newer release exists and open its page, and the daily check (check_updates) is off by default.
• Agent sandboxing (teryon sandbox, agent_sandbox = true) limits where an agent can write and hides ~/.ssh, ~/.aws, ~/.gnupg and ~/.kube; the network stays open. It guards against mistakes and leaked credentials, not against a hostile program. macOS uses sandbox-exec (deprecated by Apple but shipped); the Linux bwrap path has not been run on real hardware, and ~/.claude.json is only writable on macOS. An agent that needs to write somewhere unlisted gets "Operation not permitted" and needs --allow-write.
• Recipe restart policies are a shell loop in the pane, not a supervisor: they restart the command only (not the panes that wait on it), do not survive the shell itself exiting, and judge ready_text against the first run's output.
• To save requests, a session with no input or output for 5 seconds is polled every 250 ms (quiet_poll_ms; 0 turns it off), so output after a quiet spell can appear up to about 190 ms late. The 4x request reduction is arithmetic from the two intervals, not a measurement over a real link.

Next engineering milestones

1. Exercise the release on physical Apple Silicon hardware, including laptop sleep, mini sleep, long builds, zsh plugins, Vim/Neovim, SSH jump hosts and long-loss network conditions, and look at the desktop features added in 0.20 in a real window (pane-tree dividers, the agent Changes button, Kitty images, the update toast), which are covered by tests but have not been seen on screen.
2. Measure latency, memory and bandwidth against established tools with published reproducible workloads. A local harness exists (scripts/bench.py, BENCHMARKS.md); scripts/bench_net.py adds the interactive client over an emulated slow link (TERYON now needs about 1.2 round trips per keystroke against tmux's 1.05, and about three for a pasted line against one). Packet loss and Mosh are still missing.
3. Run an agent through teryon sandbox for a long session on macOS and Linux and widen the writable list only where real tools need it.
4. Save the pane-tree shape, and add cross-window tab dragging and multi-monitor layouts.
5. Build the macOS packages in CI without putting signing material in the repository, and decide whether the app should ever install updates itself.

See ROADMAP.md for what has shipped and what is still open.

The goal is a strong remote workspace. “Best in the world” requires evidence from real users, compatibility testing and performance measurements; it is not a release flag.

• Inline images use the iTerm2 protocol or a subset of the Kitty graphics protocol (no Sixel), draw PNG and JPEG, and assume 8×16 px cells when sizing; a daemon started before the upgrade keeps running the old code, so stop it (teryon stop --force, which ends its shells) after updating to get images or any other daemon-side feature.