Skip to the content
docs

Dashboard SPA (web/)

Cloudfield was named Aether until November 2026. The commands, paths and hostnames in this guide still use that name. View this guide on GitHub.

Browse guides / Dashboard SPA

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.

CODE
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 --noEmit

bun 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:

CODE
# 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:

CODE
# 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.
  • --hostname has 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 needs allowedDevOrigins in web/next.config.ts.
  • The token is minted per aether gui process, and the phone needs that one. Nothing else authenticates the local development proxy.
  • A tunnel or proxy in front of this must preserve Host and Origin. One that rewrites Host breaks 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/.gitkeep is committed so a clean checkout compiles the Go server before anyone has run the web build.
  • web/public/.gitkeep is copied into dist by 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.

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:

  1. 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 (the overview route), Manage workspaces and Workspace settings (the workspace page). With one workspace and no workspace.list method it is a plain label. The search button opens the command palette.
  2. 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 with children: "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 sends children only 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 with child.settings choice, 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).
  3. Sessions (sidebar-runs.tsx), a region with three groups, Needs you, Working and Finished (see Session state), each an h2 holding an aria-expanded disclosure button, a chevron that turns a quarter and the count in a CountBadge; 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 ⌘B stay the reader's call.
  4. 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 from src/lib/surfaces.ts, which also feeds the palette's Navigate group; its palette entry (Members › Devices) is reached from the palette only, and its link entries (the board's Needs you; Onboarding, opened from Settings › General › Setup guide) only from a link.
  5. One update notice row when a server, CLI or desktop update exists, for example "Server 0.5.3 is available · Update"; see Update prompts.
  6. 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_once and reject_once options shows Deny and a second half. A sudo request's title is the whole command, so the second half is Approve (the session's own DecisionButtons). An agent's tool call can be a file edit or a plan that attention.list does not carry, so its second half is Review, which opens the session where the change is shown and approved. Deny and Approve send run.input.respond with 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 or Mod+Enter sends run.inject. The field scrolls into view above the keyboard, and the list pads by --keyboard-inset for iOS, whose keyboard leaves the layout tall. A room question replies with run.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 aside named "Assistant", 400px by default and resizable from 320px to 640px by a separator on 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 and minReadableWidth (560px, lib/breakpoints.ts) of main.
  • Desktop, floating: below 320px of that room, the same aside floats over the right edge of main, raised by a shadow. Its width is the saved width, capped so at least 240px of main (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. Esc inside 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 does Mod+Shift+Space from anywhere. Crossing between docked and floating restyles the one aside rather than remounting it, so the draft, the focused composer and the transcript's scroll survive.
  • Phone: a full-screen dialog named "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's h1. 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, then assistant.reset) and Close assistant. While auto_approve is on, a line under it says the assistant acts without asking, with Change in Settings.
  • Body: by assistant.status state. setup lists each agent with its reason, and Sign in opens AssistantSignIn in place: a terminal on /ws/terminal?assistant_login=<agent>; failed shows the server's error above the transcript with Retry (assistant.start). Otherwise the transcript (role="log"), which reuses the session Session's TimelineRow and useFlatRows, with the Session's open blocks, and the constant row context id assistant, and the composer (Enter sends, Shift+Enter inserts a newline, Mod+Enter also sends; Stop replaces Send while a turn runs and reads Stopping… while assistant.cancel is in flight, so a double click cancels once and an agent that ignores it can be stopped again; the call aborts after 10 seconds with assistant.cancel got no answer within 10 seconds). An empty conversation leads with AssistantAccountCheck (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 through askAssistant, so it reaches the agent with page sharing off. Harness permission and question prompts render as the Chat view's request cards, answered with assistant.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 for run.launch a 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 (default when unset), account (Yours or <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 a confirmations frame 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 with rule adds, under Or save a rule:, a secondary button labeled with rule.wording (assistant.confirm with always: true), marked with an accent left rule and You approved this kind three times in a row. when rule.suggested, and, while auto_approve is off, Approve everything from now on: it approves the card, then sets the store's assistantConfirmAutoApprove, which opens the panel's Let the assistant act without asking? confirm (AutoApproveConfirm in components/assistant/approval-choice.tsx). While auto_approve is off a card without rule links Skip these cards… to Settings > Assistant; a card with other_member says 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): assistantView takes each Cloudfield tool call out of its step block as a card: one whose tool_name ends in an aether_* tool (Claude Code's mcp__aether__aether_launch_session, or the bare name), or a Codex call titled mcp.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 by runLabel; a tool with several actions, such as aether_session_lifecycle, takes its verb and the method its card waits on from its action input), 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 first for a call still open when its turn ended, approved or not, or Not confirmed: check status before retrying for an aether_pr_create whose result says write: "pending") with approved by you, auto-approved or approved by your rule <id> (a record with approval: "rule" and its rule_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 by access own, shared or other, fell back from its requested_account, no fallback for policy off or the ordered accounts) 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's link or url: a dashboard link (?run=<id>, a watch's settings link) opens in the app whatever its host, and any other http(s) address, such as a pull request, opens in a new tab. Without one it comes from the created ids, then from run_id or workspace_id in 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's AssistantAction) decides the state. Records with the same action.id replace earlier ones. Records carry no tool call id, so a record goes to the card already holding its action.id, or else to an unclaimed call of the same method whose input names no run_id or workspace_id other 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's Approved: note names its session only in the summary: it goes to the one unclaimed call of its method, or to the one whose run_id the summary names, and otherwise stays a row. Without a record, the state comes from the tool call's status, a declined, did not answer within or ended before the member answered error, a pending confirmation of the call's method, and the Approved: or Auto-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 (ApprovalChoice in components/assistant/approval-choice.tsx): when the status has approval_chosen: false and the state is not failed (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 call assistant.settings with auto_approve false 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 has suggest_auto_approve, the state is idle, 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 call assistant.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 with suggestion_off says 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 with env(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 a black-translucent status bar and gets the whole screen: it is --safe-top in src/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 to sonner twice, as offset and as mobileOffset, because sonner swaps 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 every dvh in the app - dialogs, the palette, selects, menus - is already sized against, so they all shorten when the keyboard opens. Nothing in the shell uses vh.
  • themeColor is the dark value, the default theme, so browser chrome matches the page before the SPA mounts; ThemeEffect then 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): every set() applies at once, so getState() 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 seq on 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.branch and run.pr bump a per-session gitSeq and prSeq (src/store/workflow-signals.ts). A view that shows that state keys its run.git.log or run.pr.feedback re-read when the counter changes (a store subscription on gitSeq[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. While unreachable is set the footer says Unreachable rather than Live, 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 carries data.edge_path, its layer, server_id and edge are used as given, and its online list, 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, ConnectionError takes the window instead of an empty sidebar and an empty board behind a toast. Which hop failed picks the copy: network says this machine has no network at all and names wifi and a VPN, server says the server did not answer through the selected transport, gateway says the local aether gui process stopped answering, tailnet says 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 is gateway only on the desktop origin, where that process can be restarted; on the server gateway it is tailnet, 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 as data.refusal on the gateway's 503, and refusalHop in src/store/sync.ts maps its kind to a class, never its wording: edge-server (the edge holds no live registration for the server id; aether-server edge status on 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 the aether login --edge command), not-member, device-revoked, device-pending, and server-refused for the server's other refusals. The device-pending page says an admin approves the device from Needs you, or the member from an approved device, and shows sudo aether-server device approve <code> only when the refusal carries approval_code. A failure without a refusal on a link through an edge is edge when the error names the edge's host: the edge did not answer, so it refused nothing. src/store/edge-sync.test.ts pins 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. connect reads GET /api/v1/capabilities before it opens the stream, and a 401 there means the local gateway refused its token. The store records that refusal verbatim, stops retrying and tells the member to open a fresh URL from aether gui. The token is minted per process and held in the tab's session storage, so a bookmarked URL, a second tab or a restarted aether gui needs 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 own 403 or 503 refusal.
  • 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 to localStorage (aether.snapshot.v1:<origin>; contents and deletion in privacy.md). connect calls paintSnapshot first, on a cold start only (a reconnect to another server never repaints the last one): it fills the store, sets hydrated and staleSince (the save time), and seeds identityKey so hydration treats a different member or server as an identity change and drops the cache. hydrate still counts a painted store as a first load (workspace selection, onboarding redirect) and clears staleSince when it succeeds. While staleSince is set, or a refresh failed, StaleBanner shows 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 the online wake 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, every RequestAction (Approve, Deny, Reply, permission choices) is disabled, and RequestActions writes Reconnect to act beside the row: a disabled button shows no tooltip on touch. runCommands and handoffCommands get stale too 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 from pausedRuns and its confirmed change time as status_changed_at; an estimated time is left out and estimated again on paint. Any access refusal (a 401 or 403, or a refused, signed-out, not-member, device-revoked or device-pending hop, from a load, the stream or the connect probe) calls refuseSnapshot: 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. connectEvents runs 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 like online. pageshow (back/forward cache) counts as a foreground return, and a navigator.connection change of type counts as online after 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 no type never reconnects on a connection change.
  • The sockets reopen on a foreground or network return. Both connectEvents and connectAttach subscribe to visibilitychange (visible) and online through onWake in src/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. online did, 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, online first 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 from lastSeq and 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 a session ended close, 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.status event 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. A run.deleted event removes the session from every connected dashboard; a run.status event that raced a local deletion treats a 404 re-fetch as resolved instead of forcing a redundant hydration. An event naming an unknown workspace re-fetches workspace.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-fetches member.list for the same reason: no member.* event exists, so a teammate who joined after hydration would otherwise render as a raw ID forever. A workspace.timeline entry of kind handoff re-reads its session the same way, because a handoff publishes no run.status event to carry the new owner. run.title, run.model, run.effort, run.protected and run.archived follow the same fetch-first rule on a session the client has never seen; run.controller skips an unknown session, whose snapshot carries the holder. run.account likewise skips an unknown session, and on a known one replaces account_member_id and requested_account_member_id with the payload's, so the header names the new account at once. run.children re-reads its session, which carries the session's own subsession setting, child_refused and detached. run.retention also fetches an unknown session, then replaces only its runtime deadline and cleanup metadata. It does not re-fetch known sessions or change finished_at, stateChangedAt, the business status, outcome_unseen or finish_unopened. A server.update event lands in the server slice, which feeds the update prompts.
  • run.agent events set a session's toolActivity ({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") or Failed; a subagent reads "Delegating". An Enhanced session's event carries verb, which the line shows as is. Calls in flight are kept by tool_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, so toolActivity is 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, inline Callout).
  • 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:

  1. the head: the agent's coloured AgentGlyph and the title (runLabel), two lines at most;
  2. 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;
  3. 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.list display_name, else the session's harness value), owner avatar, +added −deleted from the newest run.diff snapshot (N files when that snapshot is truncated, because its counts are only a floor), the card:meta slot (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:

  1. no workspace: Add your repository (onboarding, Repository step);
  2. files.tree answers CodeUnavailable (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;
  3. agent.list reports nothing installed: Set up an agent (Agents);
  4. Mine hides every session in scope: Show everyone's sessions;
  5. 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, and Home / 0 fit 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.tsx over the local forward.* verbs. It forwards the port typed to the same port on this machine and lists the ports forwarded from that session, each a link to http://localhost:<port> beside Stop. For a session it reads dev.port.list first: 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 the run.archive capability; neither confirms, since archiving is reversible. The palette resolves its focused session from the session map by route.params.runId rather 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 reopen on the command line). It is offered in More and as the primary button in the composer slot of a finished session, which calls run.relaunch and swaps the finished record for the live one the server returns. A session is eligible while the server reports container_retained_until (or, before that arrives, a retained-container reason). Relaunch clears the deadline, the status event drops finished_at and started_at restarts, 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.

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:

  1. 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.
  2. Show details / Hide details (Mod+.).
  3. More (components/run-actions.tsx, an icon button on a phone): every session verb from lib/commands.ts except 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 offers run.children.allow, the owner of a live session also gets Allow subsessions (run.children.allow on), 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 follow in the attach header. useXterm's follow option suppresses local measurements and resize reports, while setGeometry() applies the server's grid just as on desktop. The header carries standardGeometry (80x24) only for a session being created, such as a new shell tab. On phones the live terminal host exposes both axes. useTerminalPan reveals 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 disableStdin holds 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 reuses backoff() from src/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 requests screen:true and interactive:true; shells and CLI attachments keep their existing stream modes. screen:true bootstraps the compact current screen and bounded scrollback. Upward scrolling fetches older normalized output through terminal.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: -32001 downgrades 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 replay count 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-incarnation resume/cursor/resume_id supplies only the bounded gap and keeps the warm screen. If the cursor or ring cannot serve it, resumed:false selects a compact snapshot fallback. connectAttach parses 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} (omit takeover unless explicitly displacing a controller). The ordered response has type:"control", the same request_id, ok, optional code/error, and authoritative has_control, control_session_id, and control_generation. An unsolicited lease or steer-permission revocation has no request_id; it carries ok: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 current control_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. -32004 means the session has no PTY, and internal/sshd/attach.go refuses 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. A queued or provisioning session is not attached to at all: the tab clears the pane and covers it with TerminalSpinner, 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 on run.status, so the session turning running attaches on its own. On a session that is up, a -32004 is retried a bounded number of times on the usual backoff() before it counts as final, because the server names that case transient - recovery starts a session under a row that already reads running - 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. endedStatuses is that set, and it mirrors replayableStatus in internal/sshd/attach.go, which is domain.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 its run.reason carries 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.handoff granted 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, reason membership 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.tsx chains zoom, find, and clipboardKeys in that order; the first to claim a key stops it reaching the shell. clipboardKeys claims copy shortcuts but leaves native paste alive. Ctrl+Shift+F opens the find bar TerminalPane (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+- and Ctrl+0 move UiSlice.terminalFontSize, clamped to 8-32px by clampTerminalFontSize - on the way in from a keystroke and again in the store's merge, because a same-version reload never reaches migrate and xterm does not validate fontSize. 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-webgl 0.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 in src/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 at open and 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 −d totals, 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-top CSS variable the file headers stick to, and the virtual file list's startMargin is its measured offset in the scroller.
  • The git card sits above the strip. components/workflow/git-flow.tsx (GitFlow, model in store/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 #128 linking 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 with compact: 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; a truncated log 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.feedback is 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's mergeable and merge_state_status: CONFLICTING is "GitHub reports conflicts with main", naming the file count when the session's log measured the same merge; BEHIND is "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 calls run.pr.merge with the pull request's repository, number, expected_head (the head on screen), expected_base and expected_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, shows gh'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's steer_others allow), 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.branch event for the session (gitSeq in store/workflow-signals.ts), and with each 60s pull request poll, since a fetch moves the base without a git.branch event. The pull request is read again on run.pr and git.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.diff carries per-file stats and no patch text, so a snapshot bumps the session's revision and the view re-fetches the chosen comparison from GET /api/v1/run/<id>/patch (docs/local-gateway.md) whenever that has moved past the fetched revision 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 an EmptyState with 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 each diff --git boundary 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's lines are 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 recorded run.diff snapshot 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 when head moved since the next older checkpoint, otherwise "Session had N files · +a −d", the session's totals then (the count alone for a truncated snapshot). 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 from workspace.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 with before_seq while the timeline says more. 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 with snapshot_error - is a disabled row whose description says why; a history_gap before a recorded tree does not disable it. A failed history read shows the server's error with Retry. A link with file or diff: '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 through virtua in 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, which parse.ts reads from the hunk headers.
  • The path opens the file. Clicking a file's path opens it in the session's Files view (openInFiles in routes/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' and file: <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. file is 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 or Mod+Enter pins it, Cancel closes it, and Esc closes 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 hold Shift with ↑/↓ and press Enter; 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 pass FilePatch no review, 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 (reviewMessage in review.ts): a numbered block per comment in file order then line order, each with path:line or path:start-end, the lines in a diff fence 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.
  • sendToAgent is the send path. src/lib/send-to-agent.ts takes a session, the text and, when the tab holds it, the control lease. It posts a room steer_request and returns the room message, whose state is 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 same receipt function.
  • 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 last run.pr.feedback answer, 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 their path: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, start for Since the session started, since:<tree> for a checkpoint. locate finds 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-add and diff-del tokens. 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 git commands that read the session branch in the linked repository and the output of the last pull (review-commands.tsx). It is gated on the pull local 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.status once the diff has a file, and opens publish-dialog.tsx, a bottom sheet on a phone. One line above both steps names what they act on and as whom, "aether/run-1 at 4f9c2a7d · 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 in publish-state.ts and 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 commit 4f9c2a7d to https://github.com/acme/app.git as branch aether/run-1. Never a force push." and "Opens a pull request into acme/app:main from ada/app:aether/run-1 as 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, else origin when the workspace has a checkout Origin; without one origin is 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.tsx registers an overlap count into card: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.overlaps at hydration, then run.overlap events), 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 as extra_workspace_ids on run.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 repo query parameter of ?run=<id>&view=changes (a workspace id, or all; 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> in review.ts), Publish, pull request and Merge (squash); every call carries repo. 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 a run.patch read 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_id of the primary plus repo (the server refuses another workspace_id), and open files are keyed by repo as 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, #number link, 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 in publish-pr.ts.
  • Names. The session header, sidebar rows and board cards read repo +N when 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:

CODE
dev.browser.status: scheduler: the session has no live environment: the session is provisioning

One 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:

CODE
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:

CODE
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:

CODE
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:

CODE
localops: listen on 127.0.0.1:8000: bind: address already in use

The 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:

CODE
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 operation

Screenshot 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:

CODE
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 500

A 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 through run.room.decide and a bar draining toward deliver_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 publishes run.wait.changed only when a result changes, not on every read, so a next check already past is left out rather than called overdue; the state line's wait is 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 every run.wait.changed event.
  • Subsessions, where the server offers run.children and 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 carries requested_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' question messages, human to human on the session, plus open comment messages 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's Avatar ringed 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) pages run.room.list back 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, until run.room.post or the workspace.room_message refetch 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.post can 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.list page 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. useTeamRefresh in src/routes/team/sync.ts reads 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, applyEvent updates the store from the events that change these reads:
    • workspace.budget carries the state, cap and spend, applied as they are. It fires on threshold crossings, refusals and admin edits, not on every spend change, so run.cost re-reads that workspace's budget.get to 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 leaves live.
    • workspace.presence names one transition, so it re-reads presence.roster.
    • run.typing is ephemeral: the server sends it to live subscribers only, with seq 0, so it is never stored, replayed, counted or added to the live feed. It sets the actor's entry in typing (src/store/typing.ts) and returns before the cursor check, so it cannot move lastSeq. stopped: true, or that member's workspace.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 in src/store/coalesce.ts: per workspace, one in flight and one queued, so a burst of results or attaches costs two requests. AppShell mounts 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 on onWake, 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 refreshTeam reads 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 - focusedWorkspace prefers the route's workspaceId, then the workspace of the session in view, then activeWorkspace - 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.timeline forward 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), applyEvent appends 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.pr and workspace.presence only 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.tsx words 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 through plainReason (src/lib/status.ts), and room ids, session ids and wire enums never appear outside Raw events. Its table is keyed by src/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.tsx reads the event, timeline and room vocabularies from the Go sources under internal/, 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 each run.controller take 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 CountBadge of 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 EmptyState with 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.message and coord.message.acked rows 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.retention has 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. virtua mounts only the rows near the viewport of the view's scroller (routes/activity/virtual-list.tsx); each row carries aria-setsize and aria-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.list rows, newest first, drawn by components/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 watching set, which the gateway fills from live PTY attaches - the browser's attaches included.
  • The full read and the heartbeat interval read GET /api/v1/disk and write it onto the stored server.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 from outcomes, 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_tokens as "100K tokens", with the harness at the head of cost.by_agent and its share, rounded down ("Claude Code used 56% of the 100K tokens") and how many sessions reported no tokens.
  • 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 from outcomes.members and 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.status is called for the session, so after each load the page calls run.pr.status {"run_id":"<session-id>"} one after another for up to ten listed sessions whose pull request is recorded open, then reads insights.get again 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.search applies as pinned: true, source: agent, kind: outcome, source: answer and replaced: 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 to memory.search 250 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 (no scope, so the note keeps its own, as aether 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 files trimmed and without blank lines), Only me (scope: member) and Pin. Mod+Enter anywhere 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.start and shows the code, a per-second expiry countdown and aether member merge <code>. Proposing and cancelling publish no event, so connect re-reads member.merge.pending every 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.preview and 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 carries role_with_keep_admin. Propose merge (danger style) stays disabled until a side is chosen and Discard the listed settings is ticked, then sends member.merge.propose with the plan's plan_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) and GitHubRepositoryDialog (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 use type="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 with auth:"github" and the list's numeric github_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_hosts entries. 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.

Workspace deletion confirmation

Deletion refused while a schedule remains

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 pasted NAME=VALUE lines or a chosen file, parsed by lib/dotenv.ts, the format aether workspace env import reads. 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.set holding 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's warning shows 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-size on 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 and section param connectors): one exported ConnectorsSection {client}, remounted when identityKey changes so a code never outlives its member. A ChatGPT / Claude segmented control picks numbered steps. connector.list gives the URL to show at once (url), the edge's universal_url, that URL at every address of the edge (universal_urls) and sign_in. A URL in universal_urls is treated as universal_url everywhere below. With sign_in the third step mints no code and Watch for the connection polls for 10 minutes, then says nothing connected; otherwise Get a code calls connector.code and shows its code with useCountdown. A url other than universal_url adds how to link a GitHub account. Without a url, server.edge only says whether the server has an edge or is connected to it. While a code or watch lives, connector.list is 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 one role="status" region and focuses its Done button. A failed poll shows its error until the next one succeeds. Rows list each connector's scopes, its resource as Universal URL or the server's own URL, added and last-used times, Move to the universal URL (where url is universal and the connector's is not: confirm, start watching for a connector at universal_url with the old one's client_id, preferring one with a last_used_at, and connector.revoke the old connector only once it has one; localStorage key aether:connector-move-claims records 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 the client_id host or, from an older server, the redirect_host, at the connector's own resource: a connector at the server's own URL reconnects there with a code even under sign_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 without connector.list (-32601) gets the update command and hides the steps, the no-edge and not-connected errors link docs/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 serves connector.list, navigate with {section: "connectors"}.
  • GitHub, in Connections for admins when the GitHub OAuth methods are available: a Connection row holding the same GitHubConnection used 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.get and notify.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, or No push (<push.status error>), so in-app only when 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 leaves push out 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 sets assistant.settings auto_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) lists assistant.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 shows Couldn’t read your rules with 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 an Inactive badge. It reads again when a card saves a rule (the store's ruleSaves) or another member signs in. Change in Settings in the assistant panel opens {section: "auto-approve"}; the Syncing badge opens mirror and the Insights quota link opens usage.
  • 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's AgentList without 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 of invalid choices with the server's reason, and the unknown ones 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 uses launch.defaults.set with 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 lists choices, 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 offers workspace.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 unauthenticated keeps 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 calls link.switch and 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 calls link.reset, clears localStorage and 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.info carries tailnet_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 own limits under 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 host plus the server's reason, Installing… this takes a minute or two, and Install failed with the reason, Show output (the install log in a CodeBlock) and Try again. Install calls server.sysbox.install, which returns at once; the row then polls server.sysbox.status every 2 seconds while the state is installing. Reaching On from an install announces New 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 reports off sees a neutral callout, Let agents use Docker in their sessions, with Install and Dismiss (src/components/sysbox-nudge.tsx). It stays through installing and failed, and shows unsupported (with the reason) only after an install the admin started from it; it never shows for a plain on or unsupported. Dismissal is persisted as sysboxNudgeDismissed. Non-admins and older servers see neither. An off reason is shown verbatim; the not-root reason, which contains sudo aether-server sysbox install, hides Install and offers that command with a copy button.
  • Remote access, when the server answers server.edge (the edge store slice, read at hydration): the Edge URL or Off, the copyable Server id, the Access policy in words with its raw value beside it (Approved devices only approved-devices), the Owner (<login> (github) or Unclaimed) and the Connection: Connected, Not connected, or Connected, but the edge has not recorded this server while the edge reports it unclaimed. For an admin of a server with no owner, a dashboard with the local verbs edge.status, edge.login and edge.claim shows Connect my GitHub account, followed by (<login>) when edge.status reports this machine signed in at the server's edge: it signs in there first if not, showing the sign-in code, calls server.edge.claimcode, passes the code to edge.claim unless it names another server than the one shown (The gateway now reaches another server; reload and try again.), and reads server.edge again. A token-revoked or not-signed-in refusal from the claim signs in again and repeats it once. Without those verbs it shows aether edge connect to 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 has watch.list: the member's watches from the watches store slice (src/store/watches.ts, read at hydration and on wake) in an InsetList. A row holds the label or target title, the target kind (followed by Kept by the assistant for a watch whose source is assistant, also shown in the detail's header), a StateLine (Watching, Paused, Cannot check, Done, Expired) with the conditions, the server's error verbatim for error, 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 from watch.target, since watch.link is the watch's own page. It reads watch.get and shows what the server sees (observed), the conditions, label and end date to change (watch.update with 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>, and In the assistant chat for 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 has watch.create), and Watch PR beside a session's pull request status open WatchDialog (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.changed reaches only the watch's owner. The dashboard re-reads watch.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 its assistant.notice instead, here and in the desktop app.
  • Desktop app: desktop/notify.js shows 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 with run.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 (UpdateCenter in src/components/update-banner.tsx, mounted by AppShell),
  • the required-update gate (src/components/update-gate.tsx, mounted by App),
  • 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 describe tail 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 once server.update_status names a channel. 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 runs server.release_channel_set with dry_run, and when the answer says wait (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's target_error verbatim. 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, from channel_pointers in server.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 to https://github.com/3xDevOps/cloudfield/actions/workflows/promote.yml. The link only opens that page; its Run button promotes.
  • Channel wait. While server.update_status reports channel_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.tsx is mounted by App, so it keeps running behind the gate. It reads update.check from the local gateway and server.update_status from the server at these times:

    • on mount;
    • on a timer of 30 minutes ±10%, so dashboards opened together do not check together;
    • on window focus and visibilitychange, at most once a minute.

    server.update_status is read again after every reconnect, and whenever server.info names 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 reach applied instead 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 running aether 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.check answers with cli_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:

    1. clears the dismissals;
    2. opens the dialog;
    3. reads update.check and server.update_status with refresh: 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:

    1. Server update in progress, terminals reconnect briefly;
    2. for admins, Server update to X failed or The server update was rolled back;
    3. Server X is available (members: Server X is available, ask an admin);
    4. Update to Cloudfield X failed or Cloudfield X is available;
    5. 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.update with when: "now". Update when idle sends when: "idle", and the row becomes Server X is scheduled. Scheduled by <member>, applies when no session is active., with a Cancel that sends when: "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_status falls back to update.check's server_behind.

      While the server is behind (its row says available, or update.check reports server_behind because 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. When update.check reports server_first, update.apply would refuse, so the client row drops Update now; a member is told to ask an admin to run aether server update.

    • 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.update events land on the server slice through applyEvent. 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, failed or rolled_back, a late applying, restarting or verifying frame 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 lists pending.

    server.update_status carries the same phase, error, from_version and to_version. A status still in flight seeds the progress after a reload. A status with a settled phase (applied, failed, rolled_back, idle) ends it, and so does, on an older server, a server_version at or past the version the phases were about. failed and rolled_back show 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 aether binary 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's install_method (docs/local-gateway.md):

    • direct: the button and nothing more.
    • admin-prompt (macOS with a GUI session and a cli_path in 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 update with a copy button.

    When update.check's top-level can_self_update is not true (a packaged or a development build), there is no button and no aether update. One line names target_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 the vMAJOR.MINOR.PATCH[-PRERELEASE] form.

    applyClientUpdate in src/store/updates.ts runs the click, shared with the gate:

    1. It re-reads update.check with refresh: true. A fresh answer that finds this machine current installs nothing and says Cloudfield vX is the newest release. Nothing was downloaded. A fresh cli_error is the click's error, except on a gated client whose target_version is set: the server's release was found anyway, so the install goes on.
    2. It calls update.apply. While a desktop-app rebuild runs, it polls update.status every 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_command for a co-located aether-server;
    • a rebuild still running, or its real error with aether gui build.

    A 403 answer 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 -32005 or HTTP 426 (onUpgradeRequired in src/lib/api.ts hears every one);
    • after the events stream's subscribe ack does ({"ok":false,"code":-32005});
    • when update.check reports client_update_required.

    App renders the gate ahead of ConnectionError, because a gated client is refused everything except server.info and server.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), App floats This server is older than this app, the versions and aether server update over 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.info on a hydration, or the live server half of a later update.check, which writes it back into info unless a hydration replaced info while 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-continued in localStorage), so a reload or a killed WebView does not bring it back until either version changes. It is only reachable where update.check is: 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_version the server accepts. Update now runs applyClientUpdate. While gated, update.apply installs the server's release, named by update.check's target_version, not the latest one. An empty target_version means 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, or sudo aether update for a manual install) is chosen by the dashboard; the command a -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 restart aether gui and 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.check that reached the server (server_version set, no server_error) and reports client_update_required: false ends 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-reloaded in sessionStorage), 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, through link.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.

  • Dismissal is per version and it persists. dismissedUpdates on the ui slice 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, keyed server:<tag> or cli:<tag>, in announced-updates.json under Electron's userData directory: 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 build last installed. The shell's package.json carries the complete CLI version beside its npm-valid version, and the install records the CLI's executable path in resources/aether-cli.json. desktop/main.js starts the recorded binary ahead of PATH (unless AETHER_BIN overrides it) and hands the build version to the renderer. desktop/preload.js exposes it as window.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. with aether 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 of update_available: the CLI is usually current after an update that left the shell old.

    The bridge also carries onCheckForUpdates (the menu item) and notifyUpdate. On Windows and Linux, controls.showMenu opens the title-bar menu. All three are optional, because a shell built by an older aether gui build lacks 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; system follows prefers-color-scheme live. 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. StateLine pairs 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, link and the muted quiet link), 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, RequestCard with its request-section and request-choice parts, StatusDot, Skeleton, CopyButton and the Session timeline, steps and session-blocks rows. They are tuned to the shared scale and focusRing, 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, Textarea and SelectTrigger compose the shared field style with contrast-tuned --control-border borders, readable placeholders and explicit disabled/read-only states. Shared Label captions 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 htmlFor with the trigger's id, so the control announces its purpose rather than only its current option.
  • Disclosures normally unmount closed content. CollapsibleTrigger supplies 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-state tone or stays neutral. A Badge takes no title of 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 a title. A title is 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's aria-describedby at itself. It is a description rather than the name: an icon-only Button takes label, which sets both. A title stays 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 needs role="img" first: a bare <span> is generic, and ARIA gives generic no name.
  • A yes-or-no confirm is an AlertDialog, not a Dialog. 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 a Dialog. AlertDialogAction is 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, not disabled. A disabled button 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 a role="status" for assistive technology. A failure is a FailureCallout with Retry, and an empty page is an EmptyState: 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 are InsetLists of InsetListItems (with onOpen the whole row is one button), its figures are StatTiles (text-stat, 24px) and a glyph that leads a row sits in an IconTile.

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:

CODE
sudo aether-server config set web-port 443
sudo systemctl restart aether-server

Then 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:

CODE
journalctl -u aether-server -f

Prerequisites 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.

CODE
make android-debug
adb install -r dist/aether-android-debug.apk

A 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.