The dashboard is the browser client for Cloudfield. A workspace is one repository and base branch; a session is one agent working on its own branch in its own sandbox, a container or virtual machine on the server. The dashboard shows a member's sessions, lets them launch, watch, message and review them, and holds the pages for agents, files, templates, members and settings.
It is one static bundle served through either dashboard gateway: aether gui
on the user's machine, or aether-server --web-port over HTTPS on the
server's tailnet addresses. Next.js 16.3.4 produces the static export, React
19 + TypeScript render the client runtime, Tailwind v4 and the Radix-based
primitives in src/components/ui/ provide the components, and Zustand holds
the state. Both gateways use the shared internal/webgate API and WebSocket
surfaces; the server gateway authenticates each request with Tailscale WhoIs
and no browser token.
The visual contract is a dense developer workbench on graphite surfaces with
one teal accent: flat panes, compact controls, restrained elevation and short
token-driven motion. docs/styles.md defines the tokens, type and motion.
The gateways and their transport boundaries are documented in
docs/local-gateway.md. The same bundle serves both, gating machine-local
surfaces on the capabilities descriptor while keeping shared Files,
configuration, runs and terminal surfaces available through either transport.
This guide describes the dashboard's routes, store and components.
Runtime boundary and commands
src/app/page.tsx is a minimal Next App Router page. It loads
src/app/client-runtime.tsx, which is a client component that dynamically
imports src/App.tsx with ssr: false. This boundary keeps the browser-only
store, WebSocket, xterm and Electron bridge out of static prerendering. Next
still emits the document, CSS, fonts and JavaScript assets; the existing
client-side registry and in-memory navigate() state remain the dashboard's
navigation model. Next does not run in production.
make dashboard # Bun install, then Node 22+ and next build (from repo root)
make build # dashboard export, then the Go binaries
cd web && bun run dev -- --port 3000 --hostname 127.0.0.1
cd web && bun run test # vitest
cd web && bun run typecheck # tsc --noEmitbun run dev starts dev-server.mjs, the development-only Node loopback
server. It defaults to 127.0.0.1:3000, accepts --port/-p and
--hostname/-H, and uses AETHER_DASHBOARD as its gateway target. The
target may be a local aether gui URL or a server-hosted HTTPS dashboard;
local targets also proxy /local, while both targets proxy /api and /ws
with WebSocket support. The proxy preserves the browser Host and Origin
headers so the shared gateway remains the WebSocket origin boundary. Other
requests and Next HMR upgrades go to Next's development handler. The Next
Node inspector attach endpoint is unavailable through this server.
For a local gateway, run it and start the dev server in separate terminals.
The local gateway prints a tokened URL; copy its token query value onto the
dev URL:
# terminal 1
aether gui --port 8080 --url
# terminal 2
cd web && AETHER_DASHBOARD=http://127.0.0.1:8080 \
bun run dev -- --port 3000 --hostname 127.0.0.1
# open http://127.0.0.1:3000/?token=<token-from-aether-gui>The client moves ?token= into sessionStorage under aether.token, removes
only that query parameter from the address bar, and sends the value as a
Bearer token on HTTP or a token query parameter on WebSockets. The token is
minted per aether gui process and stops working when that process exits.
When AETHER_DASHBOARD points at the server gateway instead, the browser
sends no token: Tailscale WhoIs identifies the phone or development browser
on every request.
The address carries the route (see URL state and local-gateway.md).
Node 22+ is required for a hand-run dashboard build. The complete contributor toolchain and the optional desktop installer workflow are in CONTRIBUTING.md.
Testing on a phone
The shipped phone path is the server-hosted gateway, checked by hand as Testing on a real phone describes.
For a contributor's loop against a dashboard build that is not embedded in a
server yet, use the development server as a LAN-facing proxy to a local
aether gui:
# terminal 1, on the computer the phone will reach
aether gui --port 8080 --url
# terminal 2, with <lan-ip> that computer's address on the phone's network
cd web && AETHER_DASHBOARD=http://127.0.0.1:8080 \
bun run dev -- --port 3000 --hostname <lan-ip>
# on the phone: http://<lan-ip>:3000/?token=<token-from-aether-gui>- Binding the LAN address gives up the loopback boundary for as long as the dev server runs. Every device on that network can reach a proxy in front of a gateway with the member's authority on the linked server, and the local bearer token is the authentication: it travels in clear over HTTP, sits in the URL and stays in the phone's history. Use a network you trust, and stop the dev server when the session ends. The shipped boundary is the loopback rule in security.md; this is a development-time exception a contributor opts into by hand.
--hostnamehas to be the address typed on the phone. Next's development server permits only localhost and the hostname it was started on; any other origin needsallowedDevOriginsinweb/next.config.ts.- The token is minted per
aether guiprocess, and the phone needs that one. Nothing else authenticates the local development proxy. - A tunnel or proxy in front of this must preserve
HostandOrigin. One that rewritesHostbreaks every WebSocket - the terminal, the event feed and the attach stream - while plain HTTP keeps working, which makes for a confusing half-broken dashboard. - This serves the Next development build over plain HTTP, not the static export the binary embeds, and it needs the computer awake and on the same network. It is a contributor's loop, not the shipped phone path.
Automated phone coverage is the mobile Playwright project, described in
testing.md.
Build pipeline and the embed
web/next.config.ts sets output: 'export' and distDir: 'dist' outside
development. next build therefore writes a static web/dist artifact:
HTML, _next assets, CSS and copied public files. There is no production Next
server or Node process in the shipped dashboard.
web/embed.go embeds web/dist with //go:embed all:dist, which fails to
compile against an empty directory. The build output is not committed, so the
invariant is kept by two placeholder files:
web/dist/.gitkeepis committed so a clean checkout compiles the Go server before anyone has run the web build.web/public/.gitkeepis copied intodistby every Next build, so emptying the output directory never breaks the next Go build.
.gitignore ignores generated web/dist and Next metadata while retaining
web/dist/.gitkeep. A binary built without running the web build serves the
gateway's "dashboard not built" response rather than a blank page.
The web app manifest
web/src/app/manifest.ts is a Next metadata file, so the export writes
/manifest.webmanifest and links it from the page. A static export refuses to
collect a metadata route that has not declared itself static, which is what the
export const dynamic = 'force-static' in it is for.
It declares display: standalone and start_url: '/', and names four icons
from web/public/icons/: 192px and 512px in both any and maskable. 192
and 512 are the pair Chrome and MDN document; what the installability check
enforces is lower - one any icon of at least 144px - so shipping both
documented sizes is belt and braces. Installing does not depend on a service
worker: Chromium's installability check no longer looks for one, and the post
announcing the removal
(update-install-criteria)
scopes it to installing "from the menu, since version 108 on mobile and 112 on
Desktop". The one that ships, web/public/sw.js, exists for
push notifications and has no fetch handler: the
dashboard is never cached, because it lives inside the server binary and has
to change with it.
Both mobile browsers read the manifest. Safari has since iOS 11.3
(display, name, short_name, start_url, scope), with theme_color
since 15 and icons since 15.4, so an iPhone's standalone window comes from
the manifest, not from the layout's Apple meta tags. Those tags cover what a
manifest cannot say: the status bar style, which needs
apple-mobile-web-app-capable spelled out by hand because Next 16 emits only
the unprefixed mobile-web-app-capable. web/public/icons/apple-touch-icon.png
stays because Safari prefers it over the manifest icons.
The manifest's theme_color and the layout's viewport themeColor both read
web/src/app/theme-color.ts and take the dark value, the default theme;
ThemeEffect switches the page's theme-color meta to the light value when
the member picks light. background_color is the separate
iconBackground from that module, #0d1424, the navy tile of the Cloudfield
icons: an installed app's splash centres an icon on it, and any other value
would leave the icon's tile showing as a square. The splash changes to the
dashboard's own --canvas as the SPA paints over it.
The icons in web/public/icons/ are the Cloudfield logo set's PNG renders,
copied unchanged from public/cloudfield/png/ in the website repository
3xDevOps/aether-web: icon-*.png and apple-touch-icon.png are the square,
full-bleed icon, icon-maskable-*.png keep the mark inside the 80% safe zone,
and favicon-16.png, favicon-32.png and favicon-48.png are the small
drawings the layout links as rel="icon". The header logo and tile, the splash
mark and the session overview's mask are the set's SVG files from
public/cloudfield/, in web/public/. python3 scripts/make-icons.py draws
only the desktop app's icons and the Play feature graphic, from
web/public/aether-mark.png. The Android app's icons come from
scripts/android-icons.py (CONTRIBUTING.md).
CI installs Bun with oven-sh/setup-bun (version pinned in
web/.bun-version) in jobs that run make build or make release-binaries,
plus a dashboard job that typechecks and tests the SPA on its own.
The three extension seams
Views and state are added without editing the shell.
Route registry (src/routes/registry.ts). A route file calls
registerRoute('board', Board) at module scope; src/routes/index.ts imports
it once for that side effect. The center view looks the current route up by
name and renders it with route.params. Navigation is a store action -
navigate('run', { runId, view: 'terminal' }) - rather than a URL router:
Next supplies the document and static assets, while the dashboard remains one
client screen and every surface uses the same action. The route is mirrored
in the address bar (see URL state).
Store slices (src/store/). One Zustand store composed of slice creators,
one file each (server, agent-models, workspaces, runs, members, env-terminal,
terminal, board, palette, presence, cost, timeline,
diff, files, collaboration, local, messages,
sessions, ui). A new feature adds a slice file and one spread in
createRootStore. Slices are typed against the whole root state, so a slice
may read another's data. Only view preferences and local progress (theme,
text size, sidebar width and collapse state, dock height, Details open,
terminal zoom, single-key shortcuts, diff wrap, activeWorkspace, the
Mine toggle, each member's launch defaults, dismissed update versions, onboarding
progress) are persisted under the aether.ui key; persistedUi in
store/index.ts is the list that decides. Server data is always re-fetched.
Selectors return primitives or stable references. A selector that builds a
new array or object on every call re-renders its component on every store
write, and under React 19 can loop. Lists of IDs go through useShallow
(useRunIDs(workspace) in src/store/hooks.ts); one entity is read by ID
(useRun(id)); a row asks for a boolean (selected) or its own state
(useRunPresentation(run)) rather than the whole route or run map. Derived
maps live in the reducer that changes their inputs. Session rows and board cards
are React.memo components; reducers replace only the record of the session that
changed, so an event about one session re-renders that session's row and card and
leaves the rest alone.
Relative times tick on one shared clock. <RelativeTime at>
(src/components/ui/relative-time.tsx) renders a <time> whose text comes
from timeAgo and subscribes to useClock() in src/lib/clock.ts: one
30-second interval for the whole app, running only while something
subscribes. Only the <time> re-renders on a tick, so "2 minutes ago" on a
board card, a session list row, a feed entry, the members and
devices views or the Changes Compare menu keeps moving without re-rendering
the row. compact renders compactAge instead: the same steps as timeAgo
in a few characters ("now" under a minute, then "15m", "3h", "2d", "1w",
"2mo", "1y"). A sidebar session row reads the clock itself as well, because its
accessible name carries the age. A per-second countdown, such as a queued
message's delivery (DeliveryCountdown), is its own small component and
re-renders only its text.
The messages slice holds agent mail (coord.messages.list) per workspace
or run scope, merged by message ID. A scope's list is held only while
a view that shows it is mounted (useMessageList); the last one to unmount
drops it and the messages no other list holds. Messages list oldest first;
those created at the same instant keep the order the server inserted them,
which it reports newest first. A coord.message event
carries no body, so every held scope the message belongs to re-reads its
newest page; a scope whose first read failed is held empty so it re-reads too.
coord.message.acked stamps the row. Both re-read the recipient session for its
unacked_messages.
activeWorkspace is the scope workspace surfaces read. It lives on the ui
slice and names the workspace the sidebar's session list, the board, launches,
templates, budget dialogs and the activity feed all act on. Empty means "all",
which is what the board falls back to before hydration has named one.
setActiveWorkspace carries an open workspace route along with it, so the
switcher can never say one workspace while the view beside it acts on another,
and navigate('workspace', ...) makes the workspace it opens the active scope
for the same reason.
Member configuration is account-scoped and does not require a workspace.
The last selected workspace survives reopening. Browser and server-hosted
dashboards use the aether.ui local-storage preference. The local gateway also
stores it through workspace.selection, keyed by server address and member,
because the desktop app's ephemeral port changes the browser origin on each
launch. Startup restores this value before choosing a fallback; a selection
made while startup is loading takes precedence. A failed preference read shows
the gateway's original error in a toast without blocking workspace and run
data: the current valid selection or normal fallback still applies.
Derived data (the session groups, the flat session list, the Needs you counts) lives
in src/store/selectors.ts as pure functions over a StateContext
(stateContextOf in the same file), wrapped by memoizing hooks in
src/store/hooks.ts. Selectors that build new arrays must not be passed to
useStore directly. A view that owns its own derived shape keeps it beside
the view instead (src/routes/board/selectors.ts). useRunInput combines
structured native requests and unanswered teammate
questions for the request indicator; the session's state comes from
Session state.
Slots (src/components/slots.tsx). Where a route registry is too coarse -
something belongs inside a surface another ticket owns - the surface renders
<Slot name="..." /> and contributors call
registerSlot(name, id, Component) at module scope. Registration order is
render order, id keys the render and makes a double registration an error.
The slots that exist:
| Slot | Props | Where it renders |
|---|---|---|
card:meta |
{ run } |
the session card's footer, after the owner avatar and diff counts |
Its contributors are the file-overlap chips (routes/diff/conflict-chips.tsx),
the sync badge (routes/run-sync). card:meta content renders inside
CardControls, above the card's open target, so its links and buttons stay
interactive. Keep it to one short item per contributor: a count or a word,
with details behind a popover.
Shell
src/components/shell/ is the shell: a branded navigation header above one
sidebar and one content area, with the desktop window bar above them in the
desktop app. AppShell (app-shell.tsx) mounts it once, together
with the shell-wide hosts: the command palette, the dialogs the store opens
(components/palette/dialogs.tsx: launch, message, forward, close, archive
and free), the shortcuts dialog, the updates dialog (UpdateCenter), the
connection announcer, the shell keys (useNavShortcuts), the team
refresh (useTeamRefresh) and AppBadge (lib/app-badge.ts), which sets the
installed app's icon badge to the Needs you count while push is on, in any
layout, and clears it when the shell unmounts. It does nothing in the desktop
app, which badges itself.
Sidebar
The sidebar (sidebar.tsx) is a nav named "Cloudfield", 260px wide by default
and resizable from 220px to 400px; older saved widths are clamped. Mod+B, the
Hide sidebar button in its header and Enter on its splitter hide it
completely; the content view's header then shows Open sidebar at its left
edge. Hiding or showing it hands focus to the control that reverses it. From
top to bottom:
- Workspace switcher and search. The switcher
(
workspace-switcher.tsx) shows the active workspace's name and base branch, and the total Needs you count across every workspace. Its menu lists each workspace with its own count, All workspaces (theoverviewroute), Manage workspaces and Workspace settings (the workspace page). With one workspace and noworkspace.listmethod it is a plain label. The search button opens the command palette. - New session, the only filled button in the shell, for a member who may
launch. A slanted cut splits it in two. The left half, New session (
n), slides the launch panel out of the sidebar's right edge over the view, with no scrim; clicking outside or pressing Escape slides it away to an arrow that restores it. The outside click reaches the view behind it. Close dismisses the form and its draft. The right half appears once a launch has been saved: it shows the saved agent's glyph and launches that agent, mode, model, account and fallback at once with no task and withchildren: "on", so subsessions are allowed whatever your Settings choice (quick-launch.ts). Hovering or focusing it slides out the saved choices. A Background launch needs a task, so that half opens the panel instead, as it does when the saved choices name an agent or model the account cannot use. The panel's Subsessions switch follows your Settings choice and sendschildrenonly when flipped, for that session alone; it is off and disabled for a Background session. While it is on, Subsession agents (subsession-agents.tsx) opens a menu of checkboxes, one per installed agent with its accounts under it when it has several, each with its login state; a change saves the member setting at once withchild.settingschoice, one save after another, and Settings → Subsessions shows the same menu. An account whose agents could not be listed is named, with the server's error, below the row (choices_error). - Sessions (
sidebar-runs.tsx), aregionwith three groups, Needs you, Working and Finished (see Session state), each anh2holding anaria-expandeddisclosure button, a chevron that turns a quarter and the count in aCountBadge; the count stays in the button's name. Mine matches the count badge's height on fine pointers and keeps a 44px touch target on coarse pointers. Every group starts expanded and lists all of its sessions; a group closes only when its header is pressed, and the list fades back in when the viewer reopens it (rows never glide their height, and a group that mounts with hydration does not fade). Until the first sessions arrive, six row-shaped skeletons stand in for them after ~200ms, announced as "Loading sessions". Needs you lists every workspace; a row outside the selected workspace leads with that workspace's name. Working and Finished list the selected workspace, and only the viewer's own sessions while Mine (mineOnly, persisted) in the Working header is pressed. When Mine is on and no Working sessions are visible, the same toggle stays at the top of the region so it can be turned off. When Mine hides a teammate's session and leaves the list empty, it reads "No sessions of yours." The region scrolls on its own, and while more rows sit below the fold its bottom edge fades out. The sidebar never collapses on its own at narrow widths; the splitter and⌘Bstay the reader's call. - Manage workspaces, Members and Settings, for every member.
Board through Templates live in the header instead, leaving the sidebar's
height for sessions. The current destination carries
aria-current="page"; a workspace's own page keeps Manage workspaces current. Gates come fromsrc/lib/surfaces.ts, which also feeds the palette's Navigate group; itspaletteentry (Members › Devices) is reached from the palette only, and itslinkentries (the board's Needs you; Onboarding, opened from Settings › General › Setup guide) only from a link. - One update notice row when a server, CLI or desktop update exists, for example "Server 0.5.3 is available · Update"; see Update prompts.
- Footer: the member's avatar (a neutral glyph before the computer is linked) and name and a connection dot, whose word ("Live", "Reconnecting", "Offline") is in the button's name and tooltip. Its menu holds Profile (a dialog: display name, colour, git identity and agent account sharing; see Members, devices and Profile), Keyboard shortcuts, Theme, Check for updates…, and a Team line with who is online and the spend against workspace budgets.
A session row is a 28px ListRow (44px on a coarse pointer). From the left: a
static StatusDot; the owner mark, a 6px right-pointing triangle filled
with the colour of the session's owner (member_id, not the agent account and
not the controller); the title; the row's age; the agent's monochrome glyph;
and the avatars of whoever is on the session. The age is the compact form
("15m", "3h", "2d") of the time the explorer sorts by: when a Needs you row
began waiting on the viewer, else the session's last status change (since on
the row, src/store/selectors.ts). Only a snapshot without
status_changed_at (see Session state) leaves an estimate of that
change, which counts a live session's age from its start until its next status
event. The title truncates before anything to its right does. Paused, finished and other
members' working rows recede: their title is in the muted colour.
Who is on a session is every member with a terminal or an Enhanced session
attached to it, the viewer included: the watching lists of
presence.roster, which covers every workspace (runWatchers and
runPeople in src/store/presence.ts). Their avatars stack at the row's
right edge and the age and the glyph move left to make
room; a session nobody is on reserves none. A root with subsessions shows a
Network glyph and their count before the agent glyph, and its name adds
"2 subsessions · 1 working"; its subsessions list under it. Its chevron
folds the subsessions for this browser session only; they start open, and the
first child to arrive opens with the chevron's turn animation. Folding keeps
subsessions that need you visible. The first avatar sits whole at the edge and
each one after shows from behind it, to its left. First is the
session's controller. While nobody holds control it is the last controller, if
they are still on the session. The rest follow by name. A row draws three
avatars at most: a fourth person turns the stack into two avatars and +2.
While a Needs you row shows its action the stack steps aside for it, so the
title keeps its room.
Session details. Resting a mouse on a row for 400ms opens a box docked to
the row's right edge (run-details.tsx): the whole title, the state's
reason, the workspace, the agent and mode, the branch, a root's subsession counts, when the session started, when it last changed if that is later,
its owner, and the people on it with the controller marked Controlling.
A live session nobody controls says so above them and names who had control
last, when the server knows. Moving to another row swaps the box without
the delay or the animation. The box takes no pointer events, closes when the
row is pressed, scrolled or left, and gives way to the hint of a button
inside the row. It does not open on keyboard focus, on a coarse pointer, or
under 768px, where the sidebar is a sheet. It replaces the row's native
tooltip.
The title is whole up to 120 characters, where the task fallback and the
server's provisional title stop; an agent's own longer title is cut there
(clipLabel in src/lib/status.ts). The box cannot scroll, so it lists
seven lines of people at most and ends the list with a count of the rest
("and 16 more"). Under a 120-character title, with every other part at its
tallest, that fits a 600px-tall window at the Default and Large text sizes;
Larger keeps six lines. A box still too tall for its window gives way in
order: people, a line at a time down to a bare count ("22 people"); then
the reason, to one line; then the title, to three.
The row's accessible name starts with the state word, then the workspace when it is another one, the title, the reason, the age in words, whose session it is, who controls it and who else is watching ("Working · rewrite the checkout flow · Agent working · 15 minutes ago · Bob's session · Vera controls · you watching"). Its description is the exact time the age counts from.
A Needs you row offers the condition's primary action on hover, focus and a
coarse pointer, the same one its board card shows (see Board):
Reply opens the session's Chat view with the composer focused, and every
other action goes to the view the condition names. Session rows share one tab stop (roving tabindex);
Arrow keys, Home and End move within them. j and k move from anywhere (starting at the open
session), and u opens the next session that needs you, oldest first.
A Finished or Failed row does not recede while no member has opened its session
since it finished (finish_unopened, see Session state): its title
keeps the text colour and its accessible name says "Not opened yet" before
the age. A finished subsession listed under its parent follows the same rule. Once
any member opens the session, the row recedes in every member's dashboard.
Every subsession in the list is indented beneath its parent and joined to it
by tree connectors: a vertical trunk under the parent's status dot and a
horizontal wire into each subsession row
(Styles). A subsession that finished
with nothing left for a person leaves the list: one that reported success
(Finished: reported to its parent) or ended completed, merged or
abandoned, such as one its parent stopped. Its parent's last nested line
counts them (3 finished, outside the chevron's count) and lists them in place until Hide finished,
for this browser session only; the one that is open lists there regardless.
The parent's count and its Details (Subsessions) still include them. One that failed, was interrupted or
needs you stays listed, and a finished one returns while it works again. The
session stays open either way (settled in src/store/selectors.ts). Mine also filters
these subsessions under Working and Finished; Needs you keeps the whole tree
visible. Selecting a session row opens that session, from anywhere on the row
outside its buttons. The whole tree sits in
Needs you while any member needs the viewer, but only those waiting sessions
contribute to that group's count. Relationships come from the session snapshot's
parent_run_id, not task text.
App header
top-bar.tsx is a banner at every window width, padded by --safe-top.
Its first row shows the Cloudfield logo on the left, or the 32px favicon tile when
the destinations do not all fit beside the logo, then Board,
Activity, Insights, Memory, Files, Environment, Agents and
Templates in nav "Main navigation". These use the sidebar's ListRow
styling and current-page selection. A ResizeObserver measures the row and
its buttons, including font and text-size changes. Destinations that do not
fit move into More navigation, a click-to-open menu; Board
never moves into it. The current page's selection is one SlidingIndicator
that glides between buttons; it sits beside the list, not in it, so the
overflow measuring still counts only buttons, and it hides while the current
page is in More navigation. Gateway capability gates still apply. Hidden buttons
are inert and excluded from the accessibility tree.
Under 768px the header is one 48px row: the view's title and Search. On
a session page the title is "Session", because the session header under it
already shows the session's title. A connection problem is one line under the
row. On a phone the view's own header keeps only its actions, and its h1
stays for screen readers. The header's measured bottom edge sets
--app-header-bottom for the command palette's position and height limit.
Navigation moves to the phone tab bar.
Phone layout
Below 768px (mobileScreen in src/lib/breakpoints.ts) the shell adds a
bottom tab bar, phone-tab-bar.tsx, a nav named "Main navigation". Desktop
is unchanged. The tabs are at least 44px square, and the bar pads itself by
the bottom and side safe-area insets, so main does not pad the bottom on a
phone. Its measured height sets --phone-tabs-height, which keeps toasts 8px
above it. On a touch screen the bar hides while the soft keyboard is up: a
text field other than the terminal's has focus and the visible viewport is
more than 150px shorter than the tallest it has been at this width. Android's
Back and iOS's Done close the keyboard without a blur, so focus alone would
keep the bar hidden. With more than one workspace the header shows the active
one's name, muted, after the title.
| Tab | Opens |
|---|---|
| Needs you | the needs-you route; its badge counts what asks you |
| Sessions | the sessions route: List, the sidebar's session list at full width, or Lanes (phone lanes), chosen by a Sessions view switch in the top bar beside Search; the choice persists as sessionsLanes. Current on a session, the board and All workspaces too |
| New | the launch sheet; named New session, hidden if you cannot launch |
| Assistant | the assistant, full screen, with the desktop button's dot and name |
| More | a bottom sheet, a dialog named "More"; the tab is More pages |
On a phone the Sessions list is regrouped by attention.list (byAttention
in src/routes/needs-you/attention.ts): its Needs you group has the badge's
count and order, and a session the server lists as finished moves to the
review group, newest change first. A session only the dashboard's copy of the
rule puts in Needs you stays listed, last, and is not counted.
A phone that opens the dashboard with no run or page in the address lands
on Needs you (initialRoute in src/lib/url-state.ts; Back to such an
address does too), or on onboarding on a
first visit, as the board does on desktop. Every other link still opens its
own page. The board is in More, and on a phone its address carries
page=board, so a reload stays on it. A gateway without attention.list,
whether it does not list the method or answers -32601 for it, has no Needs
you tab, and its landing page redirects to the board. The Sessions route
exists only on a phone; a wider window redirects it to the board, whose
sidebar has the same list.
A phone screen has one filled button. A page whose own action is filled calls
useHeaderPrimary(shown) (src/store/hooks.ts) while that action shows; the
ui slice counts the holders in headerPrimaries, and while the count is
above zero the New tab drops its filled pill. The holders are a session
header with a primary action, Environment's Open or Save environment,
onboarding, Files with a file open and the Changes view's Publish….
More holds the workspace switcher, whose amber counts come from
attention.list too, every page the desktop header and sidebar link to
(Board, Activity, Insights, Memory, Files, Environment, Agents, Templates,
Members, Settings, Devices, Manage workspaces) in a list that scrolls, the
update notice and the profile footer. A tap outside, Escape or any navigation
closes it, and navigation moves focus to the new view's heading. Mod+B opens
and closes it; every other shell key stands down while it is open.
Needs you (src/routes/needs-you/) reads the server's attention.list
(local-gateway.md), not
the dashboard's copy of the rule. It reads it again within 250ms of any change
to a session's status, state, review, outcome flag, pause, requests, room
messages and their decisions, or controller, after a reconnect, and each time
the page opens. One read runs at a time; a change during it asks for one more.
A different member or server clears the list. While the page shows a saved
snapshot and the list has not been read, Needs you lists the saved sessions the
dashboard's own rule puts in Needs you, to open but not answer. A failed read
shows its own error unless the saved-state banner already shows one. The badge counts the same list's
requests, plus the devices waiting for approval and the merge proposals to the
viewer, as the sidebar's Needs you does; their board cards (DeviceCard,
MergeProposalCard) sit above the session cards. Cards are ranked by kind in
the order the server checks them (needsYouConditions in
src/lib/needs-you.ts): permission, question, queued message, room question,
disconnected, blocked, needs input, failed, and a kind this dashboard does not
know last. Within a kind the server's order holds, oldest first. Each card is
a RequestCard. Its title, at most two lines, opens the session's view the
condition names; the request's detail is clamped to five lines with Show
more. Then comes its inline answer:
- A permission with
allow_onceandreject_onceoptions shows Deny and a second half. A sudo request's title is the whole command, so the second half is Approve (the session's ownDecisionButtons). An agent's tool call can be a file edit or a plan thatattention.listdoes not carry, so its second half is Review, which opens the session where the change is shown and approved. Deny and Approve sendrun.input.respondwith the request's id and that option, so a tap that lands after the request changed decides nothing else. Always is not offered. A Standard session's permission has no options and opens the terminal instead. - An Enhanced session's question shows its form and its options, answered the same way. A link question opens the session.
- A turn that ended asking (
needs input, the condition's Reply) shows Reply…, which opens a focused text field; Send orMod+Entersendsrun.inject. The field scrolls into view above the keyboard, and the list pads by--keyboard-insetfor iOS, whose keyboard leaves the layout tall. A room question replies withrun.room.post, correlated to the question. A retry of the same text reuses its idempotency key; a reply not sent or uncertain keeps its draft. - Everything else has one button that opens the session.
Setup notices the board shows, such as letting agents use Docker, sit above
the cards. While the first read is in flight two skeleton cards show; a failed
read is a failed-tone callout with the server's error and Retry, and the
list and badge keep their last values. already_answered shows "Already
answered: an earlier answer won". Once the server takes an answer the card
says Answered until the list drops the request, so a second tap is never
sent. While another member controls the session, a permission or question card
names them and offers only the session, because run.input.respond would
refuse with -32003. Any other refusal shows the server's error on the card.
Below the cards, Finished: review the result lists the ready items as
plain rows. They never count toward the badge and have no Mark complete;
opening one opens the session.
Phone session
On a phone a session opens full screen: the run route renders no top bar
and the tab bar hides, so the shell pads the top safe area (above the
reconnect banner) and main the bottom and side ones.
The header (routes/run/phone-header.tsx) is one 48px row: Back, the
title with its protection lock, a state line (status dot, state, agent and
mode), the header's primary action when there is one, and More. Under it
the tabs Chat, Terminal and Changes fill a 44px row; a Standard
session orders them Terminal, Chat, Changes. Changes carries
the muted +N −M of the latest snapshot, unless it was truncated, and drops
it below 400px while a fourth tab shows. The pull request, with its checks,
feedback and Watch PR, would crowd the tabs, so it sits in a 44px row of
its own under them on the Changes tab only.
More opens with a Views group (Trace, Files, Browser, Session details, Workflow, Search…, Assistant), then the session's commands, Captures and Raw events. A view opened from there joins the tabs while it shows. The views stay reachable while a command runs. Close, Stop and Delete are the same commands, with the same confirmations, as on desktop.
Without a view in the address a phone opens the session's last chosen view,
or its default when none was chosen. A link that names a view still opens it.
A tab switch replaces the history entry instead of pushing one. Each history
entry records its depth, and an entry of a session records the depth at which that session
was opened, carried across the session's own entries, a subagent's included
(pushedEntry and sessionEntry in src/lib/url-state.ts; a
notification's entry records them too). Back steps back to the entry
below that one, so it leaves the session in one step. A session opened by a
link or a reload has no app page below it, and Back replaces it with
Sessions.
While the soft keyboard is up, the header folds to one 44px row: the title,
the status dot and, from 400px wide, the state's name. The tabs (kept
mounted but visually hidden, since each view's panel is labelled by its
tab), the wait line, the lineage line and the
multiplayer strip leave. The keyboard counts as up
on a touch screen while a text field, the composer or the terminal's input,
has focus and the visible viewport is more than 150px shorter than the
tallest it has been at that width (useKeyboardUp in
src/lib/keyboard-inset.ts, which the tab bar uses too). Android's Back and
iOS's Done close the keyboard without a blur, so focus alone is not enough.
On a phone the strip shows only while someone else watches, another member
or another of your tabs holds control, the session is not yours, or control,
presence or the stream failed (useSharedPresence). Only the owner takes
free control implicitly, by sending a message or changing a model, mode or
effort option. What waits for control runs in the order it was asked, each after the one before settles, so an
option chosen before a send reaches the agent first. An option change that does not
get control within 10 seconds says so at the composer. Details lists the people. A hidden tab bar removes
--phone-tabs-height, so toasts fall back to the bottom safe area.
The Chat composer is the desktop ComposerBox. It pads by
--keyboard-inset (src/lib/keyboard-inset.ts) less the bottom safe area
that main already pads, so it sits on an iOS keyboard. While a request is
open, the request card holds the one filled button: its answers fill the
card's width, and on Chat the header's action and the composer's
Interrupt are outlined. A session that is still loading on a phone shows
Back to sessions.
Assistant panel
The assistant is a persistent conversation with an agent running in the
member's own environment; the server side is
the assistant plan. AssistantPanel
(components/assistant/panel.tsx) is mounted by AppShell as a flex sibling
after main, so it is available on every route, onboarding included. It
renders nothing unless the server lists assistant.status and the member can
launch sessions (useAssistantAvailable); the same check gates every entry point.
- Desktop, docked: an
asidenamed "Assistant", 400px by default and resizable from 320px to 640px by aseparatoron its left edge (same keys as the sidebar's, mirrored: Left grows). Close assistant returns focus to the Assistant button. The saved width is a preference: the rendered width is capped to what the window leaves after the sidebar andminReadableWidth(560px,lib/breakpoints.ts) ofmain. - Desktop, floating: below 320px of that room, the same
asidefloats over the right edge ofmain, raised by a shadow. Its width is the saved width, capped so at least 240px ofmain(uncoveredWidth) stays uncovered on its left, but never below 320px. It has no backdrop, no focus trap and no resize handle, so the session keeps its full width, and the part the panel does not cover stays interactive.Escinside it, outside an IME composition, closes it and returns focus to the Assistant button, unless something inside it, such as the New conversation confirmation, handled the key first; so doesMod+Shift+Spacefrom anywhere. Crossing between docked and floating restyles the oneasiderather than remounting it, so the draft, the focused composer and the transcript's scroll survive. - Phone: a full-screen
dialognamed "Assistant", over the tab bar, with square corners and, with a touch screen, a 16px header inset. Its composer sits at the bottom, above the soft keyboard (--keyboard-inset). - Header: an
h2, because the view beside it owns the page'sh1. It takes the session header's height on a session and the view header's elsewhere, so the two seams line up. It holds the agent and state, Actions, New conversation (confirms, thenassistant.reset) and Close assistant. Whileauto_approveis on, a line under it says the assistant acts without asking, with Change in Settings. - Body: by
assistant.statusstate.setuplists each agent with its reason, and Sign in opensAssistantSignInin place: a terminal on/ws/terminal?assistant_login=<agent>;failedshows the server's error above the transcript with Retry (assistant.start). Otherwise the transcript (role="log"), which reuses the session Session'sTimelineRowanduseFlatRows, with the Session's open blocks, and the constant row context idassistant, and the composer (Enter sends, Shift+Enter inserts a newline,Mod+Enteralso sends; Stop replaces Send while a turn runs and reads Stopping… whileassistant.cancelis in flight, so a double click cancels once and an agent that ignores it can be stopped again; the call aborts after 10 seconds withassistant.cancel got no answer within 10 seconds). An empty conversation leads withAssistantAccountCheck(assistant.account, shown when the server lists it), the same-account line, which Settings > Assistant > Sign-in also shows under each ready agent, and offers four example prompts that fill the composer, led by the page's own: a failed session offers Fix this, one that needs you or waits Why is this stuck?, one with an open pull request (useOpenPullRequest) Review and merge when checks pass; the board What needs me?. A session or pull request prompt attaches its target throughaskAssistant, so it reaches the agent with page sharing off. Harness permission and question prompts render as the Chat view's request cards, answered withassistant.answer; each pending confirmation renders as a card titled with the summary, the method as its source line, a Details section with the exact params (three, then N more), or forrun.launcha What starts list (components/assistant/launch-summary.tsx; the title then stops before the quoted task) of kind, workspace, agent with model and mode, effort when set, permission tier (defaultwhen unset), account (Yoursor<name>'s, shared with you), fallback, task, and how the member hears back, a relative deadline with a bar draining toward it, Decline and Approve (assistant.confirm). Confirmations stack above the harness prompts in one 40dvh scroll. A card leaves only when aconfirmationsframe stops listing it. A card's footer is not sticky: the dock (65dvh with an empty conversation, whose suggestion chips it hides, else 40dvh, 50dvh on tall screens) scrolls the whole card, so its actions come after every row they approve, and rows have no scroll of their own. A card withruleadds, underOr save a rule:, a secondary button labeled withrule.wording(assistant.confirmwithalways: true), marked with an accent left rule andYou approved this kind three times in a row.whenrule.suggested, and, whileauto_approveis off, Approve everything from now on: it approves the card, then sets the store'sassistantConfirmAutoApprove, which opens the panel's Let the assistant act without asking? confirm (AutoApproveConfirmincomponents/assistant/approval-choice.tsx). Whileauto_approveis off a card withoutrulelinks Skip these cards… to Settings > Assistant; a card withother_membersays that member (other_owner) owns the session, so it asks even with auto-approval on; for a launch it says their account pays. - Action cards (
components/assistant/action-card.tsx,lib/assistant-actions.ts):assistantViewtakes each Cloudfield tool call out of its step block as a card: one whosetool_nameends in anaether_*tool (Claude Code'smcp__aether__aether_launch_session, or the bare name), or a Codex call titledmcp.aether.aether_*, whose{server, tool, arguments}input and{result, error}output are unwrapped from the call's latest snapshot. The block splits at each call, so the card sits where the call ran; a part left with no work becomes the rows its prose and notices would have been. The card names the verb and target from the inputs and the store's names ("Launched session on api with Claude Code", "Messaged run fix-login", "Merged PR #42"; a session is named byrunLabel; a tool with several actions, such asaether_session_lifecycle, takes its verb and the method its card waits on from itsactioninput), a state (Running,Done,Failed,You declined,No answer in 10 minutes,Withdrawn: the turn ended before you answered,Did not finish: the turn ended firstfor a call still open when its turn ended, approved or not, orNot confirmed: check status before retryingfor anaether_pr_createwhose result sayswrite: "pending") withapproved by you,auto-approvedorapproved by your rule <id>(a record withapproval: "rule"and itsrule_id), and its time. A call waiting for approval is one line that points at the approval card in the composer dock, and the live line under it is dropped. A failure shows the server's error verbatim; a declined, expired or withdrawn card keeps the error for Details. A launch receipt, when the result has one (result.launch: the account byaccessown, shared or other,fell back fromitsrequested_account,no fallbackfor policyoffor theorderedaccounts) or a watch result gets one more line; a done launch without a receipt gets the same line from the returned session and its inputs (kind, workspace, agent and model, the account only when the call named one,no fallback). A done launch whose session is still active reads Working in the background and says how the member hears back;useBackground, shared with the Actions list, reads the launched session from the store. The header calls the assistant's own turn Generating…. The target comes from the result'slinkorurl: a dashboard link (?run=<id>, a watch's settings link) opens in the app whatever its host, and any otherhttp(s)address, such as a pull request, opens in a new tab. Without one it comes from the created ids, then fromrun_idorworkspace_idin the inputs. A session or workspace the hydrated store no longer holds reads "This session no longer exists" and has no link; a launch's own session never does, since the transcript can show it before the store hears of it. Failed, declined, expired and unfinished cards offer Retry, which adds `Retry:` under any text in the composer and focuses it without sending. **Details** shows the input and result, and first reads a cut-down item whole with `assistant.item`, as does an expanded read. An `aether_*` tool without words of its own shows its name and inputs. The card is not a tab stop; Tab reaches its link, Retry and Details buttons. Consecutive read tools (and any `aether_list_*` or `aether_get_*`) fold into one quiet line, "Read 3 sessions and 1 workspace list", that expands to each read. Expansion lives in `expandedRows` under `assistant`. - Outcome: a notice carrying an action record (
notice.action, the server'sAssistantAction) decides the state. Records with the sameaction.idreplace earlier ones. Records carry no tool call id, so a record goes to the card already holding itsaction.id, or else to an unclaimed call of the same method whose input names norun_idorworkspace_idother than the record's target: the oldest such call in the newest block that has one, so identical calls of one block take their records in turn and an older block's unrecorded call does not take a new record. An older server'sApproved:note names its session only in the summary: it goes to the one unclaimed call of its method, or to the one whoserun_idthe summary names, and otherwise stays a row. Without a record, the state comes from the tool call's status, adeclined,did not answer withinorended before the member answerederror, a pending confirmation of the call's method, and theApproved:orAuto-approved:note. A matched notice is folded into its card instead of showing as a row. - Actions (
components/assistant/action-history.tsx): a header button opening a popover that reads the transcript only while open. It lists this conversation's cards (not reads) newest first with outcome, target and time, all read from the loaded transcript. While earlier messages are not loaded it says so and offers Show earlier actions, which loads them as Show earlier messages does. Focus starts on the newest entry. Up, Down, Home and End move, and Enter opens the target and closes the popover. - Setup question (
ApprovalChoiceincomponents/assistant/approval-choice.tsx): when the status hasapproval_chosen: falseand the state is notfailed(a failed status carries no stored settings; absent never asks), a notice above the composer asks How should your assistant act? Ask before acting and Act without asking callassistant.settingswithauto_approvefalse or true; the second shows the auto-approval warning under its button, so it opens no dialog. It scrolls past 40% of the viewport height, and the auto-approval suggestion waits until it is answered. The answer's settings replace the status, which drops the notice, unless another member signed in meanwhile; a refusal shows under the buttons. - Auto-approval suggestion (
components/assistant/suggestion.tsx): when the status hassuggest_auto_approve, the state isidle, no turn runs, no confirmation or harness prompt waits and the conversation has items, a notice between the transcript and the composer asks Skip approval cards for the assistant? It says what auto-approval passes, that each action is still noted, that read text could steer the assistant, and that messaging or stopping another member's session still asks. It scrolls past 40% of the viewport height, so the composer stays visible. Its three equal buttons callassistant.settings: Turn on auto-approval (auto_approve: true, no second dialog: the notice is the warning), Not now (suggestion: "later") and Don't suggest again (suggestion: "never"). Each leaves a one-line answer, focused, with a Settings → Assistant link; a Not now answered withsuggestion_offsays it won't be suggested again. The line clears at the next turn or a new conversation, and is dropped if another member signed in before the answer arrived. A refusal stays in the notice, focused. The server decides when the suggestion is due; see assistant.md. These links, Skip these cards… and the Acts without asking line's Change in Settings close the panel when it is a sheet, and leave a docked panel open.
State lives in store/assistant.ts. The transcript is the AcpSession under
acpSessions.assistant, built by the session reducers and kept out of runs, so
it never reaches the board, sidebar or palette. The slice holds the status,
the confirmation set, the composer draft and the generation a new
conversation bumps; assistantOpen and assistantWidth persist.
store/assistant-stream.ts connects /ws/assistant through
connectSessionStream with the assistant endpoint. AssistantPanel reads
assistant.status once on load, as soon as hydration has set the identity
(useIdentityKnown in store/hooks.ts; useAgentList waits for it too, so
neither read is sent under no identity and repeated), and on each open, then
connects unless the
state is setup. It stays connected with the panel closed
only while the state is running, installing or starting, or a confirmation or a
harness prompt is pending. After that, status frames carry the state and the
whole confirmation set, so the UI makes no further status calls. A truncated
item in the transcript is read with assistant.item. Each pending
confirmation or prompt puts a dot on the Assistant button, named "Assistant, N
requests waiting". A confirmation card lists its params as labelled rows
(workspace_id reads "Workspace"; task and message text stay whole), and its
buttons stay disabled once answered until a status frame removes the card. Only
A prompt being sent and its idempotency key live in the slice next to the
draft, so reopening the panel retries under the same key; a changed draft, a
success or a new conversation clears them. assistantOpen on desktop persists; a phone never reopens the sheet on load.
Closing the panel unmounts it. The transcript keeps where the reader left it,
including virtua's measured row sizes, in a module-level record keyed by
member, conversation generation, epoch, history generation and first row,
and reopening the same conversation returns there. Earlier messages loaded
while the panel was closed change the first row, so the transcript starts at
the bottom instead of at a stale offset. A transcript pinned to the bottom stays
pinned, so it follows output that arrived while the panel was closed. A
different conversation starts at the bottom.
store/view-context.ts builds the view context (see
assistant.md): the route's ids, the session view
RunFrame reports through setShownRunView, the active file only on the
Files page or its own session's Files view, and viewHistory, the last 8 pages,
recorded only while sharing is on and never persisted. While the panel is
open and sharing is on, syncViewContext sends syncedViewContext, the
page the chips show, as assistant.view at most once a second when it
changed, one call at a time, retrying a failed one with backoff and sending
it again after each prompt. While the draft's page is removed it sends a
context without route at once, which makes the server forget the page, and
Send awaits that call (flushViewSync, at most 10 seconds, then
assistant.view got no answer within 10 seconds) before assistant.prompt; while a
navigation conflict is unanswered it sends nothing; after where you
started it keeps the pinned page until the prompt is sent.
A prompt carries draftViewContext instead. The first character of a draft,
or an entry point, sets assistantPin to the page then shown; while
trackViewContext runs it follows the member's later views and open file on
the same session or page. Once they move to another,
draftConflict names it and ContextChips
(components/assistant/context-chips.tsx) shows You moved to X. Ask
about: with the new page and Y (where you started); Send with that
unanswered focuses the first choice and sends nothing. Emptying the draft,
with nothing attached, drops the pin. assistantAttachments (at most 6) are
what an entry point pointed the draft at; navigation never changes them,
and sharing does not gate them. Past the cap the oldest go and
assistantError names them. The chips above the composer are built from
nextViewContext, so they show exactly what is sent: the page (unless
removed or unshared, and folded into a session attachment that names
the same page, whose remove button then removes both) and each attachment,
labelled from the store
(components/assistant/labels.ts); each chip's remove button is its tab stop
and also takes Delete or Backspace. Add this page undoes a removed page.
Inspect opens a popover with the Share the page I am on with the
assistant checkbox, a list of every field the next message sends, and
Raw JSON, the exact payload (nextViewContext).
assistantAttempt holds the prompt's text, key, context and chips; changing
the text, any chip or the share choice drops it, and a retry of the same text
reuses both. When assistant.prompt succeeds, settleAssistantSend clears
the sent text and chips and keeps only chips added while it was in flight,
so a chip edit during the send cannot leave the sent message to be sent
again. assistant.prompt aborts after 60 seconds with assistant.prompt got no answer within 60 seconds, keeping the draft and its key for a retry. A new key comes from promptKey: while another tab's send of
the same text and context under the same member is still in flight (at
most 10 seconds), it reuses that tab's key, so the server runs the prompt
once; settlePromptKey clears the record when a send settles, so a second
"yes" after the agent asks again is a new message. Only a SHA-256 of the
draft is stored, in localStorage under aether.assistant.sent. Over plain
HTTP, where crypto.subtle and crypto.randomUUID are missing, keys fall
back to a timestamp and random suffix and tabs do not share them. The
assistant reads saved launch choices from the server through
aether_launch_options, never from the page. Client
fit and sendableAttachment trim as the server does (recent pages, then
the open file, then the last attachments, counting bytes as Go's
json.Marshal writes them; a check name over 128 bytes or with a control or
format character is dropped), so Inspect never shows what the server
drops. A draft or chip changed while the key is being made cancels that
send. The send guard and Stop read assistantSending
and assistantStopping from getState, so two presses before a render send
one call. assistantError keeps the last failure across closing the panel
until the draft changes, the next send or a new conversation.
askAssistant({draft, attachments, page}) in store/assistant.ts opens the
panel, adds the attachments, fills the draft unless the member has one,
sets assistantFocus so the composer takes focus once, and never sends. AskAssistantButton
(components/assistant/ask.tsx) calls it and renders nothing for a member
who cannot use the assistant. It backs Fix this and Ask the
assistant on the session failure callout, the button beside each failing
check pill, the button beside an open pull request's number in the session
header; the session menu
and palette offer Ask the assistant to fix this session for a failed session and
Ask the assistant why this is stuck for one that needs you or waits;
the palette's Ask about this page pins the current page.
The share setting itself is assistant.settings {share_view};
assistantShareChoice holds the choice until the server saves it, sending
one save at a time so an older choice never lands after a newer one,
retrying with backoff from 3 seconds up to a minute, stopping on -32004 or
-32602, or once another member signs in (resetAssistant drops the
choice). status.share_view carries it to other tabs and devices.
When the assistant launches or messages a session for the member, the server
watches it (assistant watches) and publishes
assistant.notice on /ws/events as the session finishes or needs input or
attention; watch_id names the watch. The server streams it only to the
member named by member_id. applyAssistantNotice (store/assistant-notice.ts) raises
a toast with an Open session action (warning style for needs_*, plain for
finished) and adds one to assistantNotices. The Assistant button counts
those updates beside the waiting requests, named "Assistant, 1 request
waiting, 2 updates", and opening the panel clears them. The stream does not
mark replayed events, so a notice older than 30 seconds on the server's clock (the offset read from server.info) counts toward the
badge but raises no toast. The desktop app shows the same notice as an OS
notification that opens the session on click (desktop/notify.js), and skips a needs_attention one
when a needs-you notification for the same session fired within five
seconds. A phone gets the web push the server sends for the same notice.
Entry points: the Assistant button (components/assistant/button.tsx, one
component mounted in one place at a time: the sidebar's New session row (a
secondary icon button to its right, which keeps the workspace switcher's
room), or the top bar's first row while the sidebar is hidden; under 768px the
Assistant tab of the phone tab bar replaces it; keeping
it out of the top bar's row leaves that row to the header destinations),
Mod+Shift+Space, the palette's Ask Cloudfield, a secondary Ask
Cloudfield in the board's empty states, and Stuck? Ask Cloudfield under
each onboarding step.
Landmarks and headers
Landmarks. The skip link "Skip to content" is the first tab stop; the
header navigation is nav "Main navigation"; the sidebar is nav "Cloudfield"
containing region "Sessions"; the content is the one main, with one h1 per
view from PaneHeader (tabIndex=-1). After a route
change focus moves to that h1, unless the view took focus for itself. Unit
and end-to-end tests select by these names.
Headers. Every non-session view draws ViewHeader
(src/components/view-header.tsx), a PaneHeader with the title in
text-title, an optional one-line subtitle, the view's actions, the sidebar
opener while the sidebar is hidden, and on desktop the connection problem in
place of the subtitle. While link.status reports no server configured there
is no connection to report, so neither header shows one.
Window bar
In the desktop app, the navigation row is also the window's drag area; there
is no separate title-bar strip. On Windows and Linux,
src/components/shell/window-bar.tsx adds minimize, maximize/restore and close
at the right edge, wired to window.aetherDesktop.controls. Their callbacks
take no arguments: forwarding React's pointer event through Electron's
context bridge fails with An object could not be cloned. Those platforms
have no application menu, so a right-click on the row opens the shell's
native menu - Check for Updates…, Minimize, Maximize or Restore, Close -
from the window's system-context-menu event on a drag region and from
controls.showMenu(x, y) elsewhere on the row.
No platform has a View menu, so the shell zooms the window: Cmd on macOS
and Ctrl on Windows and Linux, with = or + to zoom in, - to zoom out
and 0 to return to 100%, matched on the character typed.
desktop/preload.js acts only on a key the page has not claimed with
preventDefault, so inside a terminal the same keys zoom the terminal
instead. desktop/zoom.js scales the window's 960×600 minimum size with
the zoom, so the layout never narrows into the phone toolbar, which has no
window controls or drag region. It refuses a zoom whose minimum would not fit
the display, and on macOS moves the traffic lights to stay centred in the
row, stopping at 91% where the logo would reach them.
On macOS, the shell keeps the native traffic lights, centers them in the
44px navigation row and reserves 80px before the logo. The row uses
-webkit-app-region: drag; navigation buttons and window controls use
no-drag. The logo and unused row space remain draggable at narrow widths.
On an initial connection failure, App.tsx renders the same header without
navigation, so the window can still move and close. A browser tab has no
desktop bridge, so its header has neither drag regions nor window controls.
The bridge carries one more thing the SPA cannot do for itself:
window.aetherDesktop.chooseFolder() opens the shell's native directory
dialog and resolves to the chosen absolute path, or "" when it was
cancelled. On macOS the dialog is a sheet on the asking window; on Windows it
is modal to it. On Linux Electron asks xdg-desktop-portal when the portal
offers a file chooser of version 4 or newer, kdialog on KDE when it is
installed, and GTK otherwise. A portal or kdialog chooser runs out of process,
which is why the caller disables its button while one is open; the GTK
fallback runs in process. On KDE under Wayland (WAYLAND_DISPLAY set and
KDE in XDG_CURRENT_DESKTOP) the shell asks without a parent window:
Electron draws on X11 there unless the user sets an ozone platform, and KDE's
portal backend shows nothing for an x11: handle. On Linux Electron reports a
failed portal as a cancel and a hung one never answers, so the shell takes the
window losing focus as the sign a chooser opened. A 10s timer runs only while
the window has focus: from the call if the window is focused then, and from
every regained focus; it stops when the window loses focus. When it fires the
call rejects with a message starting the window held focus for the last 10s.
A dialog that closes cancelled while the window had focus at the call and
never lost it rejects with one starting
the folder chooser closed without opening:. A folder picked after the 10s
rejection arrives through window.aetherDesktop.onFolderChosen; the
Repository step applies the first such pick, unless the field was edited,
Use a different repository was clicked, the step was left or reset, a
link is in flight or a clone is connected. A window the shell cannot resolve
rejects with no window asked for the folder dialog.
Both properties are optional on the type for the same reason shellVersion
exists: a shell built by an older aether gui build lacks them.
Launch splash
App.tsx mounts src/components/launch-splash.tsx over the shell at desktop
startup. It intentionally preserves the original animated night sky and pixel
wordmark, not the workbench's visual language
(Styles); its logo is the Cloudfield
mark with no glow, and the wordmark is in the set's Cream.
The splash requires window.aetherDesktop and plays once per desktop window,
recorded by aether.launchSplashShown in sessionStorage. Browser tabs,
reloads in the same window and prefers-reduced-motion: reduce skip
it. A reduced-motion launch still marks the session. If storage cannot be
read, the splash is skipped; a failed write never prevents startup. The
session is marked in an effect rather than during rendering so React
StrictMode does not suppress its own first launch.
It stays for at least 600ms, then fades when hydration succeeds or fails. A hung connection starts the fade at 2500ms even without a result. The fade lasts 260ms, releases pointer input as it begins and unmounts the splash at its end, exposing the shell or the raw connection error and window controls.
URL state
src/lib/url-state.ts keeps the route in the query string. A session view is
?run=<id>, with &view=session|trace|terminal|changes|files|browser (an old
&view=diff reads as changes; changes also takes &repo=<workspace id>|all on a
multi-repo session); any other
view is ?page=<name>, plus &id=<id> for a workspace page, a
Settings section or the selected template (?page=templates&id=<name>);
the name is the route's, so Activity is ?page=timeline, and Devices is
?page=devices, a tab of the Members view (pageOf in
src/lib/surfaces.ts). The board is the bare address. The store starts on
the route the address names
(initialRoute()), bindRouteToUrl pushes a history entry per navigation,
and back and forward navigate to the entry's route, so reload, back, Esc
and a shared link agree. Other query parameters and the hash are kept; the
token is removed on first load as before.
Both shells deliver aether://run/<id> as <dashboard>?run=<id>. The
desktop shell alone delivers aether://join?…#<secret> and
aether://claim?…#<secret>, as <dashboard>#join=<link> and
#claim=<link> with the whole link URL-encoded in the fragment, which
never reaches the server (local-gateway.md).
handedLink() in src/lib/url-state.ts takes join and claim off the
address on first load, onHandedLink does the same on hashchange for a
page already open, and the link is held in memory for the Connect step.
?run=<id> opens the session's default view (see Chat view). When the first
hydration does not find the session, the dashboard opens the board instead, or
onboarding for a member who has not finished it. A ?page= name with no
view, or a page the gates in src/lib/surfaces.ts do not offer this gateway
or member, opens the board once the first hydration has the capabilities.
These redirects replace the history entry (redirectRoute), so back does not
return to the dead link.
Window size and overflow
The shell is a fixed row - the sidebar and the content view - under the desktop window bar or the phone top bar, and nothing in its own chrome scrolls sideways. A control pushed past an edge is unreachable, not merely off screen, so every row states what gives way first.
desktop/zoom.js sets MIN_WIDTH = 960 and MIN_HEIGHT = 600, the
window's minimum size at 100%. That is the size the desktop rules are
designed against; a browser tab has no such floor, so the same rules degrade
below it rather than break. A phone is the far end of that:
src/app/layout.tsx exports the viewport the shell needs there.
width=device-width, initial-scale=1- the page is laid out at the device's own width rather than a desktop-sized canvas scaled down.viewport-fit=cover- the shell paints under the notch and the home indicator, and the chrome that touches those edges pads itself back out withenv(safe-area-inset-*): the phone top bar sideways and downwards, the phone tab bar sideways and upwards, the sidebar on the left and the content view on the right (and bottom, on desktop). The top inset is the one a surface away from that edge also has to read, because an installed iOS app asks for ablack-translucentstatus bar and gets the whole screen: it is--safe-topinsrc/index.css, and the top bar's height, the palette's drop and the side sheets' top padding all count it. A surface that pads itself keeps painting to the edge and insets only what it holds, so the notch shows the bar's own colour rather than a gap. Every inset is 0 where there is none, so nothing guards them. Toasts sit 8px above the bottom inset, and the offset is given tosonnertwice, asoffsetand asmobileOffset, becausesonnerswaps to the second below 600px and otherwise falls back to its own default.interactive-widget=resizes-content- on a browser that honours it (Chrome and the Android WebView; iOS Safari does not), the soft keyboard shrinks the layout viewport instead of sliding the page under itself. That is what everydvhin the app - dialogs, the palette, selects, menus - is already sized against, so they all shorten when the keyboard opens. Nothing in the shell usesvh.themeColoris the dark value, the default theme, so browser chrome matches the page before the SPA mounts;ThemeEffectthen follows the member's stored theme.
A layout that only changes size belongs in CSS. Layouts that mount different
elements for a finger than for a mouse, or for a narrow window, ask
useMediaQuery in src/lib/hooks.ts; named constants there are
coarsePointer, belowSm and phoneScreen. A layout that depends on the
room a view has rather than the window, such as Board's columns, measures
itself with useElementSize. The md edge is MOBILE_MAX_WIDTH and useIsMobile() in
src/lib/breakpoints.ts. The shell has one breakpoint: under 768px
(useIsMobile(), Tailwind max-md:) the one-row top bar and the
phone tab bar replace the sidebar.
A panel docked beside other content decides from room, not from the
viewport. minReadableWidth (560px, src/lib/breakpoints.ts) is the width
a session's content keeps beside one. The assistant docks only while main keeps
it, and otherwise floats over main (Assistant panel).
The session's Details and Subagent inspectors dock only while the session's row,
measured with useElementSize and with the inspector inside it, holds the
inspector plus that width; otherwise they open as overlays
(Details). Measuring the row with the inspector inside it means
opening one never flips the answer, so the layout cannot oscillate. A
narrower session also narrows its terminal, and the shared PTY with it, for every
viewer, which is why the session keeps a readable width rather than giving way to
whatever opens beside it. At the desktop shell's 960px floor with the default
260px sidebar, the assistant floats; it docks from 1140px.
Touch density is one variant, defined once. src/index.css declares
@custom-variant coarse (@media (pointer: coarse)), and a control that a
finger has to hit carries its touch size beside its desktop one - for example
size-7 coarse:size-11. It answers for the primary pointer, so a touch
laptop with a trackpad keeps the desktop density. Under it the Button
sizes, Input, CommandItem, MenuItem, the CollapsibleTrigger,
the Select trigger and its options, the dialog close, the palette input,
the top bar, the sidebar session and navigation rows and the sidebar's own
buttons, the session-list title and the files tree rows
grow to 40-44px, and the terminal toolbar row grows with the buttons in it.
Desktop density is untouched.
Use this variant rather than a new breakpoint or a per-component pixel value.
Header offsets follow the rendered layout. --top-bar-height (48px,
border included) in src/index.css sets the phone header row's height.
The app header reports its measured bottom edge through --app-header-bottom
for the command palette. Desktop dragging uses the navigation row, not a
separate height token.
--safe-top is the top safe-area inset under a name, so that
a surface measuring from the top bar can add the same amount the bar itself
grew by. It carries a 0px fallback because a bare env() in a browser
without it would void every calc() height that reads it.
Below md every centred dialog opens as a bottom sheet, full width and at
most 85dvh, and scrolls inside itself, so its footer stays in reach of a thumb
and the soft keyboard shortens it from the top. iOS Safari does not resize the
layout viewport for the keyboard, so useKeyboardInset()
(web/src/lib/keyboard-inset.ts) sets --keyboard-inset from
visualViewport and the sheet sits that far above the bottom edge; it is 0 on
browsers that resize. md is a width breakpoint, so a desktop window
narrower than 768px is treated as a phone here too. A menu with more than six
items also opens as a bottom sheet below md. On a phone (phoneScreen)
onboarding's First session agent list shows only the chosen agent with Change,
so Mode sits above the fold; picking an agent collapses the list again.
New session has its own phone sheet (the forms).
What gives way first:
- Update prompts live in the updates dialog, which scrolls inside itself; the sidebar carries one notice row. Technical output is bounded, and every prompt's actions sit on their own row so long diagnostics never hide them.
- The sidebar keeps the session list scrollable between its fixed header and its navigation rows and footer, from 220px wide up.
- The session header truncates its title to one line and keeps its state line on one line: the reason gives up its room first, then the owner, then the mode word; the branch truncates only when it alone is wider than the line. The view switch always sits on its own row (see Header).
- The board places its three columns side by side when its own width fits them and otherwise stacks them into one list (see Board).
Data flow
connect() in src/store/sync.ts owns the whole lifecycle. One round of HTTP
fetches hydrates the store (server.info, workspace.list, member.list,
run.list, run.overlaps, and GET /api/v1/capabilities), then /ws/events
is the only thing that changes it. setWorkspaces keeps a valid selection;
an unset selection or a workspace that has been deleted falls back to the
first by ID, or clears the selection when none remain. An open deleted
workspace route moves to the replacement workspace or Manage workspaces;
an open session in a deleted workspace returns to the board. A gateway that
answers the capabilities fetch with an error status or a body that is not
JSON is a legacy gateway: hydration succeeds and the store holds null. A
fetch that gets no answer at all, such as Chromium's
net::ERR_NETWORK_CHANGED after the host gains a network interface, keeps
the capabilities the connect probe loaded; with none loaded, hydration fails
and retries.
The snapshot also seeds the board's paused map from each session's wire paused
field, skipping sessions that do not carry it.
removeWorkspace records deleted IDs for the lifetime of the in-memory store.
Every workspace snapshot and upsert excludes those IDs, so an older route or
hydration response cannot resurrect a deletion received from another member.
Removal also repairs the selection and open route before any refresh awaits.
- The subscription is established first. Hydration starts only once the
server acknowledges it (
{"ok":true}), which is also when the client calls itself live. Otherwise a change between the snapshot and the subscription would fall in the gap and never be delivered or replayed. - Events arriving during a fetch wait in the queue, and are applied once the snapshot lands, so an older snapshot never overwrites a newer event.
- Events are applied one at a time, in sequence order, each fully resolved before the next begins. The cursor is a single number, so it must never move past an event still waiting on a fetch.
- Listeners hear one change per frame. The queue drains inside
batchNotifications(src/store/batch.ts): everyset()applies at once, sogetState()and the cursor rules above are unchanged, but subscribers - React included - are notified on the next animation frame (a 16 ms timer in a hidden tab). The hold outlives an emptied queue, because each socket message arrives in its own task and drains before the next one lands; a burst of 200 events spread over a few milliseconds renders once. A write outside the drain, such as a click, notifies at once. - The stream subscribes live on the first connect (the fetch behind it
provides the current state) and replays from the highest applied
seqon reconnect, with jittered backoff. An event at the cursor is ignored, so a replay is idempotent; one strictly below it means the server's event log restarted (a recreated or restored data dir), and the client zeroes its cursor and takes a fresh snapshot rather than silently dropping everything the new log sends. - A reconnect with no cursor cannot replay - on a quiet server nothing has
advanced
seq- so the client re-fetches the snapshot instead of subscribing live and silently missing the outage. - Server-gateway reconnects also refresh the snapshot when replay is possible: Tailscale may identify the new connection as a different member. Only a local gateway's fixed identity can reuse replay without that refresh.
- Branch and pull request hints are counters.
git.branchandrun.prbump a per-sessiongitSeqandprSeq(src/store/workflow-signals.ts). A view that shows that state keys itsrun.git.logorrun.pr.feedbackre-read when the counter changes (a store subscription ongitSeq[runID]) instead of polling. - A failed hydration retries on the same backoff, and the affected panes say the server is unreachable rather than animating skeletons forever. That generic copy never overwrites a more precise error already recorded.
- The latest request to the server decides the connection state. The
failure class lives in
unreachable, which every failed server read sets and a successful hydration clears. A subscription the server acknowledged also clears it, including a replay reconnect that skips hydration, unless a hydration retry is pending: then the retry runs at once and its result decides, because a live stream does not prove reads reach the server. A failure recorded by a connection that was torn down (a retry, or a switch to another server) is dropped. Whileunreachableis set the footer saysUnreachablerather thanLive, and the connection line names the layer that failed - client to edge, authorization, server registration, or end-to-end - with the server id and the next command. When the gateway's error carriesdata.edge_path, itslayer,server_idandedgeare used as given, and itsonlinelist, sent on a server-registration failure, is named as the servers the edge does see online beside the server id the dashboard is linked to. Each failure is stored with the server id it was measured on. A failure measured on another server than the linked one means the gateway followed a re-link (aether link --from-edge): the dashboard re-reads the link status, resets the connection as for any server switch, and shows the failure under the new server's id. An offline computer is the client-to-edge layer on a link through an edge and client-to-server on a direct SSH link. - A total failure replaces the shell with one error page. When nothing has
hydrated and an error is recorded,
ConnectionErrortakes the window instead of an empty sidebar and an empty board behind a toast. Which hop failed picks the copy:networksays this machine has no network at all and names wifi and a VPN,serversays the server did not answer through the selected transport,gatewaysays the localaether guiprocess stopped answering,tailnetsays the phone got no answer from the server that serves it the page, and an access refusal preserves the gateway's own reason. A fetch that got no answer at all isgatewayonly on the desktop origin, where that process can be restarted; on the server gateway it istailnet, because the page came over the tailnet and there is no local process to blame and no wifi advice to give. A refusal on the edge path arrives asdata.refusalon the gateway's503, andrefusalHopinsrc/store/sync.tsmaps itskindto a class, never its wording:edge-server(the edge holds no live registration for the server id;aether-server edge statuson that host reports the server's side of the same connection and can disagree),edge-not-claimed(the edge recorded the server's owner, and the server has not applied the claim to its live connection yet; says to retry),edge-refused(the edge's other refusals),signed-out(no valid device token; gives theaether login --edgecommand),not-member,device-revoked,device-pending, andserver-refusedfor the server's other refusals. Thedevice-pendingpage says an admin approves the device from Needs you, or the member from an approved device, and showssudo aether-server device approve <code>only when the refusal carriesapproval_code. A failure without a refusal on a link through an edge isedgewhen the error names the edge's host: the edge did not answer, so it refused nothing.src/store/edge-sync.test.tspins the class of each kind. The capabilities probe records which gateway serves the page before hydration runs, so the first failure is classified too. The gateway's message appears in an initially open "Technical details" disclosure, and the page suppresses the toast that would otherwise repeat it. Retry clears connection state and remounts the subscribe-and-hydrate cycle rather than reloading the page. - A local token refusal is reported as access failure, not an unreachable
server.
connectreadsGET /api/v1/capabilitiesbefore it opens the stream, and a401there means the local gateway refused its token. The store records that refusal verbatim, stops retrying and tells the member to open a fresh URL fromaether gui. The token is minted per process and held in the tab's session storage, so a bookmarked URL, a second tab or a restartedaether guineeds a newly printed URL. On the server gateway there is no token check: WhoIs identifies the source address on every request, while a tagged node is denied and an unavailable identity service reports its own403or503refusal. - The last snapshot paints before the network answers. After a
successful hydration, ten seconds after later changes and when the page is
hidden,
saveSnapshot(src/lib/snapshot-cache.ts) writes the workspaces, sessions, members, server info and capabilities tolocalStorage(aether.snapshot.v1:<origin>; contents and deletion in privacy.md).connectcallspaintSnapshotfirst, on a cold start only (a reconnect to another server never repaints the last one): it fills the store, setshydratedandstaleSince(the save time), and seedsidentityKeyso hydration treats a different member or server as an identity change and drops the cache.hydratestill counts a painted store as a first load (workspace selection, onboarding redirect) and clearsstaleSincewhen it succeeds. WhilestaleSinceis set, or a refresh failed,StaleBannershows one line under the top bar: Saved state from 3 minutes ago, then the hydration error verbatim (or reconnecting; tap it to read it all), and Retry, which fires theonlinewake below. While it shows (a saved snapshot, or any failed refresh), the toast, the empty-board "Cannot reach the server" cards and (below 768px) the header connection line stay out, and the banner is the one place the failure is written. On a saved snapshot, everyRequestAction(Approve, Deny, Reply, permission choices) is disabled, andRequestActionswrites Reconnect to act beside the row: a disabled button shows no tooltip on touch.runCommandsandhandoffCommandsgetstaletoo and disable every gateway verb and the Send and Close dialogs, so Mark complete, the More menu (which says Reconnect to act at its top) and the palette cannot act on a session the agent may have moved on from. Each saved session keeps its current paused state frompausedRunsand its confirmed change time asstatus_changed_at; an estimated time is left out and estimated again on paint. Any access refusal (a 401 or 403, or arefused,signed-out,not-member,device-revokedordevice-pendinghop, from a load, the stream or the connect probe) callsrefuseSnapshot: it deletes the saved entry and blocks every save until a hydration succeeds. On a painted snapshot it also shows the connection error instead. A rejected link token does the same and shows the expired-link page as before. - Resuming from the pocket also reconnects without an event.
connectEventsruns a 5 s watchdog; a tick more than 15 s late while the tab is visible means the page was frozen, and it replaces the socket likeonline.pageshow(back/forward cache) counts as a foreground return, and anavigator.connectionchange oftypecounts asonlineafter it has been quiet for 1 s, so a burst of interface events reconnects once. Speed estimates (effectiveType,rtt,downlink) never count, and a browser that reports notypenever reconnects on a connection change. - The sockets reopen on a foreground or network return. Both
connectEventsandconnectAttachsubscribe tovisibilitychange(visible) andonlinethroughonWakeinsrc/lib/stream.ts. A phone freezes a background tab's timers and drops its sockets, so a tab coming back from the pocket would otherwise sit out the remainder of a wait that caps at 30 seconds. Either event clears the pending retry timer and resets the backoff unconditionally - a tab that was away cannot know how long the failure lasted - and reopens when there is no socket. The two differ on a socket that is still there: a foreground return leaves it, since tearing a working subscription down would replay the log for nothing and the tab being hidden said nothing about the network.onlinedid, so it replaces the socket whatever state it reached, an acknowledged one included. A wifi-to-cellular switch leaves exactly that socket half open: the browser goes on reporting it as connected, the store goes on saying Live, and no close ever arrives, because the server's end sees the FIN and the phone does not. If an attach is still inside its replay boundary,onlinefirst cancels its serial parser and drain with an explicit cancellation signal, clears the partial operations, and drops the socket while keeping the terminal hidden. The replacement attach starts one fresh hidden replay, so no incomplete prefix can become visible and a stale completion cannot reveal the old host. A final replacement refusal settles the gate before showing the server's error. The event is rare enough that one resubscribe fromlastSeqand one re-attach with its replay are the cheaper mistake. The 30 second cap stays for genuine outages, and an attach the gateway refused - or one parked on asession endedclose, whose transcript cannot change again - is an answer rather than a failure, so neither event re-asks it. - The hydration retry wakes as well. A re-hydration that fails after the first good one leaves a cursor to replay from, so the reopened stream goes live without re-fetching and nothing else would restart that timer. A wake with a retry pending clears it, resets its backoff and re-fetches at once; a wake with none re-fetches nothing.
- A
run.statusevent for a session the client has never seen fetches that session before the event is applied, which is what keeps two quick transitions of a brand new session in order. If the fetch fails the event is unresolved: the cursor stays put and a fresh snapshot is taken to repair the store. Arun.deletedevent removes the session from every connected dashboard; arun.statusevent that raced a local deletion treats a404re-fetch as resolved instead of forcing a redundant hydration. An event naming an unknown workspace re-fetchesworkspace.list, because workspaces arrive only by fetch and a session under an unknown one would render nowhere. An event whose actor is not in the members map re-fetchesmember.listfor the same reason: nomember.*event exists, so a teammate who joined after hydration would otherwise render as a raw ID forever. Aworkspace.timelineentry of kindhandoffre-reads its session the same way, because a handoff publishes norun.statusevent to carry the new owner.run.title,run.model,run.effort,run.protectedandrun.archivedfollow the same fetch-first rule on a session the client has never seen;run.controllerskips an unknown session, whose snapshot carries the holder.run.accountlikewise skips an unknown session, and on a known one replacesaccount_member_idandrequested_account_member_idwith the payload's, so the header names the new account at once.run.childrenre-reads its session, which carries the session's own subsession setting,child_refusedanddetached.run.retentionalso fetches an unknown session, then replaces only its runtime deadline and cleanup metadata. It does not re-fetch known sessions or changefinished_at,stateChangedAt, the business status,outcome_unseenorfinish_unopened. Aserver.updateevent lands in theserverslice, which feeds the update prompts. run.agentevents set a session'stoolActivity({verb, target, at}on the session record,src/store/activity.ts), so a state line can say "Reading src/auth.ts" without opening a socket to the session. A tool call sets the present tense with the call's detail (file, command, task) or the tool name as the target; the tool result that follows turns it past tense ("Read", "Ran", "Edited") orFailed; a subagent reads "Delegating". An Enhanced session's event carriesverb, which the line shows as is. Calls in flight are kept bytool_use_id, so a result ends the call it names: while another call still runs, the line shows the newest one. Only sessions whose agent has an adapter emit these events, sotoolActivityis optional everywhere. An event about a session the client has not loaded is dropped rather than fetched. A status change - a turn ending or starting, a reopen - clears the activity, so an earlier action never reads as current; a session re-read keeps it only while the status is unchanged, since no snapshot carries it.
The capabilities descriptor is the transport seam. The store holds the
GET /api/v1/capabilities answer (gateway, methods, ws, and local
where the gateway has local verbs - the server gateway omits it), and
useCapability() in src/store/hooks.ts wraps it as three predicates -
hasMethod, hasLocal, hasWS - with methods: ["*"] meaning everything
and a missing local meaning no local verb is available.
When the descriptor is null (a gateway that predates the endpoint), the
fallback is the read-and-message method set every gateway has always served,
events and attach sockets, and no local verbs, so an unknown gateway
degrades to monitoring rather than to "everything". Views gate on these
predicates rather than sniffing the URL, which is what lets the same SPA
render against a gateway with or without the local surfaces
(docs/local-gateway.md).
Capability is half the gate; the caller's role is the other half.
Transport capability answers what the gateway can carry, not what this member
may do. useSelfRole() and useIsAdmin() in the same hooks file read the
role off server.info's member record, and every admin affordance needs both
predicates: the gateway can carry the method and the caller holds the admin
role. Reads are gated on capability only, so the roster is reachable on the
server-hosted dashboard as well as through aether gui; the server remains
the authority and checks every call again. A non-admin cannot edit membership
or roles but can grant or revoke access to their own agent account.
Every request goes through src/lib/api.ts - the only module that knows route
shapes, gateway authentication and error decoding. It carries exactly the
methods the views call. Control calls use POST /api/v1/<method>. A refusal's
ApiError message is <method>: <server message>, or the server's message
alone when it already starts with that method. The diff
patch, disk gauge and capabilities descriptor are read through GET;
development and retained capture bytes also use an authenticated binary GET,
not base64 in control JSON. The shared browser's observation-only WebSocket is
/ws/dev/browser/{run_id}; actions stay on the typed HTTP control API.
aether gui sends its per-process token as Authorization: Bearer on HTTP
and as ?token= on WebSockets. The server-hosted gateway sends no token;
WhoIs authenticates each request.
The disk gauge in Insights › System (the Disk tile and the Storage
section) renders when server.info carries a disk object (used_bytes, total_bytes). That field does not arrive with
server.info: the gateway serves the number on GET /api/v1/disk and the
team reads write it onto the stored info, which is the gauge's only reader. The field
stays optional and the gauge stays hidden if the read fails. What statfs
answers is the whole filesystem holding the data directory, not the directory
itself, and the gauge is labelled as that: it is the number that says whether
the box is running out of room, and claiming it as Cloudfield's own usage would
be an invention.
account.usage is the quota RPC used by Settings > Usage. Its params
are {account_member_id?: string, refresh?: boolean} and its result is
{account_member_id, providers} with independently decoded Claude/Codex
provider rows (status, windows, optional plan, updated_at, retry_at,
error, and checked_at). The provider endpoints are subscription services
whose response shapes can change; the server owns credentials, fixed provider
hosts, bounded fetches and cache policy. The dashboard does not refresh
tokens, run provider CLIs, or infer billing/history. The section reads on
open, on an account change, on reconnect and on its refresh button; nothing
polls. An older server that does not know this method is shown as needing an
update.
Actions
Every action the dashboard sends falls in one of two categories:
- The client can predict the result, such as adding a note: the change
renders at once and is confirmed or reverted when the server answers. A
refusal reverts it, puts back what the user typed, and shows the server's
error verbatim (
errorSentence, inlineCallout). - The server decides the result, such as approving a teammate's message: only the control that sent it shows a pending label, within one frame, and past the deadline it reads "Still waiting for the server…".
The deadline is optimisticDeadlineMs (store/optimistic.ts, 5 seconds).
The slowest run.room.post measured through the local gateway over SSH
under load took 57 ms (p99 42 ms); each gateway RPC also costs about three
edge round trips, which were not measured, and 5 seconds leaves room for
three 1.5-second round trips.
optimistic() there runs a predictable action: it calls apply, then
send, and either confirms the server's answer or reverts on a refusal
or at the deadline. The returned outcome carries the error and a retry
that resends the same request, so send must carry one idempotency key
across calls or be idempotent by nature. An answer that arrives after the
deadline is still confirmed, and the store dedupes it by id or idempotency
key, so a late success shows as saved once and clears the error. Once any
attempt of a mutation is answered, no attempt of it reverts, and a Retry
still pending resolves as that success. A late
refusal resolves the unanswered outcome's refused promise with the
server's error, which replaces the timeout failure and drops Retry,
unless an attempt of that mutation was answered first.
Only a JSON-RPC error from the server is a refusal; a failure that carries no
answer, such as Failed to fetch, a gateway 502 or 504, the local
gateway's server unreachable:, network unreachable: or
server did not answer, or any error whose data carries an edge-path
refusal, is treated like the deadline,
with its own error text and Retry, because the server may have
committed.
A server-decided action locks only its own control, and the siblings a
second press would race with, such as the Deny beside a pressed Approve.
usePastDeadline (store/optimistic.ts) turns true once a pending flag has
held for the deadline; the label then reads "Still waiting for the server…".
Past the deadline, Cancel stops waiting and unlocks the control, only
where a resend is deduped or refused and the eventual result still shows:
| Control | Pending label | Cancel past the deadline |
|---|---|---|
| Question Reply (Details) | Replying… | Yes: a resend of the same text reuses the idempotency key, and the reply arrives as a room event |
| Teammate message and permission Approve / Deny (Details) | Approving… / Denying… | No: a second decision would race the first, and its "already decided" refusal would sit beside the first's success |
| Composer Send and the Enhanced pill's Send, Steer and Queue | Sending… | Yes: the draft keeps its idempotency key, so a resend delivers once |
| Enhanced pill's Interrupt and Resume, and a session option | Sending… | No: these carry no key, so a late interrupt could stop the turn sent after it |
| Create workspace | Creating… | No: workspace.add carries no idempotency key |
| Launch (launch dialog) | Launching… | The dialog's Cancel closes it at any time; the request keeps going, a success still opens the session, and a refusal shows as a toast |
| Close dialog Merged / Abandoned, over another verb's pending prediction | Closing… | The dialog's Cancel closes it at any time; the answer shows as a toast |
| Workspace settings Save, budget Set / Clear budget | Saving… / Clearing… | The dialog's own Cancel closes it at any time; the call sets values, so a repeat is harmless |
| Save identity | Saving… | No: a second save could reach the server before the first and be overwritten by it |
| Needs you device card Approve / Deny | Approving… / Denying… | No: a second decision would race the first |
| Settings Connect my GitHub account | Connecting as account (provider) | No: each press asks the server for a new claim code |
| Device Approve / Revoke (confirm dialog) | Approving… / Revoking… | The dialog's Cancel turns into Close; it and Esc close the dialog while the request keeps going. A late success still refreshes the list and toasts but leaves the approval code field alone, since it may hold a code typed since; a late failure shows as a toast |
| Schedule Unschedule | Unscheduling… | No |
| Invite code Generate code | Generating… | No: each call mints a new code |
| Roster Remove (confirm dialog) | Removing… | Closes the dialog, as for Device Approve |
| Giving up your own admin role (confirm dialog) | Becoming role… | Closes the dialog, as for Device Approve |
| Invitation Invite | Inviting…, and the new row reads Creating… | No, and no Retry: the row stays until the server answers, and the answer carries the join link. The dialog's Cancel closes it while the request keeps going; the answer then shows as a toast. A refusal drops the row and shows the error; a failure with no answer re-reads member.invitation.list once and keeps the invitation if the server holds it, else drops the row |
Board
src/routes/board/ is the default center view and the triage surface,
reached through Board in the app header; the sidebar owns the session
explorer and primary New session action. The Board / List / Map / Lanes tabs
in the view header choose the layout, stored per workspace in aether.ui:
triage columns, the same groups as one list, a session canvas, or a timeline of
sessions. Board shows three columns, Needs you, Working and
Finished, each a bg-chrome well headed by its name and count that
scrolls on its own under that header. List stacks the same three groups
full width in one scroll, with Finished collapsed until opened. board() in
src/routes/board/selectors.ts reads runGroups, so the board has the
sidebar's scoping, ordering and Mine filter: Needs you spans every workspace
and sorts oldest wait first. The board measures its own width, so the
sidebar and the assistant panel count: under 648px, where three 200px
columns do not fit, Board renders the list layout and the List tab
is hidden. A group of more than 60 cards renders only the cards its scroll
shows (card-list.tsx, virtua).
In a flat session list (run-list.tsx) a root lists its subsessions
under it with a toggle naming the count (**Show 2 subsessions
**). Subsessions start shown, and a folded one that needs you still shows. Nested rows add the model to the
agent. All workspaces leaves out the finished subsessions the sidebar
does (withoutSettled), from its rows and its count, except one with
sessions under it.
A card (run-card.tsx, on the Card primitive) has three parts:
- the head: the agent's coloured
AgentGlyphand the title (runLabel), two lines at most; - the description: the Needs you reason in the text colour, elsewhere the
state's reason (
stateDetail) in muted; two lines at most, one on a Working card, whose live tool activity must not change the card's height; a card whose reason only restates its state has none; - the footer:
StatusDot, state label, compact wait or change time ("4m") and the workspace name for a session outside the active workspace or across several repos, which truncates first; then the agent name (agent.listdisplay_name, else the session'sharnessvalue), owner avatar,+added −deletedfrom the newestrun.diffsnapshot (N fileswhen that snapshot istruncated, because its counts are only a floor), thecard:metaslot (file overlaps, sync) and the Needs you action.
The agent name shows once the card is 365px wide, where the description and footer also indent under the title; a narrower card keeps it for screen readers only. Device and merge-proposal cards use the same frame.
A click anywhere on the card opens the session. useBoard reuses a
card's previous object while it is unchanged (dequal), so the memoized
RunCard skips it.
A subsession is a session that another session's agent started with
aether-internal subsession start (subsessions);
its parent is that session and its root the top of the tree. Every surface reads
one hierarchy: runParents in map-layout.ts takes a session's parent
from parent_run_id, and
runTrees in src/store/selectors.ts folds each tree under its root. Child
sessions fold into their
root's card, which adds "N subsessions" and a StatusDot count per state.
Subsessions never appear as separate cards. One that needs you puts its root
in Needs you, and the card's description names it:
"<purpose>: <reason>". A subsession whose parent is not loaded is its own
card. A subsession's label (runLabel) is its child_purpose, so the palette,
which searches every session, finds it by purpose.
A Needs you card shows its primary action on hover, on keyboard focus and
always on a touch screen (card-action.tsx). Each condition in
src/lib/needs-you.ts names one action, which the card and the sidebar row
both show:
| Condition | Action |
|---|---|
Enhanced turn interrupted or stopped short, or a needs input: question |
Reply: on the card a popover composer whose message goes through run.inject (Mod+Enter sends); in the sidebar it opens the session's Chat view with the composer focused |
| Native permission or question on a Standard session; blocked, held, or an Enhanced failure | Open terminal |
| Native permission or question on an Enhanced session, or teammate question | Answer |
| Usage limit with no account to move to | Open |
| Teammate's message waiting for the controller | Review message |
| Unreviewed finish | Review |
Every action but Approve and the card's Reply goes where the condition's
target points: an agent's request or question opens the session's
defaultView (Terminal for Standard, Session for Enhanced), a blocked, held
or failed Enhanced session its Terminal view, an unreviewed finish its Changes
view, and a teammate's question or a usage limit the session's last chosen
view. Until the session's record loads, an agent's request also opens the
last chosen view.
While a card has focus, r replies and o opens (the card
key scope, pushed only then and only for the actions that card offers, so
the keys stay free elsewhere). Closing the reply composer returns focus to
the card. A failed send keeps the draft and shows the server's error. The
open composer, its draft, the send in flight and its error live outside the
card, keyed by session (useReply), so a card that remounts - its group
crossing 60 cards, or a move to another group - keeps them and still reads
Sending…. A send closes or marks failed only the reply it was sent
from, never one opened after it. Authenticating as another member or
server drops the reply.
Finished footer. Archived (n) swaps Finished for archived sessions in
scope (Mine applies); Back to Finished returns. Archived sessions have no
automatic deletion countdown. More finished-run actions (…, in the Finished
heading, only when it has an item) holds Archive finished sessions… and, for
admins, Free retained sandboxes…. Both open the
store-hosted confirmations (src/components/palette/clear-done-dialog.tsx,
drawn by src/routes/board/clear-done-dialog.tsx) over a plan snapshotted
when they open: clearDonePlan() and releaseFinishedPlan() in
src/lib/commands.ts, over the whole active workspace whoever owns the session.
runClearDone() and runReleaseFinished() run at most six calls at once,
continue past failures and report each session's real error; archive counts
CodeNotFound as done. Archiving hides a session whose status is final or
completed (isTerminal) from every group without deleting its history.
Before the archive confirmation offers its count, it reads run.close_check for
the plan's completed sessions, 50 at a time, and keeps back, with the server's
reasons, each one that still has live subsessions, a pull request not merged,
sessions waiting on it or pending cleanup; the server refuses those too, and a
completed session whose result still awaits review, which the single Archive
command does not offer.
The same confirmation offers live sessions that are idle and done:
idleArchivePlan() (src/lib/idle-archive.ts) takes a running or parked
session whose agent replied, or whose turn ended without a report, with
nothing that needs you, no pending request, no reported wait, no live
subsessions or held background tasks, not paused, and no open parent. The
batched run.close_check then says how long each has been idle
(idle_since) and whether it closes as merged (merged_pull_request, else
abandoned); one changed within 24 hours, or on an older server that does not
report idle_since, is not included. Each row leads with
its outcome, then why ("Closes as merged · idle 3d, replied"). One with a
close warning, a failed check, or an older server that cannot tell its
outcome starts unchecked and says "Check to close anyway", or "Closing
anyway" once checked; the rest start checked. The section header's select
all takes only rows without warnings, so a warned row always needs its own
click; it shows a full check only when every idle row is checked. On a phone
the Idle header stays at the top of the scrolling body. Every other live session in scope is listed under Not included,
collapsed, with what keeps it. The title and primary button say what happens
("Archive 5 sessions, closing 2 first?", Close 2, archive 5), Cancel
holds the focus with its ring drawn, and Check again rebuilds the whole
plan, as does the retry shown when an idle session's check failed. With idle
sessions offered but none checked the title reads "Choose idle sessions to
close and archive"; "Nothing to archive" means nothing was offered. On desktop the Idle list scrolls in a bounded box that fades at the
bottom while more is below; on a phone the sheet scrolls instead. Each checked session is
closed, then archived, unless it changed since the plan saw it (its status,
review, state, pause or pending requests); one deleted meanwhile is dropped
without an error, and a skipped or
failed close leaves it live and unarchived, and the toast names each session
that failed with its error.
Freeing removes a retained sandbox and keeps the session and its history.
Empty board. With no sessions in scope the board names the first unmet requirement, with one sentence and one button:
- no workspace: Add your repository (onboarding, Repository step);
files.treeanswersCodeUnavailable(no repository yet): Push your base branch, with the server's error (onboarding, Repository step); any other failure shows as an error instead. The check repeats when the window regains focus;agent.listreports nothing installed: Set up an agent (Agents);- Mine hides every session in scope: Show everyone's sessions;
- otherwise: "A session is one agent working on its own branch in its own sandbox, a container or virtual machine on the server." and New session, for members who may launch.
Loading shows two delayed card-sized skeletons per group; a hydrated empty group says "Nothing here.". An unreachable server shows its error in place of the columns.
Motion. Switching between Board and List glides every card that is in
both from its old place to its new one (useCardGlide in
src/routes/board/glide.ts); switching to or from Map is instant. A live
update that moves one to eight cards to another column glides them and the
cards they displace. Each Board column clips its own scroll, so a card that
lands in another column glides only vertically there and fades in.
Hydration, a reconnect's snapshot,
a change of workspace, Mine or archive view, and reorders within a column
change at once, and virtualized groups never glide. Under reduced motion
every change is instant. A polite live region reads "N need you" when the
Needs you count changes.
Map
Map exposes every individual session, subsessions included, finished ones
too. mapRuns() reads
the unaggregated runRows() presentation rather than Board's folded cards, and useMapRuns reuses unchanged card objects
(dequal), so a run.agent event re-renders one card. A map card opens that
individual session; its primary action still targets the condition that needs
the viewer.
A map card (map-card.tsx) has three rows: the agent glyph in a tile, the
session's label over a muted line (agent display name, model, and the workspace
for a session outside the active one) and a state pill (Badge with the
StatusDot); the reason, two lines at most, in the text colour when it
needs you and muted otherwise; and a meta row with the owner avatar when
it differs from the section's, +added −deleted, the compact age, the
card:meta slot, the card's action on hover, focus or a touch screen and, on
a parent session, the fold button. The action and fold button keep their full
width; when the row runs out of room, the rest is clipped from the
card:meta end.
The Map workspace scope picker selects the active workspace or All workspaces, without changing the sidebar's selected workspace or Board's triage scope. Mine filters individual Working and Finished sessions by their owner. As in Board, Needs you stays visible across workspaces and Mine. Cards from another workspace, and all cards in All workspaces, name their workspace. Archived (n) replaces Finished sessions with individual archived sessions while keeping Needs you and Working visible; Back to Finished returns. Archived sessions obey workspace and Mine, and an all-archived scope keeps the toggle available.
The Sessions strip counts every session in scope, folded subsessions included: Sessions N, N working, and the N needs you and N failed chips. Each chip opens a list (oldest wait first; newest failure first) whose rows bring the session into view: its family unfolds if folded, the camera centres it at a readable zoom, and its title takes focus.
map-layout.ts lays out units: a standalone session, or, for a session with subsessions
, a family unit with every descendant hanging under the root, captioned
"N subsessions", whoever owns them. Relationships come from parent_run_id
(a detached subsession is its own unit). Up to four subsessions hang in one row from
a bus; five or more fill four fixed columns row by row, each on a rail, so a
new subsession is appended without moving the others.
Units are placed newest first by the root session's created_at: each takes the
highest free spot in a band of one common width, leftmost on a tie, so the
newest sit top left and older units fill the room under short neighbours.
Subsessions keep spawn order. Sections stack the
viewer's sessions, then other owners by their newest unit, then Needs you
elsewhere: Needs you runs present only because Needs you ignores scope and
Mine, last so their churn never reflows the rest: the band width and framing
come from owner sections alone. With two or more owner sections each is
framed and headed by its owner and count; Needs you elsewhere is always
framed. A teammate's subsession under your session shows its owner's avatar.
Section headers and family captions grow as the camera zooms out so a distant
map still reads; a caption grows only into the gap above its unit.
Geometry is fixed per text size and pointer. State, reasons, titles, timestamps and profile edits never move a node. A repack happens only when sessions are added or removed, ownership or relationships change, a family folds, or the text size or pointer changes; moved units and cards glide from their old place, new cards fade in, removed ones fade out, and the camera stays.
A parent's fold button shows its subsession count; folded, +N. Folding
fades the subsessions out and repacks, and the camera follows so the parent
stays where it was on screen; a folded family never unfolds by itself.
When hidden subsessions need you the button turns amber, as +N · k need you.
Unlike the sidebar, whose fold keeps Needs you subsessions visible, the Map
never moves cards on a state change. Folds persist in aether.ui
(boardMapFolded), pruned to sessions that still exist.
- Drag the canvas or a card to pan; releasing a drag never opens the card. A press released outside the canvas cannot pan on hover or consume the next deliberate card click.
- Scroll to pan; Shift-scroll pans horizontally. Ctrl/Cmd-scroll zooms around the pointer. Touch supports dragging and two-finger pinch zoom.
- With the canvas focused, arrow keys pan, Shift increases the step,
+/-zoom, andHome/0fit all sessions. - Zoom out, the zoom percentage, Zoom in and Fit remain available in the wrapping Sessions toolbar. Tab reaches every session, its action and its fold button in placement order, bringing an offscreen focused card into view.
aether.ui stores Board/List/Map/Lanes per active workspace and the map camera per
workspace/all-workspaces, Mine and archive scope. These origin-local
preferences survive view switches, navigation and reloads. A new camera
fits all sessions once, unless that would zoom below 50%: then it opens at 100%
on the top left, where the newest sessions are, panned just enough to show the
first unit's top card whole, so a wide family on a phone opens on its
parent. Live metadata, added or removed
sessions and viewport resizing never reset a chosen camera. Use Fit to frame
the changed set. Cameras saved before this layout (persist version 9) are
dropped once.
Lanes
Lanes (src/routes/board/lanes/) draws every session in scope as a lane on
one time axis, so you can see what ran when and how the sessions relate. It shares
Map's scope picker (labelled Lanes workspace scope), Mine and
Archived (n), and Map's merge-proposal and device strips. The toolbar adds:
- Time window: 1h, 6h, 24h or 7d. Without a choice it opens on 1h while any session is working, else 6h. Ctrl/Cmd-scroll zooms around the pointer and the control then reads Custom.
- Show: which relationships to draw (Agent messages, Overlaps).
- Group lanes by: status or owner.
- Legend: every bar fill, mail mark and link style with its meaning.
- Now, shown only after panning into the past. While the window ends at now it follows now.
The axis counts back from now ("−20m") up to an hour wide; wider windows show clock times, and 7d weekday and date. Shift-scroll, a sideways wheel or dragging the track pans; the history page loads as the window reaches it.
On a phone (below 768px, and in the Sessions tab's Lanes) the label
column is 36% of the width, between 112px and 160px, and holds each session's
title, state dot, agent glyph and age. Titles stay in that column while the
track pans; bars carry the state words, cut with an ellipsis. With a touch
screen (coarse pointer) the time window's buttons are 44px wide. Everything else folds into one Filters
popover: Workspace and Group selects, Only mine (with the line that it filters Working and Finished
only) and Archived (n) switches, the Show checkboxes, Legend and Reset. The
button counts the filters changed from their defaults (this workspace, not
only mine, not archived, every relationship shown, by status) and turns
accent while any is; Reset restores them. Axis labels that would touch are
dropped. The track keeps the room the live mail arrow needs left of now.
Sections. By status, sections follow the sidebar: Needs you (oldest wait first), Finished: review and Working (newest start first), then Finished (failed first, then latest end). Finished starts folded into one summary lane ("37 finished · 3 failed") whose strip shows each moment's outcome. By owner, there is one section per owner, yours first. A section header counts the sessions that ended before the window and offers the next wider window. When no session reaches the window, a line above the lanes says so; the axis stays, so panning and zooming still reach older sessions. A session with subsessions lists as a header lane (the session's title, "N subsessions" and their counts, with the Network glyph) followed by the session and its subsessions, oldest first, in the section of its most urgent member. A family starts open while live with eight subsessions or fewer, or when a subsession needs you; folded, it draws its parent's bar and a strip of its subsessions' most urgent state over time, and still lists any subsession that needs you. Disclosure choices last until the view unmounts.
Bars. A bar runs from the session's creation to its end or now. A dashed
outline covers Starting (queued and provisioning); then each span takes the
state run.status history gives it. History knows only the server's
needs-attention, so a past span reads Needed attention; the span since
the last change shows the viewer's own state (presentRun), which alone
knows Needs you, Paused and Finished: review. Once a session ends, its working
spans take its outcome's colour, so only live work reads Working. Time
before the history read is a dotted outline that says "History not loaded";
if the read fails, bars fall back to the current state and a Session history
callout shows the server's error with Retry. A working bar has a 2px end
cap and its activity text shimmers; a Needs you bar ends in a Needs you
tag. A session awaiting review never gets that tag; its label carries a
review-tone Finished: review chip instead of the Needs you chip. Finished
bars add "took 18m" after their end when there is room.
Messages and overlaps. Agent mail (coord.message, bundled per lane
pair within 24px) draws as marks joined by a hairline: a dot on the
sender's bar and a ring on the recipient's, at the send time, on the bar
edge facing the other lane, and a thin line between them under the bars.
The hairlines are fainter below 768px. Marks within 8px on one edge merge
and show their message count. Mail into a folded family or Finished marks its header. Mail with a session that
has no lane in this view (another workspace, hidden by Mine) keeps its
drawn end, marked on the top edge. A mark's or link's tooltip names sender,
recipient, time and how many messages are not yet acknowledged; a session
folded into a family or Finished keeps its own name and counts.
Each lane's accessible name ends with its mail, such as "messages: sent 2 to
Reviewer and received 1 from Reviewer, 2 not acknowledged".
Mail is not parentage: subsessions show as a family, and nothing draws
dependencies.
Mail that arrives while the view is open (appendLaneEvent records it in
laneArrivals; history pages never do) also draws a dashed arc from
sender to recipient and tints the recipient's lane; both fade out by 4.5s
and leave the marks. Mail sent over a minute before it arrives (a reconnect
replaying the log) and mail outside the time window draw none. More mail
on the same lane pair restarts its arrow with a count, at most three show at
once (a new pair replaces the oldest), and arrows at one moment step 16px
apart, starting 28px left of the window's end. Both ends sit at the send
time, and the arc bows left by 0.3 of its height (at most 56px), so it
stays clear of the now line and the bars' end caps. An arrow under 24px
tall, such as between adjacent lanes or a stub, stays straight so its head
points at the recipient.
An arrow follows a family that folds or opens while it shows. An end scrolled past the rows gets a pinned to/from button
that moves to it; mail with a session outside the view draws a short stub
labelled with that session, with the same button when its lane is scrolled
away. Nothing draws while the tab is hidden or Agent
messages is off. A second polite status line announces each burst once,
1.5s after its first message ("New message from Lead to Reviewer", or "3 new
messages: ...", listing at most three pairs).
Hovering, focusing or selecting a lane draws its mail as solid links (a dot
at the sender, an arrowhead at the recipient, hollow until every bundled
message is acknowledged) and greys every other mark and hairline. Chips on the lanes'
labels count that mail from the focused lane's side: ↔ 3 on the focused
lane (sessions it talks with), →2 ←1 on each of them. Sessions past the
scrolled rows get a pinned ↑/↓ button that moves to them, and mail with
sessions outside the view gets a dashed note. File overlaps draw for the
focused lane only, at the now line. Moving the pointer onto a link, mark or
pinned button keeps the lane that drew it. While the pointer heads for one of
the lane's pinned buttons and keeps closing in, the lanes it crosses wait:
one it rests on for 150ms, or crosses after a second and a half, takes the
hover. An
open popover keeps the lane it opened from in focus: lanes the pointer
crosses, or that lie under the popover, show only the hover band until it
closes. Clicking a mark or link opens its
facts, every bundle a merged mark holds;
a mail link reads the bodies through coord.messages.list (the thread, else
each sender's newest page, since a mark on a folded lane can bundle several
senders) and shows them with MessageRow. Styles: Lanes
has the colour coding.
Popovers. Clicking a bar or pressing Enter on a lane opens its popover
(with one open, one click on another lane, mark or link moves it there,
clicking its own lane again closes it, and dragging the track or a pinned
button closes it):
"agent · state · elapsed", the title, the reason, next step, branch and diff,
unread mail, pending inputs, overlaps and the state span under the pointer,
then the card's primary action (Reply opens the same composer as a card),
Open session and, for Enhanced sessions, Show agents, then the
lane's Messages by session (→ sent 2 · ← received 1, then each bundle with
its direction, time and "not acknowledged"; a session's name moves to its
lane) and any overlaps, each opening the same facts as clicking its link. A popover whose lane leaves the view, as when its session folds
into Finished, closes and puts focus on the lane that now draws the session. Show
agents inserts the session's subagents as sub-lanes: from the live session when
the session is open elsewhere in this tab, else from one run.acp.history page of
1000 items, which the empty state says. Selecting a sub-lane opens the
subagent. Escape closes and returns focus to the lane.
Keyboard. The lanes are one tree named "Session lanes" with one tab stop: Up
and Down move, Home and End jump, Right opens a section, a family or a session's
agents (or moves into it), Left closes it or moves to its parent, Enter or
Space opens the popover or toggles a header, and o and r open and reply as
on a card. Focusing a lane draws its mail as links and
chips, and its popover lists every message, so nothing depends on hover. The axis is a separate tab stop,
Timeline window: Left and Right pan by a tenth, + and - zoom, 0 or
Home return to now. A polite status line announces sessions that turn Needs you,
Failed, Finished: review or Completed, gathered for 1.5s and at most three at
a time (the Workflow panel's announcer, src/lib/use-announcement.ts).
Data. useLaneHistory holds laneHistory in src/store/lanes.ts while
the view is mounted and reads workspace.timeline backward with
types: ["run.status", "coord.message", "coord.message.acked"], 1000 a page,
until it passes the window's start, the log's start or 5000 events per
workspace; "Older history not loaded" marks the last case. sync.ts appends
live events of those types to held history, which keeps a workspace's newest
5000 and moves its loaded boundary past what it drops; the last view to leave
drops it, and a server switch or a new signed-in member clears it for a fresh
read. Lane geometry comes from the model
(model.ts, segments.ts, edges.ts, axis.ts), never from DOM
measurement; above 60 lanes only those near the viewport render. Live bars
move on a timer of window width per pixel, between 1s and 30s. Lanes move with
a glide only when they change section, and lanes added after the first render
fade in; reduced motion turns both off. A live update that moves lanes keeps
the view steady: the lane at the top of the scrolled view stays where it was,
an open popover follows its lane, a resting pointer hovers the lane now under
it, and keyboard focus on a lane that leaves moves to the lane that now draws
its session, else to its neighbour.
aether.ui stores the window choice, the grouping and hidden link kinds.
Below 768px the label column shrinks to the state dot and agent glyph, and
each lane's title moves into its bar; family members keep their tree elbow and
section headers keep the ended-before count.
Session state
A session shows one state and one plain-words reason line, derived in
src/lib/status.ts (presentRun). A live session's state is the server's
state field: the scheduler derives it, so the dashboard never infers a wait
from a reason string. A live session or stored run.status event from before the
server derived one has no state, and a newer server may send a state
this dashboard does not know: a running one reads Running with a
neutral dot, never Working, and a needs-attention one reads Turn
ended. The idle older servers wrote reads exactly as waiting; no
surface says Idle. The reason line is the server's status_reason (reason on the
wire) in plain words, such as an agent's waiting summary, "Turn ended
without a report" or "No update for 12m"; the dashboard never invents one.
Details lists the raw reason as Last reason.
stateLabel and stateTone in src/lib/status.ts are the one mapping from
state to label, dot colour and dot shape; the sidebar, board, session header,
session lists, activity feed and palette all use it. Each state has
its own dot shape and a text or aria-label label, so no state is told by
colour alone. Only Working pulses, breathing in opacity and size, except in
the sidebar, board, palette and All workspaces, and not under
prefers-reduced-motion.
Waiting states are a neutral, static glyph; Needs you is the only amber
state.
stateWords gives a state's words: the reason in place of the label when
the reason names what the session waits on ("Waiting for 2 subsessions", "Waiting
for Ada"), else the label and the reason after
it. stateDetail drops a reason that only restates the label or is the
state's default, so an unreported turn end reads a quiet "Turn ended" and an
answer "Answered" or "Answered · summary". Outside Needs you, where the
label and the reason alone lead, a board card puts the words' label in its
footer and their detail in its description ("Waiting for CI", "PR 12
checks"); the sidebar's accessible row name reads them joined. A session list
row puts the label in its status chip and the detail in its meta line.
stateTitle builds the tooltip each surface puts on a state, and the
sidebar's session details box shows it: "Words since relative - reason.
What happens next. Why: cause.", for example "Waiting for 2 subsessions
since 3 minutes ago. Mail from its agents can wake it. Why: its subsessions
are live." What happens next is said only where it is a fact or a request
of the viewer; no state that asks nothing tells the viewer to send a
message. Cause is the session's cause in words; it is shown only while the
session is live and shows the state the server chose, so not for a paused session
or a request shown as "Waiting for name".
A session that shows a reported wait carries wait, what Cloudfield verified
about the conditions the agent named (Waits Cloudfield can
check). waitLine words it,
and stateWords puts that in place of the agent's summary, even one that
reads "Waiting for ...", which moves to the tooltip as "The agent reported:
summary":
wait.kind |
Detail | Dot |
|---|---|---|
condition |
"Waiting on detail · checked 2m ago", aging with the half-minute clock | the state's |
source_unknown |
"Waiting on detail since 01:10 - error": the local time of the last successful read and the source's error verbatim, never the last status as current | dashed clock, neutral |
system_fault, still waiting |
"Wait fault: detail - error" | clock, failed colour |
system_fault, Needs you |
the Needs you reason, then " - error" | amber ring |
unverified |
the agent's summary; the tooltip adds "Not verified: the wait names no condition Cloudfield can check." | the state's |
toneOf picks the dot, and the tooltip gives the exact time of the last
read. Only the server's needs-you state lists a broken wait in Needs you;
a wait's kind never does. A phone's session header adds the wait's line, wrapped,
under the header, since its state line truncates; for a broken wait that
line is the Needs you reason with the error.
Rereads (reread: true events) update wait in the session store but never
count as a state change in the lanes or trace bars. A reported wait that went
stale (cause wait-expired) reads "Reported waiting on summary, no
update for 30m", and stateName labels it Stale wait rather than Turn
ended.
The session header's state line shows the words beyond the label the Workflow
chip under it already shows, a CI wait's age first ("42m · PR 12 checks";
a stale one's reason already says "No update for 30m"), since the header
prints no age of its own; stateTitle is the tooltip of
the space it fills, there even when the line is empty. The label stays in a
visually hidden role=status element, so a screen reader hears only a
change of state. While a session waits for agents,
the header counts the Enhanced session's running subagents, "2 subagents
running".
| State | Dot | Comes from | Group |
|---|---|---|---|
| Working | filled circle, pulses | state working (a turn is in progress), or queued / provisioning ("Queued", "Starting") |
Working |
| Waiting for agents | clock | waiting-agents: held background subagents or workflows, ACP Task agents, a session with live subsessions, or a waiting --for agents report |
Working |
| Waiting for CI | clock | waiting-ci: a waiting --for ci report |
Working |
| Waiting for process | clock | waiting-tools: a background task the agent holds, such as Claude's Monitor, or a waiting --for process report |
Working |
| Turn ended | dashed ring | waiting, legacy idle, or a parked session with no state: the turn ended without a verified reason. Asks nothing |
Working |
| Stale wait | dashed ring | waiting with cause wait-expired: a waiting report went stale. Asks nothing |
Working |
| Waiting | dashed ring | a session whose request waits on another member, read "Waiting for name" | Working |
| Answered | dashed ring | answered: an answered report, the agent replied with nothing pending. Its reason is the summary, with no call to action. Also a live finished session a member answered Not yet (no review, with a review_changed_at), read "Not finished yet" |
Working |
| Needs you | amber ring | needs-you: a reported question or blocker, a pending permission, an unanswered question |
Needs you, for the member a condition below names |
| Finished: review | filled accent circle with a check | finished (a reported success on a live session) unless answered Not yet, or a completed run whose review is ready or later |
Finished: review, never Needs you |
| Completed / Merged | check | completed, merged |
Finished |
| Finished: reported to its parent | check in icon-faint |
an attached subsession's reported success, which is for its parent agent only (failure-handling.md) | Finished, beneath its parent |
| Closed | ring with a bar | abandoned ("Closed without merging") |
Finished |
| Failed | cross | failed (an interactive failure parked for review, or a turn that failed), or failed |
Needs you for its owner while live and outcome_unseen, else Finished, sorted first |
| Interrupted | ring with an exclamation mark | interrupted |
Finished |
| Disconnected | broken ring, neutral | disconnected: the agent session or process ended while the session is open |
Needs you for its owner |
| Paused | bars | a live session paused by a member | Working |
The sidebar and session list show Finished: review as its own quiet group, with its own count, directly below Needs you; the sidebar shows three of its rows and a N more button for the rest. The board lists it at the head of Finished; the list layout, which folds Finished, shows it as a group of its own above Working. Lanes sections count a session and its subsessions as one, as the sidebar does. A finished session asks nothing of anyone, so it never adds to the Needs you count, a workspace badge or the desktop badge. In the session view its primary action is Review, which opens Changes.
Live actions (stop, pause, message, Stop waiting) still gate on the wire
status (running, needs-attention), not on the state.
status_seq increments on every change of a session's status, state,
reason, outcome flags or review. applyRunStatus in src/store/runs.ts drops a
run.status event whose status_seq is not greater than the one it holds,
and toRecord keeps every field such an event set (status, reason, state,
cause, status_seq, outcome_unseen, finish_unopened, review,
review_changed_at, finished_at) when a
snapshot is older, so an out-of-order event or a late run.get never moves a
session back. A snapshot at the same status_seq never sets outcome_unseen or
finish_unopened again once run.outcome_seen or opening the session cleared it.
A kill's or close's prediction clears state with the status. applyRunReview applies
a run.review event under the same status_seq rule.
Review is the owner's answer to a reported success
(failure-handling.md). run.review with
action complete closes a live session as completed (or records it on a
completed run) and sets review to accepted; later sets it to later
and leaves the session where it is; not-yet clears it on a live session. All
return {"run": Run} and need the same
permission as run.close.
The Needs you group, its counts and badges follow the session-state attention
rule push notifications, watches and aether sessions --needs-you
share (failure-handling.md): a live session (running or
needs-attention) that is not paused, with state needs-you,
disconnected, or failed while outcome_unseen. Waiting, every Waiting
for state, Working, a reported success awaiting review (review ready or
later) and a finished session never count. An attached subsession's
success or failure is for its parent agent only (outcomeHeld in
src/lib/needs-you.ts, failure-handling.md),
so it never counts either: the family stays in its parent's group and counts
the subsession as done or failed. Its run commands offer no Mark
complete, Not yet or Review later, and its session view shows no
completion prompt. The sidebar's Needs you count, the workspace badges and the
list's Needs you rows come from the same runRows, so they always agree. The request rows below need a live, unpaused session
too.
Needs you means the viewer can resolve it.
The queued message and teammate question rows are the dashboard's own:
they come from the room, which the session's state does not cover, so push and
aether sessions --needs-you do not announce them.
src/lib/needs-you.ts holds the conditions as one table, checked in order;
needsYou(run, ctx) returns the first that applies:
| Condition | Who it needs | Reason line |
|---|---|---|
| Pending sudo command of a Default session | owner or an admin | Permission requested |
| Pending native permission | owner or terminal controller | Permission: … (enhanced: Permission requested) |
| Pending native question | owner or terminal controller | Question: answer in the terminal (enhanced: Question from the agent) |
| Queued message from another member | terminal controller | Bob sent a message, approve to deliver |
| Teammate question to the owner | owner | Bob asked you: … |
state disconnected (labelled Disconnected) |
owner | the reason: Agent disconnected: … / Enhanced could not start: … |
state needs-you with a blocked: <summary> reason |
owner | Blocked: … |
state needs-you with a needs input: <question> reason |
owner | Agent asks: …, with Reply |
state needs-you with a usage limit Cloudfield will not resume |
owner | Usage limit reached on …, with Open |
state needs-you with an Enhanced turn interrupted or turn ended: <stop reason> reason |
owner | Turn interrupted · reply to continue / Stopped: the reply reached its token limit · reply to continue, with Reply |
state needs-you, any other reason: a permission or question not loaded yet |
owner | Open the session to see its request, with Open |
state failed with outcome_unseen (labelled Failed) |
owner | Agent reported failure; review the result / the reason: Turn failed: … |
Failed and Disconnected rows show their reason in full-contrast text, as a
Needs you row does. A control hold waits since the attempt's
takeover_since.
A device waiting for approval is not a session, so deviceNeeds in the same
file turns it into a card for an admin, and a member's own pending device
into a card for that member. The store's devices come from
member.device.list, which names whom approving admits each waiting
device as. It is read at hydration, on each member.device event (published
under the workspace id server, so the event's unknown workspace does not
drop it), and whenever the tab returns to the foreground or the browser
comes back online, which catches a failed read and an approval made with
sudo aether-server device approve, which publishes no event:
| Device | Who it needs | Reason line | Actions |
|---|---|---|---|
| Pending, waiting on an invitation | an admin | laptop (github mallory) wants to join as collaborator | Approve (member.device.approve {device_id}), Deny (member.device.revoke) |
| Pending, a member's | an admin | laptop (github bob) signed in as Bob | the same |
Registered under account, on a server now under approved-devices (from server.edge) |
an admin | laptop (github bob) signed in as Bob and is not approved | the same |
| Pending, the viewer's own | the member, not an admin | New device laptop signed in as you | the same |
| Pending, waiting on the viewer's account link | the member, not an admin | laptop (github bob-gh) is waiting on your account link | the same |
The card shows the account, the key fingerprint and whom approving admits it as, and waits since the device was recorded. No card carries an approval code. Merge proposal cards (Members, devices and Profile), then device cards, list before sessions in the board's Needs you and above the Map. The sidebar's Needs you counts them and shows one row, "laptop waiting for approval" or "2 devices waiting for approval", that opens the board.
A condition that applies to someone else leaves the session in Working with
"Waiting for Alice", labelled Waiting when the session needs its owner. A
Background (headless) run follows its state like any session; the server
does not count its native questions, and neither does the dashboard. It takes
no input, so its row offers Open, not Reply. A Working session's reason is what its agent is
doing ("Reading src/auth.ts", from run.agent), else "Agent working". A
reported success, unreviewed or not, is Finished and never lists in Needs
you.
Needs you sorts oldest wait first (waitingSince: the request's or
message's time, else the state change); Working and Finished sort by latest
change. Reason lines that name a wait re-read the shared clock, so "(12
min)" keeps moving.
The change time is stateChangedAt on the session record. A snapshot's
status_changed_at sets it: when the session entered its status, or its reason
while it needs attention. A snapshot can be older than the events already
applied, so for a session still in that status it never moves the time
backwards. A run.status event moves it to the event's time
on those same changes and leaves it alone on a same-status rewrite, as the
server does, so a retention relabel of a session that finished last week does not
make it the newest Finished row. An older gateway, and a session whose status
last changed before the server recorded it, send no status_changed_at; the
record then takes the session's finish, start or creation time and is marked
stateChangedAtEstimated, and it sorts and shows its change time by that
estimate.
Terminal controller comes from controller_member_id, which the
gateway decorates from the control lease on run.get and run.list (empty
when nobody holds it). A run.controller event, published whenever a lease
is taken, taken over, released, fenced or runs out its reconnect window,
keeps it current, so a teammate holding control of someone else's session sees
its requests without opening the session. Only a gateway too old to send
the field falls back to the session's cached presence status.
last_controller_member_id beside it names the latest member to hold that
lease, the current holder included, and the run.controller event carries
the same member as last_member_id. The server keeps it in memory with the
leases (LastHolder in internal/control), so the field is absent until
someone takes control after a server restart, and on a gateway too old to
send it. The explorer then has no last controller to put first or to name.
Paused comes from the paused field the gateway decorates from the
scheduler on run.get and run.list; a paused session still reads running.
The hydration snapshot seeds pausedRuns (seedPaused, skipping runs
without the field - a legacy gateway), and live pause/resume entries on
the workspace.timeline stream keep it current (pausedFromTimeline in
src/store/board.ts).
Unreviewed outcome marks a success or failure reported with
aether-internal report that the owner has not opened. Interactive Standard
and Enhanced sessions stay live at needs-attention, with the reason
agent reported success or agent reported failure; Background sessions finish.
The server owns outcome_unseen, so it survives reloads and needs only the
owner. watchOutcomeSeen (src/store/outcome-seen.ts) calls run.seen when
the owner reveals the session through navigate(), or is already on it in a
visible tab when the flag arrives. It makes one call per reveal: a refusal
shows the server's error and is not retried until the owner opens it again.
An answer is not ordered against the event stream, so one that a newer
run.status event for the session overtook is dropped and the session is asked about
again.
A reported success presents Finished: review whether or not the flag is set; a reported failure stays a Failed row in Needs you until its owner opens the session, the next turn or Close. A session that has ended is never in Needs you; it keeps its unopened marker in Finished: review or Finished.
Completion review is the owner's answer to a reported success, held by
the server as the session's review ("", ready, later, accepted) and
review_changed_at. A success report sets ready; opening the session does not
change it, so the session stays in Finished: review. While the open session is ready,
CompletionPrompt (src/routes/run/completion-prompt.tsx) shows an inline
callout above the Chat composer, or at the foot of any other session view:
"Your agent reports this task is
finished. Mark complete?", the summary of the session's latest success
report (three lines, with Show more when it overflows them as laid out;
opened, it scrolls within 30% of the viewport), Mark complete,
Not yet and Review later (Not yet only on a live session), and "Closes
the session.", which also describes Mark complete to assistive technology.
Mark complete is a secondary button, and no button takes focus on its own. Each is a run command
(src/lib/commands.ts) that follows Actions: Mark complete
(complete) sends run.review {action: "complete"} and predicts review
accepted and, for a live session, status completed; Not yet
(not-yet) sends action: "not-yet" and predicts ""; once the server
accepts it, the command opens the Chat view with the composer focused, from
the callout, the actions menu or the palette alike, and the composer's
placeholder reads "Say what is left to do". Review later
(review-later) sends action: "later" and predicts later. A refusal puts
the callout back and toasts the server's error. While review is later the
callout folds to one line, "Finished, kept for later ·" and Review now,
which unfolds it. After Not yet the session reads Answered, "Not finished
yet" (notFinishedYet in src/lib/status.ts), its Chat view records
"name said the task is not finished yet" from the run.review event, and the callout
stays hidden until a new success report sets ready again. The session's
actions menu and the palette offer the same commands, except that until
someone opens the result (finish_unopened, which any member opening the
session clears) they offer Review the result, which opens its Chat view,
in place of Mark complete. All need the gateway's run.review
method and the kill permission.
An interactive session still accepts messages and terminal input; the reason
line says it remains open for follow-up. Its next working turn returns it
to Working. Archive eligibility and input gates use the wire status, not
the presentation state: a reported interactive outcome is not a closed session.
Use Close to end that session and start its container retention grace.
Unopened finish marks a Finished or Failed session that no member has opened
since it finished, with or without a report: an exit, a failure, an
interruption and a parent closing its subsessions count as much as a reported
outcome. A session a member closed or stopped is not one: ending it is dealing
with it. The server owns finish_unopened, so one member opening the session
settles it for every member and device. watchOutcomeSeen makes the same run.seen call for any member
who reveals such a session, or is already on it in a visible tab when it
finishes, under the same one-call-per-reveal rule; the owner's call clears
both flags. The flag only keeps the session's sidebar row from receding (see
Sidebar); it moves no session between groups and changes no order.
Execution, input and paused on the wire
The parked reason survives a fetch. protocol.Run carries reason -
the last run.status reason, persisted with the session and sanitized
server-side - so a session that was already in needs-attention when the tab
loaded still says why: waiting for your input and its siblings when the
agent reported it, stalled: ... when the silence heuristic parked it.
toRecord in src/store/runs.ts prefers the wire reason and falls back to
the previously stored one only when the fetch omits it and the status has
not changed (a legacy gateway); a live run.status event still overwrites
it with the event payload's reason. An unanswered
room question remains the card's actionable summary.
Needs you is an activity, not a new lifecycle. The persisted/wire
status remains needs-attention. Turn completion, silence and prose such as
the legacy waiting for your input reason are not evidence of a request;
only the server's needs-you state and the request rows above are.
Requests are independent of execution. A session snapshot's pending_inputs
contains native request identities (id, session_id, and kind: question,
permission, form, or extension_ui), never prompt bodies or answers.
The durable run.input event replaces that set via {pending_inputs: [...]};
an empty list clears it immediately. Closing one request leaves the others
visible. Session headers, cards, lists and sidebar rows combine this set with
unanswered teammate questions, including room
questions after execution finishes. Counts and tooltips name the source.
Native prompts are answered in the Terminal on a Standard session and in the
Chat view on an Enhanced one, and teammate questions in Details.
Unsupported native integrations show no inferred request.
A terminal lifecycle transition also clears native requests if its empty
run.input event is lost. Later native input events cannot revive a request
on a finished session. This does not clear teammate questions.
Hydration is authoritative and queues live events until its snapshot lands. Ordinary session upserts preserve a known input set, including an empty one, so an older route, room or launch response cannot resurrect a closed request. A terminal upsert clears native requests instead. Input events for unknown sessions follow the existing fetch-first and ordered-cursor rules.
An unreviewed finish is server state. Run.outcome_unseen on run.get
and run.list is true while an agent-reported outcome is unopened by the
owner; absent (an older gateway) means false. Every run.status event sets
the flag to its payload's outcome_unseen, the row's flag after that event -
a same-status re-label such as retention expiry included - so a later close or
reopen clears it. A run.outcome_seen event, or the Session run.seen returns,
clears it. run.seen is gated on cap.hasMethod('run.seen') and idempotent;
only the owner's call clears this flag.
So is an unopened finish. Run.finish_unopened on run.get and
run.list is true while no member has opened a finished session; absent (an
older gateway) means false, so every finished row recedes. Every run.status
event sets the flag to its payload's finish_unopened the same way. A
run.finish_opened event, a run.outcome_seen event (the owner's open
clears both flags), or the Session run.seen returns, clears it.
Paused hydrates from the same snapshot. With paused on the wire
(above), a reload shows Paused for a session paused earlier, and the
palette offers the right one of pause/resume. Against a legacy gateway
whose sessions carry no paused field the state stays unknown until a live
workspace.timeline pause or resume arrives, and neither surface offers a
verb rather than offering the one the server would refuse.
All workspaces
The global overview route (src/routes/overview.tsx) is All workspaces:
every session in every workspace in one RunList, in the board's group order
(Needs you, Working, Finished) with a StatusDot and the state word per row.
A subsession whose parent is also listed is indented under it, by the board
map's rule (runParents in src/routes/board/map-layout.ts); a detached
subsession stays in place. The tree sits where its earliest member falls, so a
subsession that needs you lifts its parent into Needs you. The parent's chevron,
Hide <n> subsessions, folds the subsessions that do not need you and is
absent when all of them do.
It is reached from the workspace switcher, g then l and the palette's
Open all workspaces.
Commands and the palette
src/lib/commands.ts holds the commands as data: an id, label, icon,
capability gate, optional confirmation and call. Session verbs (runCommands):
Pause session / Resume session, Send a message to the agent…, Forward a
port… (local gateway), Close session…, Kill run, Delete run, Free
sandbox…, Archive run / Restore run, Protect run /
Unprotect run, Relaunch, Pull branch (local gateway) and Hand
off to <member>. Pull branch fetches the session branch into the linked
repository; unless you are already on that branch, its toast offers Switch
to it (pull.switch, which refuses a dirty checkout with git's own
reason) and Copy command (git switch <branch>). Board verbs (boardCommands): Open the board, Open
all workspaces, Connect ChatGPT or Claude (these three in the Navigate
group), Ask Cloudfield (opens the assistant; offered when the server
serves assistant.status), New session…, Launch from a template…,
Archive finished sessions…, Free retained sandboxes… and the three theme
commands. Each verb is offered only when the server would allow it: the gates
ask the same questions internal/permissions does. useCommandRunner()
reports gateway success or its real refusal in both the session's More menu and
the palette. Pause, resume, kill, close, delete, free, archive, restore,
protect and unprotect follow Actions: the command's predict
names what the server's success certainly sets (pausedRuns; status
abandoned with reason killed; the chosen status for close, which
like kill clears state; the session's removal for delete; cleared
container_retained_until and cleanup_pending; archived_at;
protected), the runner shows them at
once, and the success toast waits for the answer. A refusal puts back each
predicted field that still holds its predicted value; a field anything else
wrote meanwhile stays. With no answer by the deadline, or a failure that
carries none, the runner does not guess: it re-reads the session with run.get
(bounded by the same deadline) and applies the server's record. If the
session's record or pause state changed while the read was pending, that change
is newer than the read, so the read only replaces the predicted fields that
still hold their predicted value. If the read's record shows the predicted
state, the verb counts as confirmed (a field the
wire omits at its zero value, such as protected, reads as false) and toasts
its success; otherwise the toast reads "The server did not answer in 5
seconds." with Retry. If the re-read fails too, the predicted fields
still on screen are put back and the same toast shows. The toast keeps
Retry until it is pressed or the late answer arrives: a late success
dismisses it, a late refusal replaces it. While another predicted verb is
pending on the session, Retry sends nothing, stays, and a second toast says
why. Each Retry is a new attempt
with its own captured state. Once any attempt of the verb succeeds, no
other attempt puts it back, a re-read answered before the commit is
ignored, and an earlier attempt's late refusal is dropped. Once the
signed-in member changes, the toast is dismissed, its Retry sends
nothing, and the press's late answer, re-read or refusal changes and shows
nothing. Kill, close, delete and free
(slow on the command) skip the deadline, because the server answers only
after the container stops: run.kill waits out the runtime's stop grace,
10 seconds by default; run.close also commits and publishes a live session,
and run.delete purges its evidence. Past the deadline their prediction stays, More
shows a disabled "Still waiting for the server…" entry (waiting on the
session's predicting marker), and a late success clears it without a toast.
Their server can publish a new status, such as a killed session's abandoned,
before a later step fails, so a refusal re-reads the session with run.get,
bounded by the deadline: the session shows what the server holds, the server's
error is toasted, and only a failed re-read puts the prediction back. A failure
that carries no answer still re-reads the session, and if the re-read does not
show the result, toasts that failure's own error with Retry. Kill's predicted change time carries
stateChangedAtPredicted, so the server's run.status event replaces it
even when the status is unchanged; any other estimated time stays. While a
predicted verb is pending on a session (predicting in store/runs.ts, held
by that attempt's marker so a late answer clears only its own lock), More
and the palette offer no other predicted verb for that session, because one
offered from the predicted state, such as Archive after Kill, could re-read
the session and overwrite the prediction. Both subscribe to the lock, so an open
menu shows the verbs again once the answer lands. An invalid-state refusal
(codeInvalidState, such as "session is already paused" after a retry) re-reads
the session with run.get instead, bounded by the deadline and applied on the
same condition, and toasts only if the session does not show the
predicted state; a repeated run.close with the same outcome is answered
as a success. Delete takes the session off every list at once: deletingRuns
(store/runs.ts) holds its record, and neither a snapshot nor an event's
run.get puts it back before the answer. A re-read that finds the session puts
it back as read, and a refusal whose re-read fails puts back the held
record; not found from run.delete or from any
re-read counts as deleted, because a Retry can resend a delete that
landed and another client can delete the session before its run.deleted
event arrives. Over another verb's pending prediction, Delete and the Close
dialog's choice do not predict: they wait for the server, as an
unpredicted verb does. Archive, restore, protect and free do not overwrite
the server's events with an RPC response.
- Forward a port… opens
forward-dialog.tsxover the localforward.*verbs. It forwards the port typed to the same port on this machine and lists the ports forwarded from that session, each a link tohttp://localhost:<port>beside Stop. For a session it readsdev.port.listfirst: a port bound to loopback is refused with the address it is bound to, and a port nothing listens on is forwarded with a note that its link works once something does. The Environment page's Forward port opens the same dialog for the environment, whose ports no method lists. - Archive / Restore are gated on
isTerminal(status)(src/store/runs.ts;completed,merged,abandoned,failed,interrupted) plus the kill permission and therun.archivecapability; neither confirms, since archiving is reversible. The palette resolves its focused session from the session map byroute.params.runIdrather than the session list, so an archived session's own page still offers Restore. - Free sandbox… removes a finished session's retained sandbox and keeps
the session and its history; the session can no longer be reopened. It needs
run.release, the kill permission and a retained-container reason (isRetainedRun). A freed or expired session no longer offers it, and the server checks the lifecycle again if the session changed after the menu opened. - Relaunch resumes a retained Standard or Enhanced session after explicit
Close (
aether reopenon the command line). It is offered in More and as the primary button in the composer slot of a finished session, which callsrun.relaunchand swaps the finished record for the live one the server returns. A session is eligible while the server reportscontainer_retained_until(or, before that arrives, a retained-container reason). Relaunch clears the deadline, the status event dropsfinished_atandstarted_atrestarts, and the next close sets a fresh deadline. Reported interactive completion needs no relaunching. Older agent-finished retained sessions remain eligible. - Hand off and Protect need the session's owner or an admin. Before
hydration the caller's own record has not arrived, and the mirror answers
yes rather than making the shell's buttons appear a beat late. Pull
branch is the desktop gateway fetching a published session branch into the
repository on this machine, so it answers to
hasLocal('pull')alone. It does not refresh a workspace base or authorize a mirror source.
A command with a confirm field - Kill, Delete and Free sandbox - opens
the session-naming confirmation (run-command-confirmation.tsx) from More or the
palette, with Cancel initially focused. Close session… opens its own dialog,
which asks whether the work was merged or abandoned; a choice closes it and
shows the outcome at once. The dialog reads run.close_check when it opens
and lists the warnings with CloseWarnings (src/components/close-warnings.tsx),
which orders them by risk (pull requests, read as one line of numbers when
there are several, and unmerged work, then mail, waiting sessions,
subsessions with their own warnings nested under each, cleanup,
protection). The buttons read Close as abandoned and Close as
merged; with any warning abandoning is danger and merging secondary,
without one merging is the primary. On a phone they stack in reading order,
Cancel first. Cancel holds the focus with the ring drawn (focusRingShown); closing as merged ignores
unmerged_work. A command with closes (Mark complete, outcome completed)
is checked by the runner itself before it runs, once at a time per session
(closeChecking): with warnings, or a check that failed, the runner opens
CloseConfirmation instead, and Close anyway runs the command. More locks
while that check and the close run. A check that has not answered within 15
seconds counts as failed, so no close waits on it forever. Open in Standard lists the same warnings in its
confirmation. Palette confirmations
capture the authenticated identity with the session and command; an identity
change dismisses a pending or visible confirmation instead of applying it to
another account. More locks while an unpredicted verb is in flight and shows
a spinner in place of its icon, which also stops a second click racing a
branch pull over SSH.
The command palette (src/components/palette/) opens from Search in
the sidebar or the phone top bar, ⌘K on macOS or Ctrl+K elsewhere;
Cmd/Ctrl+Shift+P remains an alias. Its groups are Navigate (the board
verbs' destinations and the gated src/lib/surfaces.ts list), Sessions,
Workspaces, Focused session · <title> on a session page, and Board
actions. Navigation comes first, so opening the palette initially selects
Open the board, not a mutation. With an empty query Sessions lists the
first 50 sessions in group order, Needs you first; a query searches every session. A
session matches on its label, branch, agent, workspace name and session ID, never the
full task text. Opening a workspace also makes it the active scope.
Nothing important is reachable only by a shortcut: New session is in the sidebar and on an empty board, destinations are sidebar rows, and every session view has the header's primary action and More. Appearance has explicit Use system theme, Use light theme and Use dark theme commands that set the same persisted preference as Settings.
The palette ranks with cmdk's default scorer. A command matches on its label
followed by its aliases, Command.value in src/lib/commands.ts (a
destination's keywords in src/lib/surfaces.ts), so a label that starts
with the query outranks an alias match: "delete" ranks Delete session
above Close session…. cmdk matches subsequences, so check that a new
alias does not pull a destructive command into an unrelated query; typing
never runs a command, and Enter on a confirmed verb opens its confirmation.
The pinned local cmdk patch
in patches/cmdk@1.1.1.patch stays because stock cmdk 1.1.1 leaves the
input's aria-activedescendant unset for the initial selection and stale
after filtering, and spreads caller props before that attribute, so no
wrapper can correct it. The patch also adds the list's browseOrder, which
restores current browse order when a query is cleared, and avoids redundant
scrolling and DOM reordering. Filtering and live data updates keep the
input focused and its active descendant tied to a visible enabled result.
The forms
Three verbs that need prose open a dialog rather than calling straight
through: launch, send a message to the agent, and launch from a template.
The message form is inject-dialog.tsx over run.inject; each submission
includes a caller-generated idempotency_key, which stays the same when the
request is retried and changes only after the message payload changes or the
submission succeeds. The server records the message as a room
steer_request, so it follows the controller lease, 45-second queue,
moderation and receipt rules. The launch and message forms are store dialogs
(openPaletteDialog on the palette slice) hosted by AppShell, so a
button on any surface opens one by asking the store, with no dependence on
the palette being on screen. The template form's open state lives with
CommandPalette in index.tsx instead, because the store's dialog union
does not include it. Its body is the composer's template library (see
Templates) with Launch as the primary action: it starts the
session with template.launch, sending the name and the filled-in parameters,
then reveals it. A refusal shows the server's error and any setup output.
The launch form lives in components/launch/. It asks for a
task, an agent, an account when one is shared with the caller, a mode and a
model. The agent picker is a list of rows from agent.list: the vendor glyph
in its colour, the display name, and "Ready" or "Sign in after launch"
for a shipped agent (login_found checks the launch home for login files, not
for a working session; a server that does not report it shows nothing), or
"Signed out" in the needs-you colour, with login_problem as its tooltip,
for any agent whose login file cannot sign it in (login_blocks_launch), or
"Sign-in refused" when login_problem is only an agent's own refusal. Such
an agent stays selectable: the server refuses the launch itself when
login_blocks_launch is set, unless a workspace variable signs the agent in.
For the chosen agent a needs-you callout under the refusal notes says
"Claude Code is signed out" or "Claude Code's sign-in was refused" (on a
shared account "<owner>'s Claude Code login is signed out" or "<owner>'s
Claude Code sign-in was refused") with login_problem verbatim; on the member's own
account it has Sign in on Agents, which closes the dialog and opens
Agents, and on a shared one it says "<owner> signs in again on their Agents
page or with aether agent login <agent>". While
the list is read again for another account the last one stays, dimmed and
disabled, and Launch stays off until it answers. An agent
that is not installed is not listed. Install more agents... below the
list closes the dialog and opens Agents. The last row is custom, the escape hatch that
agent.list never returns and that only launches where the deployment pinned
an agent definition with --agent-definitions. With nothing installed,
nothing is preselected, Launch stays disabled, and the form says "No agent is
installed in your environment." with a Set up an agent button in place of
Install more agents.... The list is read each time the dialog opens; a failed read
shows its error and no setup button, and Launch stays disabled.
The Task textarea grows as text is typed or pasted, up to 12rem; longer tasks scroll inside the field. A shared prompt grows without that cap so the whole prompt is visible.
On desktop, clicking outside the form or pressing Escape slides it away and leaves an arrow at the sidebar edge (the window edge when the sidebar is hidden). The outside click still reaches the view behind it. The arrow and New session restore the task and launch settings. X and Cancel discard this draft; they do not reset saved launch defaults. A picker handles its own Escape first.
The task and launch settings save on change in browser-local storage, scoped to the server and signed-in member. Refreshing or reopening the dashboard in the same browser profile restores a collapsed draft; another device, browser profile or the desktop app has separate storage. Edge-linked gateways keep the draft in memory only because another app could serve script from the gateway's loopback port. A read error is shown; the current form is kept in memory until the user starts a fresh draft. Clearing site data removes it. A successful launch clears the draft; a failed launch keeps it. Collapsing during launch keeps the pending request, so reopening does not launch twice. Shared text waits while a draft exists rather than replacing it.
Below 768px the same form is a bottom sheet (phone-launch.tsx): Task
first, focused, with one-word help; then the Repository chip, the base
branch as muted text ("from main"; sessions always start from it) and the
Agent chip; then Launch pinned under the form. Permission, the
account and fallback, Mode, Model, Effort, Resource limits, Subsessions and
extra repositories sit under More options, whose caption names the mode
and, on a shared account, "<owner>'s account", only the name truncated, with Install more
agents... at its end. Closing the sheet returns focus to what opened it. The repository starts
on the workspace of your newest session that you started yourself (not a
subsession or a connector launch) in a workspace that still exists, read once
when the sheet opens; without one, the active workspace. The agent is your
saved agent; with none saved, that session's agent if it can launch; then as
on desktop. A line under the chips says which of the two match that session. A repository chosen here affects only
this launch. If the chosen workspace is deleted while the form is open,
Launch turns off and a callout says so; the task is kept. With no workspace
at all the sheet says so and offers Add a
workspace, which opens Manage workspaces. A refusal shows between the
form and Launch, outside the scrolling form, so the keyboard cannot hide it;
past 40% of the screen it scrolls. So a quick task is three steps: New,
type, Launch.
Sharing from another app. Opening /?new=1&prompt=<encodeURIComponent(text)>, or
the gateway URL with &new=1&prompt=... through an edge, opens New session
with the text as its task. It is the entry point for sharing from another
app, so the text only fills the form. At load, before any route is written to
history, initialRoute (src/lib/url-state.ts) takes new and prompt off
the address with history.replaceState and keeps the text in memory, so
neither Back nor a reload brings it back; a prompt without new=1 is
dropped. Once the server has answered (not only a saved snapshot) and no
other form is open,
useSharedPrompt (components/launch/shared-prompt.ts) opens the form,
keeping the first 8000 characters (counted by code point, so an emoji is never split) and saying so in a toast when it cut any.
Above the task a callout says "Shared from another app: review it before
launching" with the character and line count, and the task field grows to
show all of it; both go back to normal once the text is edited. Only the
address read at load carries a share, so each one meets a fresh form. A
member who cannot launch gets a toast with the reason: the gateway has no
run.launch, or the role cannot launch. On desktop the panel opens the same
way.
Mode is a segmented control with one line per mode: Enhanced (acp,
"Native messages, approvals and progress", see
enhanced-sessions.md) with a Recommended badge,
Standard (tui, "Your agent's own terminal") and Background
(headless, "Runs the task once, no interaction"). Enhanced is disabled,
without the badge, with the reason under the control when the agent reports
enhanced: none ("<agent> has no Enhanced support.") or the adapter is not
installed ("The Enhanced adapter for <agent> is not installed.", with
Set up). A launch never switches mode on its own: the mode sent is the
one the control shows, and a refusal from run.launch appears in the dialog
verbatim under "Launch failed" while the dialog stays open, until another
agent or mode is chosen. run.launch answers only once the session is
provisioned, which can take seconds, so the dialog navigates only then: until
the answer the button reads "Launching…" with a spinner,
and past the deadline "Still waiting for the server…". A refusal that
arrives after the dialog was closed shows as a toast. The task is
optional in Standard and Enhanced - a taskless launch opens the agent with
no prompt - and required in Background, which takes no input, so Launch
stays disabled until one is written (runLaunch in
internal/sshd/handlers.go is the same rule). The mode always goes on the
wire, since a run.launch without one starts Enhanced where it is
installed; an empty task is left out.
Model, under Mode, is a searchable picker (ModelPicker in
src/components/launch/model-picker.tsx) whose choice is sent as model on
run.launch and passed to the agent as is
(per-agent flags). Its first entry, Agent
default, sends no model and shows what that default resolves to when the
agent reports it. The rest come from agent.models for the chosen agent and
account, fetched when the field first shows and kept for the page session;
the refresh button asks again with refresh: true. The list says when it is
the agent's cache, and shows a failed discovery's error verbatim without
blocking a choice, after List from <age> when it keeps the last list that
worked. Search matches id, name and description;
text that matches no id is offered as Use “<text>”, so any id works,
including for agents with no discovery. A saved model missing from the list
stays selected. A model that is not a single argument is
refused by run.launch and shown under "Launch failed".
Effort, under Model, shows only for an agent whose agent.list entry has
effort_levels. It is a select (EffortPicker in
src/components/launch/effort-picker.tsx) of Agent default, which sends
no effort, then those levels in the agent's order
(per-agent levels). It starts at Agent
default and is not remembered; switching to an agent without the chosen level
resets it.
Permission (PermissionControl in
src/components/launch/permission-control.tsx) is the session tab's first field
when server.info lists the permission feature. Its three segments are
Root access, Default (marked Recommended) and Isolated
(permission tiers); Root access is ringed in
the needs-you color when chosen, and a line under the segments says what the
chosen tier allows. It starts on the saved permission, else Default, saves
each change through launch.defaults.set at once, and goes on the wire as
permission. A server without the feature gets no field and no permission.
Where the gateway offers launch.defaults.get, the form starts from the
member's saved launch choices on the
server (store/launch-defaults.ts), so every browser and device opens on
the same ones. Each open reads them again, since another device or the
assistant may have saved since. The first pick waits for that read and for
the saved account to be applied, then
preselects the saved agent if it can launch, else the agent of the newest
session, else the first launchable one, in that agent's saved mode, else
Enhanced, with its saved model. A successful launch saves only the
agent, mode and model through launch.defaults.set with the revision it
read; when another device saved since, the refusal carries the current
choices, and the form applies its change to those and saves once more. A
failed save shows "Launch choices not saved: " and the server's error. The
saved account is preselected when account.list still lists it and get
does not mark it invalid, and the saved fallback policy fills the fallback
list, keeping only listed accounts. A launch never saves the account or the
fallback; Save as my default under Account does, and says "Saved
for every device." until the account or fallback changes again. It saves the fallback list as the session sends
it, without the selected account. Session, Default mode and Set up on
Agents, and the onboarding wizard, save their agent and mode the same way
(rememberChoice); Default mode leaves the preselected agent alone.
Agents reads the saved choices too, and its Default mode and Session use
the saved mode, else this browser's. Saves
run one at a time, each from the last one's answer; a save after the
signed-in member changes is refused, and a failed save reads the choices
again. A read's answer is dropped when another read or a save started or
stored its answer after the read began. A Saved defaults not used note lists each saved
account, fallback member, agent, and the chosen agent's mode or model that
get reports in invalid, with the server's reason.
Where the gateway does not offer launch.defaults.get, the form uses this
browser's copy instead: the launchDefaults slice ({mode, model, at}
keyed by agent name), persisted per member in savedLaunchDefaults;
defaults saved before persist version 10 had no owner and are dropped. It
preselects the launchable agent launched most recently, then as above. When
the read fails, the form says "Your saved launch choices could not be read."
with the server's error and Try again, and starts from the copy last
read from the server, else this browser's; a retry that reads them presets
the agent, account and fallback from them again. Every launch also updates
this copy; nothing copies it to the server. On a server that offers
launch.defaults.get but has nothing saved for the member, the form ignores
this browser's copy and uses the server's defaults, so a new device and an
old one open on the same choices. The form starts over when a different
member signs in while it is open. An Enhanced or remembered mode the agent cannot
use (no Enhanced support, or its adapter not installed) shows as Standard.
Account (account-picker.tsx), below Agent and above Mode, appears when
account.list returns more than the caller. It is a radio list: the caller
first, marked "You", then each account shared with them, marked "Shared".
Launch stays disabled while account.list is pending or failed. A failure
shows the server error and Retry account read; the saved account is only
replaced after a successful read confirms it is no longer available.
If the gateway does not offer account.list, the form uses the caller's
account and does not offer shared-account launches.
Each row ends with what a launch of the chosen agent there meets, read once
per open with agent.list and account.usage for every account, four reads
at a time, and nothing until that account's agent.list answers: "Not
installed", "Needs <owner>'s login", "Your account only" or "Unavailable"
(its error as the tooltip) from the agent.list fields below, else the
agent's fullest current usage window as "<n>% used" (amber from 80%, red at
100%, as on Settings > Usage; "· stale" with the provider's error as the
tooltip when its last read failed), else "Sign in after launch" when
login_found is false, else "Ready". "Signed out" or "Sign-in refused"
(needs-you, login_problem as the tooltip) comes before the usage window. A failed agent.list reads "Not
checked" with the error as the tooltip; a failed account.usage puts its
error on the status's tooltip. Expired windows drop on the half-minute
clock. A status takes at most 60% of its row, here and in the agent list,
and clips an owner name past 13 characters, whole in the tooltip. A shared
selection says "Uses <owner>'s <agent> login and quota. Runs
in your environment with your GitHub login; the session stays yours.", and
sends its ID as account_member_id on agent.list and run.launch;
run.launch refuses an account not shared with the caller with the server's
error under "Launch failed". Under the list sit Fallback and Save as my
default. agent.list still
returns the caller's own agents and installations, since the session executes
in the caller's environment, and marks each agent the account's owner has no
login for with login_missing, each name that resolves to the caller's own
member-defined agent with own_account_only, and each agent whose owner
login exists but cannot be shared with unavailable and the launch's own
error. The form takes the reason from those fields, never from source: a
member-defined name that is also a server-wide definition launches the
server-wide one, so it can be login_missing. Refused rows are disabled
("Needs <owner>'s login", "Your account only", "Unavailable"), and one note under
the picker says "<owner> is not logged in to <agent>" and that the owner logs
in from their own Environment, that the caller's own definitions run only
on their own account (choose your own under Account, or More options →
Account on a phone), and "<agent> cannot launch on this account: " with
the server's error unchanged. On a shared account with nothing installed the
heading reads "Neither you nor <owner> has an agent installed." and the note
says the session uses the owner's login and the caller's installation, or the
owner's when the caller has none.
Where the server offers run.children.allow, the form has a Child
sessions select: Use my setting (naming it, "(off)"), Allow for this
session and Off for this session, sent as run.launch subsessions: "on" or
"off"; the first sends nothing.
The collapsed Fallback under the account list, whose caption reads
"Automatic", "Ordered" or "Off", then "if <owner> runs out" with only the
name truncated, holds the usage
fallback controls (launch-options.tsx): a
Fall back to another account checkbox and the Fallback accounts list,
each account with a checkbox, "You" or "Shared", the account list's status
("Skipped: <status>" where a launch would be refused, which usage fallback
skips too, and "No saved login" for "Sign in after launch", whose tooltip
says a launch may still fall back there, last, but a running session moves
there only with an API key),
and Move <name> up / Move <name> down. A hint names the rule: "If
<owner>'s usage is 95% or more at launch, or the vendor reports the limit
mid-session, the session moves to the ticked account with the most usage
left.", with "the first ticked account, top to bottom, with usage left" once
the list was changed. Untouched, the form sends neither field and the server
orders by usage left. After a reorder or untick it sends the ticked accounts
in order as fallback_account_member_ids; with the checkbox off, or every
account unticked, it sends no_fallback: true. The list leaves out the
selected account but keeps its place and tick, so selecting another account
and editing the list never drops it; changed from automatic, the list adds
it last, ticked. An account the changed list did not hold, such as one
shared since, joins it unticked.
The launch form does not ask which workspace to launch into: it takes
activeWorkspace and says where the session will land, naming the workspace and its
base branch. The switcher is the picker, so a second one inside the dialog
would be a place for the two to disagree.
Launching is gated on run.launch and on the launch permission
(canLaunch). The local gateway advertises every method regardless of who is
behind it, so capability alone would put the button in front of someone the
server would refuse.
Base capture is server-side and precedes row creation. A mirror or local-base failure is reported by Launch and leaves no session row; the dashboard does not run a client-side base refresh before trying again.
Chat view
src/routes/run/ is the one run route. Its params are runId and an
optional view (session, trace, terminal, changes, files,
browser),
written to the address as ?run=<id>&view=<view>; the old ?view=diff reads
as changes.
Every way into a session navigates to run: board card, sidebar row, session list,
palette, feed entry, approval, conflict chip, template, and the launch and
onboarding forms. A view the address does not name is the one the member last
chose for the session, else defaultView. Choosing a view means picking a tab
(click, [ or ]) or following a link or command that names a
view, such as Review changes or a file path; an opened ?view= address shows
its view without choosing it, since a reload reopens one too. Reply is not a
choice. Session rows, card titles and u open the last chosen view even when
the session needs attention. Explicit actions, such as Open terminal or Review,
open the view needed for that action without changing the choice. Back and
forward show the view their entry names without choosing it. runViewMemory
holds the choices, the newest 200 sessions per signed-in
member, saved under aether.ui in savedRunViews by identity key, so they last as long as the browser origin's storage (the desktop app's origin changes each launch); deleting a
session drops its entry. A chosen view the session no longer has, such as
Files without a checkout, gives way to defaultView.
defaultView is
Session for an Enhanced session or any session that streams a session (acp: true),
Terminal otherwise. Trace follows Chat for a session with acp: true only.
Files is in the list while the session still has its
checkout, on a gateway that serves files.tree (hasFiles in
src/routes/files/open.ts): every session the Files tree lists, a completed one
that is not yet merged or abandoned included. Browser is in the list for
every session that has not finished, on a gateway that serves
dev.browser.status (hasBrowser in src/routes/browser/open.ts); no
browser has to be running, and opening the view starts none. isRunRoute in
views.ts keeps a sidebar row lit across views.
The frame (header, view switch, Details) stays mounted while the view
changes; CenterView remounts it only for another session, identity or event
epoch. Session, Terminal, Changes and Files mount on first visit and stay
mounted, laid out but invisible and inert: xterm hidden with
display: none measures zero and would resize the shared PTY, a Publish
draft (commit message, an uncertain pull request) must survive a view switch,
and an open file keeps its scroll position, caret and undo history. Browser
and Trace mount only while shown, so a hidden Browser streams no screencast
and a hidden Trace derives nothing and ticks no clock.
The Browser can also sit beside the other three views instead of being a tab:
its toolbar's Show beside Session (Show beside Terminal on a Standard
session) docks it at the right of the frame with a divider, and Show the Browser
as a tab puts it back. The choice and the divider's position are view
preferences (browserBeside, browserBesideWidth, persisted). Docked, it
stays on screen across Session, Terminal and Changes, leaves the view switch,
and each side keeps at least 320px (BrowserDock in
src/routes/browser/dock.tsx). The frame is measured, not the window: the
toggle is offered only while the space left by the sidebar and Details is at
least 640px, and below that the Browser is a tab whatever the preference
says. The divider is a separator that takes a drag or the arrow keys, Home
and End.
The agent's attach lives in useAgentTerminal at frame level, so switching
views never reattaches, and useRunRoom reads the newest room page once per
frame, then follows workspace.room_message events. An event naming a
message the store already holds in the event's state, such as the author's
own post, reads nothing, unless that message is a steering request, whose
agent delivery the payload does not carry. After the event stream reconnects
it reads back to the cached history, as one page or more, so a gap is
closed; each older page merges below the pages before it, so same-instant
messages keep the server's order. It polls presence every ten seconds with an abortable 15-second
deadline.
While other members watch the session, the composer shows a line above the
message box, in the space of its own fixed height: Alice is typing...,
Alice and Bob are typing..., Alice, Bob and Carol are typing..., and
Several people are typing... past three. The dots animate unless
prefers-reduced-motion is set. Your own typing is never listed. Each
keystroke in a draft calls presence.typing (Steer on the session), at most once
every 3 seconds; clearing the draft, sending it or closing the composer calls
it once more with stopped: true. A received entry lapses 6 seconds after its
last signal, so a closed tab or lost connection stops showing. A restored draft
signals nothing until it changes. Typing is held in memory only and feeds no
count, chart or timeline.
Header
The header (header.tsx) is a 56px PaneHeader size="run": the title (the
agent's last terminal or Enhanced session title,
until then a taskless Enhanced session's first message
line, else the task's first line cut at 120 characters, with a lock for a
protected session), then a one-line state line: the session branch with a copy
icon (click copies the name), the agent's glyph and mode ("Standard"; the
tooltip adds the agent.list display name, run.model and run.effort,
"Claude Code · Standard · opus · high"), a Root access (needs-you tone) or
Isolated badge for a session not at Default, whose tooltip says what the tier
allows, "On <name>'s account (fallback)" when the session carries
requested_account_member_id (usage fallback;
a run.account event updates it live when the session moves), the reason, and
the owner. The state's dot and label are the Workflow chip's, on the row
below. A subsession adds a nav "Run lineage" row under the header: its
root and parent as links, then "This subsession", and Detached once it
no longer counts toward its parent. The reason takes only the room left over, so a long command never
moves or hides the branch; the owner goes below 32rem, and the mode word
truncates before the branch does. The full task and the session record are in
Details.
The actions, in order:
- The state's one primary action, the only filled button on the frame. It is
the label the condition names in
lib/needs-you.ts, the same one the board card and sidebar row show, performed inside the frame: Reply focuses the Chat composer, Open terminal switches to Terminal and asks for the lease, Answer focuses the docked request on Session or reveals the question's card in Details, Review message reveals the queued message's card in Details, and Review opens Changes for a finish. On the Terminal view there is no terminal action in the header; the toolbar has Take control. Session rows and Details cards that send the member elsewhere use secondary buttons. - Show details / Hide details (
Mod+.). - More (
components/run-actions.tsx, an icon button on a phone): every session verb fromlib/commands.tsexcept Send a message to the agent…, which the composer replaces, then Hand off…, the mode switch, Open in editor…, Captures… and Raw events…, then Close session…, Kill run and Delete run after a separator. Kill, Delete and Free sandbox… confirm first. Where the server offersrun.children.allow, the owner of a live session also gets Allow subsessions (run.children.allowon), and the owner or an admin Turn off subsessions on a session that allowed them.
Kill and Delete of a session with unfinished subsessions (live, not detached; the
store's sessions whose parent_run_id is this session) say "Its 2 unfinished subsessions
stop too." Closing a session closes its subsessions with it.
Open in editor… (open-in-editor.tsx) is offered for a live session the
member may steer, by the same allowed('steer', …) question the session verbs
ask, and never on a phone (phoneScreen), which has no editor to hand the
session to. A paused session shows it disabled with Resume the session first. Its
dialog has a VS Code, a Cursor and a Zed button, each navigating
to that editor's deep link for the ssh host <run-id>.aether and the
checkout /workspace, then ssh <session-id>.aether and aether ssh-config as
copyable commands for whoever has not set the host up. The item is
not offered for a session whose id is not one lowercase host label (runHost),
the only kind the links and the command are built from. The dashboard calls
nothing: the server authorizes when the editor connects
(terminal.md). The desktop app lets exactly
those three link shapes out of its window.
The mode switch (mode-switch.tsx) is Switch to Enhanced… or Switch
to Standard…, shown only for a live session of an agent agent.list reports
as switchable. It confirms what happens, then calls run.mode.switch with
the lease the tab holds; while the switch runs the item and the state line
read "Switching to Enhanced…". The dashboard decides ahead what it can: with
enhanced_installed false the item reads Enhanced adapter not installed ·
Set up and opens Agents. A refusal's data.reason is kept for the session's
current status: session_not_reported disables the item with Available
after the agent's first turn, adapter_not_installed shows the setup
line, and not_switchable hides the item. Every error toast goes through
errorSentence (lib/format.ts), which drops the leading RPC method and Go
package names (run.mode.switch: scheduler: ) and keeps the server's
sentence.
The view switch is a segmented tablist named "Session views" with manual
activation, on its own 32px row under the header at every width. When the
row is too narrow for every tab, as on a phone whose session has a pull request,
the tabs scroll sideways (ViewSwitch): the shown view's tab is kept in
sight as the view or the room changes, and the right edge fades while more
tabs lie past it. The Workflow panel's chip follows the
tabs. A phone has its own header and tabs; see Phone session.
A session with a pull request shows it at the right end of that row
(pull-request.tsx): #412, a link to the pull request on GitHub, then the
state of its checks as a button, 2 failing, Checks running, Checks
passed or No checks, and Merged or Closed once it is. Failing
wins over running, and running over passed. An answer that failed part-way,
or stopped at its limit of 100 checks, may be missing some: it still reports
a failure it saw, and otherwise reads Checks incomplete, never passed. A
row under 480px wide keeps the dot and the failing count. The panel is
mounted beside the header, not in that row, so a send waiting for control
survives the row leaving while the composer has focus on a phone. The server stores no pull request, so the
dashboard reads it (routes/diff/publish-pr.ts): run.pr.feedback for the
pull request from the checkout's branch on its GitHub remote into the session's
base branch, the same target the Publish dialog fills in, or one a member
typed into that dialog and found or opened a pull request at. It asks once
when the session page opens, every 60
seconds while the page is visible, after each push or creation in the
dialog, and at once on a run.pr or git.branch event for the session. The header and the git card
share one poll per session however many of them are mounted. It re-reads run.git.status only when the answer says the branch or
HEAD moved. Both calls execute git and gh in the session's sandbox, so the
check state exists only while the session is running or needs-attention: a
session that leaves those states keeps the link and drops the state, and a page
loaded after that shows neither. The board and sidebar show no pull request.
See
Changes view and Publish for the panel the button
opens.
Multiplayer controls
Enhanced sessions render MultiplayerControls (routes/run/multiplayer-controls.tsx)
below the view switch at frame level, so Session, Terminal and Changes share
one control surface. The Browser view leaves it out: it is about who controls
the agent's session, and the page has a lease of its own
(Browser view). The Files view leaves it out too: reading
and saving a file uses no lease. With the Browser docked beside Session,
Terminal or Changes the strip is back, above both. It shows the controller and every watcher
with their member name and Avatar, protection and the existing
ControlButton: take a free lease, release it, or hold for three seconds to
request an occupied lease. A local lease acknowledgement takes precedence
over polled controller metadata; the controller's name remains visible
beside You control or You control in another session since <time>.
That text appears when run.room.status names your member with a
control_session_id other than this tab's: another tab, device or
aether attach, held since the lease's acquired_at.
Multiplayer still opens Details for shared notes and run facts.
The strip is one row whenever the controls fit beside a 6rem roster, which
covers desktop windows. Only when they cannot, as on a phone with
Protected and a connection word, do the controls wrap to a second line
rather than overlap the roster. The roster takes the space left between
Multiplayer and the controls and scrolls horizontally rather than replacing names with a count;
below a 34rem strip it shows avatars with the names kept for screen readers,
and below 30rem Multiplayer keeps only its icon. The controller summary
truncates instead of wrapping, at 12rem below a 48rem strip. Offline or
failed presence reads mark the retained roster (last known). Control and
presence failures stay beside the action rather than inside a closed composer.
With a mouse or touch pointer on the multiplayer strip, useDotFade
(routes/run/dot-fade.ts) swaps the strip's dot texture for SVG copies of
it and springs each dot away from the pointer. Pointer speed adds a
two-branch V wake, and a click or tap swells the nearby dots under a spreading
ring. The clear bars behind text damp motion to 25%. The effect is decoration,
so the strip is not a tab stop and takes no keys. The hook listens on the strip
alone: ControlButton's pointer capture and a touch's implicit capture keep a drag's
moves there, and touch-pan-y keeps a horizontal touch drag from turning into
a pan. Events only record the pointer; each animation frame measures the strip
and its clear bars once, moves the dots, and rewrites only those not at rest.
When every dot is back at rest the SVG is removed and the static texture
returns. With reduced motion the strip keeps the static texture.
ACP control uses the same server-timed hold, seven-second holder dialog, cancellation and server acknowledgement as Standard sessions. Streaming updates do not cancel a held gesture. Explicit control choices and revocations stop automatic acquisition for the open stream; release carries the current lease generation. Takeover denials belong to the requester, not the holder.
MultiplayerControls renders ControlMatrix as the strip's background,
and TerminalPane renders it behind the agent terminal's toolbar. The
component is a neutral dot layer, one radial-gradient tile, under a
colored copy of the same dots. While the strip's dots move, useDotFade
removes these backgrounds and draws each layer's dots as an SVG inside the
same element, red hold copy included, so the clipping, masks, colors and paint
order below apply unchanged.
The bars give each group of text and buttons .control-matrix-clear, a 90%
--chrome fill with a blurred shadow of the same colour that hides the dots
under the group and fades them back in around it. A rule on the matrix's
siblings turns text-muted on the bar to --text. The copy is clipped from the
left by --control-reach, a registered @property number (1 empty, 0 full),
so it is revealed from the right edge, where the control button sits. The
acquisition, release and takeover animations drive --control-reach and
color on the colored layer. Its opacity is a separate animation: 70%
while the dots move or a hold is under way, then half once acquisition
settles. Behind the terminal toolbar it then breathes on an infinite 8-second
loop; on the multiplayer strip, whose dots answer the pointer, it holds still.
During a hold --control-hold moves a 4rem gradient mask that fades the teal
out and a red copy in. In
Enhanced sessions its appearance follows the acknowledged ACP lease, not the
unused agent terminal's history or connection state, and it shows on every
view that shows the strip. Voluntary release retracts it; takeover
feedback requires an explicit revocation matching the held session and
generation. Disconnects, permission loss and other fencing return it to
neutral immediately. The shared component supplies acquisition, holder
progress, takeover loss and reduced-motion behavior.
Chat view
The Chat view (session-view.tsx) is the session's conversation: what was said
to the agent, what it did and asked, and the session's notes. It is a virtua
list in a 736px column over rowsForRun (store/sessions.ts). For a Standard
session the rows come from the session's run.agent, workspace.timeline,
run.status and run.review events (read with workspace.timeline filtered by session and type,
then kept live by sync), room messages, the session record and its pending inputs:
user (a message to the agent with its delivery word), note (the owner's
own question as a Notes thread row, without the thread's own arrival motion;
comment messages get no row, they are stickies), steps (consecutive
tool calls in one closed block, "Ran 3 commands and read 2 files", expanding
to verb-first steps), request (an agent request reads "Answer in
the terminal." with Open terminal, or "Answer it from the agent's
session." when the session has no agent terminal; a teammate question offers
Reply, the owner's own question is a plain message), event,
finished, and while the session works with no pending input a live row (the
session's toolActivity, "Reading src/billing.js", else its state label such as
"Working" or "Waiting for agents", with that state's dot, which pulses only
while Working) and a
terminal-note row, Live detail is in the Terminal. with Open
terminal. An "Agent report" event is dropped while the report's agent
message is shown. Request titles and that copy live in lib/run-requests.ts, shared
with Details. A timeline message that matches a room message is shown once.
Show older messages at the top pages room history back 100 messages at a
time, and a failed history read shows the server's error with Retry. The
log keeps the last 2,000 events: the first read pages backward from the log
head (workspace.timeline with newest: true, then before_seq set to the
previous page's older_seq) and stops there, and a later read resumes forward
from next_seq, which a backward page sets to the head. The list is
role="log" with aria-live="off", and each row carries
aria-setsize/aria-posinset. The docked composer ("Message the agent",
Send) posts a room steer_request with the lease the tab holds; its rules
are in Session control. A refused send or image upload
shows the error above the textarea (role="alert", Dismiss); Details
shows only the failures of its own actions. Details' Agent messages
section ends with Hide from Session (Show in Session once hidden),
which drops those messages from the timeline; the choice is per session, in
hiddenAgentMessages, until the page reloads. Esc in an empty composer focuses the list's
viewport; the next Esc is the session's leave-run.
The composer fills the Chat pane with 16px gutters on both sides; on wide screens, opening Details narrows the pane rather than overlaying the composer. Its focus highlight follows the outer border around the textarea and attachments. Transcript rows retain their 736px reading width.
Open comment room messages show as a floating sticky rail in the pane's
right gutter (session-notes.tsx), not as transcript rows: stacked oldest first,
236px wide, 20px from the top, right and bottom edges, each card rotated a degree
off the last, and not scroll-linked to the rows above it; the rail scrolls its own
contents instead of growing past the pane. A card still being sent shows "Sending…"
in place of the time and "via ChatGPT" after the name when a connector posted it,
the same as a thread row, and its Complete and Delete stay disabled until the
saved copy, under its server id, replaces it. A check completes a
note: red strokes scratch across its text, the text dims, then the card fades
and collapses; an X deletes it the same way with no scratch. Both buttons show
on hover, focus, or touch and need the note's author, the session's owner, or
an admin; there is no undo. A screen reader hears "Note completed." or "Note
deleted." once the server accepts. When the Chat pane is below 1248px wide
(Details or a docked Browser can narrow it), the rail becomes a strip above
the composer, "N notes ▾", that expands to the same cards within its own
bounded, scrolling list so expanding it cannot push the composer out of view,
and Details keeps listing open notes as it always did. At 1248px and over,
while Chat is the active view, Details drops that list - the rail already shows
the open ones - and keeps only the composer and a "Done" history of completed
notes; switching to Terminal, Changes or another view, the rail no longer shows,
so Details lists open comments again. question notes are never stickies; they
keep their row in Details and Reply. A refused completion or deletion
restores the card with the server's error and Retry; if the server answers
after the 5 second deadline, the late refusal replaces the "did not answer"
text with its real reason. If another member already completed or deleted
the note, the card shows the error without Retry, and Dismiss removes
it.
The changes bar (changes-bar.tsx) sits above the composer: one line,
"14 files changed +612 −140" and Review. It counts the session's whole
worktree against its base, the Changes view's All changes, so
edits made by shell commands count too. Its source is the newest run.diff
stat set. Until the page has received one live, it reads the newest with
workspace.timeline (types: ["run.diff"], newest: true, limit: 1)
on load and again whenever the connection returns, since the page may hold
no replay cursor yet; after that, a resumed event stream replays any it
missed. It starts collapsed and stays expanded per session
once opened. Expanded, it lists each file with its status letter and
+a −d, at most 192px tall (30% of the viewport on a phone). A file opens
the Changes view at that file; Review opens its All changes. A
truncated snapshot shows no line counts, because they are only a floor.
The bar is hidden while nothing has changed and once the session is merged or
abandoned, which removes its checkout; a
failed read shows the server's error with Retry. Conversation rows carry no file lists: each edit's diff stays in its edit step.
For a session with acp: true (Enhanced, or Background over ACP) the rows come
from its session item log instead.
With no conversation rows or older-history control, the pane shows a
decorative, low-contrast Cloudfield mark above the session's title, workspace, agent
and mode, branch, owner and creation time. The title and each metadata row
are centered in the conversation pane, including when long metadata needs
scrolling. The overview gives way to the conversation as rows arrive. History
errors and their Retry action remain visible above it; the overview does
not imply that the agent is connected. While the stream first connects, a
session with nothing held shows neither the overview nor the people's
messages: after ~200ms a skeleton of three exchanges stands in, announced as
"Loading the conversation…". It gives way to the conversation, or to the
overview when the replay holds no rows or the first connection fails. A
session switching mode opens no stream and shows the overview.
Screenshots with fixture data: desktop, phone, history error.
useAgentTerminal subscribes the session to /ws/acp/<session> while the session is open
and not switching; store/session-stream.ts owns the socket
(lib/acp-stream.ts: the events feed's backoff and onWake, after_seq
resume, an immediate resubscribe on close 1012, a final stop on 1008 or a
-32602 refusal) and the controller id, so the lease and timed takeover
frames work as on an attach and switching views keeps the stream. The tab asks
for the lease once it has shown Session and the stream has acked, when the
terminal would (the owner, not a phone). A refused
automatic request shows no error: it retries with backoff while the holder is
the viewer or nobody, and again when run.controller reports the lease free.
Leaving the session page, by navigating elsewhere in the dashboard or by closing
or reloading the tab, releases a held lease before the stream closes, so a
reload takes it straight back. Navigating away waits up to 2 s for the release's answer, because the
server commits it on the stream's context. Closing the stream resets the
session's stream and lease state. Frames go through batchNotifications, so a
burst re-renders once per frame. The client holds the ack until the replay
items it announces have arrived and applies them together, so a conversation
never paints half loaded or shows a finished turn as live. A stream that closes
mid-replay drops what arrived, and the next subscribe replays it again.
An ack or history page's truncated_before displays the expired-prefix
boundary. The page's oldest_seq stops older-page requests at the actual
retained boundary. A same-epoch reset preserves the ack's authoritative
pending approvals and expiry metadata; it cannot synthesize missing frames.
An expired full-item request shows the server's error rather than empty detail.
The sessions slice keeps each session's AcpSession: items grouped into
turns (store/session-rows.ts), the ack's live state (turn in flight,
pending requests, config options, commands, auth, steering), the lease and
the stream state. A reset frame or an ack with oldest_seq starts the
timeline over. Scrolling within three viewport heights of the top
automatically pages run.acp.history before the oldest item held, 1000 items
at a time, along with older room messages, and repeats until that much is
loaded above the viewport or history ends. A page shorter than the request
does not end paging, so a server with a lower limit cap still pages to the
start. If the loaded rows do not fill the viewport, paging continues until
they do or history ends; that paging keeps a view that follows the newest row
following. Inactive views and failed reads do not auto-page;
failures keep the server's error with Retry. While older items remain, a
room message or agent message from before the oldest item held stays hidden
until the items around it load; a message the agent has not taken yet always
shows. A page can merge into the first loaded row and change its key (a block
gaining the person's message that starts its segment), so the list matches
rows by key from the end. A step's open or shut choice is stored under the
step's own id, so it outlives that change.
While every row below the top visible one keeps its key, it anchors the page
from the end. That keeps the distance from the end, which moves with any row
that resizes below the reader, so an unpinned view also restores the first
visible row that survives, by key and offset; that alone places the view when
live rows arrive with the page. A view at the end follows the newest row, also
while a streamed reply grows its row in place; only the reader's own scrolling
stops it. A closed
turn's rows are derived once and kept; only the open turn re-derives. At most
three sessions stay whole; the least recently
opened others keep their newest 200 items. Rows: user (a
right-aligned bubble; the author shows only when it is not the viewer or the
message came through a connector, and the session's appended instructions hide
under its task), steps, assistant (markdown through react-markdown and
remark-gfm, split into blocks with marked's lexer so only the streaming
block re-renders, code highlighted with the Lezer languages), live,
event (a wake, a new agent conversation, or a notice outside a block),
finished and agent-message.
turnRows splits a turn into segments at each person's message, wake and
new agent conversation (store/session-steps.ts). In a segment, the agent's
prose stays in the conversation as assistant rows, and the work between
two pieces of prose (thoughts, tool calls, plans, subagent launches and
answered requests) joins one steps block. The prose after the last block
is the answer. The aether-internal report call (or aether_report tool)
that ends a Cloudfield turn joins the block before the prose it follows, so a
reply written before reporting stays the answer. A segment without work,
such as ping and pong, has no block. The
block's header names the work ("Read 12 files, ran 5 commands and edited 3
files") with up to three tool icons, failures, plan progress and tools still
running. While the turn is open and the stream live, the header carries the
live state instead: the state dot, "Running npm test", "Waiting on 2
subagents", "Waiting for your approval: <command>" (or "Waiting for your
answer") in amber, else "Working", with the seconds since the block's work
began: the segment's start for its first block.
A turn whose newest row is not a block keeps the live row. Steps sit on a
rail: thoughts (a two-line preview that expands to the whole thought), lookups
(consecutive reads, searches and fetches as chips; a chip for a file in the
checkout opens Files,
a page chip a new tab; four, then +N more), tool calls (the command, the
edited path with +a −d, or an MCP tool's name; a spinner and seconds while
running, the duration, Failed or Exit N once returned, and "Waiting
for approval" while its permission is pending), the plan as its segment
last updated it, with each entry's state, subagent cards, answered requests, notices and mode changes. A tool
step with detail expands to the command and output tail, a DiffBlock per
file, or its Input and Result (JSON highlighted, ten lines until
Show all, which a copy without clipboard access also opens so the
selection holds every line); a body cut to fit the wire is read whole with run.acp.item.
A block over 40 steps shows its first 5 and last 30 around Show N more
steps, which then reads Show fewer steps.
A block is open while it is the newest row of an open turn, or while a
subagent in it runs, and shuts once the agent writes after it or the turn
ends; the viewer's own choice for a block or step
(expandedRows, kept until reload) wins. Those defaults, and how much of a
growing block folds, change only while the view follows the newest row and
focus is outside the block, so nothing moves under a reader scrolled up or a
keyboard in the block. An open block's steps and details splice into the same list after its
header, so they virtualize. The answer's footer keeps the turn's outcome,
Finished in 12s, in view; its time and Copy the reply, which turns
to a check, show on hover. A turn that ends Cancelled (stop reason
cancelled), Interrupted (interrupted, a turn a restart or lost
connection cut off) or Stopped, or ends without an answer, gets a
finished row with its dot instead, matching the session reasons turn cancelled and turn interrupted. Rows that arrive while the view is open
rise in, at most eight at a time, and a streaming answer's new blocks fade
in from a blur above a pulsing dot; a first load, a replay and a history
page do not animate. A person's
message is matched to the room message that carried it for its author. While
older items remain and the same text was sent more than once, a delivered
room message sent within the loaded items, before the row, is matched first.
One not in the log yet shows its delivery word. One polite status region
announces a new request, a finished turn and a state change. The row
components (components/ui/timeline.tsx, steps.tsx, session-blocks.tsx,
markdown.tsx, components/messages/message-row.tsx) serve both modes.
A subagent is the agent that Claude Code's Agent or Task tool launches,
that another agent announces as an ACP child session, or that a fallback
launch call names; a dynamic workflow is its Workflow tool. A launch card is any call with tool_call.subagent, or a
Claude Agent, Task or Workflow call. Their items carry a parent link
(parent_id in internal/acphost/items.go), and
store/subagents.ts keeps them out of the conversation. Each session holds
an index keyed by the launching tool call's id, with the call's latest
snapshot, the subagent's own items, nested subagents, tool count, latest
activity, and start and settle times. acpFrames and acpOlder update it
incrementally; a history page that arrives out of order prepends, and a
reset starts it over. Only the turns' own items reach turnRows, so a
child item re-renders its card, not the conversation. A launch call
becomes a subagents step, and consecutive launches share one step:
"3 subagents · 2 running", expanded by default. Each card shows a status dot,
the description, the subagent type, the tool and nested counts, and the
elapsed time. A running card shows its latest activity, a settled one the
first line of its report, without Markdown marks. The state comes from the
launch call: completed is done, failed failed, a call still open when its
turn ended and silent since is stopped, and a call whose snapshot is not
loaded is unknown. Elapsed time counts from the call's opening snapshot, so a
card whose replay starts after it shows none until history reaches it. A
Workflow call, or an Agent call with run_in_background, completes as soon
as its work starts. When the call carries tool_call.task
(internal/acphost/items.go), the card follows
the task: running, then done, failed or stopped, with elapsed time to the
snapshot that settled it, and a settled subagent card's report is the first
line of the subagent's last message. Without it, the card reads "Launched in the
background", and running once a child item is logged after the call
completed. The launch acknowledgement is never shown as a report. A workflow card lists the subagents whose items name it as parent.
A subagent whose launch call is not loaded, or was trimmed, shows its card at
its first held item until a history page brings the launch; without the
call its state is unknown. When the session state lists a live subagent or
workflow task that no held call started, the Chat and Trace views page
run.acp.history, up to five pages, until one does or history ends: a reload
replays only the newest 200 items, and leaving a session trims it, either of
which can drop a launch that still runs. A launch id seen again after
its call settled names a new subagent, keyed <id>@<seq>. While the main
agent only waits on its subagents, the live steps header reads "Waiting on 2
subagents". A fallback launch shows a card with no nested items;
an agent with neither child sessions nor a launch call renders as before.
A card opens the subagent inspector (routes/run/subagent-inspector.tsx)
at ?agent=<tool call id>. While the session's row holds 448px for it plus
minReadableWidth (560px), it is an inline aside that replaces Details
while open; narrower, it is a side sheet, and a bottom sheet on phones.
Until the row is measured neither renders. An inline inspector that loses
that room to the assistant docking beside the session closes instead of reopening
as a modal sheet over it, and focus stays in the assistant
(replaceRouteKeepingFocus in components/shell/center-view.tsx skips the
focus move to the session heading). Losing the room any other way, such as
showing the sidebar or narrowing the window, reopens it as the side sheet. It shows breadcrumbs back to Chat through nested
subagents, Previous subagent and Next subagent among siblings, and
Close subagent; Esc closes it before it leaves the session. Stepping
between siblings and closing replace the history entry, so Back does not
reopen it. Below them,
one virtualized list holds the prompt (raw_input.prompt, read whole with
run.acp.item when the item was cut; a launch input over the log's
16 KiB raw limit is kept cut, so the prompt reads as unavailable), the
subagent's transcript through turnRows, flattenRows and TimelineRow
with every block open, and its report (the completed
call's text content). Until a known subagent's launch call is loaded it pages
run.acp.history, at most five pages, then offers Load earlier history;
an id the loaded history does not name pages only on that button. A failed
page, or a failed read of the whole launch item, shows the server's error
with Retry.
A tool call snapshot logged in a later turn than the call's first, as when a call outlives its turn, joins that first turn and keeps one row.
A path the agent names opens that file in the session's
Files view: in an answer's, narration's or thought's prose
and inline code, in a tool step's command and output tail, and in a
DiffBlock's caption. A Markdown link whose target is a repository path
opens there as well, where it used to open a dead address in a new tab. A link to a
same-origin dashboard route (?run=<id>, ?page=...) opens in the app
(OpenRoute, which the assistant panel supplies so its phone sheet closes
too); any other link opens in a new tab. A notice's description is plain
text except [text](?<query>) dashboard links (LinkedText), which open
the same way.
Fenced code blocks, a person's own messages and the entry labels, which
toggle their detail, are left as text.
A turn_start with autonomous is a turn the agent ran with no prompt
(Claude Code reacting to a finished background task). It opens a turn as a
prompt does, so its rows, live row and Steer, Queue and
Interrupt work the same. The ack's state carries background and
tasks; advance (store/sessions.ts) updates them from items newer than
the ack's seq only, so a replay of older items cannot bring back tasks the
ack no longer lists. A background item replaces tasks, and with no turn
in flight sets background while a task holds or a follow_up is owed;
one with no tasks and stop_reason: "interrupted" clears them. A turn
boundary sets turn_in_flight and, at turn_end, background from the held
tasks. backgroundWait returns the live tasks while the stream is live,
background is set, no turn is in flight, and the session is running or
parked stalled: or needs input:. A running session's wait adds a live
row reading "Working in background" when only a follow-up is owed, or
"Working in background: N tasks" with N held tasks.
The Enhanced composer (routes/run/composer.tsx, state in
composer-state.ts) sends with run.inject and the lease; its pill reads
Send, Steer (a turn is running and the agent advertised steering),
Queue (Mod+Shift held, or no steering), Interrupt (run.acp.cancel,
an empty composer during a turn), Stop waiting (run.acp.cancel, an
empty composer while backgroundWait holds, including a wait that stalled
or shows a question) or Resume (a paused session). Stop waiting ends the
wait and parks the session turn cancelled; the agent's background tasks keep
running, and a later follow-up opens a new autonomous turn. With text typed
the pill is Send, which starts a turn, so a reply to the question still
goes out. Enter does what the pill says and nothing without text or
images, Shift+Enter adds a line and Mod+Shift+Enter queues; on touch only
the pill sends. With the box empty or the caret at the very start,
ArrowUp fills the box with the last prompt you sent in this session and each
further press the one before; ArrowDown steps forward again and, past the
newest, restores what you had typed. Anywhere else the arrows move the caret,
so a wrapped draft is never replaced. The walk uses the prompts as they were
when it started, and any edit ends it (composer-history.ts). Enter is a plain key, which the shortcut table stands down
for inside a field, so the textarea answers it itself through isPress; the
binding stays registered so the shortcuts reference lists it. A key still composing in an input method
never sends. The shared upload state in
composer-images.tsx accepts file selection, native file paste and drops,
enforces the eight-file limit, and uploads PNG, JPEG, GIF and WebP through
terminal.image and every other file through terminal.file, one at a time
and stopping at the first failure. A file over its limit (8 MiB for an image,
64 MiB for anything else) is refused before it joins the draft, naming the
file in the alert; the rest of the batch still goes up. Enhanced
sends pass text and ordered attachment references separately through
run.inject; the server resolves images into ACP image blocks and other files
into resource_link blocks. Attachment-only messages are allowed, incomplete
uploads block sending, and failures preserve the draft and previews.
prompt_images from the ACP snapshot gates sending a message with an image
(hasImages), not other files.
Attaching has three surfaces over the one draft. Above the field,
composer-attachments.tsx draws one compact chip per file: a 40px thumbnail
for an image (an object URL, revoked when the file goes), an icon with the name and size for any other file, and a state
mark - a spinner while it uploads, a check that shows for a second once it
lands, a failed dot with "Not uploaded" when it did not. Under a fine pointer
the + (Attach files, composer-dropzone.tsx) opens a popover holding
the drop zone, one row per file and a footer. Clicking the zone or pressing
Enter on it opens the file chooser, and a file dropped on it is attached; its
hint states the real limits. A row reads size and Waiting, Uploading…
(with an indeterminate 2px bar: the upload is a single request with no byte
progress) or Attached, or the failure reason beside Retry. Uploads run
in order, so a failure marks the first unattached file and the rest read Not
uploaded. Remove is disabled while an upload runs, because it cannot be
cancelled. The footer counts "Uploading n of m" with the bytes already
attached, then "n files attached", or "n of m attached" with Retry, and
Clear empties the draft once nothing is uploading. The popover stays open
while files upload and reads the draft store, so a remounted composer shows
the same rows; closing it with files attached returns focus to the field unless the viewer clicked into another control, which keeps focus. Rows animate only for changes seen while the popover is open: a reopened popover replays nothing. A
coarse pointer skips the popover: + opens the chooser directly and the
chips carry the progress.
Dragging files over the Chat pane attaches them; the pane covers with a dashed
veil reading "Drop to attach n files". The pane is the conversation and
composer area, below the session header and beside neither the sidebar nor
Details. The composer also keeps its own drop target. Both share the composer's
current capacity and disabled state and ignore text and link drags; their veils
take no pointer events, so the field keeps its caret. A refused drop reads "At
most n files fit", "Uploading…", "At most 8 files" or "Files cannot be attached
now" (the cursor then shows no drop). useFileDrop in
web/src/lib/file-drag.ts counts the files in the drag (not the link or markup it carries) and the enter and leave
events so a child never ends the drag early, and stops them so a drag over the
popover's zone does not also drive the box around it. A drag over a dialog or
popover opened from the chat, such as the image viewer, is not a drop on the
pane. Folders are not walked:
a dropped folder fails as a file with the browser's own read error. The Session
view and Home both call useRefuseStrayFileDrops, so a file dropped outside a
target does nothing instead of replacing the dashboard with that file.
The timeline rows and both composers share sessionColumn
(session-rows.tsx): the 736px column with 16px gutters, so message text and
the message box line up at every width. The box (rounded-composer, 14px)
holds the textarea above one footer row: attach, Insert a template, the
agent's mode, model and effort pickers, the context meter, and the send pill
at the end, with the dictation mic (see Dictation) just left of
it. The Standard composer's row has attach, Insert a template, the mic and
Send. The pill is a
round arrow while it reads Send and widens to its word otherwise. Hints
and the 45-second delivery notice sit under the box. Footer controls wrap on
narrow screens. The context meter shows the agent's last ACP usage_update
(state.usage in the snapshot, replaced by each usage item) as a share of
its context window, and is a button that opens the Context window popover
(routes/run/context-window.tsx); hovering it shows the token counts. An agent
that reports no usage shows no meter. The popover holds the model, the tokens
used (it counts to each new report, and jumps under reduced motion), a percent badge
that turns state-needs-you at 90%, a 24 by 9 grid of 216 cells, a legend, and
a footer with the tokens left, or by how much the window is exceeded. The agent
reports only used and total tokens, so the grid has only what they imply: used
and free. When the Chat view still holds the turn before the newest one that
reported, and the window grew since, used splits into Earlier context and
Latest turn; after a compaction or once that turn is trimmed it is one
Used row. Pointing at a legend row or a cell dims the other cells and
swaps the headline and footer to that row; touch and a single category skip
this. Session cost shows only when the agent reported one. The single
role="meter" is the headline inside the popover. Compact appears only when
the agent advertises /compact; it puts /compact in the message box and
focuses it, so Send (or the pill's steer and queue rules) still decides
how it goes out. It is inert, with the reason on hover, while a prompt is
being sent, the box holds text or files (a draft is never replaced), or you do
not hold control of the session.
An unsent prompt is a per-session draft held by composer-state.ts: the text, the
attached files with their uploaded paths, and the idempotency key of the last
attempt to send them, so sending the same prompt again delivers it once. The
Standard and Enhanced composers read the same draft, so it survives opening
another session or page, an event-log restart that remounts the session, and a switch
between Standard and Enhanced. A sent prompt empties the draft; deleting the
session, or authenticating as another member or server, drops it.
A send or an upload outlives the composer that started it, so the
request in flight and its error are part of the draft too. A composer that
mounts meanwhile reads Sending… or Uploading… and stays locked until
the request settles: nothing can be added to a prompt that is being sent, and
it cannot be sent or uploaded a second time. A request settles only the draft
it marked (beginDraftRequest), never one that replaced it. Past the
deadline a send reads "Still waiting for the server…" with Cancel, which
clears the mark and unlocks the draft, and a resend reuses the draft's key.
A late success then settles nothing; a late failure of an Enhanced prompt
still shows its error on the draft without locking it, unless a newer send
is in flight or the draft no longer carries that send's key. The first focus
of a composer that mounts with text puts the caret after it, and the
suggestion menu follows the selection as well as the text.
Drafts live in memory and end with the page. They sit in their own Zustand
store, not a root-store slice: every root-store write rewrites aether.ui,
and one made while events drain notifies on the next frame, which drops
keystrokes in a controlled textarea.
Insert a template (shown when the gateway offers template.list,
disabled while the draft is locked) opens the template library above the
button, or as a sheet on a phone, over the session's workspace's templates, with
a clock on each scheduled one (schedule.list). Its primary action,
Insert, writes the filled-in task into the draft: over
the textarea's selection, or after a blank line when nothing is selected.
It never sends. The picker closes and the caret lands after the inserted
text; Esc closes it and returns focus to the textarea, while a click
elsewhere leaves focus where it landed.
User rows keep room-message IDs and attachment indices, not image bytes, and
the container paths of other files. A path under
.aether/terminal-files/<random>/ is a file (isAttachedFile); any other
attachment is an image. Image-bearing ACP rows match room messages by those IDs
rather than caption text, so separate image-only messages remain separate; an
ACP row whose resource_link URIs name attached files matches the room
message with the same text and the same attachment paths. message-images.tsx
fetches authorized image blobs through api.roomImage and revokes its object
URLs when identity, session or row changes, and shows each other file as a chip
named by its basename with the path as its title. Attachments wrap within
320px, so an image-only message bubble is no wider than its thumbnails.
Thumbnails keep each image's aspect ratio within 320×192px; their composer
radius shrinks on short images so the corners do not meet. Each image is named
by its place in the row ("Image 2 of 3", or "Attached image" when it is alone),
and its thumbnail is a button that opens the same blob in a Dialog filling
the window (the whole screen on a phone). The dialog shows the image on a
near-black backdrop, centered in the viewport with the composer's thin border
and corner radius, at up to 80% of the viewport width and height. Escape or
clicking outside the image closes it; the image name stays for screen readers.
Each image fits the frame, enlarging small images when needed. Zoom
runs from fitted to 400% of the larger of the image's native size or fitted
size, in a frame that scrolls and takes keyboard focus; the focus outline
follows the image. A trackpad pinch (a ctrl wheel, or Safari's gesture events,
both kept from zooming the page) or a two-finger touch pinch zooms about the
fingers or pointer. Mod+=/Mod+- step by 1.25 about the frame's centre while
Mod+0 fits again. A click on a fitted image zooms downscaled images to 100%
or enlarged images to 125% of fit, preserving the clicked point. A multi-image
gallery has no step buttons: ArrowLeft and ArrowRight, or a horizontal
swipe, step through loaded images while the image is fitted, stopping at either
end. With a fine pointer, a hint at the top right reads the image's name and
"← →". Zoomed in, or with a modifier key held or the page pinch-zoomed, the
keys and swipe do not switch. With the image fitted, clicking beside it closes the dialog; while
zoomed, the outer gutters close it and the frame remains scrollable. Losing an
image's blob, as on reconnect, closes the dialog if it was showing that image.
Closing returns focus to the thumbnail of the image last shown. Attachments sit
outside the text-collapse area and remain available through history and reconnect.
Mode and effort menus use content-sized described rows; model selectors use
Command inside Popover, preserving every advertised option and provider
group with search by name, ID and description. Selections use
run.acp.set_option; / completes the agent's commands and @ paths from
the Files tree cache. It closes with one line of reason while switching, for a
Background session, while connecting, or while the controller has a pending
request (keeping Interrupt). An authorized non-controller can Send
through the existing 45-second moderated path even while an agent request
waits for an answer; model and mode menus stay disabled and the hint explains
controller approval. useImplicitControl
(agent-terminal.ts) lets the owner of a session nobody controls act in one step
on any screen: Send, the Standard composer's Send and a request's options
request the lease and run the action once it is held (given up after 10
seconds). Pending requests dock above it
one at a time, oldest first, with "1 of N" and Previous request / Next
request in the card header (routes/run/request-dock.tsx). The dock holds
the card on screen by request id, so arrivals and other answers never swap
it, and stays empty until the stream has replayed up to the ack's seq, so
a session opened with a request waiting shows it whole and without motion. The
dock scrolls at 50dvh (40dvh on phones) and the card's footer sticks to its
bottom.
A request card (routes/run/session-requests.tsx, shared with the
assistant) reads "agent wants to action": the action comes from the tool
call's tool_kind ("run a command", "edit totals.go", "edit 4 files"), a
subagent's call names that subagent, and before the tool call arrives it
reads "asks for permission" over the request title. Below come the tool icon
and tool_name, the agent's own description of the call as a quote, then a
section: the command, or the files with +a −d that open their diff one at a
time (three, then N more), or the locations. A truncated item loads whole
first; one the session log itself cut shows what the log kept, with a note
that the preview may be incomplete. Questions show their form and links the
URL with Copy link and
Open. Options with exactly one allow_once and one allow_always, all
kinds distinct and set, once the tool call is known and is not a mode switch,
become How long pills,
Just once (the default, never remembered) and Always, beside the
reject_once option as Deny, reject_always as a quiet extra, and Allow
named after the chosen option. Anything else keeps one button per option in
the agent's words, rejects first and the primary (allow once, or accept) last.
A delete call's Allow is danger. 1-4 pick options in allow-once-first,
allow-always-last order while a card has focus, 1 never an allow-always one;
each button shows its digit as a Kbd on a fine pointer. A pressed answer
reads Sending…, then "Still waiting for the server…", and errors show
under the footer. When a request leaves pending its card fades out and the
dock glides to the next card or closes; there is no Escape binding, since
Escape already closes sheets and an accidental reject cancels the tool call.
The header's Answer focuses the docked card on every screen. While Session shows the dock, Details' Needs
you shows one link, "1 request, shown below the timeline", that closes a
Details sheet and focuses the card; on other views it lists the cards. routes/run/session-failure.tsx shows an adapter failure with
Retry Enhanced and Open in Standard, and a sign-in failure with the
agent's auth methods. On a run on the viewer's own account it adds Sign in
on Agents, and when that agent's agent.list row has login_problem its
title is the alert's ("Claude Code is signed out" or "Claude Code's sign-in
was refused"); a login-file problem shows verbatim, while a refusal is
already the failure quoted below. On a run on another member's account it
says that member signs in again on their Agents page or with
aether agent login <agent>.
Dictation
components/dictation/ turns speech into text in a message box. Its
DictationButton takes { textarea, onInsert, hints? }: the box, a callback
that stores the new text, and optional hints. It is mounted left of Send in
the session composer and the assistant composer, and in a row under the New
session Task box (run-fields.tsx). It renders nothing unless
server.info lists the dictation feature, which the server sets only once
dictation is installed.
The button and the composer around it share state through state.ts, keyed by
the box's ref: useDictationState(textarea) returns active (starting,
recording or transcribing) and the current notice. While active, the
composer's text-sending actions (Send, Steer, Queue) are disabled and Enter
does nothing, so a missed press cannot send the old draft mid-recording;
Interrupt, Stop waiting and Resume stay available. The mic will not start in
a box that is read-only because its message is still sending, since the sent
draft would replace the dictated words; it shows a notice instead. The New session dialog and the onboarding
first run hold Launch the same way through useDictating(), which is true
while any box dictates. DictationNotice draws the notice as a strip
above the box: failed tint, alert icon and role="alert" for an error, a plain
role="status" strip for "No speech was recognized.", and an x that
dismisses it and returns focus to the box.
| State | Button | Live region |
|---|---|---|
| Idle | Mic in text colour | - |
| Starting | Neutral pill: spinner, "Starting mic…" | Starting microphone |
| Recording | Red pill: stop square, seven-bar level meter, elapsed time | Recording. Press again to stop, Escape to cancel. |
| Transcribing | Neutral pill: spinner, "Transcribing…" | Transcribing |
The button's name is always Dictate; aria-pressed says whether it is
recording. The pills share one minimum width, so the button does not jump
between states. A tap starts and a second tap stops. A press held 300 ms or
more after recording began stops on release (hold to talk); a press that
outlasted the browser's permission prompt counts as a tap. Enter and Space
toggle like a tap. A pointer press keeps focus in the box, so a phone keeps its
keyboard up. Escape pressed in the box or on the mic while starting, recording
or transcribing drops the audio or the request in flight; an Escape anywhere
else goes to its own owner. Recording stops by
itself at 2:00.
The browser asks for the microphone on the first press, never on load.
capture.ts opens it with getUserMedia at the hardware rate (a 16 kHz
AudioContext records silence on some macOS devices), downmixes each render
quantum to mono in an AudioWorklet loaded from a blob URL, and reads the
meter from an AnalyserNode at 15 Hz. The track stops as soon as recording
ends. wav.ts averages down to 16 kHz, clips at 120 s and encodes PCM16 mono
WAV; api.dictationTranscribe posts it base64 to dictation.transcribe with
the hints. Without hints, dictationHints sends up to 200 names of at most
80 bytes: every workspace, the open workspace's repo and run repos, and its
sessions' titles, newest first. Transcription times out after 240 s, the local gateway's bound.
insertTranscript puts the text where the caret or selection was when
recording started; if the text changed meanwhile, at the caret the member left
in the box, or at the end, adding a space on either side only where a word would
otherwise touch it, then focuses the box with the caret after the text. It
never sends: the mic has type="button", so a press inside the New session
form does not launch. Errors show verbatim, with paths and the install command
in code: the server's message (not installed, busy, too long) or the
browser's, as Microphone: <DOMException name>: <message>. A
NotAllowedError adds, on its own muted line, how to allow the microphone
again. A page served over
plain http to a non-loopback host is not a secure context and has no
microphone; the notice names the origin. The meter keeps reading the level
under reduced motion but drops its transition. On a coarse pointer the mic and
pills are 44px tall.
Trace view
The Trace view (src/routes/run/trace-view.tsx) shows when each part of an
Enhanced session ran, as a span tree beside a time waterfall. A span is one
timed piece of the session: the session itself, a turn, a tool call, a subagent, a
wait for a person, an error notice, or a subsession.
deriveTrace in src/store/trace.ts builds the tree from data the Session
view already holds; nothing new is read from the agent:
| Span | Start | End |
|---|---|---|
| Session | started_at, else created_at |
finished_at, else now |
| Turn | its turn_start item |
its turn_end, or its last child's end |
| Tool call | the call's first snapshot | the snapshot that settles it (a background task's own status) |
| Subagent | startedAt from the subagent index |
settledAt, or its last activity for a Workflow or background agent |
| Wait | the request item opening it |
the item answering or cancelling it |
| Subsession | its started_at, else created_at |
finished_at, else now |
A subagent whose launch is not held starts at its first held item and sits in that item's turn, or under the session when that turn is not held either. A session's subsessions sessions join the Workers group as spans from their creation (or start) to their end, drawn failed or stopped by their status; they come from the sessions the dashboard already holds, so a new subsession appears at once.
A call still open when its turn or subagent ended is Stopped at that end,
unless it is a background task of a live session. Item times are log times, so a
call that settled within 50ms is instant. A turn is named by the first line
of its prompt, by Cloudfield's wake-up wording ("Woken by new agent messages"),
or Turn N. The session's bar is its run.status history, coloured by state;
readTraceLog (src/store/trace-log.ts) reads the session's run.status and
run.cost events with workspace.timeline (newest first, at most 2,000),
and sync appends later ones while the log is held. Until that read finishes
the session's bar stays neutral; a failed read shows its error on the bar, and
the next read starts again from the newest event.
The stats strip shows Duration (shimmering while live), Turns, Tool calls,
Subagents when there are any, and Errors: failed calls, subagents, turns
and error notices. Errors is a button that steps through the failures,
unfolding each one's ancestors and opening its details. Tokens and Cost appear only for a metered
session (run.cost with metered: Enhanced increments add, headless totals
replace) and never as an invented zero; a failed read shows Not read
with the server's error; when the read stopped at 2,000 events they read
≥. While earlier history is not held the counts read ≥. A neutral Slowest pill marks the longest finished tool call once
three have finished.
The axis is elapsed session time. A stretch with nothing running that is longer
than a minute and 5% of the active time becomes a fixed break labelled with
its length ("2h idle"); history before the first held item is a hatched
Not loaded break. An idle stretch reaching now is a break too, its label
updated once a minute. While the session is live the axis keeps headroom and
steps through a ladder of round lengths, as does a zoom to a running span; a
line and dot mark now, moving each second on the server's clock
(serverOffset), and the list follows new rows at its end until you
scroll; Jump to now returns. Bars are placed through CSS variables on
the list (--trace-origin, --trace-scale, --trace-now), so a zoom or a
scale step glides; the first layout after opening does not. A tool call's bar is accent; running, failed, stopped and waiting bars
take those state tones; a turn's or subagent's bar packs its model time and
its tool calls' density, failures and waits.
Closed turns start folded with a +N count; the live and the last turn
are open, as is a running subagent, and the Subsessions group while it has 8 or
fewer. A failed or waiting span shows under its folded parent. Trace
actions has Expand all and Collapse all. Folds, zoom, the
keyboard's row and the older pages read so far are kept per session in this tab
(traceViews), not persisted.
Past 200 visible rows the list renders only those in view. The tree takes
one tab stop: Up, Down, Home and End move, Right unfolds or enters, Left
folds or leaves, Enter or Space opens the span's details, and Shift+Enter
zooms the axis to it. Escape closes the details, then leaves the zoom
(Whole session does too), then falls through to leaving the session. One polite
status line announces turn starts and ends and new failures, batched over
1.5 seconds; failures in older history as it loads stay silent.
The details open beside the bar, or as a bottom sheet on a phone: the kind ("Tool call · Bash", "Turn 4 · autonomous"), state, duration, start and end ("+43s", the clock time in its tooltip), exit code, spans below, files changed, context window, the command and the stop reason or exit code of a failure. Open subagent, Show in Session (switches views and scrolls the Session to that row, opening its block of steps and any fold that hides the step; for a wait still open, focuses the docked request), Open subsession, Zoom to this span and Copy command act on it.
While earlier history is not held, the view reads up to 5 older pages
(run.acp.history, 1,000 items each), then leaves Load earlier. Expired
history reads "History before 14:02 expired on the server." and a failed
page shows its error with Retry. Below 561px the rows stack: the name
and duration, then the bar on its own line. The view is not offered for a
Standard session, which has no turns or timed tool calls.
Terminal view
TerminalView (terminal-view.tsx) stacks the agent's TerminalPane and
the selected shell under one toolbar, a 32px strip (44px on touch): the
terminal tabs (Agent, then each shell; one menu under 768px), + Shell,
the Tools menu, and on the right the presence summary with
ControlButton (click to take a free lease, hold three seconds to request an
occupied one; Release has the accent fill) and the connection word only
while a live session's attach is not live. A finished session reads "Container
removed · read-only" in muted text there.
Refusals, lost steering and presence errors are one line under the strip. A
session with no agent terminal, such as an Enhanced session, shows "No agent
terminal" and the shell controls. Under 768px (useIsMobile), the first time
the Terminal view shows for such a session useRunningShellOnPhone reads
the shell list with shells.refresh(), whose revision counter drops a list
that an Open shell overtook. It then shows a running shell a member
started (started_by: 'member') and has not hidden; the agent's own shells
stay behind the tab menu. A failed read shows its error with Retry. It
never starts a shell, because viewing a tab must not start a process or take
a lease: the empty state carries a primary Open shell (shells.open)
instead, with a spinner while it starts and the shell-limit reason under it
when four are running. On that view the Enhanced session's
MultiplayerControls strip, which is about the Chat lease, is hidden; the
shell's toolbar shows the shell's own control. These three follow the phone
layout's breakpoint (useIsMobile, under 768px, any pointer), because they
are layout. Fitting, read-first focus and the size stepper follow
phoneScreen (a coarse pointer under 640px) instead: the same query that
makes a terminal follow the PTY, which fitting needs, and the screens where
focus raises a soft keyboard. The frame renders one TakeoverDialog
above every sheet and dialog for the holder's decision; the dialog restores
the interrupted focus.
Shells. A shell is a shared development terminal in the session's sandbox
(terminal.md). + Shell (named "New shell")
starts one with dev.terminal.start. useRunShells(runID, visible) in
shells.tsx lists them with dev.terminal.list every two seconds while the
Terminal view is showing and every ten behind another view, and holds what
outlives one mounted shell: the write intent and controller of each
incarnation, and open, show and stop. A session's shells start hidden behind
the agent's terminal (shellShown: false in initialRunShellDock, keyed by
session id in shellDocks).
TerminalTabs draws one tab per shell: its name ("Shell 2" for the server's
tab-2, so a number never moves), the agent's glyph when started_by is
run_agent, its process state once it is no longer running, and a close
button. ShellCloseItems is what closing means, in the tab's menu and in
Shell actions alike: Hide, keep running and Stop shell for a
running shell, one Close for an ended one. Hidden running shells are a
count beside + Shell ("2 hidden") whose menu shows them again; on a phone
they follow New shell in the terminal menu. At four running shells started
by people (maxOwnShells, mirroring maxRunShells in
internal/scheduler/run_shell.go) + Shell is aria-disabled beside "At
most 4 shells", and the phone's New shell carries the reason as its
description. syncShellTerminals gives an ended shell a tab only where it
ended in front of this viewer, so a closed one never returns.
ShellTerminal (shell-terminal.tsx) owns the selected shell's attach on
/ws/attach/<session>?shell=<terminal_id> (sockets registered in
store/terminal.ts) and its own control lease, independent of the agent's and
the Browser's. A shell that open started attaches asking for the lease. In
any other shell nobody else controls, the first onData buffers what is typed
and reopens the attach with write and resume. sendPending sends the
buffer under the granted fence once the lease is held and the replay gate is
no longer muted, so keys typed while the shell redraws arrive in order; a
refusal, a release or a dropped connection discards them. If the server
answers with a full replay instead of resuming, that redraw stays on screen
rather than behind "Restoring terminal history", which would blur the terminal
mid-word.
The toolbar shows an accent-filled Release while you control the shell, or "<name> controls"
/ "The agent controls" with Take control, which confirms; with nobody
controlling it shows neither. Under 768px the controller's name moves to the
line under the toolbar. Leaving the Terminal view releases the lease. Shell
actions holds Take a screenshot and the close items. shells.stop uses
the lease the page holds, or acquires one with dev.control.acquire and
releases it afterwards; StopShellDialog asks first when someone else holds
it. A member without steer permission gets "You can view this session but not
open a shell in it" in place of the terminal.
TerminalTools in src/components/terminal-pane.tsx is the Tools menu
(named "Terminal tools"): Find (Find in recorded output while
reading history), the text size with Smaller text, Larger text and
Reset text size, Copy selection, Copy screen, Paste,
Upload image… and, on a session, Captures…. On phoneScreen the
trigger is icon-only so the toolbar fits 360px, and, except while reading recorded history (drawn at the
chosen size), the size items follow useTextSizeStepper (below), with
Fit to width in place of the reset. It is one menu at every
width; on a phone a menu longer than six items opens as a bottom sheet.
The rest of this section is the terminal machinery the session terminal, its shells and the Environment share.
CenterView mounts only the active route. A terminal key includes the route,
the authenticated identity, the terminal data-generation epoch, and the session id,
so a change of identity or epoch remounts the surface instead of reusing it.
Leaving the session closes its WebSocket and disposes xterm; no hidden live
terminal stays warm. A pinned view retains only its static presentation and
history state. Returning attaches again at the compact current screen behind
the saved reading surface, without replacing its content or position. A session
left following live output shows that fresh current screen. Neither path
replays the retained archive into xterm.
The normal session xterm requests up to 5,000 scrollback rows. Once the server
acknowledges geometry, xterm adapts the combined normal and alternate buffers
to stay near 1,000,000 cells; wider terminals therefore retain fewer rows.
That bound is the live surface. history.tsx integrates older recorded output
into upward scrolling in the same pane: normal-buffer wheel-up, PageUp,
Home, scrollbar movement or a downward finger drag freezes the current
presentation and enters reading mode. Ordinary alternate-screen gestures
remain app-owned; Shift+PageUp explicitly enters recorded output there,
using a prior captured normal screen if available rather than pretending the
alternate screen is normal scrollback.
The reading surface virtualizes visible rows plus overscan and prefetches near
the oldest loaded rows. Its bounded scroll coordinate window shifts around the
reader for very large archives; it does not discard older pages or impose a
fixed line-count cutoff. Archived rows have stable negative indices, with
the newest at -1, and retain their opaque server cursors. Frozen normal-screen
rows have nonnegative indices. An explicit inline boundary separates normalized
recorded text above from frozen VT presentation below. There is no heuristic
text deduplication across that boundary and no claim of exact historical VT
reconstruction.
history-cache.ts stores pages, continuation metadata and the frozen HTML view
in IndexedDB, with an eight-page resident text LRU. The saved anchor is a stable
row plus its relative pixel offset and horizontal offset, not a distance from
the ever-changing live bottom. Prepending pages and switching A to B to A
preserve that anchor and the same cursor-linked row while output continues.
The frozen rows keep their captured layout through live geometry changes;
shared font zoom scales their presentation without rewrapping them.
Storage is scoped by authenticated identity, terminal-data epoch, session id and
creation time. Identity/epoch changes, authoritative session deletion and stale
async completions cannot restore another scope's data. Leaving cancels fetching,
not the saved view. Browser-storage failures are visible; unavailable storage
allows an in-memory session fallback, not a durable-restore guarantee. Missing
persisted pages are errors, not silent truncation.
The saved continuation also preserves truncated_before, so a restored page
still names an expired recording prefix. An expired server cursor leaves the
read location intact and displays the refusal; it never quietly restarts
older-page loading from another window.
Arrows, PageUp/PageDown, Home, wheel and touch browse the read surface.
Scrolling downward to its bottom or pressing End returns live. Only a new
reading episode after returning live resets paging to the newest archive
head; remounting a pinned session keeps its continuation and loaded pages.
Empty bounded scan windows continue automatically while yielding to input;
genuine fetch/storage failures appear inline. Existing pane Find searches
retained loaded pages and frozen rows, not unfetched server history; copy
selects from the read surface. Typing, paste and image insertion stay muted
while reading. The hidden native host is inert; input guards block user
actions without suppressing authorized terminal-generated protocol replies.
A same-incarnation resume, when the current surface is still mounted, supplies
only the bounded gap. An invalid cursor, ring, geometry, or incarnation falls
back to a compact current-screen bootstrap through the hidden serial
transaction. A finished session stays read-only until that same session is reopened.
A reopened session reattaches its agent terminal once the old stream ends with
session ended. A run.account move does the same, because the replacement
session keeps the same name while the session stays live.
Find replaces the toolbar strip's contents while it is open, so it never obscures a matched terminal line; closing it returns focus to the terminal.
TerminalPane lays out its shared toolbar and optional Find row above the
terminal host. During a dashboard session's compact current-screen
bootstrap it receives replaying={replaying}: the xterm host is hidden with
CSS visibility while each frame-sized operation is parsed through one serial
xterm write chain. When no saved reading surface covers it, the pane says
Restoring terminal history throughout the parse, paint delay, and
saved-viewport restoration; the status clears only when the surface is ready
to reveal. It describes compact bootstrap restoration, not an archive scan.
When a pinned view exists it remains visible instead. The session terminal,
run-shell tabs, and environment dock all use this shared replay gate. User
input and terminal-generated replies remain muted through the final replay
write callback. That callback restores authorized protocol replies, including
while reading; user input remains blocked until returning live. A full replay
remains hidden for two paint turns, then its queued viewport restoration
settles before visibility is restored.
There is one vertical scroll owner at a time: xterm while live, the virtual
read surface while pinned. The host and ancestors suppress competing vertical
overflow. xterm's scrollbar inherits the host's CSS visibility: its
visible/invisible classes control opacity and must not pick up Tailwind's
visibility utilities. Otherwise an inert live scrollbar remains painted over
the reading surface or compact-bootstrap overlay.
Live xterm follows output at the bottom. Its controller still protects viewport intent across structural replay or column reflow: it restores only a current operation, with no intervening viewport interaction and no normal/alternate-buffer change. The session's saved static reading surface is independent of those live-buffer operations, so a fresh bootstrap cannot overwrite it or shift its anchor.
The scrollbar comparison shows, top to bottom, the leaked scrollbar, the corrected reading surface, and the return to the live prompt. It uses the real terminal components with synthetic output; the headless browser suppresses its own native scrollbar in captures.
Terminal tools delegate key behavior to the xterm controller and clipboard
helpers rather than putting those actions in each dock. useTerminalImage
owns the hidden file input, preview dialog, validation, upload call, and
shell-quoted path insertion. Its identity (terminal, target, active-tab
key, and enabled state) plus a generation token rejects a chooser, paste, or
upload callback that completes after the host or target has changed. The
find overlay sizes to the available width, so a narrow pane clips neither
its input nor its close control.
The image half of clipboard handling is registered by useTerminalImage with
registerClipboardImages on the current xterm input in capture phase. The
effect cleans up and registers again when the terminal identity changes; it
claims only image-file paste events from a terminal with a live image
handler and leaves text to the native xterm path.
Shared terminal geometry. Every terminal renders the server's acknowledged
grid and subsequent geometry frames, including desktop writers whose panes
are larger than another writer's. useXterm.geometry() returns the local pane
measurement from FitAddon without resizing the renderer; setGeometry() queues
the server resize and optional attach reset between xterm writes. A font or
pane resize reports the local measurement, never the smaller rendered grid,
so a viewer cannot accidentally pin the shared minimum after it grows.
Terminal padding belongs to the xterm element, not its host: FitAddon subtracts
the element's padding when calculating the rows and columns that fit.
Queued geometry work is discarded when its terminal is disposed.
The server queues geometry with terminal output. SSH and in-process dashboard
attachments request ordered framing, and the gateway emits the geometry frame
before the next output record; independent geometry and output pumps would
allow a repaint to reach xterm at the old size.
The terminal on a phone. The PTY is the per-dimension minimum over the
clients that impose a geometry on it, so a client that fits xterm to its own
pane reflows the agent's screen for everyone else. The protocol's answer is
the follow flag (docs/local-gateway.md): a follower renders the session
at the size it already is, is left out of that minimum whether or not it can
write, and is told the size in the ack and in a geometry frame after every
change. On phoneScreen - a coarse pointer on a screen narrower than sm,
from src/lib/hooks.ts - all three terminals follow: the session's terminal, its
shell tabs and the environment dock, each of which is a session someone else
may be watching at a desktop's width.
A following terminal therefore:
- sends
followin the attach header.useXterm'sfollowoption suppresses local measurements and resize reports, whilesetGeometry()applies the server's grid just as on desktop. The header carriesstandardGeometry(80x24) only for a session being created, such as a new shell tab. On phones the live terminal host exposes both axes.useTerminalPanreveals the cursor on entry, focus, input and viewport changes, without resizing xterm; a manual pan pauses following until a tap, focus or input resumes it. It rounds fractional viewport bounds inward so the whole cursor cell remains visible. History capture keeps the absolute outer pan offset separate from accumulated gesture deltas, including when disposal beats the next paint. Layout cleanup records the latest pan before host detachment, even if its scroll event has not fired. The integrated run-history surface owns both axes while reading, with live-grid panning disabled. Holding control still keeps this viewer out of the shared size calculation. - does not ask for control on entry even on the member's own session. Take
control is the only way in, and
disableStdinholds until the ack grants write - that is what makes xterm's textarea read-only, so a tap on a mirror raises no keyboard.
Sizing the PTY to a phone is not done. A phone could size the PTY while no wider client is attached, but the server keeps one grid and one transcript per session, so: every keyboard open and close would resize the agent's screen and make its TUI redraw; a desktop attaching or leaving would flip the width, and output drawn at the phone's 45 columns stays in the recorded transcript that later desktop viewers replay; and an older server reads an unknown "size only when alone" flag as an ordinary writer imposing its size, shrinking every desktop viewer. A phone therefore follows, and fits on the client.
Fit to width. useTerminalFit (src/components/terminal-fit.ts), on
phoneScreen, sets xterm's fontSize so the followed grid's columns fit the
host's content box: proportional from the drawn .xterm-screen width,
floored to 0.25px steps, no larger than the chosen size and no smaller than
minFitTerminalFontSize (7px, src/lib/term-font.ts), below which the grid
pans. It grows only when the pane, the grid or the preference changes; a
render only shrinks an overflow, so device-pixel rounding cannot make it
oscillate. 80 columns fit a 360px screen at about 7px. The fitted size is
not stored: the store keeps terminalFitWidth (persisted, default on) beside
terminalFontSize, and setTerminalFontSize turns fitting off.
useTextSizeStepper (terminal-keys.tsx) backs the sheet's bottom row -
A−, the drawn size with Fit, A+ - and the phone's Tools menu: a
step is one whole pixel from the drawn size, and a step down to the fitted
size or below the 8px zoom minimum returns to fitting, so A− is disabled
while fitted. Only a phone shows the stepper; a tablet keeps the Tools
items. A two-finger pinch on the host draws the size live in 0.5px steps;
on release it returns to fitting when it ends at or below the size fitting
would draw or below 8px, and otherwise stores the size rounded to a whole
pixel.
Read first. On phoneScreen focusTerminal() does nothing, so no
effect - a new shell, a tab change, a closed find bar - raises the soft
keyboard. Only a tap on the terminal's own textarea, or Show keyboard in
the more-keys sheet, focuses it.
TerminalKeys is shown under the host on any coarse pointer while the
terminal is writable, a tablet included. Its row does not scroll: Ctrl,
Alt, Esc, Tab, the arrows, Enter and More keys share the width at
44px tall. 4px apart. More keys (its trigger carries Radix's aria-expanded) is a
non-modal Popover above the row that keeps focus where it was: symbols a
phone keyboard buries, ^C, Home/End, PgUp/PgDn and Del; F1–F12, which
toggles the function keys; Show/Hide keyboard; and the size stepper last,
next to the row. It stays open while keys are tapped and closes on its
trigger or a tap outside. The keyboard label reads the textarea's focus and
whether the visual viewport has lost at least 120px from its tallest,
because Android's Back hides the keyboard and keeps focus. The stepper's
size readout stays focusable at full contrast while fitted, with
aria-disabled, rather than a greyed disabled button. Every key goes through
terminal.input, so the replay gate and disableStdin treat a tap exactly
like a keystroke, refuses focus on pointerdown so the keyboard stays as it
was, and then calls focusTerminal(), which a tablet honours and a phone
ignores. The row pads its bottom by --keyboard-inset (keyboard-inset.ts)
so it stays above an iOS keyboard.
Ctrl and Alt are sticky modifiers held in the host (modifiers,
tapModifier, clearModifiers on XtermController), because a soft
keyboard sends characters and never a modifier. terminal-modifiers.ts has
the rules: a tap arms a modifier for one key, a second tap within 400ms locks
it, the next tap releases it. A locked modifier stays aria-pressed, shows a
lock glyph and adds a visually hidden ", locked" to its name. applyModifiers
rewrites a single character into its control code (xterm's: Ctrl+Space and
Ctrl+are NUL, Ctrl+? is DEL, Ctrl+Backspace is ^H) and/or an ESC prefix for Alt, and the cursor, Home/End, paging and function-key sequences into xterm's1;<n>modifier parameter form. A key it does not cover passes unmodified and keeps the modifiers armed rather than spending them on the wrong byte, and a paste (flagged from the DOMpasteevent and aroundterminal.paste(), which Tools → Paste calls, since xterm hands either to onData like a key) never takes them. The row's arrows, Home and End send SS3 (ESC O) while the program has asked for application cursor keys (terminal.modes.applicationCursorKeysMode`).
Losing write access clears them.
In a session's normal buffer, a downward finger drag pans the live grid to its top before handing off continuously to integrated history. Horizontal drags do not enter history. Subsequent history swipes browse older pages or return live at the bottom. Panning either surface does not resize the PTY or raise an input keyboard. Oversized alternate screens use live-grid panning too; when the grid fits vertically, application scrolling remains native. Shells and the Environment keep native xterm scrollback.
The socket is
attach.ts, framework-free. It reusesbackoff()fromsrc/lib/stream.ts, splits paste input below the gateway's 64 KiB frame cap, and keeps callbacks bound to the current terminal host. The primary session header requestsscreen:trueandinteractive:true; shells and CLI attachments keep their existing stream modes.screen:truebootstraps the compact current screen and bounded scrollback. Upward scrolling fetches older normalized output throughterminal.history, independently of the attach. The dashboard does not download the raw archive.Controller lease and compact bootstrap. A desktop owner's attach asks for write once the Terminal view has been shown; until then it is a mirror. Other members start as mirrors. The server grants write only when no controller exists; a second tab cannot become a second writer. A mirror shows who controls ("Nobody controls", "<name> controls", "You control in another session since <time>", with "(last known)" while the status is stale) and Take control. Live, acknowledged local control reads "You control" with an accent-filled Release, plus teal control dots behind the terminal toolbar while input is writable (styles.md). They never change layout, and return to neutral during replay or history reading and after release, mirroring, disconnect or a refused write. Starting sessions keep their spinner; ended sessions show no control and replay their recording, or say This session has ended and left no recorded terminal to replay. Whether a member may write is the server's answer:
-32001downgrades the attach to a mirror and disables the control button. An occupied write request is a conflict and needs the host's shared confirmed takeover.The attach ack's
replaycount is the exact bootstrap/live byte boundary, even when a WebSocket frame straddles it. For a fresh, live, or finished dashboard session attach, those bytes are the compact current-screen snapshot, not the complete retained transcript. A valid same-incarnationresume/cursor/resume_idsupplies only the bounded gap and keeps the warm screen. If the cursor or ring cannot serve it,resumed:falseselects a compact snapshot fallback.connectAttachparses frame-sized operations through one serial xterm write chain. Input and terminal-generated replies remain muted through the final write callback; input can then open unless the user is reading history. The host stays hidden through two animation frames and structural viewport restoration, and remains behind a pinned reading surface until return-live. The attach never allocates a transcript-sized browser buffer.Control changes stay on this WebSocket. The client sends
{"type":"control","request_id":17,"write":true,"takeover":true, "control_generation":8}(omittakeoverunless explicitly displacing a controller). The ordered response hastype:"control", the samerequest_id,ok, optionalcode/error, and authoritativehas_control,control_session_id, andcontrol_generation. An unsolicited lease or steer-permission revocation has norequest_id; it carriesok:false,has_control:false, and the exact revoked generation. An interactive attach remains open as a read-only mirror, with no replay or reconnect. Input carries the currentcontrol_generation; stale input is fenced. Take and release do not reconnect or replay, and the UI changes its writable state only from acknowledged metadata.A missing session is not a dead terminal.
-32004means the session has no PTY, andinternal/sshd/attach.gorefuses rather than waits for one, so the client is what has to tell a container that is still starting apart from a terminal that is gone. Aqueuedorprovisioningsession is not attached to at all: the tab clears the pane and covers it withTerminalSpinner, the overlay the environment dock uses, reading Starting the session's sandbox, and reports no connection state while nothing is connecting. The attach effect already re-runs onrun.status, so the session turningrunningattaches on its own. On a session that is up, a-32004is retried a bounded number of times on the usualbackoff()before it counts as final, because the server names that case transient - recovery starts a session under a row that already readsrunning- and says the client's retry is what resolves it. Only then does the tab show the gateway's error.A dead end gets no Retry. Retry is offered on every refusal except on a session that has finished, where no session will ever answer it.
endedStatusesis that set, and it mirrorsreplayableStatusin internal/sshd/attach.go, which isdomain.RunStatus.Terminal(): the same answer decides whether a missing session is worth waiting out, so the client cannot drift from the server gate. A session waiting for a human is not finished, so it keeps both its retry and the gateway's own words. A session that never started has no transcript either, and itsrun.reasoncarries the provisioning failure, so the tab shows that reason directly alongside the shared session header. That substitution is keyed on the refusal's own code: only a missing session says anything about the session, so a revoked token or a withdrawn membership still shows the gateway's own message.Every attach answers for itself. The agent conversation slice is reset when the view mounts, and a successful attach clears the standing refusal. Otherwise a denial outlives the socket that produced it: leaving the tab and coming back would show a live terminal beside a stale error, with steering greyed out even after
run.handoffgranted it.Interactive revocation stays on the mirror socket. The server re-checks a live attach's authorization every few seconds. Losing the steer permission sends an unsolicited control notification on the existing interactive WebSocket; the client applies its exact revoked generation, disables input, and remains a read-only mirror without replaying or reconnecting. A raw legacy (non-interactive) attach retains the named 1008 close, reason
steer permission withdrawn. Membership withdrawal also uses 1008, reasonmembership withdrawn, and stops reconnecting. A refusal frame's own close is handled only when no prior control response explains it.Live Find, zoom, and clipboard share xterm's key handler.
xterm-host.tsxchains zoom, find, andclipboardKeysin that order; the first to claim a key stops it reaching the shell.clipboardKeysclaims copy shortcuts but leaves native paste alive.Ctrl+Shift+Fopens the find barTerminalPane(src/components/terminal-pane.tsx) places above the terminal. Live search uses@xterm/addon-search; while reading, the same bar delegates to loaded archive pages and frozen rows. No matches comes from the active surface's answer rather than a tracked count. The read surface handles the same find, copy and zoom shortcuts without forwarding typing or paste to xterm.Ctrl+=,Ctrl+-andCtrl+0moveUiSlice.terminalFontSize, clamped to 8-32px byclampTerminalFontSize- on the way in from a keystroke and again in the store'smerge, because a same-version reload never reachesmigrateand xterm does not validatefontSize. The size is one persisted preference behind every terminal, applied to the live instance and re-fitted rather than by rebuilding it, which would throw the scrollback away. The static reading surface scales with that same preference while preserving its row-relative anchor.DOM renderer, deliberately.
@xterm/addon-webgl0.19.0 can reuse stale glyph-atlas positions under heavy glyph churn (xtermjs/xterm.js#6038), garbling scrolled rows until a forced refresh; the DOM renderer never desyncs. The terminals render in the shipped JetBrainsMono Nerd Font Mono (src/lib/term-font.ts, declared insrc/index.css), so agent TUIs get their powerline and devicon glyphs at the same advance as text. The terminal opens only once regular and bold faces are loaded, because xterm caches glyph metrics synchronously atopenand would otherwise bake fallback metrics in.Delivered messages need no extra terminal work. Once a message to the agent is delivered, the server writes the attributed member-coloured banner into the PTY stream itself, so it arrives as ANSI and xterm renders it like any other output.
The terminal's colours are the one place the tokens cannot be used directly:
xterm needs resolved theme values rather than the CSS variables, so the view
reads the computed background and foreground off its own host element and
re-reads them when the dark class on <html> changes.
Changes view and Publish
src/routes/diff/ is the session's Changes view, and src/store/diff.ts holds
both what it renders and the overlap set the conflict chips read.
- One strip, then the files. A 32px strip (
strip.tsx) holds the file count and+a −dtotals, the Compare menu, the conflict chips, and on the right Wrap lines, Refresh, More (Expand all files, Collapse all files, Review locally…) and Publish…. A file list (file-list.tsx: status letter, name, folder,+a −d) runs down the view's left edge once the view itself is 780px wide - a container query, so opening Details narrows it too; narrower, the count in the strip is a menu of the same files. Picking a file opens it and scrolls its header to just under the strip. With nothing changed the view is the "No changes yet." empty state.Land(land.tsx) adds a row above the git card only after a pull put the session branch on this machine, with the same Switch to it as the pull's toast. - The card scrolls away; the strip stays. Everything right of the file
list is one scroller:
Land, the git card, the strip with the review bar, then the patches. Scrolling down moves the card out of view while the strip sticks to the top and each file's header sticks under it, so a long list of checks never squeezes the diff. The strip's measured height is the--diff-topCSS variable the file headers stick to, and the virtual file list'sstartMarginis its measured offset in the scroller. - The git card sits above the strip.
components/workflow/git-flow.tsx(GitFlow, model instore/git-flow.ts) is the session branch, its pull request, checks and merge readiness in one card that updates in place. The header is the pull request's title and#128linking to GitHub with Draft, Open, Merged or Closed and its dot, or the branch name before there is a pull request. Its commit list shows at most six rows (168px) and scrolls inside the card past that; the rest of the card takes the height it needs. The Workflow panel shows it withcompact: the header, the head row, one line of check counts and the primary action, with Show N commits unfolding the graph. The panel leaves it out while the Changes view shows the full card. - The graph is
run.git.log. One 28px row per commit under one SVG of two lanes: the session branch's commits (commits) on the accent lane, the base's commits the branch does not have (upstream) muted on the second, interleaved by time, and the merge base at the bottom. A merge curves into the base lane from its own row; the branch's first commit bends into the merge base. A row shows the subject (focusable, with the full subject in a tooltip), a mono pill with the branch or base name at its tip, the short SHA, and the author and age once the card is 420px wide. An upstream commit that touches a path a merge would conflict on (paths) is amber with a count. More than eight commits fold into N more commits, which keeps the three newest upstream commits in sight and unfolds the rest; atruncatedlog ends in a row that says so, with dotted edges. The top row is the pending action, a hollow node with dashed edges to both tips: Open pull request, Merge into main, Merged into main, Closed without merging or No commits ahead of origin/main, with its state on the right: 2 conflicts (a button whose popover lists the files), 3 behind, not pushed, draft, ready, merged, or what else holds the merge. The status line under the card reads "7 of 9 checks passed · 1 running · 2 ahead · 1 behind origin/main". A failed log read keeps the last graph on screen beside the error. - Checks, reviews and readiness come from GitHub. Each check from the
last
run.pr.feedbackis a pill, failed first, with its name and passed, failed or running; its tooltip gives its status and conclusion and the pill links to the check on GitHub. Under them, the latest approval or change request of each reviewer by name, and the review comments behind a disclosure (send them to the agent from the header's dialog). Merge readiness lists Draft for a draft, then Checks, Conflicts, Review and Base, each with its own dot. With a pull request, Conflicts and Base are GitHub'smergeableandmerge_state_status:CONFLICTINGis "GitHub reports conflicts with main", naming the file count when the session's log measured the same merge;BEHINDis "Behind main";BLOCKED, a branch rule GitHub still enforces such as a second required approval, blocks the row and offers Open on GitHub instead of Merge;UNKNOWN, which GitHub answers while it is still computing, is Not checked yet. While the checkout has commits the pull request lacks, Base reads "Pull request head is behind the branch: 2 unpushed commits" and Merge is not offered. Before a pull request the log only predicts, against the checkout's last fetch of the base: "1 file conflicts with origin/main as last fetched" holds the row, and "None against origin/main as last fetched" is never counted as done. Anything not yet read, read from a failed refresh, or from a partial answer is Not checked yet or "Incomplete answer from GitHub", though a failure or change request it saw still counts. The heading reads Ready to merge only when every item is grounded. - One primary action, by state. Review changes (outside the Changes
tab, with nothing to publish yet) opens the Changes tab; Open pull
request opens the Publish dialog, which also appears when the branch is
ahead of its base with an empty patch; Ask agent to resolve conflicts
sends the session, through
useAgentSend, one message naming the base, its commit and every conflicting file the log found (or only GitHub's report when it found none against that base), under the composer's rules, and the receipt reads "Sent conflict list to Claude Code."; Squash and merge callsrun.pr.mergewith the pull request's repository, number,expected_head(the head on screen),expected_baseandexpected_login, after a confirmation that repeats the checklist, and its menu switches to Create a merge commit or Rebase and merge; Open on GitHub covers a draft, a blocked, an unpushed, a merged or a closed pull request. A merge GitHub accepted but has not done, as through a merge queue, showsgh's output, or "GitHub has not merged #128; it is open.". Open, merge and resolve need a live session, the collaborator role and leave to steer the session (its owner, or anyone the session's protection and the workspace'ssteer_othersallow), the rules the server applies; resolve also needs a member who may message the agent now. While the card offers an action, Publish… turns secondary, so the view keeps one filled button. A running action disables its button with a spinner and names itself in the status line. Every error, from the log, the feedback, a send or a merge, is shown as the server or GitHub wrote it. - The card reads on events, not timers. The log is read when the first
card for a session mounts and again on each
git.branchevent for the session (gitSeqinstore/workflow-signals.ts), and with each 60s pull request poll, since a fetch moves the base without agit.branchevent. The pull request is read again onrun.prandgit.branch. One read of each is in flight per session (store/coalesce.ts). A refetch keeps every row whose commit did not change as the same object, so its memoised row does not re-render. A polite screen-reader region repeats the status line once it has held for a second. - The patch is fetched, the events only say when.
run.diffcarries per-file stats and no patch text, so a snapshot bumps the session'srevisionand the view re-fetches the chosen comparison fromGET /api/v1/run/<id>/patch(docs/local-gateway.md) whenever that has moved past thefetchedrevision the stored patch answers for. Counters rather than a stale flag, because a snapshot landing during a request would write true over true and then be cleared by the response: the answer records the revision it was issued at, and anything newer asks again. A failure records the revision too, so it cannot spin, and the patch already on screen stays beside the server's error; the next snapshot or Refresh asks again. One fetch per session is in flight at a time, even across a remount of the view. A stored patch over 1 MiB is not re-fetched on a snapshot, so a reader is never frozen or reshuffled mid-read: the strip's button becomes New changes · Refresh and loads them on click. The store keeps one patch per session and records which comparison it answers for (from); choosing another comparison shows a loading state and fetches at once, never the previous comparison's text. The loading state, after ~200ms, is a skeleton of a file header and ten lines of code, announced as "Loading the diff…". An empty comparison is anEmptyStatewith a branch icon and a title without a period ("No changes yet"). - Files are split by scanning, then parsed when read.
parsePatch(parse.ts) finds eachdiff --gitboundary and counts a file's additions, deletions and content lines without allocating a row per line, so a 20 MB patch splits in well under a second. A file'slinesare parsed the first time something reads them, so a closed or off-screen file is never split into lines. A refetch hands the previous files back in, and a file whose text is unchanged is the same object, so its memoised rows and placed review comments are not redone. - Compare is a menu. The Compare menu chooses what the patch is measured
against, and its trigger names the choice. All changes (the default)
is the cumulative diff against the session's effective base, described as
"Against main @ 1a2b3c4" with the base branch and the short sha the patch
response names. Since the session started appears only when that base
differs from the fork point on the session record (
base_commit), meaning the session merged upstream work: it requests?from=<fork_tree>, so it also counts that upstream work. Under Changes since a checkpoint every recordedrun.diffsnapshot is a row, newest first, labelled with its local time (with the date when not today) and its age. Its description is the session at that checkpoint, not the size of what choosing it shows: "After" and the commit subject whenheadmoved since the next older checkpoint, otherwise "Session had N files · +a −d", the session's totals then (the count alone for atruncatedsnapshot). The newest row says "Latest checkpoint" in place of the totals, after the subject when it has one, since choosing it shows only edits not yet snapshotted. Choosing a row requests?from=<tree>: everything that changed since that checkpoint up to now, which grows as the session goes on and re-fetches on each new snapshot like the whole diff. The newest 50 checkpoints load fromworkspace.timeline(types: ["run.diff"],newest: true) when the view first opens for a session on this page, live snapshots join them, one row per tree, and Show older checkpoints pages back withbefore_seqwhile the timeline saysmore. A checkpoint keeps only its time, tree, head, subject and counts, never its file list. A snapshot with no tree - from a server that predates them, or one whose capture failed withsnapshot_error- is a disabled row whose description says why; ahistory_gapbefore a recorded tree does not disable it. A failed history read shows the server's error with Retry. A link withfileordiff: 'current'selects All changes. - Big files start closed. Each file (
patch-view.tsx,FilePatch) has a sticky header with a chevron, its path, a status word and+a −d. A file over 500 lines or 256 KiB of patch text, a binary file and a deleted file start collapsed; the header then also gives the line count, or the size for a file big in bytes but short in lines, such as a minified bundle. Line counts here leave out hunk headers. An opened file over 500 lines renders its lines throughvirtuain a box of its own. A patch over 1,500 lines in total or over 100 files also mounts only the files near the screen, so a large diff costs the rows on screen rather than one DOM node per line. The file list virtualizes past 100 files, and the strip's file menu lists the first 100 and says how many more there are. A line renders at most 3,000 characters followed by "… N more characters"; review comments still quote the whole line. Lines carry old and new line numbers, whichparse.tsreads from the hunk headers. - The path opens the file. Clicking a file's path opens it in the session's
Files view (
openInFilesinroutes/files/open.ts), without leaving the session. It needs a session that has a Files view. Binary files and files the current diff shows as deleted have no link. - A link can name a file. A navigation to the session route with
view: 'changes'andfile: <path>selects All changes, expands that file and scrolls to it once the diff has it;diff: 'current'selects All changes alone. The Chat view's changes bar navigates these ways.fileis not written to the address. - Lines take comments. A review comment is a note on one line or a range
of lines of the diff, held in this browser until it is sent to the agent.
Each line's number gutter takes a click (
LineGutter,components/ui/line-gutter.tsx) and shows a+while the pointer is on the line or the gutter has focus, and nothing otherwise. A click opens an editor under the line (comment-card.tsx). Comment orMod+Enterpins it, Cancel closes it, andEsccloses one nobody typed into. A pinned comment has Edit comment and Delete comment. For a range, drag across the gutters, Shift-click another line while the editor is open, or holdShiftwith↑/↓and pressEnter; a range stops at the edge of its hunk. A file's gutters are one tab stop and↑/↓move between its lines: only the line the keyboard is on has a real button, so a long file adds one control to the page and to a screen reader, not one per line. On a touch screen a tap on a line shows its+, and a tap on another line while the new editor is still empty makes the range. A new editor nobody typed into closes when another opens. Commented lines keep a tinted gutter and the file header counts its comments. The Files diff pane and the Publish dialog passFilePatchnoreview, so their lines stay plain. - A review is one message. The review bar (
review-bar.tsx) is a row under the strip that exists only while a pinned comment waits or the last send has a receipt. It holds the count, Discard behind a confirmation, and Send to agent, the view's filled button while it shows (Publish… turns secondary). Sending builds one message (reviewMessageinreview.ts): a numbered block per comment in file order then line order, each withpath:lineorpath:start-end, the lines in adifffence with their+,-or space markers, and the comment. Line numbers are the new file's; lines that were only removed give the old numbers and(removed). An open editor's text is sent in place of the pinned text; an empty one leaves the pinned text as it is. A sent or queued review clears the comments it carried, except one changed while the request was out, and leaves "Sent 2 comments to <agent>." with Open the session; the receipt reads the room message from the store, so a later denial or failed delivery replaces it. A send the server refuses, cannot deliver or cannot vouch for keeps every comment and shows the server's error in the bar, beside the reason when the session has since stopped taking messages. sendToAgentis the send path.src/lib/send-to-agent.tstakes a session, the text and, when the tab holds it, the control lease. It posts a roomsteer_requestand returns the room message, whosestateis the receipt, so the composer's rules in Session control apply unchanged. A send the server has not answered keeps its idempotency key by session and text until it is answered or another member signs in: the same text sent again is delivered once, whatever went to the session in between.useAgentSend(agent-send.ts) wraps it for the review bar and the pull request panel: it passes the lease and, for the owner of a session nobody controls, takes it first (useImplicitControl); anyone else's message waits 45 seconds for the controller, and both surfaces say so. Send to agent is disabled, with the composer's own sentence beside it, for a finished, starting or switching session, a Background session, a protected session and a member who may not message the agent. Both surfaces word their receipts with the samereceiptfunction.- A pull request's feedback is one click from the agent. The check state
in the session header (Header) opens
publish-feedback.tsx, a dialog that is a bottom sheet on a phone: the pull request's title linking to GitHub, its state and target, then Checks and Review comments from the lastrun.pr.feedbackanswer, with Refresh to ask again. Failing checks come first, then running ones, each named with its conclusion and linking to its page on GitHub; passed checks fold into "7 passed" under them, and are listed outright when no other check is. Comments are the pull request's conversation, its inline review comments with theirpath:line, and reviews that approve, request changes or carry text, oldest first. Each failing check and each comment has Send to agent, which sends one message: the pull request, its target and head, then the check's name, conclusion and link, or the comment with its author, lines, commit and diff hunk. The server returns no log for a check, so none is sent; the link is what the agent reads it from. The row then shows the receipt, "Sent 1 check to Claude Code." with Open the session, or the server's error with the button still there. One send is out at a time: the other rows' buttons are disabled from the click until the server answers, including while the owner's tab is taking control, and a send whose control never arrives says so and frees them. GitHub's own error, when the read fails, shows above the lists with the last answer kept under it. - Comments follow their lines. Unsent comments sit in their own Zustand
store in
review.ts, keyed by session, for the reason composer drafts do. They survive switching views, opening another page and every diff refresh, and end with the page, a deleted session or another identity. A comment stores the lines it was written on - kind, text, old and new numbers - and which comparison that was:''for All changes,startfor Since the session started,since:<tree>for a checkpoint.locatefinds those lines in the diff on screen: at the same numbers first, otherwise where the same block appears exactly once. A comment therefore follows code that moved, and is never pinned to one of two identical blocks by guess. A comment whose lines the diff no longer shows is kept and marked Outdated with its quote, at the top of its file, or above the files when the file left the diff; it is sent with that quote and a note that the lines changed. A comment written on another comparison shows wherever its lines appear and is counted otherwise. - Colour is the whole of the highlighting. Added and removed lines use the
diff-addanddiff-deltokens. The dashboard never edits code, so there is no editor and no language grammar. The server sends complete session diffs up to 64 MiB, and the parser stays tolerant of incomplete input. - Long lines wrap or scroll, and the pointer picks which first. Wrap
lines starts on for a coarse pointer and off for a mouse. The choice is a
persisted view preference on the UI slice (
diffWrap), which the Files diff pane and the Publish dialog's diffs read too. - Review locally is a dialog. More → Review locally… shows the two
copyable
gitcommands that read the session branch in the linked repository and the output of the last pull (review-commands.tsx). It is gated on thepulllocal verb: a gateway without it - a phone on the server's dashboard - has no repository for those commands to run in. - Publish is two steps. Publish… appears with
run.git.statusonce the diff has a file, and openspublish-dialog.tsx, a bottom sheet on a phone. One line above both steps names what they act on and as whom, "aether/run-1at4f9c2a7d· as Ada Lovelace · GitHub ada-l", with Refresh status beside it and the status's own errors under it. 1 · Commit selects changed paths, reviews their worktree and staged diffs and untracked contents, and runs Commit selected. 2 · Push and pull request is where the dialog opens when the first status has nothing to commit. The dialog's state lives inpublish-state.tsand stays mounted while the session is open, because the Changes view stays mounted after its first visit, so a typed message and a PR creation whose outcome is uncertain survive switching steps, closing the dialog and switching views. - The destination is two sentences. Step 2 (
publish-push.tsx) says where the work goes instead of asking: "Pushes commit4f9c2a7dtohttps://github.com/acme/app.gitas branchaether/run-1. Never a force push." and "Opens a pull request intoacme/app:mainfromada/app:aether/run-1as ada-l. It is not merged from here." Under them sit only what the member writes, PR title, PR description and Draft PR, and the buttons. A pull request the branch already has replaces the second sentence with its number, title and state, linking to GitHub, and the title fields go. A push to anything but GitHub says no pull request is filled in. - Change destination holds the fields. The seven fields the sentences are built from, the push remote, its URL and branch and the pull request's repository, base, head repository and head branch, sit behind one disclosure with Discover existing PR, the full HEAD, the agent account's id and the branch's upstream. It opens by itself only when a sentence cannot be written or a destination refused: no checkout Origin, a remote with several push URLs, a detached HEAD, a refused push, a failed lookup or a failed creation. The reason is on screen with it, in place of the sentence or in the outcome under it.
- Defaults come from the checkout. Every field starts from what the
checkout and the workspace already say (
publish-target.ts), follows each status refresh, and stops following once the member edits it. The push remote is the branch's upstream, elseoriginwhen the workspace has a checkout Origin; without oneoriginis the server's own repository, so nothing is chosen. The push URL is the remote's, when it has exactly one, and the branch is the upstream's or the checkout's. The pull request's head is that push when its URL is a github.com repository, its base branch is the session's, and its repository is the one the workspace's source mirror reads (workspace.mirror.status), which for a fork Origin is the upstream; without a GitHub mirror it is the head repository. The title is HEAD's subject (head_subject) once the session has a commit of its own. - One button publishes, and says how far it got. With no pull request yet the filled button is Push and open pull request: it pushes, and only if the push landed opens the pull request. Each half reports under its own sentence, Push outcome and PR creation outcome, with the server's error and output, so a push that landed stays "Pushed: yes" whatever the pull request did. After such a partial result the filled button is Open pull request, which only creates. Push only sits beside both. A branch with a pull request, or a push that leads to none, has Push branch alone. An uncertain creation leaves Reconcile PR read-only, which looks the exact target up and never creates.
- The server holds the fences. Nothing is pushed or opened unless its
sentence is on screen, and every mutation names the branch and HEAD in
that sentence: the server refuses it when the checkout moved, refuses a
push unless the remote still has exactly that URL, and refuses a creation
when the GitHub login is no longer the one shown. The dialog looks for an
existing pull request by itself (
run.pr.status) after every status read, which follows opening the dialog, Refresh status, a commit and a push, provided GitHub is logged in and the target is complete. Editing a field stops that until Discover existing PR is pressed, so a half-typed target is never looked up, and a pull request can be opened only after a lookup of the exact target on screen has answered. - Conflict chips write their list out for a finger. The overlapping file names live in the chip's tooltip, which a touch screen cannot open, so on a coarse pointer the same list is rendered as visible text beside the chip.
- Conflict chips are advisory.
conflict-chips.tsxregisters an overlap count intocard:meta, whose popover lists the chips, and the Changes view renders the chips in its strip. It reads the overlap set the conflict radar reports (run.overlapsat hydration, thenrun.overlapevents), names the file and the other member, and navigates to their session. Attribution comes from the sessions the store already holds; an empty peer list means the overlap cleared and the chip goes.
Multi-repo sessions
A session launched with extra workspaces carries repos (RunRepo: workspace id,
name, container path, branch, primary), the primary first; a single-repo session
has none and shows none of what follows. The dashboard offers it only when the
gateway lists the run.repos method.
- Launch. With another workspace to add, the launch dialog shows Add
repos (
launch/extra-repos.tsx) in the launch form, a checklist of the member's other workspaces. Each pick becomes a chip and goes out asextra_workspace_idsonrun.launch; the repo is checked out at/repos/<name>. A subsession inherits its parent's extra repositories. - Changes. The view gains a Repos tab strip above it: one tab per repo
with its changed-file count, then All repos. The choice is the
repoquery parameter of?run=<id>&view=changes(a workspace id, orall; none is the primary). The primary tab is today's view unchanged. Another repo (repo-changes.tsx) shows that repo's files against its base, with its own review comments (kept under<session id>#<workspace id>inreview.ts), Publish, pull request and Merge (squash); every call carriesrepo. It has no Compare menu: Compare ranges over the session's diff snapshots, which exist for the primary repo only. The primary tab's count comes from the session's snapshot, and from arun.patchread until the first snapshot arrives. All repos lists each repo's changed files under its name, branch and pull request; a file opens in its repo. Paths in a repo are relative to that repo. - Files. With extra repos the view gains a Repos strip above the tree.
An extra repo's tree, files, saves and diffs send
workspace_idof the primary plusrepo(the server refuses anotherworkspace_id), and open files are keyed byrepoas well. The changed-file dots come from that repo's patch. - Pull requests. The header's pull-request group becomes one chip, 2
PRs, with the worst check state of them (failing, then running, then the
rest). It opens a list of repo,
#numberlink, state and checks, and Feedback opens the usual panel for that repo (repo-pull-requests.tsx). A pull request is tracked per session and repo inpublish-pr.ts. - Names. The session header, sidebar rows and board cards read
repo +Nwhen the session has extra repos.
Browser view
src/routes/browser/ is the session's Browser: a tab among the session's views,
or a pane beside them (see Chat view), in the same bundle the
local SSH gateway and the server-hosted tailnet gateway serve. It shows the
session's own Chromium, which the server starts beside the session's container in the
same network namespace, so http://localhost:3000 is the app in the session, not
the phone or laptop looking at it. It is not an iframe or a forwarded preview
host: app JavaScript, cookies, redirects, popups and hot updates run there.
No debugging/CDP endpoint is exposed to the dashboard.
Opening the view reads status, pages and the control lease; it starts no browser. It re-reads every 1.5 seconds while the tab is visible and the session is live. The first page starts the browser, which takes longer than later pages; the pane says Starting the browser meanwhile. A server that cannot run one answers the status read with its reason, and the pane shows that reason under Browser unavailable. A status read that fails shows its error the same way:
dev.browser.status: scheduler: the session has no live environment: the session is provisioningOne row of chrome (index.tsx), a toolbar named "Browser":
- Back, Forward and Reload, icon buttons whose tooltips carry their shortcuts. Reload is a spinner while a navigation this tab started is in flight.
- The Address field (
address-bar.tsx). - Ports (
ports.tsx): how many ports the session is listening on, with their list behind it. A pane narrower than 480px has no room for it; the address field and the empty pane list the ports there. - Keyboard, on a coarse pointer only: it opens the phone's keyboard for the page, which a tap on the page deliberately does not.
- Annotate, a toggle; see Annotate below. A phone's row has no room for one more button, so there Annotate starts from Browser actions, and while it is on its toggle takes the place of Keyboard.
- Console and network, a toggle that counts the rows not yet seen; see Console and network below. In a pane narrower than 480px it is in Browser actions, and that button carries a dot instead of the count.
- Viewport, a menu: Fit the pane, Desktop 1280 × 800, Tablet 820 × 1180, Phone 390 × 844. In a pane narrower than 480px the same choices head the Browser actions menu instead.
- Show beside Session / Show the Browser as a tab, only on a frame wide enough for both.
- Browser actions: New page, Screenshot, Release control while this tab drives, Close page… and Reset session….
- Who is driving, when it is not nobody; see Control below.
A second page or a popup adds a tablist named "Pages" under the toolbar;
with one page there is no strip. A page that opened by itself carries a dot
and "(new)" in its name until it is selected. Selecting a tab selects that
page for the agent and every other viewer. New page opens a blank page
and puts the caret in the address field.
Under the chrome there is only the page. Before one is open the pane reads Open a page over the ports the session is listening on, each a button that opens it (see Ports below), and the address field has focus, except on a touch device and when the Browser is docked beside another view. A message about an action, such as a failed navigation or who is driving, is laid over the top of the page with a Dismiss button, so it never changes the page's size.
Address. normalizeAddress (address.ts) gives a scheme to an address
typed without one, because the server accepts absolute http(s) URLs and
about:blank only: localhost, *.localhost, an IPv4 literal or a bracketed
IPv6 literal becomes http://, any other host https://, and an address
that already has a scheme is sent as typed. There is no search fallback and
no history. Focus selects the whole address. What is being typed is kept
until it is submitted, dropped with Escape, or the page moves on while the
field is not focused. Enter navigates the selected page, or opens the first
one. Enter pressed while another action is still in flight runs when that
action ends; of several, the last one. Once its own address has opened, the
field hands the keyboard to the page, unless focus has moved or something
else was typed meanwhile. A navigation the server refuses shows the server's
message and leaves the typed address in the field:
dev.browser.navigate: browser: page.goto: net::ERR_CONNECTION_REFUSED at http://localhost:3000/With a page open, the focused field is a combobox that offers the listening
ports whose address contains what is typed, in a listbox under it. Up and
Down choose one, Enter or a press opens it, and Escape drops the offers with
the draft. With no page open the pane already lists them.
Ports. usePorts (ports.tsx) reads dev.port.list when the view opens
and every three seconds while the view is shown, the browser tab is visible
and the session is live. Nothing is pushed, and a server without the method gets
none of this. A port reads as the address that reaches it from inside the session
and the name of the executable listening, as in localhost:5173 node:
localhost for a port bound to every interface or to loopback, the address
itself for any other binding (portAddress in src/lib/ports.ts). The ports
are listed before a page is open, behind Ports in the toolbar, and under
the address field. Picking one opens it like an address typed and entered:
the first interaction takes the lease, and the keyboard goes to the page once
it is open. With nothing listening the pane says what to do:
Nothing in this session is listening on a port yet. Start a server in the Terminal, or ask the agent to, and it appears here.A read that fails shows the server's error where the list would be.
Each listed port also has Open on this computer on the local gateway and
in the desktop app. It reads the ports again, starts a forward from
127.0.0.1:<port> on this machine (forward.start) and opens
http://localhost:<port> in the person's own browser (openOnThisComputer).
The tab is opened before the first request, so a popup blocker lets it
through, and closed again when nothing was forwarded. The row then links the
forwarded address and says where to stop it. A forward cannot reach a port
bound to loopback (local-gateway.md),
so none is started and the row names the address:
Port 5173 is bound to ::1 inside the session, so only the session can reach it. Start the server on 0.0.0.0 to open it on this computer.A port that closed since the last read answers "Nothing in the session is listening on port 5173.", and a forward the gateway refuses shows its error:
localops: listen on 127.0.0.1:8000: bind: address already in useThe server-hosted dashboard has no machine of the viewer's to open a port on.
There the button is Open on your own computer, and it shows
aether forward <session-id> <port> beside Copy the command.
Control. Input to the page is serialized by one lease per session browser
(dev.control.*, surface browser). The server fences every mutation by the
lease's session and generation, an agent may take a free lease but never one
a person holds, and a person may take over from anyone; see
coordination.md.
A lease held over HTTP does not expire, so the dashboard holds one only
while the Browser is what its user is working in:
- Nobody driving: the first click, key, scroll, toolbar action or Enter takes the lease without asking and then acts, so the first click lands on the page. A click beside a page that does not fill the pane takes it too. There is no Take control button.
- This tab driving: a pointer mark in the toolbar, You are driving beside it in a wide pane, and Release control in Browser actions.
- Someone else driving: the toolbar names them ("The agent is driving", "Pat is driving", "You are driving in another tab") beside one Take over button, which displaces exactly the lease it shows. Until then every action here does nothing but say who is driving.
- The user goes elsewhere: the tab releases its lease, so the agent or a
teammate can drive. Elsewhere is the window losing focus or being hidden,
the view or the dashboard being left, and focus or a key press landing in
another part of the dashboard, such as the composer beside a docked
Browser. A menu or a dialog does not count, since it may be the Browser's
own. An action still running when focus or a key lands elsewhere in the
dashboard, such as the first page opening, finishes and then gives its
lease back, and takes no focus back with it; so does a terminal link
opened in a docked Browser while the keyboard stays in the terminal. A
press on the page whose lease arrives after that is dropped with the
lease. A press, a touch or a wheel in the Browser is a return to it,
though none of them moves focus. A status read that finds this tab still
holding the lease while its user is away, because a release failed,
releases it again. Nothing is shown as blocked on return; the next
interaction takes the lease again when it is free. A wheel over a window
that is not focused takes nothing. The release is sent
keepalive, so it survives the tab closing.
A reload starts a new tab-local control identity. A lease the old one still holds reads "You are driving in another tab".
Viewport. While this tab drives, the page's viewport follows a target:
the pane's size (paneViewport in viewport.ts, inside the 240-2560 by
240-1600 the server accepts) or the chosen preset. A mismatch is corrected
250ms after it last changed, but not until the page has had no input for half
a second, and never while a pointer is down, text is being composed or an
earlier correction is still being applied: a resize invalidates input aimed
at the old viewport. The first page opens at
the target. A preset is remembered for the
session while the dashboard stays open (browserPresets). Presets change the
real remote viewport, not the displayed image, and emulate no user agent,
pixel ratio or hardware. A page someone else drives keeps their size here and
is shrunk to fit; a frame is never enlarged, so a preset smaller than the
pane shows at its true size.
Stream. The page arrives as frames on /ws/dev/browser/{run_id}
(surface.tsx), one bounded binary frame per WebSocket message (16 KiB
metadata and 2 MiB image maximum). The view keeps one pending compressed image
and one decode, closes decoded bitmaps after painting, and never builds an
image history. A stream that closes or is refused reconnects by itself after
0.5, 1, 2, 4 and 8 seconds, with the last frame still on screen and the lease
untouched. A press the page still held is released and what was queued is
dropped; until a fresh frame is painted the page takes no input, since the
real page may have changed under the frame that stopped updating. When the
sixth attempt fails the pane shows The page stream
stopped, the server's last refusal or the socket's close reason, and
Retry.
Input. Click or touch the image to interact. Keys carry their modifiers, pointer gestures include button and click count, wheel input scrolls the remote page, and up to ten touch contacts retain distinct IDs. Committed composition/IME text is sent once rather than forwarding intermediate candidates. Input uses the metadata of the frame actually painted, including page revision and viewport ID; coordinates exclude the margin around a shrunk frame and undo image/page scaling. The ordered input buffer is capped at 32 operations and one second, not counting the time taken to acquire a free lease; redundant moves for the same contact are coalesced. A changed frame identity, expired input or changed authority discards pending input with a visible message. Failed mutations are not retried or replayed. While a toolbar action or a viewport change is in flight, input is dropped without a message. A press still held when a toolbar action starts is released first, because its release could not follow an action that changes the page. Native hardware-bound login flows and identity providers which reject automated Chromium remain limitations; use test accounts rather than importing a personal browser profile.
Shortcuts. The page receives every key pressed on it, so the four Browser bindings are matched first and kept from it; see Keyboard and focus. The address-bar shortcut shows the Browser first when it is neither selected nor docked. It is also the way out of the page for a keyboard user, since Tab goes to the page.
Links from a terminal. openRunLink (open.ts) is the link handler of a
session's agent terminal and shells. An http(s) link to localhost,
127.0.0.1, 0.0.0.0 or [::1] is recorded in browserRequests; the session
frame shows the Browser unless it is already docked, and the Browser opens
the address as if it had been typed. A path in the session's checkout opens in
its Files view. Every other link opens in a new tab as
before, and an OAuth callback link is still intercepted first. The
address-bar shortcut uses the same record with an empty address.
Switching to another session view or closing the dashboard detaches observation
only. The app, pages and login continue according to the session's lifetime.
Close page… and Reset session… take the lease like any other action
and then confirm in the shared AlertDialog. Close removes the selected page
for everyone while leaving the other pages and the session; Reset destroys
shared pages, cookies and logins. Each confirmation captures the session and
control identity and generation, plus the page and revision for Close. A
replacement page, session or authority invalidates it rather than retargeting
the mutation; that includes the lease released by a window blur. Cancel
restores focus to Browser actions, and raw failures remain readable in
the confirmation. Closing the session owns stopping the companion itself.
Annotate. A person points at what is wrong instead of describing it.
While Annotate is on (annotate.tsx), the pointer picks elements and
sends the page nothing. Moving it outlines the element under it with a label
such as button#save 120 × 36; a click, or a tap on a phone, opens a card
beside that element. The card names the element, shows where it comes from
(src/components/SaveButton.tsx:12:5 when the page exposes it, its selector
otherwise) and takes the comment. Comment pins a numbered marker;
Cancel, or Escape in an empty card, drops it. A marker opens its note to
read, edit or delete. Leaving the mode, by the toggle, its shortcut or Esc,
keeps what an open card holds.
The outline is drawn beside the canvas from the bounds dev.browser.inspect
returns, one read at a time and at most ten a second, so it can trail the
pointer by a frame. Nothing is injected into the page. Inspection is a read:
it needs no control lease, so a page the agent is driving can be annotated
without taking over, and annotating never takes the lease. The wheel still
scrolls the page; keys do not reach it. Markers show while Annotate is on and
the Browser shows the page they were made on at the same viewport size, and
they follow the page's scroll. Picking needs a pointer; a screenshot note and
the console rows below do not.
A server without the method, or a session whose browser companion is older than the server, cannot annotate. The toggle is dimmed, and its tooltip and a notice give the reason in the server's words:
dev.browser.inspect: this session's browser companion predates dev.browser.inspect; update the server's browser image, then stop and reopen the session to replace the companion: browser: invalid_request: Unknown browser operationScreenshot calls the real capture API at its own recorded boundary, not a canvas copy or the last received frame, and needs no lease. It creates a private transient capture and a note for it, with its card open: words for the agent are optional, Keep as evidence… opens Captures (see Captures), where a member inspects and retains it, and Remove takes it out of the message while the capture stays in the session. Taking a screenshot does not publish or retain anything.
Send to agent. Once there is a confirmed note, a screenshot or a ticked
row, a bar under the toolbar (feedback-bar.tsx) counts them, "2 annotations,
1 screenshot, 1 failed request", beside Discard and Send to agent. It
is the Changes view's review bar for a page: one message, sent under the
Chat composer's rules (useAgentSend), with delivery reported the same
way. A refused send leaves everything in place under the server's reason.
Sending first uploads each annotated element's picture through
terminal.image, which returns a path inside the session. The picture is cut in
the dashboard from the frame that was on the canvas when the element was
picked, with 12 pixels around it. A gateway without terminal.image sends the
notes without pictures. The message (feedbackMessage in feedback.ts)
gives the page URL and viewport, then for each note what the person wrote
followed by what the page says:
Feedback from the page in this session's browser: 1 annotation, 1 failed request.
Each screenshot path is an image file inside the session; open it to see what I saw.
Page: http://localhost:3000/settings (viewport 1280x800)
1. button "Save changes"
The label is cut off at this width.
- Screenshot: /home/aether/.aether/terminal-images/image-4f2c.png
- Selector: button#save
- Source: src/components/SaveButton.tsx:12:5
- Component: App > Toolbar > SaveButton
- Role: button
- Name: Save changes
- Text: Save
- Attributes: id="save" class="btn primary"
- Bounds: x 40, y 30, 120 x 36
- Styles: display: block; position: absolute; width: 120px; ...
```html
<button id="save" class="btn primary">Save</button>
```
Failed requests (http://localhost:3000/settings):
- 12:01:04Z GET http://localhost:3000/api/user 500A line is left out when the page has nothing for it: Source needs a
development build of React 18 or earlier, Component any development build
of React. HTML is trimmed to 1200 characters. No form control's value is in
the message; see inspect in
coordination.md.
A screenshot note names the capture's own path in the session. One message
carries at most 20 notes. What waits to be sent is kept per session while the
dashboard stays open, across view switches.
Console and network. The strip under the page (logs.tsx) stands in for
developer tools, which a streamed browser cannot offer. It lists what the
server has recorded for the selected page, read every two seconds while the
Browser is shown: console errors and warnings, uncaught errors, and requests
that failed or answered 400 or above. console.log output and requests that
succeeded are not recorded, and the empty strip says so. The toggle counts
the rows that arrived while the strip was closed. Ticking rows, or the
header's box for all of them, adds them to the bar above.
web/e2e/development-browser/ adds real-server Playwright scenarios using the
existing server/SSH-gateway harness, a Node 22.14.0 app process bound only to
run-loopback, and the real browser companion. They cover the first page from
the address bar, invalid credentials, cookie-backed sign-in/logout, module
hot replacement without logout, desktop/phone input, native Chromium
composition, multiple touch contacts, same-page run-principal actions,
popups, fit-to-pane and presets, silent acquisition, watch/takeover and stale
control/viewport rejection, and annotating an element of a page the agent is
driving, with a failed request, into one message. The app container publishes no host port.
Use the normal E2E binary/build prerequisites and a built aether/browser:test
image, or the harness's inherited AETHER_BROWSER_IMAGE override. The
deterministic harness only holds the session alive: these are not proof of an
authenticated vendor model/tool loop, nor an authenticated Tailscale-hosted
device run.
Details
While the session's row holds 320px for it plus minReadableWidth (560px),
Details is a 320px complementary "Run details" beside the view, toggled by
the header button or Mod+. and remembered (detailsOpen, persisted). When
the row narrows, for example when the assistant docks, the inline panel goes
and comes back once there is room again. Narrower rows open it as a side sheet and
phones as a bottom sheet, each a dialog "Run details" that returns focus to
whatever opened it. Sections (details.tsx):
- Needs you:
RequestCards for pending native inputs, teammate messages awaiting the controller with Deny / Approve throughrun.room.decideand a bar draining towarddeliver_after, and teammate questions with a reply field. Message bodies clamp to six lines with Show more. A pending decision or reply locks only its own card (Actions). With none of these, one card with the needs-you reason and the header's action as a secondary button, or "Nothing is waiting on you." - Waiting until, when the session carries
wait_conditions: what its agent reported waiting--until(session waits), pending first, then the last resolved list. Each row has the pull request link (<owner>/<repo>#<n>, to GitHub) or the session link, cut to two lines, then "merged", "checks final" or "finished", and a badge: how a resolved condition resolved ("Passed", "Merged", "Abandoned", "Reported success"), or the state (Pending, Cancelled, Replaced, Expired, Unreadable). Under it: the condition's summary and detail unless they repeat the error; the pull request state, head commit, session status and checks the server last read, as Required checks when the base branch requires them, else Checks ("4 passed, 0 failed, 1 running", or "None reported yet"); Last verified; Next check while it is still ahead; Failures ("3 in a row: <error>") with the source's own error; Resolved; Delivery ("Delivered to the agent", "Waiting to be delivered", or "Not delivered after N attempts: <error>"); why it ended, "Cancelled by <name>" or "Cancelled by you" when a person cancelled it; and when a pending one gives up. Only the session's owner and admins get what the server read and the errors. The server publishesrun.wait.changedonly when a result changes, not on every read, so a next check already past is left out rather than called overdue; the state line'swaitis the server's own judgment of a stale read (session state). Cancel (run.wait.cancel, for whoever may steer the session) ends a pending condition and shows the result, unless the linked server or member changed meanwhile or a newer read already replaced that condition. The section rereads the session on everyrun.wait.changedevent. - Subsessions, where the server offers
run.childrenand the session has any: every descendant, nearest first and indented by depth, with its purpose, state, agent and model, "On<name>'s account" plus "(fallback from<name>)" when the store's session carriesrequested_account_member_id, its cost or "Cost not reported", its latest report and error, and a Detached badge. Open opens a started subsession. Under the list: the cost of this session and all its descendants, "At least $X: N sessions report no cost" when some are unmetered and "Cost not reported" when none are metered, never $0; the split by paying account; tokens; and "1 of 8 busy, 1 queued" against the workspace limit. The list rereads whenever a descendant the store holds changes. - Agent messages: the session-scoped agent mail, which the Chat view also shows inline, with Show older and Show all.
- Notes: a thread (
note-thread.tsx) of teammates'questionmessages, human to human on the session, plus opencommentmessages too, unless Chat is the active view and its pane is 1248px or over (however Details or a docked Browser narrowed it) - there, the rail already shows open comments, so the thread here holds only questions. Each note is a row: the author'sAvatarringed in their member colour, the name ("via ChatGPT" after it when a connector posted it, the name the message carried when the member is gone), a question badge, the time, and the body indented under the name, clamped to eight lines with Show more. A reply to a question nests under it behind an L connector. A teammate question nobody has answered also has Reply, which scrolls to its Needs you card; the owner's own question has none. The thread is chronological and shows the newest five loaded notes with Show N earlier notes above them; once every loaded note shows and history remains, Show older (also shown when the loaded pages hold no notes) pagesrun.room.listback 100 room messages at a time and expands the thread, and a failed read shows the server's error with Retry. The count beside the title is the loaded notes, not a total. A note that arrives after the thread settled, yours or a teammate's, fades in and rises 4px once, its body 100ms behind its header; the first page, Show earlier and older pages appear at once, and a sent note saved under its server id does not replay it. A teammate's note is also announced politely ("Bob added a note: <text>"). The field Add a note and the round Add note control (an up arrow) follow Actions: the field empties and the note shows muted with "Sending…" in place of its time, under its idempotency key as its id, untilrun.room.postor theworkspace.room_messagerefetch brings the server's copy with that key. A refusal, the deadline or a failure with no answer removes it and shows the note's text and the error as a row marked "Not sent" under the thread, one row per failed note; the text goes back into the field when the field is empty. Every failure except a refusal adds Retry. Until a saved copy arrives, resending the same text by Retry, Add note, or after Dismiss reuses its key, so a late answer never shows twice. A refusal keeps the key too:run.room.postcan save the note and then fail, so the key is dropped only when a saved copy with it arrives or the signed-in member changes. The field, pending keys and failures live in the store per session, so they survive closing Details, and are dropped, with any note still reading "Sending…", when the signed-in member changes; an answer or failure that arrives after the change is dropped too. Adding a note never disables Reply, Approve / Deny or the composer. - Done: completed comments, newest first, five shown with Show all
for the rest; each row is the same as a thread row with a done badge, timed
by when it was completed rather than posted. Deleted comments show nowhere:
not in Details, the rail, the strip, or the Chat transcript. A delete tombstones
its id client-side, so a
run.room.listpage already in flight when it lands cannot re-add the row, and a retried send that turns out to target an already-deleted note drops its own sticky too, rather than leaving an orphan. - Details: the task, Owner, Agent account (when it is someone else's),
Agent and mode, Branch, Created, Changed, Last commit, In control,
Watching, Sandbox ("Starting", "Running", "Stopped, kept for reopening"
or "Removed"), Sandbox size (what a Docker session wrote inside its container
outside the mounted home, checkout and cache; shown to the session's owner and
admins once measured), Archived, and Last reason, the server's
run.reason, so a parked error or stall detail the reason line leaves out is never hidden.
Any other failed room action shows its error above the sections with Dismiss; the composer's own failures stay above the composer.
Workflow panel
The Workflow panel (src/routes/run/workflow-panel.tsx) shows what the session
and its agents are doing as a tree; the Trace view shows when
they did it. Its chip sits after the view switch and
mirrors the session's state: ● Working · 2 agents running (subagents and
workflows running at any depth, a background one included) or
● Waiting for CI · 3 of 9 checks (passing checks of the pull request's
checks this tab last read). The chip toggles the panel. While the
session's row holds 320px for it plus minReadableWidth, the panel is a 320px
complementary "Workflow" rail at the right of the frame, remembered per
device (workflowOpen, persisted, closed until the chip first opens it). A
row too narrow for it beside Details or the subagent inspector shows those
instead; the chip then closes Details to make room.
Narrower rows open it as a side sheet and phones as a bottom sheet, a
dialog "Workflow" that returns focus to the chip, and that closes when a
row opens the subagent inspector or the request, or the view changes. Under the tree, a session
with a branch shows the compact git card (GitFlow in
src/components/workflow/git-flow.tsx), except on the Changes view, which
shows the full one.
The tree (src/components/workflow/workflow-tree.tsx) is derived by
src/store/workflow.ts from what the dashboard already holds: the session's
presentRun state and reason, and the session's subagent index. Its root is
the session; a session that needs you leads with a Needs you row naming the
request; under it every subagent and nested workflow nests under the agent
that launched it (one whose launch the loaded history lacks sits under the
session, Not checked yet), with its label, state and a summary of its tool calls
("Read 3 files and ran 2 commands"), never its prose. Subsessions follow the
agents, each under the session that started it, at any depth; selecting one
opens it. Node ids are server
ids (run:<id>, agent:<tool call id>), and a re-derivation keeps every
unchanged subtree's object, so only rows that changed re-render.
Each 28px row shows a status dot (shape and text, the vocabulary of
Session state plus Not started and Not checked yet), the label,
the muted reason, and at the right the elapsed time in tabular figures, or
on the root real counts (2 agents running, counting every depth, or
3 of 5 tasks done).
Completed subtrees start folded to their summary row; everything else starts
open. A folded parent still lists every descendant that needs you under it.
Rows below the fourth level collapse into one Nested workflow · N agents
row that opens that subtree in place, with Show the whole workflow to go
back. Past 200 visible rows the tree renders only the rows in view.
Selecting an agent row opens it in the subagent inspector; selecting the
Needs you row performs the header's action or reveals the request card.
The tree is a tree with one tab stop among its rows: Up and Down move,
Home and End jump, Right opens a folded row or moves to its first child,
Left folds an open row or moves to its parent, and Enter or Space selects.
Links and buttons inside a row, a pull request link or Task details, are
tab stops of their own after it. When the focused row disappears, as when a
completed subtree folds, focus moves to its nearest remaining ancestor; in a
virtualized tree the focused row stays mounted while scrolled away. Each
treeitem carries aria-level, aria-posinset, aria-setsize and, on a
parent, aria-expanded. One polite status region announces rows that come
to need you, fail, finish awaiting review or complete: transitions are
gathered for 1.5 seconds from the first, then up to three are read, Needs
you and Failed first. Only Working dots pulse, and rows added after the first
render enter with animate-entrance (a fade and a 4px rise over 360ms); with
reduced motion requested, neither animates.
Captures
Captures… in More (and in the terminal's Tools menu) opens
routes/run/captures.tsx, a dialog titled Captures (a bottom sheet on
phones, positioned against the viewport so the session view's scroll containers
cannot clip it). Captures record what was seen, not that it was verified. The
dialog holds, top to bottom:
- Select transient captures to retain and Retain selected captures: a screenshot from the Browser or a shell is private and transient until retained here. Nothing is retained or attached to a pull request on its own.
- The session's retained packets, each with Open, and Load older. An open packet shows its summary, changed files, source availability, unresolved questions, verification notes and retained captures, with its patch and transcript on demand. Answer on an unresolved question closes the dialog and puts the question in the Notes field.
Raw events… opens the session's slice of the activity feed
(routes/run/raw-events.tsx) and restores the feed filters on close.
Missing run
A session id none of the four tabs can find renders one shared MissingRun
(src/components/missing-run.tsx) instead of that header, its tab strip and
four copies of a sentence with nothing to press. What it says is what the
store actually knows. While the server is unreachable it reports that, in
the same words run-list.tsx uses and with the same split - a dead token is
not a server that is retrying, so that one says what the error recorded -
rather than a claim about the session. While the store is still hydrating it is
a skeleton, held behind useDelayed so a fast load never flashes one. Only
once the store has hydrated does it say the session is not on the server, and
offer Back to board. The launch paths seed the session they just started -
both template launches and the onboarding first-session form, the way
launch-dialog.tsx does - so a launch never lands on the deleted claim.
Activity and budgets
src/routes/team/ holds presence and budgets, and src/routes/activity/ the
workspace activity feed - the readouts of the team features
(internal/timeline, internal/cost). Watchers show in the session view,
presence and spend are the Team line in the sidebar footer menu, and the
full view is a registry route: Activity (timeline) is in the header
navigation (or its overflow menu), gated on the method it needs.
Teammate questions and queued messages stay contextual to their session, in its Details Needs you section. Unanswered questions to the owner put the session in Needs you.
- Events keep them current; a full read only fills gaps.
useTeamRefreshinsrc/routes/team/sync.tsreads everything once hydration has listed the workspaces, again whenever the event stream comes back live - a reconnect that re-hydrates does not replay what it missed - and when the workspace set changes. A read before hydration would find no workspaces and be repeated. Between those,applyEventupdates the store from the events that change these reads:workspace.budgetcarries the state, cap and spend, applied as they are. It fires on threshold crossings, refusals and admin edits, not on every spend change, sorun.costre-reads that workspace'sbudget.getto keep the spend and unmetered count current, once 1.5 s pass without another result for it. Each budget event is counted per workspace, and a read that started before one is dropped. A failed read retries after 5 s, doubling to 60 s, until a read succeeds, a budget event lands, or the stream leaveslive.workspace.presencenames one transition, so it re-readspresence.roster.run.typingis ephemeral: the server sends it to live subscribers only, withseq0, so it is never stored, replayed, counted or added to the live feed. It sets the actor's entry intyping(src/store/typing.ts) and returns before the cursor check, so it cannot movelastSeq.stopped: true, or that member'sworkspace.room_message, removes the entry. These reads start without holding up the events queued behind them (only a session fetch does, for the cursor rule), and each is coalesced insrc/store/coalesce.ts: per workspace, one in flight and one queued, so a burst of results or attaches costs two requests.AppShellmounts the hook once, which is also where the presence heartbeat lives (every 15 s, with the disk gauge read beside it). It also reads and beats ononWake, because a backgrounded tab freezes its timers and drops its socket: a phone returns with its presence already expired server-side (the TTL is 45s) and may have missed events. That read keeps a 2.5 s floor, so app switching cannot turn into a request per workspace each time; the heartbeat is one request and always goes.
- One refresh covers every workspace, and there is only the one. These
reads are per workspace on the wire, and a workspace is a repo plus its
team settings. A deployment has a handful of them and they outlive every
session in them. So
refreshTeamreads all of them each time rather than splitting into a bounded recurring pass and a wide occasional one. The Team line asks a whole-deployment question anyway - it claims the worst budget state anywhere - and a workspace does not stop being over its cap when its last session finishes, so no subset could answer it. Failures leave the last good data in place. - The heartbeat is narrower. It claims only the workspace in view -
focusedWorkspaceprefers the route'sworkspaceId, then the workspace of the session in view, thenactiveWorkspace- because presence is keyed on (member, workspace) and beating them all would report you online to teammates in workspaces you have never opened. - The feed opens at the end of the log. The feed reads
workspace.timelineforward from a cursor, so the view first asks for a page past the end - that answer carries the log head - and opens a window back from it. After that the feed is live without reading: while a feed view is mounted (useLiveFeed),applyEventappends each event the filters select by the server reader's own rule (workspace, session or mail to it, actor, type;run.diff,run.title,run.agent,coord.message.acked,run.prandworkspace.presenceonly when asked for by type), skipping a sequence already held. The cursor follows only while the window is whole - no read in flight, failed or cut short - and a view reads from the cursor again when the stream reconnects. A failed or cut-short read is retried on the next event applied (a failed opening read reopens the window), so one bad response does not pin the error until the user changes a filter. A read that reaches the log head clears the cut-short notice. "Load older" reads the new stretch only, up to where the previous window began, keeping what is already loaded: re-reading the whole widened window would spend the page budget on history the feed already has and lose the newest end of it. Pages merge into the feed in sequence order however they arrive, so the window stays oldest-first. When that budget does run out the view says so rather than stopping quietly. Every open stamps the read, so pages still arriving under the filters the user just left write nothing. Actor avatars carry the member's own colour from the member payload. This is the one scoped surface that keeps a workspace filter of its own (shown when there is more than one workspace), because comparing what happened in one workspace against another is the question the view exists to answer; it opens on the active workspace and switching it clears the session filter, since a session belongs to exactly one workspace. - A feed row is a sentence.
src/components/event-words.tsxwords every event type the server declares: "You messaged the agent: “…”", "Waiting: turn ended without a report", "Alice approved “Bash: rm -rf build”", "Failed: Agent exited with code 1". The viewer is "You", server reasons go throughplainReason(src/lib/status.ts), and room ids, session ids and wire enums never appear outside Raw events. Its table is keyed bysrc/lib/events.ts's type names, which also name the filter options, so a type cannot gain a name without words.src/lib/events.test.tsxreads the event, timeline and room vocabularies from the Go sources underinternal/, so a server type without words fails the test. A type this dashboard has never heard of reads "Something changed" under the type name "Other". A usage fallback move reads "Moved from Alice's account to your account" (run.account, filter Account changed), and the headless Claude output that triggered it "Usage limit reached: You've hit your session limit · resets 3pm (UTC)", the agent's message cut at 160 characters (run.usage_limit, filter Usage limit reached). - Opening a session is one row. Viewing a session takes its control and leaving
releases it;
foldVisits(routes/activity/visits.ts) folds eachrun.controllertake and the release that ends it into one "Alice viewed the session" row ("is viewing" while it lasts). A release with no take on the page stays "Control released". Show › Session control lists only these rows. Raw events does not fold. - One Filter popover. Filter in the Activity header holds Workspace,
Show (every event, one event type, or Agent messages), Run and
Member; its label carries a
CountBadgeof what is set (the button is named "Filter, 2 active"), so a narrowed feed is not read as an empty log, and Clear filters resets it. More activity options holds the Raw events checkbox, which prints each row's wire type and JSON payload instead of its description. - Loading and empty. While the first page reads, eight row-shaped
skeletons stand in after ~200ms ("Loading activity"; "Loading agent
messages" in the Agent messages view). An empty feed is an
EmptyStatewith a history icon. - Rows share one time column. Each row is a grid: relative time, a state
dot only on
run.status(the session's new state), the actor's avatar or the message kind glyph, the sentence, and the session as a quiet link. On a phone the sentence shares the first line with the time and the session link takes the full width under it.coord.messageandcoord.message.ackedrows name sender and recipient by their session titles, never the payload's ids, and a delivery word only once the message is in the messages slice; the event alone does not say whether it was delivered.run.retentionhas its own Runtime retention filter and describes the exact grace deadline, pending cleanup, and safe cleanup diagnostic. It has no business-state dot; cleared metadata is not another completed outcome or proof that a reopened session's runtime was removed. - The feed is virtualized.
virtuamounts only the rows near the viewport of the view's scroller (routes/activity/virtual-list.tsx); each row carriesaria-setsizeandaria-posinset, so a screen reader still hears the list's real length. When live events land above a reader who has scrolled down, the list shifts by their height so the rows in view stay put; at the very top the new rows show. - Agent messages is the workspace's message history. Choosing it in
Show swaps the feed for
coord.messages.listrows, newest first, drawn bycomponents/messages/message-row.tsx: kind glyph, sender → recipient (each a muted link to that session), kind word, delivery word (Sent, Delivered, Acknowledged), relative time, and the body clamped at three lines. Sender or Recipient asks the server for that session's mail (run_id) and keeps the chosen side; Thread on a question or report asks the server for that thread (correlation_id), so replies on older pages show too; all three are in the Filter popover while Agent messages is shown. The search box filters the bodies already loaded and says so while older pages remain; Show all reads the older pages, at most 20 per click. New mail re-reads the newest page through the messages slice. - A budget warns, it never stops anything. The Team line in the sidebar
footer menu shows the spend and the worst state any workspace is in (
ok,warn,exceeded) - every workspace, ones with nothing running included, which is what the wide read above is for - and says so in those words, for example "1 online · $12.40 spent". The spend is every session's total, not a month's. A spend that includes unmetered sessions renders as a floor ("at least $1.20 spent"), because an agent with no adapter reports nothing; a zero spend reads "no spend yet", or "no spend reported" when only unmetered sessions exist. - Watcher avatars come from the roster's
watchingset, which the gateway fills from live PTY attaches - the browser's attaches included. - The full read and the heartbeat interval read
GET /api/v1/diskand write it onto the storedserver.info, which is what fills the disk gauge in Insights › System. One read runs at a time, so a reconnect or wake joins the heartbeat's read, and a read unanswered after 10 seconds is aborted and shown as the gauge's error: both gateways speak HTTP/1.1, so a stuck read holds one of the browser's six connections to the host.
Insights
The page has two tabs, Activity (below) and System, kept in the route
as params.tab (?page=insights&id=system). src/routes/insights/system/
is the System tab: use-system-stats.ts polls system.stats every
interval_ms while the tab is mounted, the connection is live and the
document is visible, sends the newest t_ms as since_ms, merges samples
into a one-hour buffer and polls once more after 1.5 s while a container has
no CPU figure. model.ts builds the donut slices and keeps each session on its
colour slot (--series-1 to --series-8) while it is present. Charts are
Recharts, framed by components/ui/chart.tsx. The Storage section there
replaced the disk rows of Settings › Server. The CPU, Memory and Network
figures glide between polls (useTween, one glide per new sample; they never
count up on mount and snap under reduced motion); the Disk figure is a meter.
Storage's container and owner rows are an InsetList, a row that names a session
opening it. While the first sample is read, six tile skeletons stand in after
~200ms.
src/routes/insights/ is Insights (?page=insights), what a member's
agents finished over the last seven local days. It is in the header
navigation after Activity when the gateway offers insights.get, and
reads that one method; the server computes every number
(insights.md). The page reads twice, scope: "mine" and
scope: "everyone", and re-reads when the workspace changes and when the
event stream comes back live, dropping answers to an older request. Each
section loads, fails and retries on its own.
Controls. Workspace (All workspaces or one; shown with more than one workspace, opening on
activeWorkspace). The window is the seven local days ending at the next local midnight, so today counts. The request carries the browser's IANA time zone for day buckets, or "" (UTC) when the browser reports none, which the page then says. The choice lasts while the page is open; it is not in the address. On a phone it wraps above the content instead of sitting in the header. Sessions in Needs you follow as a link to the Board.My statistics and Team statistics. Two sections with the same layout, mine first. Each has three
StatTiles and one chart; until they load, four tile skeletons and a chart skeleton stand in:- Sessions completed:
outcomes.runs.done, with the failed and abandoned counts below. Every number is fromoutcomes, work that finished in the window, so the box and the chart agree. - Success rate: sessions that ended with a merged pull request or
were marked complete, over all that finished,
success.runs, rounded down in integers so 100% means exactly all succeeded; a dash when none finished. Each fraction is written out below. - Total tokens used:
cost.total_tokensas "100K tokens", with the harness at the head ofcost.by_agentand its share, rounded down ("Claude Code used 56% of the 100K tokens") and how many sessions reported no tokens.
- Sessions completed:
Outcome chart. One chart per section: seven day groups, each three bars side by side, Done, Failed and Abandoned, from
outcomes.series. Every bar carries its count; the letters D, F and A under each group name its bars, and Failed is striped and Abandoned dotted, so no outcome is told by color alone, not even when a member's color is red. Hovering or focusing a day highlights its group, dims the other six and opens a tooltip with the counts; a day stays active while the pointer is on it, whichever day loses focus. Each day is one tab stop labelled with its counts. The team chart stacks every bar by member, using the member's profile color fromoutcomes.membersand a legend of members. A color repeats after eight members, so each member also has a two-letter tag (numbered when two collide) in the legend and tooltip, and a ringed swatch; labels give each member's count. On the team chart the outcome swatches in the legend and tooltip are neutral gray, keeping their stripes and dots, so they cannot be mistaken for a member's color. The chart always draws its axes and says so when nothing ended. The y axis tops out at the busiest bar. The sections below cover only the member's own sessions in the same window.Finished work. The server's 50 most recent sessions that ended, ten shown until Show all: title, outcome badge, workspace, agent and model ("default model" when the session used the agent's own), duration, pull request link and relative end time. A row opens the session. The server learns a merge only when
run.pr.statusis called for the session, so after each load the page callsrun.pr.status {"run_id":"<session-id>"}one after another for up to ten listed sessions whose pull request is recordedopen, then readsinsights.getagain once if any state changed. The team statistics do the same for their own list, skipping sessions already checked, and a change in either rereads both. A failed call leaves the row as it was and puts the error in the pull request link's tooltip; a failed second read is shown above the page, which keeps the first.Last 26 weeks. A calendar heatmap of sessions active each day in one accent hue, with a Fewer to More scale. It is one tab stop; arrow keys move by day and week, and each day is labelled with its date and count.
Breakdown. By workspace and by agent: launched, finished and failed as numbers beside a bar.
Time. Median and slowest-10% session time, and, from the server's state record, median time working, waiting on you and your response time. When fewer sessions have state times than session times it says "measured for N of M sessions; Cloudfield records this from <date> on."
Usage, collapsed: cost as a floor ("at least $4.12") with how many sessions reported it, tokens, and a link to Settings › Usage for subscription quota. Cost never stops a session.
A failed read shows the server's error with Retry in the section that
failed; a server without insights.get, or one whose answer lacks
outcomes, success or cost.by_agent, gets one neutral line asking for
an update. Until the event stream is live the page names the connection
problem instead of loading. With nothing in the window the boxes read zero
and the chart says nothing ended.
Memory
src/routes/memory/ is Memory (?page=memory), the active workspace's
team memory: short attributed notes every session can search and
write, and the brief a new session starts with. It is in the header navigation
after Insights when the gateway offers memory.search. It reads
memory.search, memory.show and memory.brief, writes with memory.add,
memory.pin, memory.unpin and memory.rm, and re-reads the list, the tab
counts and the brief after each write, 250 ms after the last of a burst of
memory.change events for the workspace, and when the event stream comes
back live, dropping answers to an older request.
The header holds Workspace (shown with more than one, opening on
activeWorkspace or the first; notes belong to one workspace, so there is no
"all") and Brief, which shows the brief's size against the 3072-byte cap
and opens it at the top of the page: the bytes memory.brief returns for the
viewing member, in a code block. On a phone both sit in a row at the top of
the panel instead, which wraps. Below sits one bounded panel, at most 768px
wide and as tall as the page, bordered from 640px and full-bleed on a phone.
Top to bottom:
- Show, a radio group of pills: All, Pinned, Agent notes,
Outcomes, Answers and Superseded, which
memory.searchapplies aspinned: true,source: agent,kind: outcome,source: answerandreplaced: true, so a match older than the newest 100 notes is still listed. Arrows move the choice; Home and End pick the first and last. Each pill counts from the unfiltered pair of reads, and only while the count is exact: "100+" when a read stopped at 100, no count for Agent notes, Outcomes and Answers once the newest read stopped, and none for Superseded. Search notes swaps the pills for a search field whose placeholder names the filter; its words go tomemory.search250 ms after typing stops, with the filter kept. Escape or Close search clears them and brings the pills back. - Notes. Two reads with the same words and filter: the 100 newest pinned
notes or best pinned matches (
pinned: true), and the 100 newest notes or best matches, which Pinned skips. Superseded makes only the second read, since a replaced note is never pinned. Each note is listed once, pinned first, each group in the server's order, so a pin older than the newest 100 still leads; Pinned and Newest (Best matches while searching) head the groups when both have notes. A row is the title, at most two lines, and one line of kind, source (Agent note, Member note, Run report), the author with the agent's display name, the pull request or else the session as a link (not on a phone, where the detail lists them), the age, the pin badge ("Pinned by Dana", or "Pinned for you" or "Pinned for Dana" on a pin for one member's briefs) and Superseded; cited files are in the detail. Under a mouse, hover or focus shows Pin for every new session or Pin for your new sessions (noscope, so the note keeps its own, asaether memory pin), Unpin, Replace and Remove; a replaced note offers only Remove. On a touch screen a tap opens the detail instead. A pin or unpin glides the row into its group. While a new search or filter is read, the previous list stays on screen, dimmed. - Add note, which opens the composer in place: the text (first line is the
title), Kind as pills (decision, convention, gotcha or preference),
Files (cited repository paths, one per line, sent as
filestrimmed and without blank lines), Only me (scope: member) and Pin.Mod+Enteranywhere in the composer adds and Escape cancels; focus returns to Add note. On a short screen the composer scrolls. While it holds an edit to any field, Replace on another note leaves it open and says to finish or cancel it first. A duplicate answers with the live note already holding the text; its row scrolls into view and flashes. - The footer line, a live region: Undo after a removal, the composer's keys and byte count against 1024, then the last result ("Added note-…", "Replaced note-… with note-…", "Already kept as note-…") for four seconds, then what the hovered or focused row does for new sessions ("Pinned by Dana · in every new session's brief", "Not pinned · sessions find it by searching"), and otherwise the count of listed notes and pins, or matches. When a read returns 100 notes it says what the list holds instead: every pinned note, or the 100 newest pinned notes or best pinned matches, then the 100 newest notes or best matches. Each member's own pins have their own budget, so a workspace can hold more than 100 pins; there is no paging, and an older pin is found by searching. With nothing to say, such as on an empty list, the line folds away.
Remove hides the note at once and offers Undo for five seconds before
it sends memory.rm, which cannot be undone. A second removal, a workspace
switch and leaving the page or tab send the waiting one at once; if the tab
closes before that request lands, the note stays. Adding the waiting note's
text again answers with that note, so the removal is dropped. A refusal comes
back as a toast with the server's text and the note returns. Focus that was
on the removed note moves to the next note, else the previous one, else Add
note.
A row opens memory.show: the note's text, its provenance (author, session and
its ID, commit, pull request, files, the report or question it came from,
when it was written and pinned, what replaced it) and the supersede chain in
replacement order, each other note a link. A member who may push gets Pin
for me only (scope: member, as aether memory pin --me), Pin on a
workspace-scope note, Unpin, Replace… and Remove, which closes the
detail and offers Undo in the footer; a replaced note offers no pin and
no Replace…. Replace, from a row or the detail, opens the composer as
aether memory add --supersedes: the note's text, its kind (an outcome
note's becomes decision), its files and Only me for a member-scope note.
It sends supersedes with the note's ID; from the detail it then opens the
replacement. For a pinned note the server moves the pin to the replacement in
its own scope, so Pin is hidden and Only me is disabled at the note's
scope.
Every refusal shows the server's text unchanged, method included, in the
composer, the detail or, for a row's pin, a toast:
memory.add: rejected, gitleaks rule github-pat at 0:22; remove the secret and retry, or memory.pin: pinned workspace notes use 980 of 1024 bytes; this note needs 120; unpin one first. A pin refused after an add
(memory.add: <id> is stored but not pinned: …) also re-reads the list,
because the note was stored. A viewer sees no write controls. A server
without memory.search gets a neutral line asking for an update. Activity
words memory.change as "Dana pinned a team memory note", "The agent
added a team memory note" for a session's write or outcome.
Files
src/routes/files/ is the Files explorer and editor. It combines each visible
workspace's base branch, live session checkouts, and Home, the authenticated
member's whole persistent home (Home). files.tree,
files.read, files.write, files.diff, and the home.* methods are
available through both the local SSH-backed gateway and the server-hosted
WhoIs gateway. Directory requests are lazy and cached in
src/store/files.ts; file content comes from files.read or home.read.
A live session's file can switch from File to Changes vs base. The same
tree and editor are a view of each session, scoped to that session's checkout: see
Files in a session.
Folder chevrons turn as a folder opens, and the empty editor pane is an
EmptyState with a folder-tree icon. The tree lists each workspace's base: <branch> first, then its live sessions
under Session checkouts, then one Home row; both start folded, so a
session's tree or the home is read only when it is opened. Folder expansion is
kept per view. The tree sits beside the
editor from md up. On a phone it is the first view; once a file is open the
editor fills the screen and Browse opens the tree as a side sheet.
CodeMirror provides syntax highlighting for JSON/JSONC, JavaScript/TypeScript,
Markdown, Python and TOML, plus find/replace. The editor renders complete
UTF-8 text without NUL bytes up to 64 MiB; binary and oversized responses
remain read-only.
The action label states the write target: base files show Commit to
<branch>…, which opens a dialog saying the commit lands on that branch and
is not pushed upstream, then creates one file commit (a failed commit keeps
the dialog open with the error); live-run files show Save, changing the
session's uncommitted checkout; Home files show Save, changing only
the authenticated member's persistent home. Base writes need the push
permission, run writes the steer permission, and Home reads and writes are
always for the calling member and need the launch permission. A text file
the member may read but not change shows Read-only in place of the
action. The header names a Home file as ~/<path>.
Saves are explicit (Save, Commit to <branch>…, or Ctrl/Cmd-S, which opens the same commit dialog for a base file); there is no autosave or force-save. A tab closes from its ×, a middle click, or Delete while it has focus. Open tabs and dirty drafts live in memory and survive route changes and reconnects to the same identity. A different authenticated member or server clears them. The browser warns before unloading dirty buffers. The revision is the SHA-256 of the complete bytes read. A failed or stale save keeps the draft and its error. On a conflict, Reload from server replaces the document and discards that draft. Discard edits restores the last successfully loaded or saved content without fetching. All sessions the member launches and their Environment mount one shared read-write persistent HOME, so uploaded configuration and saves are visible to active and future sessions; a tool may need to reload. Files edits do not create CLI snapshot history. Optional run snapshot pins are provenance, not isolated writable copies. Manual profile push and rollback overlay snapshot files into that same HOME without removing paths absent from the snapshot; rollback is not an exact-tree restore.
A run.diff event drops every listing and document cached for that session,
because its checkout changed; a save into a session's checkout causes one too.
The tree and the editor keep what they last read until the reread lands
(TreeDirectory, FileEditor), and EditableDocument then replaces only
the span that differs, so an open folder does not blink and the caret, the
scroll position and the marked line stay where they were. A draft started
during the reread is still based on the revision that was on screen.
Files in a session
RunFiles (run-files.tsx) is the session page's Files view: that session's
checkout under its branch name, with the tree, the editor, the tabs and the
phone layout of the Files route (FilesPane, closeTab in pane.tsx). Its
tabs are the open files of that session; they are the same tabs the Files route
shows under Session checkouts. The base branch and Home stay
on the Files route. The pane is measured: below 640px, with the Browser
docked beside it for instance, it shows the tree until a file is open and
then the editor with Browse, as a phone does.
A live session's checkout root, here and under Session checkouts on the Files
route, is a RunCheckoutTree (tree.tsx). When the gateway serves
files.upload, its row has an Upload files… icon button, and files and
folders dropped on its tree upload into the root of the repository it shows,
folders kept (droppedUploads). useUpload sends one files.upload per
file, so a path the checkout has
fails as README.md already exists in this session; open it to edit; there is
no Replace. UploadStatus under that tree shows progress and failures as
on Home, and invalidateRun rereads the session's listings afterwards. The
upload state lives in the tree: closing the phone sheet or folding Run
checkouts hides an upload's progress, not the upload.
openInFiles(runID, { path, line, column }) (open.ts) is the one way in
from outside the tree. It navigates to the session route with view: 'files',
file and, when named, line and column; those three are not written to
the address. The view opens the file, opens the folders above it in the tree
and scrolls its row into view (TreeExpansion reveal), and the editor puts
the caret at the line and column, scrolls the line to the middle and marks
it with the selection colour. The mark follows edits and stays until another
line is opened. Following the same link again is a new navigation, so it
shows the line again. A line past the end of the file marks the last line.
A file the checkout does not have opens with the server's files.read error.
Three things call it: a file's header in the Changes view, a path in the Chat view and a path in one of the session's terminals.
findPaths (paths.ts) reads what could name a file: path, path:line,
path:line:col and path#L12, relative to the repository, with a leading
./, or under /workspace/, where every session's checkout is mounted. A lone
word counts only with an extension or a line (go.mod, Makefile:12).
URLs, absolute paths outside /workspace, .. and .git segments are not
paths.
A path is a link only when it is a file in the checkout, and the dashboard
does not ask the server about text that is merely on screen. isRunFile
answers from the directory listings in src/store/files.ts, the cache the
tree fills, and reads at most two it lacks: the repository root, which rules
out prose such as "and/or" with no request of its own, and the file's
directory. The Chat view asks when the pointer reaches a path or a finger
taps it (FileLink in path-link.tsx); a terminal asks for the line under
the pointer (findRunFiles, through useXterm's findLinks, which joins a
wrapped line before it is searched). Each listing is fetched once however
many paths wait on it, so every path in a directory becomes a link together,
and a path that became a link stays one while it is on screen. A path
that is not a file is never styled and does nothing when clicked. Until a
path's directory has been listed it has no link style and cannot be reached
with Tab; the tree is the keyboard's way to any file.
There is no file finder: files.tree lists one directory, and nothing lists
a whole checkout.
Home
Home is one root row with a trailing ~, shown when the gateway serves
home.tree. Under it is the member's whole persistent home, the directory
that is $HOME in their Environment and sessions, read one folder at a time
through home.tree with nothing filtered. Only this tree creates, renames,
moves and deletes entries; base and run-checkout trees are read and edited,
and a live session's takes uploads (Files in a session). The
methods and the server's rules are in
local-gateway.md.
| File | Holds |
|---|---|
home.tsx |
HomeFiles, the provider that owns naming, the dialogs, uploads and drag state, and useHomeFiles |
home-tree.tsx |
HomeTree, its rows, and HomeStatus, the transfer line under the tree |
home-menu.tsx |
HomeMenu, a row's actions |
home-name.tsx |
NameRow, the field a name is typed into |
home-dialogs.tsx |
The delete, move and replace confirmations |
home-upload.ts |
useUpload and droppedUploads, shared with run checkouts |
HomeFiles wraps the whole route, above FilesPane: a phone remounts the
tree in its side sheet, and an upload in progress or an open dialog must
outlive that. It is keyed by the signed-in identity, and every answer is
dropped when sameIdentity() says the member changed while it was pending.
Each row has a … button in the ListRow hoverAction, which a coarse
pointer always shows, and a right click on the row opens the same Menu:
| Row | Items |
|---|---|
| Folder | New file, New folder, Upload files…, Rename, Copy path, Delete |
| Home | New file, New folder, Upload files…, Refresh, Copy path, beside a Refresh Home icon button |
| File | Download, Rename, Copy path, Delete |
| Credential file or symlink | Rename, Copy path, Delete |
Copy path copies ~/<path>. Download reads the file with
home.download and saves it through an object URL; HomeStatus shows
Downloading name meanwhile. Refresh drops every
Home listing from the store (refreshHome), so each open folder is reread;
useListing in tree.tsx keeps the last listing up meanwhile. Nothing
watches the home: a file an agent writes shows after a refresh.
A name is typed where the entry sits. New file and New folder open
the folder and put NameRow first among its subsessions, with the entry's
icon; Rename, or F2 on a focused row, replaces the row's label with a
field holding the name, its stem selected. Enter commits, and a new file
then opens in the editor. Escape or leaving the field cancels. A name is one
path segment: an empty one, one with /, . and .. are refused before any
request, and a server refusal such as notes/drafts already exists shows
under the field, which stays open. When naming ends, focus returns to the
row (takeFocus). A menu item that opens the field does so from the menu's
onCloseAutoFocus: a closing menu returns focus to its button, which would
otherwise blur the new field and cancel it.
Delete, or the Delete key on a focused row, opens an AlertDialog
titled Delete <name>? that names ~/<path>, says a folder goes with
everything in it, and says when open files under it have unsaved edits.
Confirming calls home.remove. A refusal stays in the dialog.
Upload files… opens the system file picker. Files and folders dragged
from the desktop upload into the folder under the pointer: a folder row is
that folder, a file row its parent, and the Home row or the empty pane
below the tree is ~. The folder that would receive them is outlined, and
a folded one opens after 600ms. droppedUploads walks dropped folders with
webkitGetAsEntry, so their structure is kept; empty folders are not
created. useUpload sends one home.upload per file, in order, first
without overwrite, while HomeStatus shows Uploading 3 of 12 · name
pinned to the bottom of the tree pane. A file over 64 MiB fails without being
read. Files the server already has are collected and asked about once at the
end, Replace 2 files? with Replace and Skip; replacing sends
them again with overwrite: true. Each file that failed is listed with the
server's error until dismissed. One batch uploads at a time: a drop is
taken, and a second one refused, before its folders are walked, while the
status reads Reading dropped files…. An upload or download started as
one member stops when another signs in, before any byte is sent or saved.
While the
route is mounted, a file dropped anywhere else on the page is refused, so
it cannot replace the dashboard.
Dragging a Home row onto a folder, or onto Home, asks Move <name> to
~/<folder>? and calls home.rename. A row cannot land on itself, inside
itself, or in the folder it is already in.
Open tabs stay truthful. After a rename or a move, moveHomePath rekeys the
tabs, documents, drafts and listings of that path and of everything under
it, and TreeExpansion keeps a renamed folder as open as it was; after a
delete, dropHomePath closes those tabs and drops their documents and
drafts. A listing or
read in flight under the moved path is dropped, so its reader asks again at
the new one. A save in flight keeps its saving state and settles on the
file wherever it is by then: the editor follows the homeMoves recorded
since the save began (followHomeKey), and drops the answer when the file
was deleted.
A credential file, locked in home.tree, shows a lock at the end of its
row, has no Rename, and cannot be dragged. It opens like any file, and
the editor shows the server's refusal:
home.read: .claude/.credentials.json is a credential file; read it in the Environment terminal.
A symlink shows a link icon and does not open. Inline and dialog errors show
the server's sentence without its method prefix (errorSentence).
Drag and drop needs a mouse. On a phone every action is in the row's menu,
and Escape in the name field cancels the name without closing the tree
sheet (FilesPane).
Templates
src/routes/templates/ is a two-pane library of the active workspace's
templates (template.list). The list, sorted by name, has a search over
name, task, agent, mode and model, and one row per template: agent glyph,
name, a clock when it is scheduled and the mode word (Standard, Enhanced,
Background). The arrow keys, Home and End move the selection and focus
together; ArrowDown in the search enters the list and Esc clears it. The
selection is the address's id; with none, or a name the workspace lacks
("That template is not in this workspace."), the first row is shown. A new
or duplicated template is selected once saved, and deleting the selected one
selects the next.
The detail shows the name, the mode, Edit and a menu with Schedule…,
Duplicate and Delete; a meta line with the agent, the model or
"agent default", the effort when set, the schedule (Scheduled <cron> UTC, next in 3 hours) or
when it was saved, and the advisory budget; then the task. Each {{name}}
placeholder (the server's pattern in internal/templates/render.go) is an
inline field at its first occurrence, prefilled with the template's default;
later occurrences mirror it. "N of M filled" counts placeholders with a value
or a default, and a preview shows the rendered task. The footer shows "~N
tokens" (characters / 4, an estimate whatever the agent's tokenizer), a
field's default while it has focus, or "Fill N more to launch" on the
disabled Launch; Copy copies the rendered task. Enter in a field
moves to the next empty one, or launches once none is left. Launch sends
template.launch with only the values typed over a default, never the task,
reads "Launching…", with every Launch held, until the server answers so
one click starts one session, and opens the new session; a refusal toasts the
server's error. Typed values last, per workspace, while the page is open.
On a phone the list and the detail are one pane at a time, with
Templates to go back. A failed template.list read shows the
server's error with Retry.
Schedule… opens the cron editor in a dialog; the preview is
the next_fire_at that schedule.save returned, shown relative and in UTC,
never computed in the browser. Duplicate opens the form prefilled under
<name> copy. The form's agent select lists the agents from agent.list by
display name and keeps the template's current agent as an extra option when
the list omits it. An Effort field, as in New session, shows for an agent with
effort_levels, and picking an agent that lacks the chosen level clears it. Its Parameters group lists each {{name}} the task
uses, live, with an optional default (clearing the field removes it); defaults for names the task no longer
uses are dropped, and the template's budget hint is kept, so an edit never
wipes either. With no templates the view says what one is and offers
New template.
Save, Delete and the schedule save follow Actions: the dialog
closes on Save or Delete and the list shows the result at once; a saved
schedule shows at once and its next launch arrives with the server's answer.
A refusal puts the list back and shows the dialog again, reopened if closed,
with what was typed and the server's error. At the deadline it shows "The
server did not answer in 5 seconds." with Retry. template.save and schedule.save
upsert by name, and a delete retry treats "not found" as deleted, so a retry
never applies twice. A refusal or deadline puts back the last value the
server confirmed, and only while the row still shows that action's
prediction. A late success shows the saved row or removes the deleted one,
and closes the dialog only if it still shows that unedited draft. If another
dialog is open when a failure arrives, it stays as it is and a toast shows
the error with Reopen, plus Retry at the deadline; a late refusal
replaces that toast, and is dropped once a Retry of that action was
answered. A late success of that action dismisses its toast. After the
signed-in member changes, the toast is dismissed, its Retry and
Reopen do nothing, a later failure of that action is not shown, and its
late answer or rollback leaves the lists alone.
The same toast shows a failure that arrives after you
left Templates, or after a workspace switch, and its Reopen opens
Templates in the workspace the action was sent from, with the dialog as it
was. A form reopened before the first template.list read answers keeps
what it saves.
Retry in a dialog sends what the dialog shows now, so edits made after
the deadline are not lost. A template whose save the server has not answered, past the deadline
too, offers no Launch, Delete or Schedule…, since
template.launch sends the name and the filled-in parameters, never the
task. Unschedule reads "Unscheduling…", then
"Still waiting for the server…" past the deadline; while a schedule save for
that template in that workspace is unanswered it reads "Saving…" and is disabled, so the delete
cannot land before the save. Both holds last across leaving Templates and
coming back, and so do the lists, kept per workspace in
src/store/templates.ts: coming back shows them at once, an answer or
rollback that arrives after you left still lands on them, and the composer
and palette pickers read and refresh the same lists.
When saves of one template, or of its schedule, overlap, only
the answer to the last one sent is written; an earlier answer leaves the
list alone. An earlier save's answer becomes the value a later pending
save of that template, or of its schedule, puts back on a refusal or
deadline. A template.list or schedule.list answer older than the last
one applied in that workspace, or sent before the signed-in member
changed, is dropped. A template.list or schedule.list read,
on opening, on a workspace switch or after Unschedule, keeps the
templates and schedules saved or removed here while it was pending, and
those whose save is still unanswered. A
refused delete puts the template back only if none of that name was saved
meanwhile, and a successful delete removes the row, or its schedule, only if
none of that name was saved after the delete was sent. An answer or rollback that arrives after the active workspace
changed lands on the list of the workspace it was sent from, not the shown one.
Agents
An agent is the coding CLI a session starts, such as Claude Code or Codex.
src/routes/agents/ is the Agents page; it and onboarding's Agent step
render the same parts from src/components/agents/, so this section covers
both. The page header has Add agent… where the gateway serves
agent.register, and a sub-screen there shows All agents to go back.
AgentList rows show the agent's coloured AgentGlyph (ui/agent-glyph.tsx
maps each shipped name to an icon and its --agent-* colour token), its
display name,
"Not installed", "Installed", "Installed · Login found" or "Installed · No
login found" (from login_found), or "Signed out" or "Sign-in refused" with
a needs-you dot and login_problem verbatim on a line of its own when the
server reports one,
"Standard · Enhanced" or "Standard", and
one button by state: Set up while not installed, Log in while
installed with no login found or signed out, and Run once ready, with Set up again
in the row's More menu; closing a setup returns focus to that row's
button. On the Agents page only, where the gateway serves agent.remove, the
More menu of a member agent or an installed agent also has Remove….
It opens RemoveAgent (remove-agent.tsx), a confirmation that says what is
deleted (~/.local/bin/<executable>, plus the Enhanced adapter's link, or the
member's definition) and what stays; a refusal appears in the open dialog, and
success reloads the shared agent list, so the launcher's picker updates too. On the Agents page an installed agent's row also has a Default
mode select, shown as "Default: Standard", which writes launchDefaults
without changing which agent New session preselects. Rows sit in an InsetList with the glyph in an IconTile. Once one agent is
installed the page folds the rest under More agents, whose count is a
CountBadge (the button is named "More agents (n)"). While agent.list is
pending, three row-shaped skeletons stand in after ~200ms. What's the
difference? beside the page's lead opens the Standard and Enhanced cards
(ModeOverview) in a dialog.
Run remembers the agent and its default mode and opens New session on it;
in onboarding it moves to First session with that agent preselected. Add
agent… (add-agent.tsx) asks for a name, a Standard and a Background
command and an optional Enhanced command, Enhanced start mode and login file,
sent through agent.register. The Background default follows the Standard
command's first word, which is also the executable. A session that is not
signed in offers its terminal login method, typed as the ACP server command
(agent_command in the session state) with the method's args.
Signed-out logins. SignedOutAlert (components/shell/signed-out-alert.tsx),
mounted by AppShell under StaleBanner, shows while any installed agent in
the member's own agent.list has login_problem: a needs-you band with one
line per agent, "Claude Code is signed out" when the login file cannot sign
it in (login_blocks_launch) or "Claude Code's sign-in was refused" when an
agent refused, then the problem verbatim, Sign in on Agents and a dismiss
button at the right. On narrow screens each agent's label and problem stack;
the actions stay beside them. Dismissal hides the alert for the current app
launch; it appears again next launch. Otherwise it leaves out what already
sits beside its own sign-in action: everything on the Agents page, and, in
the Chat view of a session on the member's own account whose reason is a
refused turn or open, that session's agent. If not dismissed, it goes when a
read no longer reports the problem. agent.list
has no event, so it reads again every 60 seconds while the page is visible,
on window focus, and when one of the member's runs gets a new
enhanced turn failed: or enhanced session failed: reason.
Below the list, AgentExtras holds collapsed disclosures: Git identity
(Agents page only), which says agents commit as the name and email in the
member's Profile and opens it with Set it in Profile rather than editing
the identity itself; GitHub; and Agent config files, a prompt that
has an agent on the member's computer upload its configuration.
Set up opens agent-setup.tsx, three numbered steps: Choose how sessions
show it, Install and log in and Check. The first is
mode-comparison.tsx: a radiogroup of two cards (ModeOverview draws the
same cards as a static list with agent-neutral notes), side by side
when its container is at least 640px wide and stacked below, each with a mock
at least 160px tall above its description, trade-off and note. The mocks
draw one canned item log (mock-moment.ts, SessionItem shapes): the
Standard card as a terminal still, the Enhanced card through session-mock.tsx
as messages and tool lines. Neither shows a permission prompt, since both
modes run with full permissions by default. Both are spans with aria-hidden, static, so they can sit inside
the radio's button; the description and
trade-off are its aria-describedby. Below the cards a dl gives the
per-agent lines from agent-copy.ts: support, setup, switching (from
switchable, otherwise "Chosen when the session starts"), fallback, and billing
for Claude Code. An agent whose enhanced is not native or adapter gets
the Enhanced card disabled with the reason as its note; otherwise the note
is permissionNote from agent-copy.ts, which says per shipped agent how it
runs without asking and whether a session mode can ask. The selection starts
on the remembered default, else Enhanced when enhanced_default is set,
else default_mode.
Install and log in calls agent.install with enhanced set when Enhanced
is chosen and shows the answer: the log tail in an Install output
disclosure, open when error is set, and Install failed with the error.
Once the agent is installed it mounts an Environment dock. The login or
install command appears above the dock. Use Copy login command or
Copy install command, paste at a shell prompt, review the command, then
press Enter. Resize the dock by dragging its visible top grip or using the expand/shrink button;
both stop at the space available to the dock. A gateway without a terminal
socket prints the aether terminal commands.
Check re-reads agent.list and lists
Installed, Enhanced installed and Login found or No login
found, or Signed out: or Sign-in refused: with login_problem when
the server reports one;
the copy never says "signed in", because the probe checks for a
file. Done appears once the agent is installed with no missing login and
calls rememberLaunch with the chosen mode, which seeds New session and
First session. Setup does not save the Environment image: the install lands in
the member's home directory, which every container mounts.
GitHub (member-scoped terminal setup). github-connect.tsx remains the
Agents page's native setup and the collaborator onboarding path. Administrator
onboarding instead uses the shared browser connection described under
Manage workspaces, including a persisted status check on
the Agent step so Repository-step authorization need not be repeated.
The terminal setup's closed <section aria-label="Connect GitHub"> says what a connection
buys - sessions push branches and open pull requests as the member, and commits
are signed with a key kept in their home directory - and Connect GitHub
opens the sub-screen. The sub-screen mounts the same TerminalDock the
setup screen uses and calls github.probe once that dock reports a running
container: the probe runs gh --version inside it and refuses when there
is nothing to run it in. Until then the screen says it is waiting for that
terminal to start, and once it has one, that it is checking it for gh;
through both it shows no login command and types nothing. I've logged
in stays live there on purpose: github.connect makes the same check
itself, so it is the way out of a probe that never settles.
Once the probe answers with a gh that can do the login, initialLine
becomes typedLoginCommand from src/lib/github.ts: gh auth login --hostname github.com --git-protocol https --web --scopes admin:ssh_signing_key, prefixed with Ctrl-U. The member can have typed at
the prompt while the check was out, so the line clears it rather than
landing on top of it. Ctrl-U kills backward from the cursor, so anything to
its right survives and is appended to the login command; Ctrl-K would cover
that, but the terminal falls back to /bin/sh on an image without bash and
dash passes Ctrl-K through as input, which breaks the command. The byte is
raw input either way, so a member sitting in an editor or a pager gets it as
one. The screen echoes the command itself, without the prefix, in a code
block for anyone who would rather type it, and says what that login looks
like from inside a container: gh asks the member to press Enter to open a
browser and then reports that it could not open one, so the member presses
Enter, ignores the failure and opens the printed URL with the one-time code.
A probe reporting no gh, a gh that would not run, or one too old for the
login check replaces the login command and its explanation - not the dock,
which is where the remedy is carried out. In their place comes the screen's
own sentence about the gh the probe found, then the server's commands as
CopyableCommands - the admin one when there is one, then the member's -
and gh's own answer in the same monospace pane refusals use; no login
command is offered at all, and I've logged in is disabled, because
connecting would only collect the matching refusal.
There are three shapes. A gh the member installed into their own home
directory - which the probe reports as path, and which comes first on PATH
and survives every image - is named as the file it is, with no image command
at all. A member on their own saved image is offered the install-and-save that
keeps it first, and told that aether env reset removes it. A member on the
server's standard image is told an admin runs the command, or just to reopen
the terminal when the image has already moved without them. Every remedy the
copy names is reachable from the dock right below: Save environment, or
Environment actions for Reset to standard… and Stop environment….
Check again re-runs the probe, because none of those three restarts the
container by itself.
A probe that fails, or a dock that never got a terminal at all, puts the login command back - shown, not typed, and said to be untyped - because a member whose gh is fine must not be stopped by a check that could not run. A dock that has a terminal and merely refused a write is not that, and does not release it. A failed probe renders its own error above Check again; a dock that could not open reports in its own pane, and gets no button, because a second probe cannot run without a container and the attach is already retrying.
I've logged in calls github.connect, which does the non-interactive
rest on the server; success names the account and the signing key's
fingerprint, and Close returns to the page, whose GitHub disclosure
then opens on "Connected in this session as <login>" - the connection is
React state that a reload loses. Server refusals - most often github: not logged in to github.com in the environment terminal; run aether github connect - render verbatim in the same
monospace pane the Repository step gives git's output, because gh's answer
runs to several lines, and leave the screen open to retry.
Where the gateway serves no terminal socket the screen gives the CLI path
and nothing else: aether terminal, the same gh auth login, then aether github connect. There is no I've logged in button there - with no
terminal to log in through, the whole flow is the CLI's. The login command
itself lives in src/lib/github.ts, so the screen and the Playwright spec
assert one string.
Agent config files
src/components/agents/config-prompt.tsx fills the Agent config files
disclosure on Agents and in onboarding's Agent step whenever config.roots
and config.import are advertised, on both gateways, without a workspace.
There is no separate route: typing "config files" in the command palette
finds Agents, through the keywords its entry in src/lib/surfaces.ts
carries.
The browser reads and uploads nothing. The section gives the member a prompt
to paste into a coding agent on the computer that has their configuration;
that agent picks the files, asks the member, and uploads them with
aether config ls and aether config push, so that computer needs the
aether CLI linked to this server. The two sentences above the prompt say so and link
the quickstart's install and link steps.
The prompt is configPrompt in src/lib/config-prompt.ts, a plain module
so the Playwright spec can import it; the user docs print the same text byte
for byte. It shows in a read-only, focusable monospace block that keeps its
line breaks, wraps long lines and scrolls past 18rem. Copy prompt goes
through copyText (src/lib/clipboard.ts): it toasts Copied, or, when
the clipboard refuses, selects the whole prompt and toasts Selected. Press
Ctrl+C to copy. Open remote files navigates to the files route with
home: 'open', which unfolds Home, where the uploads are. Agent
logins are separate. See
Agent configuration for
the user workflow and the
protocol for the
config.* methods.
Environment
src/routes/environment/ is the member's Environment: a shell into their
own long-lived sandbox, where they install tools, log in to agents and save
the result as the image new sessions start from
(environment-home.md). It is reached through the
header's Environment button (or More navigation → Environment) or
g e, and only when the gateway advertises the terminal WebSocket.
The view mounts TerminalDock (terminal-dock.tsx) with
containment="fill", so the dock fills the view with no resize handle and no
collapse control. While the status is read the pane shows a spinner and
"Checking environment…"; a failed read is a FailureCallout (with Retry
before the container exists). Before the container exists the view says
"Your environment starts on first open" with Open. On desktop the dock hands
its actions to the view's header (header prop): Save environment is the
header's only filled button while the container runs, Environment
actions (…) holds the rest, and the save hint Installs here reach
agents after you save. is the header's second line while nothing is saved.
On a phone the top bar already names the view, so the actions sit at the end
of the tab row. The tab strip is 32px, 44px on a touch screen, and holds up
to six tabs; Add terminal tab opens another. Before the first open there
is no Add terminal tab, and no strip at all when it would be empty; the
empty state's Open starts the environment.
Environment actions holds capability-gated Forward port, Stop
environment… and Reset to standard…. Stopping the container and
discarding the saved image are separate decisions with separate
confirmations: Stop confirms with a plain primary button and says the saved
image is kept. Reset appears only when there is a saved_image to throw
away, confirms with the image's own name ("Reset to the standard image?") and
carries the only destructive button either dialog has; that confirmation
names the container only while there is one to stop, because Reset outlives
it. Stopping carries the rest of the status forward, so Reset stays on offer
with the environment stopped. Closing a dialog opened from the menu returns
focus to its trigger, or to Open if stopping or resetting removed the
menu.
From the moment a tab opens until its attach is acked, a spinner covers the terminal. The words follow what the dock knows: a terminal it has not seen running is Starting your environment, the wait its sandbox's start accounts for; a second tab, a tab switch or an expanded dock is Connecting to your environment. A refused or failed start replaces the terminal with the gateway's own error and Retry.
The same dock mounts inline, collapsible and resizable, on the Agents setup
screen and the GitHub connect screen, with its actions in its own tab row.
There it has a persisted height (UiSlice.terminalDockHeight) and, on a fine
pointer, a resizer; under coarse the separator is not rendered and a header
control toggles between half of the room it has and all of it.
TerminalDock mounted with openOnMount expands itself once, because those
screens type into it.
The environment dock's state and socket registry live in
src/store/env-terminal.ts (session shells use src/store/terminal.ts). The
live attachment objects stay outside persisted Zustand state, but a dock
socket can outlive the component that last displayed it. When a new xterm
host adopts one, the dock calls Attachment.rebind() with fresh callbacks.
rebind(next) is a host-replacement boundary: it cancels any old replay
parser or drain with an explicit cancellation signal, drops the old socket,
updates the handlers, and starts one fresh full replay after cancellation.
Docks must not separately call reopen() after rebind(). Host
subscriptions are removed on cleanup, while closing a tab or an exited shell
unregisters its socket, so route changes and tab remounts cannot deliver late
output, resizes, or image actions to a disposed host.
The same stop confirmation (StopEnvironmentDialog) backs the Members
page's notice after a member's first account share: containers started
before that share lack the in-place mount of Claude Code's login file
(security.md), so when the store's
envTerminal.status, re-read with terminal.status at the share, says the
container is running, or that re-read fails, the roster says so and offers
Stop environment. The advice follows the first share the
server answered while no other grant was saved; a later share shows
nothing, because the page cannot tell whether the container predates the
first one.
Members, devices and Profile
src/routes/members/ is one page with two tabs, Members and Devices.
Each tab has its own route name (members, devices), so the address, back
button and the palette's Devices entry land on the right tab, and the
sidebar's Members row stays current on both.
Members is a roster table, each row filling on hover: name, role, agent
account and last seen (Online, a relative time, or Offline). Below
64rem, where the sidebar leaves the table too little room, the agent account
and last seen sit below the name, so the table never scrolls sideways. Roles are
Viewer, Collaborator, Admin and Super admin. A super admin changes a role with
the select in the Role column and removes a member with the row's trash
button; giving up your own super admin role, and removing anyone, ask first.
The Agent account column holds a Share my account switch for every
other member (account.share, account.revoke) and says when that member
shares their account with you; the omp warning sits behind What a teammate
can do with your account above the table. Members
waiting for approval are listed above the roster with Approve. Below it,
admins see Open invitations with Revoke and the workspaces each
invitation grants.
Invite… carries a workspace multi-select of the workspaces the inviter administers, for an account invitation and for an invite code. An admin who is not a super admin must pick at least one and may invite only a viewer or a collaborator; a super admin may pick any role and no workspace.
Manage workspaces shows each workspace's owner. Where the caller's role
in workspace.list is admin, a row's Access button, or Access… under
Team on the workspace's settings page, opens the owner, a search field and
a scrolling list of every other member, each with a checkbox; ticking grants
and unticking revokes at once, showing the server's error verbatim. Super
admins are ticked and locked, since they reach every workspace, and an admin
who is not a super admin cannot tick or untick another admin. Super admins
also get Change owner… on the owner's line. A grant,
revoke, workspace.access event or member.access event reloads the workspace
list. member.access (workspace id server) goes only to the member whose
access changed, so a member who just lost a workspace still gets it. Server-wide
controls (server update, session limits, Docker inside sessions, remote access)
show to super admins; the dashboard hides what the caller cannot use and the
server refuses it regardless.
A role change, Approve, and a confirmed Revoke follow
Actions: the radio moves, the member joins the roster, or the
invitation row goes at once. A refusal puts it back and shows the server's
error above the roster or the invitations. At the deadline the change is put
back with "The server did not answer in 5 seconds." and Retry, which
resends the same call, unless a server record for that member arrived
meanwhile; your own name and colour in the header then follow that record.
When overlapping changes of one field all fail, the field returns to the
last value the server confirmed. Starting an action clears only that
action's earlier error, such as the same member's role or the same
invitation's revoke. A retried revoke that is refused as not found counts
as revoked, because the first member.invitation.revoke landed; a first
revoke refused as not found, such as of an invitation already accepted,
puts the row back and shows the server's error. A late
success applies the change again and clears its error; a late refusal shows
its error even after newer actions, unless a Retry of that action was
answered, and an older answer never overwrites a newer one, and writes only
the field that action changed, also across closing and reopening Profile
(nextMemberOrder in store/members.ts). A member.list read keeps the
record of a member changed anywhere since the read was sent, Profile
included; for a member with a change still pending it keeps only the
fields that change touches and takes the rest from the read. This holds
for every member.list read, including the read after Remove, the reads a member.changed event or
an unknown actor triggers, and the reconnect snapshot unless the signed-in
member changed. The member.invitation.list read made
when the section mounts keeps rows created or revoked while it was pending,
and rows whose create or revoke is still unanswered, so switching tabs and
back keeps a Creating… row and leaves a revoked row out. An answer that arrives
after the signed-in member changed leaves the invitations alone. Remove
and giving up your admin role read "Removing…" and "Becoming role…", then
"Still waiting for the server…" past the deadline, when the dialog can be
closed and the request goes on.
Invite… in the header is the one way to invite. Its dialog has two tabs
when the gateway serves both: Account invites a GitHub login or an email
with a role (member.invitation.create) and then shows the invitation's
join link once, with Copy link; Invite code mints a one-time code
for an SSH-key join (member.invite), shown only there. The server records
every new invitation for a GitHub account; an email invitation an earlier
version stored for another provider shows that provider, such as
dana@example.com on google. Learn more says what the link admits
under each policy: under account opening it makes the account a member;
under approved-devices its device waits until an admin approves it from
Needs you.
Invite on the Account tab lists the invitation at once with
Creating… in place of its expiry, then swaps in the server's row. The
join link comes only in the server's answer, so the dialog stays open and
Invite reads "Inviting…", then "Still waiting for the server…", until
the answer shows the link. member.invitation.create takes no idempotency
key, so nothing offers a resend that could create a second invitation. A
refusal, early or late, drops the row and shows the server's error in the
dialog, with what was typed. A failure with no answer, such as Failed to fetch, re-reads member.invitation.list once: an invitation the server
holds for that account and role replaces the row, and the error says its
link was lost with the answer, so revoke it and invite again. Otherwise, or
if that read fails too, the row goes and the error warns that the
invitation may have been created, since the create may still be running;
nothing resends it. If that dialog was closed, or you have left Members, a
toast shows the error with Reopen, which opens Members with the dialog
as it was, or shows Invited <account> with Show link, which opens the
dialog on the link. Once the signed-in member changes, that toast is
dismissed, its action does nothing, and a later answer to that invite is
not shown. Generate code reads
"Generating…", then "Still waiting for the server…".
Devices (src/routes/devices/) lists the computers members reach the
server with through an edge: the member's own, or every member's for an
admin, with status Approved, Pending, Registered (admitted by
signing in under edge-access account) or Revoked, and the key
fingerprint. Approving by id is the Needs you card's
(Session state); this tab approves by an approval code typed in
from that device, which no row shows: Review looks the code up with
member.device.lookup, and a dialog shows the device, its account, its
fingerprint, and the member and role approving admits it as, before
Approve sends member.device.approve with the device id and the code.
Revoke shows on the member's own devices, on a device still waiting,
and, for a super admin, on every device; it shows every server refusal
verbatim. The
list is an InsetList; until it arrives, three row skeletons stand in after
~200ms ("Loading devices").
Personal settings are not on this page. The sidebar footer menu's
Profile opens the Profile dialog (src/routes/members/personal.tsx):
the member's name and role, Display name (an input with Save, sent
as member.rename), Colour and Git identity (the name and email
the member's agents commit as, saved with member.git; the same form
onboarding shows). Agent account sharing lives on Members. Profile is the
one place that edits the git identity; Agents links to it.
Display name, colour, and share or revoke follow Actions: the
header, roster and avatars take the new name or colour, and the teammate's
row flips, at once; that row's button stays disabled until the server
answers. A refusal restores the earlier value, keeps the typed name in the
field, and shows the server's error under the section. A share or revoke
goes back to the last grant the server confirmed for that teammate, which
a late answer to an earlier press may have changed. At the deadline the
change is put back with "The server did not answer in 5 seconds." and
Retry, which resends the same call; each is idempotent by nature. A late
success shows the change again unless a newer one for the same field or
teammate has started, and a late refusal shows its error even after a newer
change saved, unless a Retry of that change was answered. A failure that arrives after Profile closed shows as a toast
with the server's error, Retry at the deadline, and for the display name
Reopen, which opens Profile with the typed name and the error. Once the
signed-in member changes, that toast is dismissed, its Retry and
Reopen do nothing, and the action's later failures are not shown, so
nothing is resent as the new member.
The account.list read made when Profile opens keeps the shown state of a
teammate shared or revoked since it was sent.
A member.changed event re-reads member.list in every other open
dashboard, and updates the viewer's own name when it is theirs.
Sign-ins in Profile (src/routes/members/sign-ins.tsx) lists, from
member.identity.list (readable by the member or an admin), the member's
tailnet login, SSH key fingerprint, GitHub accounts and devices with their
status, re-read whenever the devices are (a member.device event or a
wake), since approving a device binds an account. Link a GitHub account
sends member.identity.link for the viewer and shows the join link with
the next step: open it on a device signed in as that account, or aether link '<link>', then approve that device. Merge with another member
opens a dialog with two tabs:
- Get a merge code sends
member.merge.startand shows the code, a per-second expiry countdown andaether member merge <code>. Proposing and cancelling publish no event, soconnectre-readsmember.merge.pendingevery 5 seconds while that code is valid or a proposal is open, dialog closed or not, and when the tab wakes. Only the latest read lands, and a cancel or accept outdates reads already sent; a failed read keeps the proposals shown and its error shows on the board and in Sign-ins. - I have a merge code sends
member.merge.previewand shows both members side by side (role, sign-ins, devices, sessions, schedules, settings), stacked at phone width. Keep settings from has no default; choosing a side lists what the other loses. When the roles differ the resulting role is stated, and the admin side gets Keep the merged member an admin only when the plan carriesrole_with_keep_admin. Propose merge (danger style) stays disabled until a side is chosen and Discard the listed settings is ticked, then sendsmember.merge.proposewith the plan'splan_digest; the answer says the other sign-in must accept. A refused propose shows the error and drops the preview, as does editing the code, so only a new Preview can propose.
A proposal for the viewer to accept (member.merge.pending where the viewer
minted the code) shows in Sign-ins, in the code tab, as a Needs you card and
as a row in the sidebar's Needs you; Review and the row open Profile at
Sign-ins. Profile is mounted by the app shell (profileOpen in
store/ui.ts), not the sidebar, so Review works with the sidebar
collapsed or the phone's More sheet closed. It lists the proposer's sign-ins,
the settings kept, what is discarded and the resulting role; Accept and
merge (danger style) needs the same tick and sends member.merge.accept
with the proposal's digest, and Cancel sends member.merge.cancel. A
refused accept clears the tick and re-reads the proposals, so a refusal the
server now reports disables Accept and merge. A proposal the server could
not plan shows only its refusal and Cancel, and the viewer's own open
proposals show with Cancel. Every RPC error shows verbatim, as a toast
when it arrives after its dialog or Profile closed, unless the signed-in
member changed. After a merge the record shows in Sign-ins; Merge history
lists member.merge.list with the discarded settings, custom agent
definitions included, and the archive path.
member.list's merged_into is kept as mergedInto. memberName and
resolveMember in lib/member-name.ts follow it, so an id history names
(events, sessions, costs, comments, devices) shows the survivor's name
with (merged). A member.merged event (workspace id server) takes a
fresh snapshot: a merge moves runs and roles without their own events, and
a session absorbed by the merge then shows the survivor, with its role,
without a reload.
Manage workspaces
src/routes/workspaces/ lists workspaces as rows, with three row skeletons
while the list loads. A row's name opens the
workspace: it becomes the active one and the board shows. Below the name sit
its base branch and its owner, and beside
it two buttons, never a menu: Access (for the workspace's admin) and
Settings (the workspace page, for every member). Current marks the
active workspace beside its name. Add
workspace in the header shows the creation choices above the list; with no
workspace yet they show without it. Open the page from the sidebar, the
workspace switcher or the command palette.
The creation choices are the shared src/components/workspace-create.tsx,
the same ones onboarding's Repository step shows:
- Add GitHub repository is the primary administrator path, using shared
GitHubConnection(components/github-connection.tsx) andGitHubRepositoryDialog(routes/admin-dialogs/github-repository-dialog.tsx). Connect displays a one-time code, Copy code and open GitHub, a visible Open GitHub fallback and Cancel connection. It completes automatically: no terminal or I've logged in confirmation is required. Status is read from the server on mount, not inferred from a previous React session. Connection controls explicitly usetype="button"so authorization inside source settings cannot accidentally save or rebind a mirror. The picker labels the account, searches loaded pages and offers Load more. Private collaborator repositories with read-only access are selectable. Selection changes only local form state. Name and branch use the repository's actual defaults. A writable selected repository is proposed as the publishing destination and shown before import; read-only sources leave it unconfigured. Advanced lets the admin change the name, branch or destination, including choosing None - do not publish. Review repository imports withauth:"github"and the list's numericgithub_account_id, then shows the actual observed branch/SHA inline. Use repository explicitly adopts that generation and the exact displayed SHA (expected_commit) before reporting success. Generation pins source configuration; the SHA pins the reviewed code even if another actor refreshes the candidate without changing configuration. A stale review keeps the workspace and displays the server error without fetching or accepting the new candidate automatically. Check source status deliberately loads the latest candidate for review; Use repository then accepts that reviewed SHA. A failed fetch retains the workspace ID: Retry fetch refreshes it, never creates another workspace. Source settings opens the existing source dialog locally; closing it returns to this same workspace and reads status before another action. Saving a different account/branch requires a fresh review. Lost mutation responses are shown as uncertain, not automatically retried; use Check source status, or inspect Workspaces if creation itself was uncertain. - Import a remote repository opens Import repository.
Public sources use credential-free HTTPS. This manual alternative's private
sources use a server-held, read-only deploy key, installed by an administrator of the upstream
repository. Generic SSH sources also require independently verified
known_hostsentries. Import retains the new workspace even if fetching fails and then opens its repository page; repair the source there rather than importing again. Verify the key, review the observed commit, and explicitly adopt its generation and exact displayed SHA. A stale adoption keeps the existing accepted base and candidate review visible; Refresh loads the new candidate for another explicit Adopt candidate confirmation. Reconfiguring rotates the key; verifying does not. - From a local clone opens Create from local clone on a local gateway. Name the workspace and the base branch that exists in the clone; the repository page then opens with the clone link started. A hosted gateway instead gives the desktop/CLI path; it neither creates an unusable local workspace nor pretends to browse the member's filesystem.
Creation and remote source administration require an administrator. A collaborator can link a clone to an existing workspace; a viewer cannot push its base.
The GitHub entry is available only to admins with workspace.import,
github.oauth.start and github.repositories.list; local-clone controls retain
their gateway capability gates. Async connection/list/import results are fenced
by client, server identity/connection epoch and member/role. Context changes
discard stale selections/results; unmount or terminal OAuth states stop polling.
An account change between repository pages clears the selection rather than
mixing identities. Server permission checks independently reject forged calls.
Delete… asks first and lists what is permanently removed; Cancel leaves the workspace untouched. The server refuses active work, pending cleanup and configured schedules rather than stopping them. Failures remain in the dialog verbatim, so the admin can resolve the blocker and retry. See workspace deletion for the CLI and cleanup rules.


After deletion, the list and workspace switcher update together.
workspace.deleted events reconcile other connected dashboards, including
their selection and any open deleted workspace or run.
Workspace settings page
The workspace switcher's Workspace settings item and a row's Settings
button in Manage workspaces open routes/workspace.tsx. It is one
workspace in sections: Base branch, read-only because sessions have already
forked from it; Source and clone, the shared
components/workspace-repository.tsx (link a local clone, the
server-fetched source with its mirror status and deploy key, the checkout
Origin) with its Advanced part open; Environment, below; and Team:
Access, naming the owner, with Access… for the workspace's admin; the
budget with Set budget… (budget.set) and who may message others'
sessions with Change… (workspace.settings), and, where the server offers
workspace.child_limits, the subsession limit ("8 subsessions busy at once per parent session"). The
admin's Change… dialog edits it as Busy at once, saving with
workspace.child_limits. Last, for the workspace's admin, Danger zone
holds Delete… (workspace.delete), which confirms, then lands on Manage
workspaces. Each button is gated by its
server-side permission; a member without it reads the same facts. The page
lists no sessions: the board does.
Environment (components/workspace-environment.tsx) is the workspace's
setup script, variables and egress control (environments.md),
read with workspace.environment.get when the page opens. A link that opens
the page with section: 'environment' scrolls that section into view once it
has loaded.
- An admin edits the Setup script in a monospace field and each variable as a row: name, value, a Secret checkbox and Remove. A saved secret shows a fixed row of dots, since the page never holds its value: its name is read-only, Replace swaps the dots for an empty field and Keep current puts them back. Ticking Secret on a plain variable masks the field and saves it as one; a saved secret cannot be made plain, only removed. A value with line breaks, whether loaded, imported or pasted into the one-line field, is edited in a multi-line field that does not wrap. As a secret it shows the dots and Replace instead, since that field cannot mask.
- Import .env… (
components/workspace-environment-import.tsx) takes pastedNAME=VALUElines or a chosen file, parsed bylib/dotenv.ts, the formataether workspace env importreads. It lists each name as New or Replaces the current value, counts the lines it skips, and has Store as secrets ticked. An empty value has nothing to hide and is added plain; over a saved secret it stays a secret with no value, which Save refuses, so the saved one is not removed unnoticed. Add n variables puts them in the list; nothing is sent yet. - Limit outbound traffic is a checkbox. While it is ticked, the allowed hosts show, each with Remove, over a field with Allow that refuses a URL, a port or a repeat before anything is sent. Its help says that on and off reach sessions launched afterwards and the host list reaches limited sessions at once. A server from before egress control gets no such row.
- Save sends one
workspace.environment.setholding only what changed, so an untouched secret is never named. It is disabled until something differs; Unsaved changes. and Discard show while it does. Beside it the page says what a save reaches: sessions launched afterwards, not sandboxes that exist. A row that cannot be saved - no name, a name used twice,=in a name, a secret with no value - is marked on Save, which focuses it and sends nothing. The server's refusal shows verbatim under Not saved, and the edits stay. A result'swarningshows under Saved. - Any other member reads the script, each name and each plain value, with Secret in place of a secret's value, whether egress is limited and to which hosts, and Only an admin can change this. A failed read shows the server's error with Retry.
When the setup script fails a launch, the New session and template launch
dialogs show the server's reason and, under Setup script output, what
the script printed (components/launch/setup-output.tsx, from the error's
setup_output).
When the refusal is a pending source mirror with a revision to adopt (error
data adopt_command), the New session dialog shows the server's reason with
its closing aether workspace mirror adopt command moved into a code block
with a copy button. An admin also gets Open workspace settings, which leads to
Review source mirror → Adopt candidate; other members read where an admin
adopts it.
The source mirror dialog reports local-only, pending, ready or failure,
including the configured source, branch, accepted SHA and last check time.
Configure source starts from Workspace.Origin and offers public,
deploy-key and github authentication, with source URL and branch fields.
Deploy-key mode alone shows known_hosts, the public key and GitHub deploy-key
installation link; Save source rotates that key, not Verify.
GitHub mode uses the shared connection control and shows the source's numeric
account ID and authorizing member (github_user_id, github_member_id).
An explicit Save source binds it to the current admin's verified account;
reconnecting alone does not silently change an existing binding. These are
non-secret source fields, never a token or member-home path.
Verify (Refresh once the source is ready) reports the server's
result; fetching is not approval, so Adopt candidate and Disable
source require explicit confirmations. A local-only workspace uses its
pushed base.
Settings
src/routes/settings/ is available through either gateway. A nav on the
left lists categories in three groups, the open one marked by a selection
that glides between them on desktop; the selected category fills the
content pane, a PageBody that fades in when the category changes. registry.ts holds the categories and one entry per setting
(id, label, help, keywords, and a gate over capabilities, admin, assistant
availability, onboarding and membership). A category shows in the nav only
while one of its entries is visible, so the nav and search never disagree.
| Group | Category (id) |
Sections and rows (anchor ids) |
|---|---|---|
| You | General (general) |
Appearance: Theme (theme), Text size (text-size); Keyboard (keyboard); Profile (profile); Setup guide (setup-guide) |
| You | Launch (launch) |
Saved defaults (saved-launch-defaults) |
| You | Connections (connections) |
ChatGPT and Claude (connectors); GitHub (github) |
| You | Notifications (notifications) |
Push notifications (push); Watch notifications: push devices (watch-push), Quiet hours (quiet-hours); Slack (slack) |
| You | Watches (watches) |
Watches (watch-list) |
| You | Assistant (assistant) |
Approvals (auto-approve) |
| You | Subsessions (children) |
Subsessions (child-runs): the on/off switch, Limits (child-limits) |
| You | Usage (usage) |
Subscription usage (subscription-usage) |
| This computer | This computer (this-computer) |
Link (link); Syncing: Sync daemon (sync-daemon), Mirror session files (mirror); Danger zone (danger-zone) |
| Server | Server (server) |
Status: Version (version), Tailnet dashboard, Disk and performance (disk); Admin: Docker inside sessions (docker), Retained sandboxes (retained-containers) |
| Server | Remote access (remote-access) |
Edge (edge) |
Addressing. The route is {name: "settings", params: {section}}, and
the URL is ?page=settings&id=<id>. A category id opens that category; a
section or row id opens its category, scrolls the element to the top, moves
focus to its first enabled control (or the section heading) and tints it
with bg-selection for 1.5 seconds. An id that is unknown or hidden for this
member shows That setting is not available here. above the default view.
With no id the desktop shows General and a phone shows the category list;
?page=settings is never rewritten. On first load only, a #<id> hash with
no id is read as the id. Choosing a nav item focuses the category's h2.
Search. The Search settings field at the top of the nav (/ focuses
it while Settings is open and single-key shortcuts are on) matches every
whitespace-separated word, as a substring, against an entry's label, help,
keywords and category title. Label matches come first, then nav order. While
the query is non-empty the nav lists the results with their category, and a
polite status reads N settings or No settings match “q”. Enter opens the
first result; ArrowDown moves to the results; Escape clears the query, then
leaves the field. Two results leave the page: Workspace settings and
budget opens the active workspace's settings page, and Members and
devices opens Members.
Phone. Below 768px the category list is the page. A category shows on its
own, under a Settings back button that returns to the list and focuses
the category it left; browser Back does the same. / in a category returns
to the list and focuses the search field.
Sections. SettingsSection (layout.tsx) is an h3 with an optional
neutral scope badge (This browser, This device, Your account,
Server · admins) over a bordered card of SettingRows. tone="danger"
draws the card border in state-failed. Below sm, a row's select takes the
full width under its label; checkboxes and icon buttons stay on the right.
While a row's first read is pending its help reads Reading … and its
controls are disabled. A failed read shows the error verbatim in a
role="alert" callout with Try again, which reads again (Slack,
Assistant, Linked server, Sync daemon, Docker inside sessions, Remote access).
Categories:
- General: Theme (Dark, the default, Light, System; the palette and the footer
menu offer the same), Text size (Default, Large, Larger; it scales the
interface type tokens through
data-text-sizeon the root element and leaves terminal zoom alone), Single-key shortcuts (see Keyboard and focus), Open profile (the sidebar footer's profile dialog), and Open guide, which reopens onboarding where the member left it. - ChatGPT and Claude, first in Connections
(
src/routes/settings/connectors.tsx, element id andsectionparamconnectors): one exportedConnectorsSection {client}, remounted whenidentityKeychanges so a code never outlives its member. A ChatGPT / Claude segmented control picks numbered steps.connector.listgives the URL to show at once (url), the edge'suniversal_url, that URL at every address of the edge (universal_urls) andsign_in. A URL inuniversal_urlsis treated asuniversal_urleverywhere below. Withsign_inthe third step mints no code and Watch for the connection polls for 10 minutes, then says nothing connected; otherwise Get a code callsconnector.codeand shows its code withuseCountdown. Aurlother thanuniversal_urladds how to link a GitHub account. Without aurl,server.edgeonly says whether the server has an edge or is connected to it. While a code or watch lives,connector.listis polled every 3 s, and once more when it ends; a connector of the tab's app at the URL shown, absent at mint time, or for a sign-in absent from the list shown before Watch for the connection, since the sign-in may be done already, shows <client> (<host>) connected in the section's onerole="status"region and focuses its Done button. A failed poll shows its error until the next one succeeds. Rows list each connector's scopes, itsresourceas Universal URL or the server's own URL, added and last-used times, Move to the universal URL (whereurlis universal and the connector's is not: confirm, start watching for a connector atuniversal_urlwith the old one'sclient_id, preferring one with alast_used_at, andconnector.revokethe old connector only once it has one;localStoragekeyaether:connector-move-claimsrecords which move took which new connector, so two tabs never revoke two connectors for one; a move that ends without one says the old connector was kept), Reconnect (confirm, then the same watch on that client's tab, the tab from theclient_idhost or, from an older server, theredirect_host, at the connector's ownresource: a connector at the server's own URL reconnects there with a code even undersign_in; a failed mint revokes nothing) and Revoke (confirm). A move or reconnect stays in progress past its code or watch, so Get a code or Watch for the connection continues it at its URL, until its replacement calls Cloudfield or Stop ends it; until then the status region names it and the other Move and Reconnect buttons are disabled. Errors show verbatim with a fix: a server withoutconnector.list(-32601) gets the update command and hides the steps, the no-edge and not-connected errors linkdocs/edge.md, anything else links the connector troubleshooting. The palette's Connect ChatGPT or Claude and the first session step's optional Finish setup and connect ChatGPT or Claude, both shown only where the gateway servesconnector.list, navigate with{section: "connectors"}. - GitHub, in Connections for admins when the GitHub OAuth methods
are available: a Connection row holding the same
GitHubConnectionused in onboarding, and a Repositories row whose Add repository opens the shared picker, not another importer. Existing native authorization is reused. Successful explicit revision acceptance upserts/selects the workspace and opens its repository page. Non-admins see neither row. - Notifications: Notify this device when a session needs me, described
under Push notifications, Watch notifications
and Slack direct messages (slack.md). Watch notifications
(
notify.prefs.getandnotify.prefs.set, shown when the server has them) holds Watch notifications on push devices, whose help states where notices go now (Push to 2 devices,Push is off,No push device subscribed, so in-app only, orNo push (<push.status error>), so in-app onlywhen the server has no Web Push, then the desktop app and in-app; it is re-read when this device subscribes or unsubscribes above), and Quiet hours: turning it on saves 22:00 to 07:00 in the browser's time zone; From, Until and Time zone change it, with Save; a quiet-hours save leavespushout so the server keeps its value; a refused change shows its error on that row. See Watches. - Assistant, where the assistant is available (
useAssistantAvailable): Let the assistant act without asking reads and setsassistant.settingsauto_approve. Under it, What auto-approval covers lists what sessions without a card, what always asks and that the assistant's shell and file tools are unaffected. Turning it on first asks Let the assistant act without asking? with the warning that the assistant will launch sessions, message and stop the member's sessions and save the environment on its own; turning it off does not ask. A refusal stays in the dialog or under the row. Approval rules (routes/settings/approval-rules.tsx) listsassistant.rules: each rule's wording,From:the card it came from, when it was created and last used and how many times,Inactive: <reason>when set, and Revoke (assistant.rules.revoke), which drops the row once the server answers and reads the list again; with none it says No rules yet, and a failed read showsCouldn’t read your ruleswith its error and Try again. A muted line under the heading says rules work with auto-approval off; an inactive rule's wording is muted with anInactivebadge. It reads again when a card saves a rule (the store'sruleSaves) or another member signs in. Change in Settings in the assistant panel opens{section: "auto-approve"}; the Syncing badge opensmirrorand the Insights quota link opensusage. - Agents, where the server offers
agent.list: each agent's install and login state (useAgentList, read again each time the section opens, rendered by the Agents page'sAgentListwithout its actions) and Open Agents, which leads to the Agents page; that page still owns install, sign-in, update and removal. Search finds it by "sign in", "login", "Claude", "install" or "agents". - Launch, where the server offers
launch.defaults.get: Saved defaults says who saved them (you or the assistant) and when, or "Nothing saved yet". It lists each agent's saved mode and model with Forget, a Not usable now list ofinvalidchoices with the server's reason, and theunknownones as "Not checked: " and the reason. When the saved account or a fallback member is invalid, Remove unusable accounts saves both repaired at once: your own account, and the order without them, or fallback off when none are left. Account and Fallback (any account, off, or the saved ordered list) save on change; the order itself is set in the launch dialog with Save as my default. Clear asks first, then clears them. Each change useslaunch.defaults.setwith the revision read and retries once on a conflict, as the launch dialog does. The section starts over, closing Clear's confirmation, when a different member signs in. Subsessions keep their own choices in Subsessions. - Subsessions, where the server offers
child.settings: Let my sessions start subsessions (enabled, on by default), with a What subsessions cover list (what it allows, that budgets and limits apply, how to override it for one session). The switch saves on change; a refused change rereads the setting and keeps the error under the row. Subsession agents, once the server listschoices, is the launch panel's agents menu; a refused change there shows the server's error in a toast and rereads the setting. Where the server offersworkspace.child_limits, a read-only row gives the active workspace's limit. - Usage: the subscription usage of your account, or of an account
shared with you. A provider that reports
unauthenticatedkeeps the server's error and adds Sign in on Agents. - This computer, only on the local gateway: the Linked server and
Repository (
link.status) with Link another server (Link a server before any) and Manage workspaces, Saved servers (the default link, then named ones) with Switch, which callslink.switchand reloads the dashboard, the Sync daemon (daemon.status), and Mirror session files, which starts and stops a live session's sync overlay (sync.status). Each row says in one sentence what it does and prefills its target read-only: the daemon the linked server and repository, the mirror the newest live session (or the one already mirroring). Change edits the target; Install and Start mirroring are secondary buttons. The daemon's enable command stays across category changes until a read finds no daemon. Danger zone comes last, with a red Clear local state button. Its confirmation dialog names what goes -config.json, the edge device key and tokens, and the dashboard's saved settings - and what stays: the SSH key, the clone and the server's data. Confirming callslink.reset, clearslocalStorageand reloads into onboarding, so the computer can link to a different server from scratch. A refusal stays in the dialog. - Server: the server version and protocol, Check for updates… (named
Check now after a failed check, whose error shows verbatim below it)
and Update… when an update is waiting; Tailnet dashboard, only
when
server.infocarriestailnet_dashboard_error, with that error verbatim and the restart command a config change needs, re-read every 30 seconds while the category is open because the server keeps retrying; and Disk and performance, a link to Insights › System. For admins, Free retained sandboxes… opens the same confirmation as the board's Finished menu for the active workspace. It prevents reopening those sessions but does not delete all session data: checkouts, homes, repositories and history retain their existing lifecycle. - Session limits, a row in Server › Admin, for admins when the server
answers
server.run_limits: CPUs, memory in GiB and processes, empty meaning the flag or automatic value shown in grey, and Save. The launch dialog reads the same method for the grey values and sends a session's ownlimitsunder Resource limits. - Docker inside sessions, a row in Server › Admin, for admins when the
server answers
server.sysbox.status(src/lib/use-sysbox.ts). States: On, Off with Install,Unavailable on this hostplus the server's reason,Installing… this takes a minute or two, and Install failed with the reason, Show output (the install log in aCodeBlock) and Try again. Install callsserver.sysbox.install, which returns at once; the row then pollsserver.sysbox.statusevery 2 seconds while the state isinstalling. Reaching On from an install announcesNew sessions get it now. Reopen your Environment to use it there.in a polite status region, because an existing Environment keeps its old container. The last state read lives in the store until the dashboard follows another server, so an install that finishes while another category is open still announces itself on return. On the board, an admin whose server reportsoffsees a neutral callout,Let agents use Docker in their sessions, with Install and Dismiss (src/components/sysbox-nudge.tsx). It stays throughinstallingandfailed, and showsunsupported(with the reason) only after an install the admin started from it; it never shows for a plainonorunsupported. Dismissal is persisted assysboxNudgeDismissed. Non-admins and older servers see neither. Anoffreason is shown verbatim; the not-root reason, which containssudo aether-server sysbox install, hides Install and offers that command with a copy button. - Remote access, when the server answers
server.edge(theedgestore slice, read at hydration): the Edge URL orOff, the copyable Server id, the Access policy in words with its raw value beside it (Approved devices onlyapproved-devices), the Owner (<login> (github)orUnclaimed) and the Connection:Connected,Not connected, orConnected, but the edge has not recorded this serverwhile the edge reports it unclaimed. For an admin of a server with no owner, a dashboard with the local verbsedge.status,edge.loginandedge.claimshows Connect my GitHub account, followed by(<login>)whenedge.statusreports this machine signed in at the server's edge: it signs in there first if not, showing the sign-in code, callsserver.edge.claimcode, passes the code toedge.claimunless it names another server than the one shown (The gateway now reaches another server; reload and try again.), and readsserver.edgeagain. Atoken-revokedornot-signed-inrefusal from the claim signs in again and repeats it once. Without those verbs it showsaether edge connectto copy (edge.md).
Repository settings, base freshness and the source mirror live on the Workspace settings page on either gateway.
Watches
A watch is a member's standing request that the server tell them when a session or a pull request needs them or finishes; the server evaluates it, so it keeps checking with every page closed. Notices appear in the dashboard and go to the member's push devices when push is on. The server side and the conditions are in watches.md. The dashboard's parts:
- Settings › Watches (
src/routes/settings/watches.tsx), shown when the server haswatch.list: the member's watches from thewatchesstore slice (src/store/watches.ts, read at hydration and on wake) in anInsetList. A row holds the label or target title, the target kind (followed byKept by the assistantfor a watch whosesourceisassistant, also shown in the detail's header), aStateLine(Watching,Paused,Cannot check,Done,Expired) with the conditions, the server's error verbatim forerror, the last notice and the last and next check. Active (the default) hides done and expired watches; All shows them. With none, the empty state says what a watch is and where to add one. - Detail (
src/routes/settings/watch-detail.tsx): a row opens?page=settings&id=watches&watch=<id>, a dialog that is a full-screen sheet under 768px. Its Open session or Open pull request link is built fromwatch.target, sincewatch.linkis the watch's own page. It readswatch.getand shows what the server sees (observed), the conditions, label and end date to change (watch.updatewith only the fields the member changed, the end at most 90 days from now). An untouched form follows changes made elsewhere, such as by the assistant. An expired watch shows the same form with Watch again, which needs a new end date; a done watch shows when it finished. Pause or Resume, Delete… (confirmed), and up to 50 notices, each with one line per delivery:Push delivered to 2 devices,Push off: <why>,No push device - in-app only,Held for quiet hours: Until 07:00 CET,Push pending: <why>,Push not sent: resolved before delivery,Push skipped: <why>,Push withdrawn from your devices: the need ended(or the server's detail),Push failed: <error>, andIn the assistant chatfor a notice the assistant also wrote into its chat. Opening or closing it keeps focus in the dialog's hands rather than the category heading. - Creating: Watch… in a live session's menu and the palette
(
runCommands, when the server haswatch.create), and Watch PR beside a session's pull request status openWatchDialog(src/components/palette/watch-dialog.tsx). It pre-checks the target's default conditions, describes each (Finished means the agent reported done; Merged means GitHub merged the PR), and sends one idempotency key per open form. The success toast is the server's receipt with View watch; a refusal stays in the form verbatim. - Watched sessions: the session header's state line shows Watch on (or Watch paused, Watch failing) while the member has a live watch on the session; its hint names the watch's conditions, or why it is paused or failing, and it opens the watch. A watched pull request shows Watching PR.
- Live:
watch.changedreaches only the watch's owner. The dashboard re-readswatch.get(src/store/watch-notice.ts); when the event names a new notice and is not a replayed catch-up (older than 30 seconds on the server's clock), it toasts the notice's title and body with Open, which follows the notice's link: a dashboard link in place, a GitHub link in a new tab. A watch the assistant made (source: assistant) toasts through itsassistant.noticeinstead, here and in the desktop app. - Desktop app:
desktop/notify.jsshows each new watch notice natively and opens its link on click. A session's needs-you or finished notice shares the session's five-second duplicate window withrun.status, so one need or one outcome shows once, in either order. A live failure the owner has not seen is a needs-you notice on the server, so it shares the need's window. A need's notice closes when the need is answered, a finish's when its outcome is seen or put off.
Push notifications
src/routes/settings/notifications.tsx is one row over src/lib/push.ts.
What a notification is sent for, and what the server needs, is in
networking.md; the server side is
internal/push.
readPush gives the row its state, and the checkbox is enabled only for the
first two:
| State | When | The row shows |
|---|---|---|
| on | the browser holds a push subscription and push.status says the server holds it too |
checked, with Send test notification |
| off | no subscription, or one the server has dropped | unchecked |
| blocked | Notification.permission is denied |
how to allow notifications in the browser |
unsupported, desktop |
the Electron shell | that the desktop app notifies by itself |
unsupported, gateway |
any gateway but the server's own | that aether gui cannot be opened by a notification later |
unsupported, home-screen |
no Web Push, on an iPhone or iPad outside a home-screen app | install steps in a dismissible callout (kept in localStorage) in place of the switch, and a link to Add it to your home screen |
unsupported, browser |
no Web Push anywhere else, the Android app's WebView included | the same link |
enablePush calls Notification.requestPermission() before anything else is
awaited, because Safari grants the prompt only straight from the tap. It then
registers /sw.js, subscribes with the key push.status returns and hands
the subscription to push.subscribe. A subscription the browser made for
another server key is replaced. disablePush unsubscribes on the server and
then in the browser. A failure of either, or of Send test notification
(push.test), is shown as the error the browser or the server gave.
web/public/sw.js is the whole worker. On push it shows the notification
under the message's own tag when it has one, as every watch
notice does so the session's clears never replace it; otherwise under the session's
ID, budget:<workspace> for a budget notice, or the message's url for a
notice about another page. A newer one replaces the older, and it shows a fallback for a message it
cannot read, because Safari drops a subscription whose push shows nothing.
A message with clear set means the session's need, or the watch's, ended: for
the same reason it is not simply closed but replaced, under the same tag and keeping the shown
title, by a silent notification with the server's body,
No longer needs you, or No longer awaiting review for a finished session's. The server sends it only to the devices whose push
service took the need, when the need ends or the session changes hands,
under the session's Web Push topic, so a need still queued at the push service
is never shown, and tries again a minute later for a device it could not
reach. The worker handles pushes in arrival order, so a clear still reading
the shown notification never lands over a newer need. An assistant's news
about the session, such as that it finished, carries notice; a clear that
finds it shown shows it again, silently, as it was. An assistant's notice of
a need carries no notice, so a clear replaces it like any need. On
notificationclick it focuses a dashboard window that is already open and
posts it {type: 'aether:open-run', run}, {type: 'aether:open-url', url}
or {type: 'aether:open-workspace', workspace}; it never reloads the page,
which would lose its unsent drafts. The page acknowledges
aether:open-url on the message's port; a dashboard from an older build
that does not within a second is navigated to url, or a new window opens
when the worker cannot navigate it. When no window is open, it opens url,
/?run=<id> or /?page=workspace&id=<id>.
watchPush, started with the connection in src/store/sync.ts, navigates on
that message; for url on this origin it also puts the full url in the
address bar, so query keys the route does not carry still reach the page. It also calls push.active at most every 20 seconds while the
pointer, the keyboard or the wheel is in use, which is what makes the server
hold a member's notifications while they are at a dashboard. A server that
has no such method, or that the member is still pending on, is not asked
again.
The desktop shell does not use Web Push. desktop/notify.js applies push's
rule to each run.status event (see
failure-handling.md): it reads the session
with run.get for its title, paused and member_id, and
announces only sessions the signed-in member owns, as push does. When run.get
fails it announces nothing. It notifies once per need, keyed on the session's status, state, reason and status_changed_at, and
words it as internal/push/need.go does. An event whose status_seq is not
above the last one seen is ignored. waiting, waiting-* and working
never notify. A need counts toward the dock badge and its notification
closes when the need ends, including on run.outcome_seen for an unseen
failure and on a run.review event that sets later or accepted. A
review ready gets one silent, low-urgency notice per entry into ready,
counted in the badge; an unseen failure of a session that already ended gets
one outside it.
It also shows watch notices; see Watches.
cd desktop && node --test runs desktop/notify.test.js; make test-scripts includes it.
Clicking it pushes ?run=<id> onto the page's history and dispatches
popstate, which bindRouteToUrl follows, so the session opens without the
reload that would discard an unsent message.
Onboarding wizard
src/routes/onboarding/ is the guided first-session path: four steps under one
header, Connect, Repository, Agent and First session. The header is
the view's PaneHeader with the steps as numbered chips in its right-hand
slot; there is no step counter or second header. A local gateway starts at
Connect. A hosted gateway, which has no link.status, starts at Repository:
remote import, server-side agent setup and configuration do not require a
clone or SSH identity on the browser's machine. Only the local clone controls
require local capabilities, and their hosted replacement names the exact
desktop/CLI handoff. Each step's action row holds its filled button, so on a
phone the top bar's New session is an icon throughout onboarding.
Each step is a file: connect-step.tsx (with edge-link.tsx),
repository-step.tsx, agent-step.tsx and first-session-step.tsx, all built on
Step from layout.tsx, which draws the step's <section aria-label>, its
title and lead line, and the sticky action row. Git identity is
git-identity.tsx, a form rather than a step. The shared
workspace-create.tsx and workspace-repository.tsx components keep initial
and later workspace setup on the same paths; local linking is repo-step.tsx.
The Agent step and the Agents page share src/components/agents/.
Navigation is two levels: the step index, and one sub-screen name owned by
whichever step has sub-screens. The Agent step owns all of today's - an
agent's setup, named by the agent, Add agent… (@custom) and the GitHub
connect screen (@github) - and the wizard holds the name, so Back
closes an open sub-screen first and leaves the step only from the step's own
screen. A step with sub-screens takes them as setup and onSetup rather
than keeping them in its own state.
The wizard passes a Back action to each step. While a local clone form is open, its Cancel closes it. Returning from Agent preserves the selected workspace and repository state; changing workspaces never applies the previous workspace's link or Git result.
In the step header, every step the member has already reached carries a check (a dash for a skipped Agent step) and is a button that jumps to it, forwards as well as back, so walking backwards does not strand them on a step they cannot leave. The current step and the ones never reached are inert text. Leaving the wizard keeps its progress, and Settings › General › Open guide reopens it at the furthest step reached; only finishing First session starts it over.
Git identity is the name and email the member's commits are authored as,
saved on the server with member.git by Save identity. A local gateway
shows it at the bottom of Connect once the server is linked; a hosted one at
the top of Repository. Where the gateway serves git.identity it prefills
them from this machine's own git config, without overwriting a field the
user has typed in; what the member already saved wins over both. Moving on
without saving leaves the server's fallback in place, so it never blocks the
wizard. See teams.md for what the identity does once it is set.
Repository's first line defines the word: a workspace is one repository and
base branch, and the sessions started from it. With no workspace chosen it lists
the member's workspaces with Use and, for an admin whose gateway serves
workspace.import or workspace.add, the shared Add a workspace choices.
Add GitHub repository leads when its methods are available on either
gateway; manual remote import and local-clone creation remain alternatives.
After explicit GitHub revision acceptance, onboarding continues to Agent.
A member who cannot add one and finds
none gets Ask an admin to add a workspace and Continue to Agent,
because Agent setup does not depend on a workspace. Once a workspace is chosen
the step shows it as one row with Change, then the Local clone section
and one Advanced disclosure holding the server-fetched source status, the
checkout origin and the mode-specific source authorization details. The source status stays mounted while
collapsed, so a source that is not ready says so above the disclosure.
Link local repository opens the local path form; its path must be
absolute, accepting a leading /, a drive letter or a UNC prefix. The field
offers folders link.status already knows: the current clone and named
profiles as a datalist. In the desktop shell it also gets a Choose
folder button, which opens the native directory dialog through
window.aetherDesktop.chooseFolder, writes the answer into the field and
clears any error the last attempt left; cancelling leaves both alone, a dialog
that fails puts the shell's own error under the form, and the whole path form
waits while a dialog is open, because a chooser that is not modal to the
window leaves it live. On Linux the shell gives up once the window has held
focus for 10s and puts its error under the form; a folder picked after that
fills the field unless it was edited or the step moved on since (see the
bridge paragraph above). On a shell built before that, leaving the step and
coming back is the way out of a chooser that died without answering. Typing
stays the fallback, because a browser tab has no dialog and a shell built by
an older aether gui build has no method.
The step adds the aether remote (link.repo) and then seeds the workspace:
where the local gateway serves repo.push it shows a Push now button.
The gateway compares the clone's base branch with the workspace's copy before
pushing and answers with one of four states, so the second member to join a
workspace reads what happened instead of git's ! [rejected] main -> main (fetch first).
Local-only workspaces retain Push now, Fast-forward my clone, daemon base pushes and direct base writes. A mirrored workspace owns its base on the server and rejects direct base writes; session branches can still be pulled. The dashboard withholds base push controls while an administrator's source status is unresolved or identifies a mirror. Configuring or fetching a source never silently authorizes its candidate.
When link.repo answers an origin, the connected line adds Sessions push to <origin>: the upstream a session pushes to, the same one aether link --repo
prints. That push destination is separate from the Source control read source.
A link that recorded none says nothing about one.
pushed names the branch that landed; up-to-date names the commit the
workspace already has. Both keep git's output in a "What git did" panel,
open on arrival because Everything up-to-date and [new branch] are both
success and mean different things, and Continue moves on.
behind means the workspace is ahead. The step names both tips and offers
Fast-forward my clone, which runs repo.fast-forward and then reports
the new tip, whether that branch was the checked-out one, and whether the
working tree is dirty. The panel then shows both outputs in the order git
produced them: the comparison's fetch, then the fast-forward. diverged
means both sides moved on: the step names both tips and offers the fetch,
log, rebase and push commands to resolve it by hand, copyable as one block,
with no fast-forward button, because Cloudfield never force-pushes.
Both states keep Push now, which re-compares - the thing to do after
resolving by hand - and both take away the copyable git push -u aether <branch>: it is the command that produced the rejection this comparison
exists to replace. That command stays only where it is the right one, which
is a clone the workspace has not moved past: before any push, after one that
failed, and after one that landed. A refusal keeps the user on the step with
git's own output in a monospace block. The three outcome panels - behind,
diverged and the fast-forward result - are aria-live="polite", because they
appear without a page change.
The branch is the workspace's base branch, so a workspace created with
--base seeds the branch its sessions fork from. When repo.push is unavailable,
the step shows only the copyable command.
Link, push and fast-forward always carry the selected workspace ID. Each
server profile has one current clone, not a clone per workspace. The UI
rechecks link.status on entry, focus and before Git mutations; a remembered
connection for a different current clone must be linked again. The gateway
also checks that the clone's aether remote names the requested workspace.
What the step settled - the clone path, the remote the gateway wrote,
git's push answer, and the fast-forward once one has run - lives on the UI
slice as onboardingRepo, not in the component. Each answer is written onto
the record as it stands in the store rather than the one captured at render,
so a push and a fast-forward started from the same screen cannot lose each
other's result. Each answer also carries the clone it ran against. A member
who re-points while a request is in flight has that answer - and its error -
dropped rather than merged onto the repository that replaced it, and the new
form starts with its own push button rather than the old request's spinner.
A member who picks another workspace keeps the answer on the record it was
issued for, and the step, which shows only the record matching the selected
workspace, never renders it against the workspace that replaced it.
Returning to the step shows that connected
repo with Use a different repository to go back to the form, prefilled
with the old path; a blank form there would ask again for a remote that
already exists.
The UI slice persists the resume point, furthest step reached, selected
workspace, source choice, connected repository and First session draft. Finishing
the wizard or navigating away clears these fields. Steps are stored by name
rather than position, so inserting a step never
relocates someone who is mid-wizard. The persisted state is versioned, and one
migration in web/src/store/index.ts covers every older shape: versions 0
through 2 stored the resume point as an index, so those numbers are read back
as the steps they named; versions 0 and 1 stored a Repository answer this build
cannot use - version 0's predates the comparison states and version 1's carries
no link id - so it is dropped rather than rehydrating a blank panel; and
no version before 4 has a furthest step, so the resume point becomes it, or
the first backward jump would turn every later step inert. Versions before 8
named the six steps of the old wizard; each maps to the step that absorbed it
(Link and Git identity to Connect, Workspace to Repository, Agents to Agent).
Anything it cannot place starts over. Repository without a workspace opens on
the workspace list; Agent never needs one; First session without one says so and
offers Choose a repository.
Hydration reads link.status first for a local gateway. A linked machine with
no in-progress workspace is marked onboarded on initial hydration. An
unlinked local gateway routes here when onboarded is false. Hosted onboarding
also resumes after reload when its saved workspace still exists, even after
the first import. A linked clone must not erase a resumed wizard's workspace
or draft, and a reconnect must not redirect navigation.
Authorized session deep links take precedence. Completing the final step or
navigating elsewhere marks the UI onboarded and clears wizard state.
Connect asks How does this computer reach your server? with three
radio cards (src/routes/onboarding/connect-step.tsx): Tailscale,
marked Recommended and chosen by default, Cloudfield relay, and SSH
address. On a phone the three share one row and the chosen card's
one-line description shows below it, so the field below stays above the
keyboard. A handed link, or Link
another server while an edge link is the default, chooses the relay
instead. Tailscale shows one Server's
tailnet name field and Link, with a line for people without a tailnet;
SSH address shows Server address, Invite code and Your name,
which link.apply takes as the invite's display name or the saved link's
profile name. Both send link.apply; only SSH address sends the invite and
name.
Cloudfield relay signs in to an edge (src/routes/onboarding/edge-link.tsx):
Sign in with GitHub runs the edge's device flow through the local
gateway, which keeps the device token, shows the code while it polls
edge.status, then lists the servers the account reaches, each with one
Link. Signed in to more than one edge, it lists them and
shows nothing to link until one is chosen; the server list, link by id and
claim then pass that edge to the gateway, as --edge does on the command
line. A server picked from the list opens a Confirm server panel with its
id and the host key fingerprint edge.hostkey read, and links only on Link
and pin, because that id comes from the edge. Opened from Settings > This computer > Link another server, the step
starts on this picker with a server already linked; linking an edge server makes it the default and keeps the
previous edge default as a saved server named by its server id. Claim
or invite link takes the claim link or code aether-server setup printed
and refuses a claim link naming another edge than the one signed in; a join
link pasted there opens the Join panel below. It shows below the server
list; Other ways to link holds Server id from your admin, which the
edge cannot substitute. While no edge is signed in, below the
sign-in, Have an invitation or claim link? takes either link or a bare claim
code, and Open link opens it as a handed-over link, so a join or claim
link can be given before signing in; anything else answers
That is not an invitation or claim link. A join or claim link entered in
the Tailscale or SSH address field opens the same way. A link whose member
is pending says Waiting for an admin to approve you with the aether member approve command instead of Connected, and reconnects only on
Continue, because a pending member's hydration fails. The relay panel
stays mounted, hidden, while another card is shown, so a link in flight
keeps its busy state. Connect
distinguishes no configured server from a linked one, shows Continue only
once a server is configured, and refreshes on Retry and when the window
regains focus, so a separate aether link command appears without
restarting the GUI.
A link a shell hands over (URL state) opens
Connect at any step, on the relay card. A claim link says Claim link
received and fills Claim or invite link. A join link replaces the
sign-in with a Join panel:
You are invited to the server <server id>. with the account edge.status
reports for the link's edge, signing in to that edge first if needed, and
Join sends the link to edge.join. On a device-pending refusal it
shows Waiting for an admin of <server> to approve this device with the
device label and key fingerprint, or, when the refusal carries an
approval_code because nobody can approve in the app, the refusal's
message with the console command, and calls
edge.join again every 5 seconds until it links or is refused otherwise;
a token-revoked or not-signed-in refusal signs the panel out and offers
Sign in, and a join-wrong refusal, an invitation that names another
account, offers Sign in with another account;
the admin's side is the Needs you card (Session state). A join
or claim that succeeds but could not move the clone's aether remote
shows the gateway's remote_error as an error toast; the link stays. A
gateway without edge.join or edge.claim, such as the Android app's
Tailscale-mode dashboard, shows the link and the aether link command to copy
instead, with Continue.
The Agent step opens with the agent list, Add agent… and the extras
described under Agents; each agent's setup starts with the
Standard and Enhanced choice. Its primary action is Continue once any
agent is installed; before that the Set up of Claude Code, else Codex,
else the first agent is the filled button, with Skip for now beside Back. A skipped Agent step shows
a dash in the step list instead of a check. On a phone the setup
sub-screen's Back row scrolls with the page rather than sticking over the
cards. A gateway that cannot
install agents says to run aether agent add from a terminal instead.
First session is the launch form, not a copy of it: RunFields and
useAgentChoice from src/components/launch/run-fields.tsx are what the
New session dialog's session tab renders, so the task, the agent picker and the
Mode control follow the same rules - task optional except for
Background, a mode the agent cannot use disabled with its reason. The persisted
draft's agent wins the first pick, then the most recently remembered launch
default, which the Agent step's Done or Run just set. With nothing
installed the step drops the form, says No agent is installed yet and
offers Set up an agent, which jumps back to Agent. A failed agent.list
shows the server's error with Retry, because a gateway that could not
answer is not the same fact as an account with nothing installed. Launch
sends mode unless it is Standard and records it with rememberLaunch.
Before enabling Launch, the step checks the selected workspace's base
through files.tree where available and reads available mirror status for
every role. A mirrored workspace must have a ready source and an accepted
commit. Missing branches, pending authorization and source errors show as
The base branch is not ready with Check again and Review
repository. Empty workspace creation is not source readiness. The server
rechecks permission and source policy at launch. One line says what happens
between Launch and the first output: the container starts, the image is
pulled the first time the server uses it, then the agent starts, about 5 s
more in Enhanced. The fake agent is documented in
quickstart.md,
not on the step.
Update prompts
The dashboard tracks three update targets: the server, this client
(the aether binary running aether gui) and the desktop shell.
src/store/updates.ts derives each target's state from the store:
up_to_date, checking, check_failed, available, required,
scheduled, channel_wait, applying, restarting, ready_to_restart,
failed or rolled_back. Every surface below renders from those states:
- the sidebar notice row,
- the Updates dialog (
UpdateCenterinsrc/components/update-banner.tsx, mounted byAppShell), - the required-update gate (
src/components/update-gate.tsx, mounted byApp), - Settings › Server.
The client row lives in src/components/cli-update-banner.tsx. The pieces
the rows share are in src/components/update-banner-shared.tsx. Versions
compare with src/lib/version.ts, which follows internal/selfupdate's
semver precedence:
- numeric prerelease identifiers order numerically;
- a
git describetail ranks just above its tag; - an unparseable version (
dev, a bare commit) is never behind.
That order decides only the dashboard's own comparisons, and only when a
side reports no signed build. When the client and the server both report
one (cli_build in update.check, build in server.info), the notice
that the server is older than this client (serverTooOld) orders by
(build, hotfix), as the server's client gate does, so a beta promoted
from a nightly is not older than that nightly.
- Release channel. Settings › Server has a Release channel
section (
src/routes/settings/release-channel.tsx) with Stable, Beta and Nightly pills, shown onceserver.update_statusnames achannel. Every member sees the current channel; only a super admin gets the pills. Picking Nightly always asks Switch to nightly builds? first. Picking Stable or Beta runsserver.release_channel_setwithdry_run, and when the answer sayswait(the running build is above that channel's newest), or the channel's newest release could not be read, shows Switch to beta? with the running and target versions and builds, or the dry run'starget_errorverbatim. Anything else saves at once. Saving installs nothing; a pending update the new channel does not take is cancelled and the section says so. A server error shows as it came. On a nightly or beta server a super admin also sees the newest beta, with the days since it was cut, and the newest nightly, fromchannel_pointersinserver.update_status(each present only when the last check verified that pointer, and absent after a restart until the first check). Each has a Promote link tohttps://github.com/3xDevOps/cloudfield/actions/workflows/promote.yml. The link only opens that page; its Run button promotes. - Channel wait. While
server.update_statusreportschannel_wait, the server row says the server stays on its build, with both builds, until the channel reaches it, instead of "up to date" or an offer. An update the server scheduled itself (pending.by_server) reads "Scheduled by the server".
The server always comes first. It updates before its clients, and a server that runs a newer release than a client refuses that client (install.md).
The reads.
src/components/update-checks.tsxis mounted byApp, so it keeps running behind the gate. It readsupdate.checkfrom the local gateway andserver.update_statusfrom the server at these times:- on mount;
- on a timer of 30 minutes ±10%, so dashboards opened together do not check together;
- on window
focusandvisibilitychange, at most once a minute.
server.update_statusis read again after every reconnect, and wheneverserver.infonames a different version. A reconnect that finds an update in flight (preflight,applying,restarting,verifying) re-reads the status every 3 seconds, up to 20 times, so a server that came back verifying is seen to reachappliedinstead of timing out. The timer and focus reads skip the status while the stream is not live, or while a status read is already out. Nothing is read while the window is hidden, except in a desktop shell that can notify: there the reads run in the background too.The CLI and shell rows come from
update.check, because the dashboard can update only the machine runningaether gui. The server row comes from the server's own background release check. Any member may read the server's status.Reads of each kind are numbered, and only the newest one's answer is written, so a click supersedes reads already out and an older status cannot overwrite a newer one. The periodic read stands down while an install runs, so it cannot rename the release the row names.
A failed read is recorded, not swallowed. The last good answer stays on the store, so an offer already on screen does not vanish. The error shows wherever the target has nothing better to say, even over an older status. The server counts as up to date only when its status names a latest release. When the gateway's release lookup fails,
update.checkanswers withcli_error; that is a failed check too.Check for updates. Check for updates… is always in the sidebar footer menu and in Settings › Server, and Check now is in the dialog footer. The desktop shell's Check for Updates… menu item runs the same check. It:
- clears the dismissals;
- opens the dialog;
- reads
update.checkandserver.update_statuswithrefresh: true.
The server runs its release check there and then, and the gateway skips its cache. The check always answers. With nothing to update, the dialog says You're up to date (vX). Checked HH:MM., and each row says the same for its target; an out-of-date desktop app withholds that line. A check that failed shows the error verbatim:
- Could not check for a new Cloudfield release.
- The server could not check for a new release.
- Could not read the server's update status. when the status read itself failed.
Settings › Server shows the same error under Version, and its button reads Check now.
The notice row. The sidebar shows one line, linked to the dialog by Update. In priority order:
- Server update in progress, terminals reconnect briefly;
- for admins, Server update to X failed or The server update was rolled back;
- Server X is available (members: Server X is available, ask an admin);
- Update to Cloudfield X failed or Cloudfield X is available;
- The desktop app is out of date.
The dialog lists the server first.
Admins get the server's version, the latest release and the release notes link. What else the row offers comes from
server.update_status:- capable: Update now and Update when idle. Update now opens
a confirm dialog. It counts the sessions active in this member's own session
list, using the server's definition of busy: a paused session and one
parked at needs-attention do not count. The dialog says what the
restart costs: sessions keep going because the server reattaches to
their sandboxes, and attached terminals reconnect on their own. The
confirm calls
server.updatewithwhen: "now". Update when idle sendswhen: "idle", and the row becomes Server X is scheduled. Scheduled by <member>, applies when no session is active., with a Cancel that sendswhen: "cancel". A scheduled row also names what the update is still waiting for (status.waiting), because a live terminal attach holds it back the same way a working session does. - not capable: no buttons. The row shows the server's own reason,
then the commands to run on the server host, each with a copy button.
A server without
server.update_statusfalls back toupdate.check'sserver_behind.
While the server is behind (its row says available, or
update.checkreportsserver_behindbecause the server's own release check failed), the client row adds Update the server first, from its row above or with aether server update; this client updates after it. Whenupdate.checkreportsserver_first,update.applywould refuse, so the client row drops Update now; a member is told to ask an admin to runaether server update.- capable: Update now and Update when idle. Update now opens
a confirm dialog. It counts the sessions active in this member's own session
list, using the server's definition of busy: a paused session and one
parked at needs-attention do not count. The dialog says what the
restart costs: sessions keep going because the server reattaches to
their sandboxes, and attached terminals reconnect on their own. The
confirm calls
Members see Server X is available. and Ask an admin to run
aether server update; this client updates after it., with no buttons. A failed update shows the server's error and says to ask an admin.
Server phases.
server.updateevents land on theserverslice throughapplyEvent. They arrive once per workspace and once more from the RPC result, so the slice keeps the furthest phase of one update, never the last frame to arrive. The phases render as:- preflight and applying: Updating the server to X…, saying nothing has been replaced yet;
- restarting and verifying: Restarting the server on X…;
- failed: the server's error verbatim, then the manual commands;
- rolled_back: The server update was rolled back; it runs Y again., with the error.
Once one update is
applied,failedorrolled_back, a lateapplying,restartingorverifyingframe for the same version is ignored; Update now and Update when idle clear the settled phase before they ask. A Cancel result ends a schedule at once, ahead of the status read before it that still listspending.server.update_statuscarries the samephase,error,from_versionandto_version. A status still in flight seeds the progress after a reload. A status with a settledphase(applied,failed,rolled_back,idle) ends it, and so does, on an older server, aserver_versionat or past the version the phases were about.failedandrolled_backshow only while the server is still behind the latest release. A server whose phases stop for 10 minutes becomes failed: The server did not finish updating to X within 10 minutes. Last error: …, with the last error the status, the last attempt or the status read reported. Every phase is also a row in the activity feed, filterable as Server updates.The client row is for everyone. It names the new version and the running one, says what updating costs, and offers Update now, the release notes and a dismiss. Updating replaces the
aetherbinary on this machine and restarts the dashboard, which stops attached terminals and any running sync session; the sessions keep going on the server.What the button does is decided before the click, from
update.check'sinstall_method(docs/local-gateway.md):- direct: the button and nothing more.
- admin-prompt (macOS with a GUI session and a
cli_pathin a directory only root can write, such as/usr/local/bin/aether): the button, and before the click: macOS will ask for an administrator password: {cli_path} is in a directory this account cannot write to. The dialog is labelled osascript, the tool Cloudfield asks through. Cloudfield never sees your password. - manual: no button. The row shows
sudo aether updatewith a copy button.
When
update.check's top-levelcan_self_updateis nottrue(a packaged or a development build), there is no button and noaether update. One line namestarget_version, such as This aether cannot update itself. Install vX from its release page., followed by a link to that tag's GitHub release page. The link appears only when the tag has thevMAJOR.MINOR.PATCH[-PRERELEASE]form.applyClientUpdateinsrc/store/updates.tsruns the click, shared with the gate:- It re-reads
update.checkwithrefresh: true. A fresh answer that finds this machine current installs nothing and says Cloudfield vX is the newest release. Nothing was downloaded. A freshcli_erroris the click's error, except on a gated client whosetarget_versionis set: the server's release was found anyway, so the install goes on. - It calls
update.apply. While a desktop-app rebuild runs, it pollsupdate.statusevery second.
The outcome stays on the store, so the row keeps saying what happened after the re-checks report this machine as current:
- the paths replaced;
- the
restart_commandfor a co-locatedaether-server; - a rebuild still running, or its real error with
aether gui build.
A
403answer means the macOS dialog was cancelled or the password refused: Update cancelled, nothing was changed., muted, with the gateway's words, and the button comes back. Any other refusal is rendered verbatim. A failure or cancel is about one release: a later check that names another one clears it and offers the new release.When the gateway reports the CLI as
packaged(the Android app), the client row and its notice are gone. The dialog says Updates come from the Android app: install its new version to update Cloudfield., followed, when a newer release exists, by Cloudfield <tag> is released; the app's banner says when and where to update. The app's own banner is the notice (install.md).The required-update gate. The gate replaces the whole dashboard while this client is gated:
- after any call answers
-32005or HTTP 426 (onUpgradeRequiredinsrc/lib/api.tshears every one); - after the events stream's subscribe ack does
(
{"ok":false,"code":-32005}); - when
update.checkreportsclient_update_required.
Apprenders the gate ahead ofConnectionError, because a gated client is refused everything exceptserver.infoandserver.update_status. The hydration retry and the event stream stop for good, since every retry would be refused the same way.The reverse direction is
ServerTooOldBanner: when the server release is older than this client's (release cores compared, so a source build of the same release does not count),Appfloats This server is older than this app, the versions andaether server updateover the mounted shell. The check can answer while a form is half filled, so the warning never replaces the shell or takes focus. The server version is whichever was read last:server.infoon a hydration, or the live server half of a laterupdate.check, which writes it back intoinfounless a hydration replacedinfowhile the check was out. The server refuses nothing in this direction, so Continue anyway dismisses it for that pair of versions (aether.server-too-old-continuedinlocalStorage), so a reload or a killed WebView does not bring it back until either version changes. It is only reachable whereupdate.checkis: the local gateway, which includes the Android app. The server gateway serves a dashboard built into the server itself.The gate cannot be dismissed. It is a region labelled by its heading, which takes focus when the gate appears. It shows the server's own message once, which names both versions, and the
min_client_versionthe server accepts. Update now runsapplyClientUpdate. While gated,update.applyinstalls the server's release, named byupdate.check'starget_version, not the latest one. An emptytarget_versionmeans no published release matches the server; the click then installs nothing and shows that error. Progress, the real error and a cancelled administrator prompt share one status live region. The manual command (aether update, orsudo aether updatefor a manual install) is chosen by the dashboard; thecommanda -32005 carries is ignored, so a server cannot choose what a member pastes into a terminal. It is followed by what makes it take effect: Then restartaether guiand reload this page., or in the desktop shell Then quit and reopen the desktop app., because the running gateway keeps the binary it started with. A client that cannot update itself gets neither button nor command, only the line and release link the client row shows; a packaged one (the Android app) reads Updates come from the Android app: install its vX release to update Cloudfield. What follows a finished update depends on the gateway:- under the desktop shell, the gateway relaunches and the page comes back on the new version;
- in a browser tab, the gate says Cloudfield X is installed., says to
restart
aether gui, and offers Reload.
A later
update.checkthat reached the server (server_versionset, noserver_error) and reportsclient_update_required: falseends the gate with one reload, since the stopped stream restarts only on a reload. It reloads once per client version per tab session (aether.update-gate-reloadedinsessionStorage), so a server that keeps refusing leaves the gate up rather than looping.The way out is always there:
- Copy details copies the versions, the message, the manual command and the last error;
- Reload;
- Switch to <name> for every other server saved with
aether link --name, throughlink.switch.
A dashboard served by the server itself is never gated. It reloads instead when the server comes back on a different version, since its pages are that server's build.
- after any call answers
Dismissal is per version and it persists.
dismissedUpdateson theuislice records which version was dismissed for each target. It rides the persisted preferences, so a dismissal survives a reload, and the next release shows the prompt again. A dismissal hides only an offer. A scheduled, applying, failed or rolled-back server update still shows.Desktop notifications. In the desktop shell, a newly available release raises one OS notification per target and version, through
desktop/notify.js. It names the server release for an admin whose server is behind, and the client release otherwise. It fires only while no app window is focused; in front, the notice row is the notice. The shell owns the record of what it announced, keyedserver:<tag>orcli:<tag>, inannounced-updates.jsonunder Electron'suserDatadirectory: the gateway listens on a new port every launch, so the page's own storage would start empty each time. Clicking the notification opens the dialog and runs a check.The desktop shell has a prompt of its own. The SPA ships inside the CLI, but the Electron shell around it is whatever
aether gui buildlast installed. The shell'spackage.jsoncarries the complete CLI version beside its npm-valid version, and the install records the CLI's executable path inresources/aether-cli.json.desktop/main.jsstarts the recorded binary ahead ofPATH(unlessAETHER_BINoverrides it) and hands the build version to the renderer.desktop/preload.jsexposes it aswindow.aetherDesktop.shellVersion. On a local gateway, a shell whose version differs from the capabilities version by release precedence raises The desktop app is out of date. withaether gui build. Two builds of one tag do not count as different. A browser tab and a server-hosted dashboard have no local shell to compare. The prompt is independent ofupdate_available: the CLI is usually current after an update that left the shell old.The bridge also carries
onCheckForUpdates(the menu item) andnotifyUpdate. On Windows and Linux,controls.showMenuopens the title-bar menu. All three are optional, because a shell built by an olderaether gui buildlacks them.
Keyboard and focus
Everything the dashboard can do is reachable without a mouse, and every control a keyboard reaches draws the same focus indicator.
One focus indicator. focusRing in src/lib/utils.ts is the shared
outline utility. Every focusable primitive composes it, including
SelectTrigger, SelectItem, Checkbox and CollapsibleTrigger. Raw
buttons, links, menu items, dialog close controls and resize handles use it
too. Controls that fill a scroll container use the inset variant so the
outline is not clipped. Keyboard outlines appear immediately, without a
colour transition, and focus remains on a real control when a row or pane
changes. Verify focus, keyboard and accessibility as observable behavior, not
CSS class or source-string contracts.
Only after Tab. Browsers match :focus-visible after any key press
followed by a scripted focus move - Enter sending a message, a shortcut, a
dialog returning focus - so a control nobody tabbed to could wear an outline.
index.css redefines the focus-visible: variant to also need
data-tabbing on the root, which an effect in App.tsx sets on Tab and
clears on the next pointer press, and removes the browser's own
ring outside that state. Text fields keep the native rule, so a clicked field
still shows its outline.
It is an outline rather than a ring, for two reasons. Windows High Contrast
(forced-colors: active) discards box shadows, which is what Tailwind's
ring-* compiles to, and would leave the app with no focus indicator at all.
And ring-* already means "selected" on the member colour swatches, where a
focus ring in the same property could not be told apart from the selection.
The outline sits 2px outside the control, except where the control has no
room outside it: a row that fills its scroll container - a sidebar session, a session
list entry, a changed-file row, a board card - and a menu item, which sits flush
against its neighbours. There it is drawn 2px inside instead. An outline
outside a full-bleed row is clipped at both edges by the scroller, and padding
the container would inset the dividers that are meant to run edge to edge. The
inset has to carry the same variant as the token
(focus-visible:-outline-offset-2): a bare -outline-offset-2 is one
pseudo-class less specific and loses at the moment the outline is drawn.
MenuContent and DialogContent suppress the outline on themselves:
each takes focus programmatically when it opens and has nothing to show for
it. Their contents are not the same case. A MenuItem takes real DOM
focus under Radix's roving tabindex, so it wears the outline like any other
control, keeping its focus: background as well. A SelectItem is that case
again: Radix moves DOM focus onto the highlighted option, so it wears the
outline inset like a menu item, and SelectContent suppresses its own for the
reason the other two containers do. A CommandItem suppresses the outline
too, and that one is deliberate: cmdk never moves focus to it at all, leaving
it on the input and tracking the highlighted row with aria-activedescendant,
so a background is all it has, and all it needs. It is the one row the focus
sweep is told to skip.
One keybinding table. src/lib/keybindings.ts lists every shortcut as { id, keys, scope, label, when? }, with keys in
tinykeys syntax ($mod is Cmd on
Apple platforms and Ctrl elsewhere; a space separates the two presses of a
sequence). The table drives the handlers, the tooltips (shortcutLabel(id))
and the shortcuts dialog (?, or Keyboard shortcuts in the sidebar footer
menu), which groups it by scope and adds the keys a focused tab strip,
splitter, Changes line or terminal owns itself. keybindings.test.ts fails when two
bindings in overlapping scopes share keys, or one begins the other's sequence.
| Key | Scope | What it does |
|---|---|---|
⌘K / Ctrl+K |
global | Open the command palette |
⌘Shift+P / Ctrl+Shift+P |
global | Open the command palette |
⌘B / Ctrl+B |
global | Show or hide the sidebar |
⌘Shift+Space / Ctrl+Shift+Space |
global | Open or close the assistant, from a field, an editor or a terminal too |
? |
global | Open the shortcuts dialog |
n |
global | New session |
u |
global | Open the next session that needs you |
j / k |
global | Focus the next or previous session in the sidebar |
g then b, l, a, f, g, e, , |
global | Go to the board, all workspaces, activity, files, agents, environment, settings |
[ / ] |
run | Show the previous or next session view, Trace included on an Enhanced session |
⌘. / Ctrl+. |
run | Show or hide session details |
c |
run | Message the agent (focuses the Chat composer) |
Esc |
run | Leave a session for the board |
⌘L / Ctrl+L |
browser | Focus the Browser's address bar, from anywhere in the session |
⌘R / Ctrl+R |
browser | Reload the page |
⌘[ / Alt+← |
browser | Go back |
⌘] / Alt+→ |
browser | Go forward |
⌘Shift+C / Ctrl+Shift+C |
browser | Annotate the page for the agent |
Enter |
composer | Send the message, or steer the running turn |
⌘Shift+Enter / Ctrl+Shift+Enter |
composer | Queue the message for after this turn |
1 to 4 |
request | Pick that option of the focused Session request; Escape does not deny it |
A component answers its bindings with useKeybindings(scope, handlers), which
pushes the scope onto the stack in src/lib/key-scope.ts while it is mounted.
The scopes are global, run, browser, card, request and composer;
card is the board's r/o on the focused card, request the option
digits on a focused Session request, composer the send keys while the
Chat composer has focus and browser the keys of a session's Browser
while it is on screen. Esc is the session's, to leave it, and the table gives a
key to one binding; while a page is being annotated the Browser answers
Esc itself first and stops annotating instead. When a key matches in two live scopes, the
innermost wins. A binding without a handler does
nothing and is left out of the dialog: n is offered only to a member who
may launch, and a g destination only when the gateway serves it. A session's
keys are listed even from the board, where no session scope is on screen.
A dialog a shortcut opens has no trigger to return to, so useReturnFocus in
src/lib/hooks.ts records what had focus when it opened and puts focus back
there on close: New session (n), the shortcuts dialog (?) and every dialog the
palette opens. A palette command that opens a dialog hands the palette's own
invoker over (handOverFocus), so closing New session after ⌘K returns to
where ⌘K was pressed, not to the vanished palette input.
Two window listeners serve every scope. Chords (a modifier beyond Shift) are matched while the event is capturing, so a terminal's own handler never turns them into input. Single keys are matched while it bubbles, after Radix and any component that acts on the key first have had their chance to mark it handled.
The single keys stand down whenever something else has the keyboard:
keyboardBusy and inModal in src/lib/keys.ts cover a text field or a
select, a live terminal or its focused history surface, an open menu or list
box, or an open dialog. A stray n typed at an agent has to reach the agent;
in history it does nothing. In a menu it is that menu's typeahead, and on a
select it jumps to the option that starts with it. The guard finds a select by
its combobox role, since the control is a button. Settings > General >
Single-key shortcuts (on by default, persisted with the other view
preferences) turns off every character key: n, ?, u, j, k, / in
Settings, the g sequences and the board card's r and o. Escape and the chords stay
live. The g prefix waits 1.5s for the key that completes it, and any key
that goes somewhere else ends the wait.
A chord's own handler or its when decides where it stands down. The palette
chords cannot be mistaken for typing, and with the terminal holding the focus
and swallowing Tab they are the way out of a session. They stand down for a modal
rather than for anything that has the keyboard, through inModal and the
store flag that names the form the shell is hosting. They take the key from
the browser either way, so a stand-down cannot land the reader in the address
bar. Mod+B stands down like a single key, so a terminal keeps Ctrl+B for
tmux.
The Browser's chords are the host browser's own, taken from it only where
they are about the page. Mod+L answers anywhere in the session except inside a
terminal, a menu or a dialog, so Ctrl+L still clears a shell; the session frame
registers it, so it works before the Browser is on screen. Reload, back
and forward answer only while focus is inside the Browser (its page, its
address field or its toolbar); anywhere else the host browser or the desktop
shell keeps them. History uses the platform's keys, ⌘[ and ⌘] on macOS
and Alt+← and Alt+→ elsewhere, because Alt and an arrow moves a caret by
a word on macOS. Each handler prevents the default and stops the event while
it is still capturing, so neither the host browser nor the remote page, which
is sent every other key, acts on it.
That guard reads the event target rather than the document. Radix dismisses an
overlay from a capturing document listener without stopping the event, and
React commits the close in a microtask that runs before a window listener is
reached: asking the DOM what is open would find the dialog already gone and
let Escape both close the dialog and leave the session. The shell also stands down
on defaultPrevented, which is how Radix marks the Escape it just acted on.
The document is asked in one case only, by both guards: a key that landed on
body, where focus falls when an overlay removes the control that was holding
it, or merely disables it - Radix's focus scope watches for removals and does
not take the keyboard back from a button that disabled itself mid-flight.
There is no target left to read, so the fallback asks whether a dialog or a
menu is open, and a dialog playing its exit animation does not count. It does
not ask about terminals: focus on body with a terminal on screen is
ordinary, and closing a shell hands the keyboard to the next running shell or,
when there is none, to the selected terminal tab or + Shell rather than
orphaning it.
An open tooltip is the one overlay that neither guard names, and it does not
need to: a tooltip owns no keys, and its trigger is an ordinary control.
Escape is the exception. Radix closes the tooltip and marks that press
handled, so the shell ignores it: on a session, the first Escape closes the
tooltip and the second leaves. Every other key reaches the shell as usual, and a
tooltip closes on the first of them whatever it is, so a pending g is
untouched.
Blocking a control with aria-disabled rather than disabled keeps it in the
tab order, which is the point; the Styleguide rule below says why. The session's
More trigger, the shell button and the Session mode toggle keep their tab stops
while their verbs are unavailable, and each guards its own handler rather
than relying on the browser.
The modifier is named after the reader's keyboard. $mod is Cmd on Apple
platforms and Ctrl elsewhere, read from navigator.platform as tinykeys does,
and formatKeys in src/lib/keybindings.ts prints the same side: the palette
badge reads ⌘K on macOS and Ctrl+K elsewhere. Terminal zoom belongs to
xterm, not the table, and accepts Ctrl and Meta alike. Terminal copy, paste and
find are Ctrl on every platform, because that is what xterm binds; see
terminal.md.
Tab strips behave as tab lists. The session view switch is a Radix Tabs
(TabsList look="segmented") whose panels are the session's views, so Radix wires
aria-controls and the tabpanels. The terminal strip in the session toolbar
(TerminalTabs in routes/run/shells.tsx, named "Terminals") and the
Environment dock (components/dock.tsx) carry role="tablist",
aria-selected, a single tab stop that follows focus, and Left/Right/Home/End
through onTabListKeyDown in src/lib/keys.ts. The terminal strip's Agent
tab controls the agent pane and each shell tab the shell pane, both
tabpanels while a shell is open; with only the agent there is one terminal
and no tab list. A removable dock tab and a shell tab advertise unmodified
Delete and Backspace through aria-keyshortcuts.
Those keys move focus and nothing else. Selection does not follow focus here, which the ARIA tab list pattern reserves for panels that are cheap to swap: behind these tabs are websocket attaches, a patch fetch and xterm hosts, so arrowing must not open the tab it lands on. Enter or Space opens the focused tab, and a click opens the tab it landed on. Delete or Backspace closes the focused removable dock tab. A close repairs focus to the next surviving tab, the previous one when closing the last tab, or Add terminal tab when the dock becomes empty. On a shell tab the same keys open its close choices, or close a shell that has ended.
Resize handles are window splitters. The sidebar's, the assistant's and the
docks' separator handles take Tab, name the pane they size with aria-controls,
report aria-valuenow against their available bounds, move 16px per arrow
press, snap to those bounds on Home and End, and collapse the pane on Enter,
handing focus to the control that restores it. Pointer dragging stays within
the available space and follows the same bounds. Both handles set
touch-action: none, without which the browser claims the drag as a pan and
cancels the pointer stream the drag listens to. The sidebar's is a drag a
finger makes: it grows to a 24px hit area centred on its edge under
coarse:, without changing what it paints, and carries a z-index so the
half of it that overhangs the pane beside it is not covered by that pane.
The docks' is not - dragging a horizontal edge to size a terminal on a phone
is not something a finger does well - so that handle is not drawn on a
coarse pointer at all and the dock offers collapsed, half and full instead
(see Environment).
Styleguide
- Tokens only. See styles.md for the palette, interaction
tokens,
--state-*tokens, geometry, radii, fonts and the one inline-colour exception for member attributes. Components use semantic token classes rather than route-specific colour literals. - Dark, light, system. Settings > General and explicit palette commands
set the stored preference;
systemfollowsprefers-color-schemelive. There is no additional theme mode or cycling status icon. - Typography and density. DM Sans at 13px with 12px supporting copy, on the type scale in styles.md. JetBrainsMono NFM is the terminal's alone; code uses the system monospace stack. Use the 28px control and row, 24px small control, 44px view header and 56px session header, and avoid promotional titles or oversized cards.
- Flat shell and palette host. One 220-400px sidebar beside the content
view; under 768px a 48px top bar and the sidebar as a side sheet. Mount the
command palette, the shortcuts dialog and the updates dialog once in
AppShell. - Agent and state are separate. The agent glyph says who is running;
the state mark says what state.
StatusDot(src/components/ui/status-dot.tsx) is the only session-state mark: one shape and colour per state (filled circle Working, clock Waiting for, dashed ring Waiting, amber ring Needs you, filled accent check Finished: review, check Completed, ring with a bar Closed, cross Failed, ring with an exclamation mark Interrupted, broken ring Disconnected, bars Paused), named by the state word where it stands alone.StateLinepairs it with the reason. The states are described under Session state. - Lists stay still. Sidebar rows, board cards, the palette and All
workspaces draw a static dot. Only the session header's dot and the Session
view's live row or live steps header pulse while Working (
state-pulse, a breathe in opacity and size). - Motion is optional. Every animation and transition stops under
prefers-reduced-motion: reduce: the state pulse, the Session live shimmer, row and answer-block entrances, overlay and sheet entrances, tab indicators, disclosures, spinners and skeletons. The controlling terminal's 1px teal outline is always static. There is no startup scene or reveal-flash animation. - Primitives first.
src/components/ui/holds the house primitives on Radix:Button(primary,secondary,ghost,danger,linkand the mutedquietlink),Input,Textarea,Label,FormField,Select,Checkbox,Radio,Collapsible,Dialog,AlertDialog,Menu,Popover,Tooltip,Tabs,Command,Card,Callout,Badge,CountBadge,ProgressBar,TextSwap,IconSwap,SlidingIndicator,ListRow,PageBody,InsetList,StatTile,IconTile,PaneHeader,EmptyState,RequestCardwith itsrequest-sectionandrequest-choiceparts,StatusDot,Skeleton,CopyButtonand the Sessiontimeline,stepsandsession-blocksrows. They are tuned to the shared scale andfocusRing, and preserve props, events, refs and accessibility contracts. Use them instead of raw form elements. Fields and buttons are 28px, small buttons 24px, all 44px on a coarse pointer; adjoining panes and rows are square, and controls use the 8px--radius-control.Input,TextareaandSelectTriggercompose the sharedfieldstyle with contrast-tuned--control-borderborders, readable placeholders and explicit disabled/read-only states. SharedLabelcaptions are block-level; stacked caption-to-field gaps must measure 4px, including wrapped inputs, rather than relying on inline margins. - The empty string belongs to the Select placeholder. Use a named, non-empty sentinel for an empty API or filter value, then map it back at that boundary. The Select wrapper ignores the empty report Radix can send through its hidden native select while options arrive.
- Name the Select trigger. Pair the caption's
htmlForwith the trigger'sid, so the control announces its purpose rather than only its current option. - Disclosures normally unmount closed content.
CollapsibleTriggersupplies the marker, which turns over 200ms; the body glides its height open and shut and unmounts once the closing glide ends. - Status and metadata pills are
Badge. It takes a session-statetoneor stays neutral. ABadgetakes notitleof its own, so a pill whose text can be clipped wears one on the span around it. Session and dock tab strips retain their custom manual tab semantics. - A hint a reader needs is a
Tooltip, not atitle. Atitleis drawn by the pointer and by nothing else, so on a control a keyboard can land on it is information that reader can never get at. A Tooltip opens on focus and hover, with a 250ms hover delay that a tooltip closed in the last 300ms skips, and points the control'saria-describedbyat itself. It is a description rather than the name: an icon-onlyButtontakeslabel, which sets both. Atitlestays only on what a keyboard cannot land on - a truncated path, a timestamp, a breakdown - since a tooltip needs a focusable trigger, and a hint on a mark would buy a tab stop per feed row or per card. A mark that names itself needsrole="img"first: a bare<span>isgeneric, and ARIA givesgenericno name. - A yes-or-no confirm is an
AlertDialog, not aDialog. The role interrupts rather than announcing a form, it takes the close X away, and an outside click no longer dismisses it. A dialog that asks which of several outcomes to record - closing a session as merged or abandoned - is a choice rather than a confirm, and stays aDialog.AlertDialogActionis destructive unless the caller says otherwise. A confirm that reports its own failure prevents the default on that click and closes on the answer instead, or the refusal would be unmounted with the dialog. - A control a reader still needs is
aria-disabled, notdisabled. Adisabledbutton takes neither focus nor a pointer, so anything it had to say - the full verb behind a shortened label, why a row cannot be opened - goes with it. Those keep their place in the tab order, guard their own handler, and drop the hover the enabled state paints. - One focus indicator, one source:
focusRing; see Keyboard and focus. - Member colour attributes, it does not fill. The avatar rings itself in the member's colour and keeps its initials in the foreground token, because the colour is arbitrary server data with no contrast guarantee in either theme.
- Loading feedback matches duration. Skeletons appear only after ~200ms
(
useDelayed), so a fast response never flashes. A skeleton has the shape of what it stands for (rows, tiles, a diff's header and lines), is capped at about ten rows however long the real list is, and its words stay in arole="status"for assistive technology. A failure is aFailureCalloutwith Retry, and an empty page is anEmptyState: an icon, a title without a period, one line and at most one action. - Pages share one anatomy. A scrolling page is a
PageBody(a centred column, 32px between sections, a short fade in), its lists areInsetLists ofInsetListItems (withonOpenthe whole row is one button), its figures areStatTiles (text-stat, 24px) and a glyph that leads a row sits in anIconTile.
Tests
The dashboard tests use Vitest, jsdom and Testing Library for observable client behavior, with fixtures and stub API/WebSocket transports where a server is not required. Store slices, selectors, token bootstrap, stream lifecycle, terminal attach/reconnect behavior, permissions and error paths remain covered as state transitions. Component tests should assert labels, accessible names, focus handoff, keyboard actions, navigation, loading and empty states, server errors, capability gates and mutation results.
Session component fixtures unmount before restoring timers or browser globals. Await the stream-disposal batch, then reset the root store to cancel its held notification frame and fallback timer.
Session actions cover the retained-run contract: Close chooses merged or abandoned,
while Reopen run appears only for eligible retained Standard sessions. Free
sandbox is also offered for finished retained subsessions; its
confirmation and error path do not hide or delete history. Expired or
unavailable sessions offer no Free sandbox. Sidebar tests cover group
disclosure: every group starts expanded and closes when its header is pressed.
They also cover an unopened finish: the row and a nested subsession keep the text
colour and say so in their names until finish_unopened clears. They also
cover a session row's age, owner mark, people stack and details box.
src/lib/needs-you.test.ts has one case per Needs you condition, and the
device cards an admin and a member see.
src/routes/board/lanes/model.test.ts covers lane segments from status
history, section order and folding, axis ticks and link
bundling; the board test's lanes view cases cover the tree keyboard, the
session popover and its links, a popover whose lane folds away, an empty
window, bundled mail bodies and failed history reads. e2e/lanes.spec.ts
moves a real pointer over Lanes, with sessions and mail answered in the
browser: from a lane to its popover and off it, one click from one lane's
popover to another's, a drag and a pinned button closing it, and from a lane
to its pinned button, on a held clock. Its live cases send run.status
through the events socket: a session leaving above the view, one arriving
above an open popover, and the focused lane folding into Finished.
src/a11y.test.tsx exercises the session tab strip, dock tabs and sidebar
splitter with keyboard events: arrow navigation, Enter and Space activation,
Delete and Backspace close, focus handoff, clamped resizing and collapse.
src/store/trace.test.ts covers span derivation (open, stopped and
background calls, subagents with and without a held launch, waits, turn
names and stop reasons, the status lane), stats, folding, bar segments, idle
breaks and a 5,000-span derive and flatten budget;
src/routes/run/trace-view.test.tsx covers the Trace tree's keyboard,
details, zoom and Escape order, the Errors stat, metered-only and capped
cost, a history read retried after a partial failure, history notices, virtualization and which
failures are announced.
src/components/shell/nav-shortcuts.test.tsx covers the shell shortcut
precedence across fields, dialogs, menus, lists and selects, and the
Single-key shortcuts setting; src/lib/keybindings.test.ts fails on two
bindings sharing keys in overlapping scopes.
src/components/ui/controls.test.tsx and primitives.test.tsx check the
primitives: button and field sizes per pointer, tooltips and names,
aria-disabled tab stops, form-field labels and Select behavior. These are
behavior assertions against rendered controls; source scans, literal class
assertions and CSS text checks are not behavior coverage.
Route and shared-header tests cover the board, global overview, terminal, Browser, diff, files, workspace, onboarding, team, members, settings, agents, templates, palette and update surfaces. Keep assertions on what a member can observe: a route or control appears or disappears under its capability and role, a focus or navigation action lands in the expected view, a loading or error message is shown, or the API receives the mutation only after the relevant confirmation. Preserve verbatim gateway errors in assertions when they are part of the contract.
web/e2e/ is the layout and browser-behavior layer. Playwright drives a real
browser against the local aether gui gateway and the server it proxies,
while the same static bundle is also usable through the server-hosted
gateway. keyboard-focus checks Escape ordering across an open dialog, the
footer menu and a session view, confirms that a focused control paints the app
outline, and drags the sidebar resizer. window-sizing exercises the updates
dialog at the smallest desktop window and below it. run-deep-link checks
that the address follows navigation, survives a reload and agrees with back
and Escape. run-session streams an Enhanced session, answers a permission,
sends a message and stops it with Interrupt, then checks its Trace tab.
The touch shell is driven by the mobile project, which
testing.md describes: phone-shell.mobile.spec.ts checks the
tab bar at 360px and 430px with no sideways scroll, Needs you as the landing
page and its badge, and approves a permission and replies to a question from
their cards; shell-drawer.mobile.spec.ts taps a session in the Sessions tab
and finds it on screen with focus on its heading;
dialog-anchor.mobile.spec.ts checks that a short dialog sits at the top
rather than the middle, and that the launch form keeps its footer on screen on
a viewport as short as a keyboard leaves; toast-clearance.mobile.spec.ts
checks that a toast comes to rest 8px clear of the bottom edge;
home-screen.mobile.spec.ts checks the manifest, icons, favicons and that the top bar
clears a phone status bar and the tab bar shows; run-views.mobile.spec.ts
protects a session from More and reads its changes; and
files-browser.mobile.spec.ts opens a second file from the tree sheet.
sidebar-drawer.spec.ts stays on the desktop project because its keyboard
contract - Mod+B closing the drawer and the palette coming back once it is
gone - needs a narrow window with a keyboard rather than a phone.
sign-ins-merge.spec.ts gets a merge code as one member and previews it as
another at phone width; both harness members have an SSH key, so it checks the
server's refusal verbatim, and src/routes/members/sign-ins.test.tsx covers
choosing, proposing and accepting. board-card, run-switch,
run-attach-retry, run-provisioning, terminal-tools and the onboarding
scenarios cover the corresponding real UI transitions, gateway responses and
terminal behavior. Run the full browser workflow with make test-e2e; its
scenario inventory and setup details live in testing.md.
run-room.spec.ts and run-room.mobile.spec.ts cover shared notes,
moderated messages, explicit control transfer, the phone Details sheet and
Captures on a phone; run-evidence.spec.ts and run-evidence.mobile.spec.ts
cover retained captures. src/routes/run/frame.test.tsx covers the view
switch, header actions, Details sections and composer gating;
shells.test.tsx covers the shell tabs, closing, the limit and shell
control; terminal.test.tsx covers the agent
attach, presence and occupied-lease fencing; src/store/sessions.test.ts
covers the Session rows; src/store/session-rows.test.ts,
acp-sessions.test.ts, src/lib/acp-stream.test.ts,
src/routes/run/composer-state.test.ts and session.test.tsx cover the
Enhanced rows and their blocks of steps, store, stream client, composer and
requests, and
src/store/session-perf.test.tsx (RUN_PERF=1) streams 5,000 items and
opens 2,000. src/routes/browser/index.test.tsx covers the first page,
silent acquisition, takeover, release on blur and on focus elsewhere, the
address field and its queue, shortcuts, fit-to-pane and presets, the page
strip, close/reset identity fencing and raw refusals; surface.test.tsx
covers input queued across acquiring a lease, watching, wheel input, stream
reconnection and its failure; address.test.ts covers the
scheme rules; ports.test.tsx covers the port list in the empty pane, the
toolbar and the address field, its polling, and opening a port on this
computer or showing the command for it; and src/routes/run/frame.test.tsx
covers when Browser and Files are offered, the docked layout and run-local
terminal links.
src/routes/files/home.test.tsx covers the Home tree: each row's menu,
naming in place, delete, upload from the picker and from a drop, and moving
a dragged row.
src/routes/files/run-files.test.tsx covers the session's Files view, a drop
uploaded into its checkout, and path
links in the Chat view, paths.test.ts what reads as a path, and
src/routes/run/terminal-links.test.tsx a path link in a terminal.
src/routes/settings/settings.test.tsx covers Appearance without local RPCs.
src/routes/settings/notifications.test.tsx covers every state of the
Notifications row, src/lib/push.test.ts the browser side behind it
(permission before anything else, the server key, the activity report), and
src/sw.test.ts runs public/sw.js against a stand-in for the worker scope.
src/routes/settings/watches.test.tsx covers the Watches list, detail,
delivery lines, pause, resume and delete, the Watch form, the watch
notification preferences, the phone sheet and watch.changed toasts.
src/components/workspace-environment.test.tsx covers the workspace
Environment section: the change a save sends, replacing a secret, the .env
preview, rows that cannot be saved, egress control, the server's refusal and
the read-only view.
Use the browser workflow for real computed geometry, top bar and sidebar behavior, responsive overflow, keyboard focus and gateway-backed transitions. Exercise both themes and narrow and desktop widths against the actual surface; do not pin CSS classes, source strings, token declarations or component plumbing. When changing a visible contract, update the assertion at the layer that can observe it. Use a component test for state, text, role, focus and navigation behavior, and Playwright for computed layout, actual browser focus outlines, responsive overflow, Escape ordering and gateway-backed flows.
Testing on a real phone
The browser suite exercises the local gateway path; the server-hosted gateway and a real touch device are checked by hand. Give the server a dashboard port and restart it:
sudo aether-server config set web-port 443
sudo systemctl restart aether-serverThen open https://<the server's MagicDNS name>/ on a phone joined to the
same tailnet. Expect hosted onboarding for a member who has not completed
setup, even when other members have created workspaces; completed members
start on the board. WhoIs already identifies the member. The machine-local
Link step, update notice, pull, forward and sync controls are absent
because the descriptor carries no local verbs. Repository linking instead
shows a local-client/CLI handoff. Settings remains available for General.
Files and configuration editing also remain available through the
server-hosted gateway.
The installed app is a manual check too, because no browser lets a test
emulate the display-mode: standalone a real install gives. On Android,
Chrome's ⋮ menu should offer Install app; on iPhone, Safari's Share >
Add to Home Screen. The icon that lands on the home screen should be the
Cloudfield mark on a navy tile, and opening it should give a full-screen dashboard
with the shell's own top bar, safe-area padding intact under
the notch, and the soft keyboard still shortening the layout rather than
covering it. Watch what the server saw with:
journalctl -u aether-server -fPrerequisites and the refusals a bad tailnet setup produces are in networking.md.
The Android app is the same page in a WebView, served by the server in Tailscale mode and by a local gateway in Edge mode, so the same expectations hold there. It is worth checking separately for two things the browser does not exercise: whether the top bar and the content clear the system bars, which depends on the WebView forwarding safe-area insets, and whether the soft keyboard shortens the layout rather than covering it.
make android-debug
adb install -r dist/aether-android-debug.apkA debug APK allows chrome://inspect from a computer on the same USB
connection, which is how to read the page's console and its computed
env(safe-area-inset-*) values on the device. A release APK does not. The
shell falls back to padding for the system bars itself on a WebView older
than Chromium 140, so check chrome://version on the phone before
concluding the page is wrong.