[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10,"_11":12},"actionData","errors","root",{"_271":-5,"_274":275,"_276":277},"routes/shell",{"_41":42,"_270":-5,"_271":-5,"_272":273},"routes/repo",{"_34":-7,"_35":36,"_37":38,"_39":40,"_41":42,"_43":32,"_44":32,"_45":32,"_46":32,"_47":32,"_48":32,"_49":50,"_51":50,"_52":32,"_53":-7,"_54":-7,"_55":56,"_57":58,"_59":60,"_61":-5,"_62":63,"_64":65,"_66":67,"_68":69},"routes/repo.blob",{"_13":14,"_15":16,"_17":18,"_19":20,"_21":22,"_23":24,"_25":-5,"_26":27,"_28":29,"_29":30,"_31":32,"_33":14},"ref","main","path","docs/architecture.md","oid","532bd1161605b4a312879097cd56b2d252d76bd9","size",37825,"commit","ebddef689afe799c51f8829a3c3ed570bfa8eda9","mounts",[],"source","plain",{"_13":14,"_15":16},"kind","text","# Architecture\n\nAce is a collaborative coding environment that runs on the team's own machines. Old Ace ran one\nprocess per channel inside a cloud VM; most of its pain was the VM and cloud infrastructure, not\nthe per-channel process. Ace keeps the process and drops the infrastructure.\n\nWords in this document have the meanings in [terms](terms.md).\n\nAce is open source software that teams clone, fork, and operate on their own machines and in\ntheir own infrastructure or cloud accounts. Ace will not operate a hosted service. The tailnet\nis the sole authority for team membership and collaboration access; see [the team](#the-team).\n\n## Layout\n\n| Path | Runs | Owns |\n| -------------------- | ----------------------- | -------------------------------------------------------------------- |\n| `packages/channel` | inside a channel worker | The channel: chats, agents, lanes, and the client protocol types |\n| `apps/host` | on every machine (Bun) | The `ace` CLI, channel workers, the channel catalog, local transport |\n| `apps/desktop` | on macOS | The desktop client and packaging for Ace Helper |\n| `services/channel` | Cloudflare Workers | Hosted channels: one Durable Object per channel |\n| `services/directory` | Cloudflare Workers | The team's list of hosts and where each channel lives |\n\nClients (the CLI and desktop app) attach to channels; a channel is not a client.\n\nThe app's Issues and PRs pages read the selected project's GitHub repository through the host's\nGitHub CLI account. A peer can resolve the Git remote of a project already exposed by its channels;\nthe app's own host performs authenticated GitHub reads. The app caches GitHub responses in\nIndexedDB, scoped to its host connection. It refreshes in the background at startup and every\nthree hours, keeping cached content visible while requests run or fail. GitHub content stays\noutside channel history. Issues and PRs share the Channels sidebar and project picker, with\nOpen, Closed, and All filters in the sidebar. Items open on GitHub; a row's \"Open in a channel\"\naction creates a channel in the selected project and invokes its agent with the item's title and URL.\nThe shared project picker also offers All Projects, which opens Channels with collapsible sections\nnamed for each project and its ten most recently active, non-archived channels. Opening a channel\nkeeps that grouped view; channel creation and GitHub pages retain a concrete project selection.\n\nThe app identifies a project with a GitHub remote by its repository, compared case-insensitively,\nso checkouts of it on any host are one project; a folder without one is its host and main checkout.\nA project keeps every known checkout. A GitHub project shows its name wherever it is checked out;\na folder without one on another host is labeled with that host. Creating channels and archiving\ninactive ones use this host's checkout. A GitHub project checked out only on teammates' hosts lists\ntheir channels, and its channel creation entry points first offer to set it up on this machine:\nthe person confirms or edits a destination, `~/code/` by default, before anything is cloned.\nA creation that led to setup continues here with its initial text once the project is added;\nstandalone setup only adds the project. The dashboard draft belongs to the project, so it\nsurvives setup until a channel admits it. Channels never start on the other host. Its Channels sidebar shows the person's own channels, then one\nsection per teammate across all of their hosts, with that teammate's archived channels in a folded\nsection of their own. Saved host-and-checkout selections from earlier versions resolve to the\nmerged project. This is client navigation only; channel records and listings are unchanged.\n\nA channel's details sidebar shows the root chat's changes and branch, the newest pull request from\nthat branch with its checks, subagents and links from the transcript, and the channel's usage.\nThe pull request is read through the same GitHub CLI account while the sidebar is open, again when\nthe branch moves and every minute, and is not cached. A channel can work on many lanes and pull\nrequests over time; the sidebar follows the chat's current lane.\n\nAvatars come from GitHub logins. Each host resolves its owner's login with `gh api user`, returns\nit from `hello` to peers, and publishes it to the directory. The app maps message authors'\nTailscale logins to GitHub avatars and shows initials when no login is known.\n\n## Channel\n\nA channel owns one [pi-durable](https://github.com/earendil-works/pi) Session. A local channel runs\nas one worker process over one SQLite file; a hosted channel runs in a team-deployed cell. A chat\nis one pi conversation in that Session.\n\n- **Durable state is pi's.** Messages, runs, tool calls, and child chats are pi entries, tasks,\n and conversations. A crash resumes unfinished work from its last checkpoint; tools that are not\n safe to rerun report an interruption to the model instead.\n- **The model sees the whole room.** A human message that does not invoke an agent is a pi\n `write`: it enters the transcript without starting a run. Invoking an agent is a pi `input`.\n- **Providers are optional until invocation.** Creating a channel or chat, posting human messages,\n and using its workspace require no model or provider credentials. A chat without a model resolves\n its runtime's default on its first invocation: the local host's current preference, or an available\n model on the hosting service. Availability is checked before admitting the input, so a rejected\n invocation queues no work and leaves its draft editable.\n- **Model and effort per run.** The chat's model and reasoning effort are set when a run is\n admitted, stored in pi's agent configuration. Changing either while a run is active is rejected\n rather than changing its later turns. Admissions are serialized per chat. The composer lists\n levels from the channel's model catalog; Default leaves reasoning to always-thinking providers,\n while Off disables it where supported. Switching models resets the composer's effort to that\n model's default until a level is chosen.\n- **Queued messages are pi's inbox.** Clients opt into queue events on the chat watch. The channel\n projects the built-in conversation view's inbox into complete queue snapshots on attachment and\n committed changes, including passive human writes but excluding internal writes. The app shows\n these messages above the composer until pi consumes or withdraws them; reconnect reads pi again.\n There is no additional queue store or change to admission and steering behavior.\n- **Subagents are child chats.** A subagent's chat is owned by the parent's tool task, so killing\n the parent kills the child. Agents in different channels only exchange messages.\n- **Lanes are Git worktrees** created by the chat's agent for each unit of work. A chat's working\n directory is its current lane. A new lane starts from origin's advertised default branch, fetched\n first, or from an explicit base, without changing the project checkout. Each lane records that\n base as a ref or commit, and its Diff shows what a pull request into that base would. An explicit\n base for an existing lane changes only that comparison.\n- **Kill is durable.** Killing records pi's abort marks before the worker exits, so reopening the\n channel does not resume the killed work.\n- **Usage comes from pi's ledger.** A chat reports cumulative model and tool usage from\n `UsageDoc`, including compaction. The app shows input, output, cache tokens, and estimated USD\n at model catalog prices. Reopening the chat reads the same totals; Ace keeps no second ledger.\n- **Names and summaries are durable metadata.** The owner can rename a channel. The root chat's\n agent names a randomly named channel and keeps a short summary as work progresses, preserving\n deliberate names unless asked to rename. Metadata lives in a pi session document and is\n projected into host listings. Watch events update open clients; the details sidebar shows the\n full summary. Lane paths and branch prefixes keep the channel's original name.\n- **Busy is a live listing projection.** A channel is busy while any chat, including a child chat,\n has a run in pi's `LiveDoc`. Opening takes an initial snapshot before scheduling resumes;\n committed live-document changes maintain the aggregate and `onBusy` publishes only transitions.\n Streaming transcript watches are not needed for sidebar rows. Pi remains authoritative: the\n optional catalog and listing `busy` field is rebuildable, not a second run store or history format.\n\n`packages/channel` must stay runtime-neutral: no `node:*`, `bun:*`, or Workers imports. The host\ninjects storage, models, and the execution environment. This keeps hosted channels (a channel\ninside a Durable Object, with tools served from a team machine) an adapter rather than a rewrite.\n\nProcess per channel gives isolation and instant kill, and lets thousands of channels exist as\nfiles: a dormant channel is a closed SQLite file with no process. It is process isolation, not a\nsecurity boundary: every worker runs as the host's user and can read the others' files. Agents\nhave full access to that user's execution environment by design. Collaborator invocation is\ncontrolled separately from the channel-wide native desktop tools gate. Neither switch is a shell\nsecurity sandbox.\n\n## Host\n\n`apps/host` keeps channels under `$ACE_HOME/channels//` (default `~/.local/state/ace`). Each\ndirectory holds `channel.json`, `channel.sqlite`, and the channel's lanes. Clients start a\nchannel's worker on demand and talk to it over `channel.sock` with newline-delimited JSON. A worker\nretires when it has no clients and no live work.\n\nThe app owns its transcript watches. A gateway or peer host relaying a watch reports its end with a\nfailure frame after the accepted reply, whether it was released or its worker, hosted connection,\nor peer gateway closed; relays then drop it and never re-watch on their own. The app ignores the\nend of a watch it released, restarts others with a fresh replay and channel info, which wakes a\nkilled channel's worker as reopening it would, and stops after three quick ends with an error.\nA rejected watch retries only when asked, or once when an offline channel's host becomes reachable.\nDeleting a channel kills its worker and keeps the worker lock, then removes the record before its\ndirectory. Workers read the record only after taking the lock, so a watch recovering during the\ndelete cannot start a worker over storage being removed.\n\nWorkers clear the busy projection on startup and normal exit. Listings suppress it for archived\nor dormant channels, and check the worker PID as well as the socket path. A five-second host\nliveness sweep broadcasts when a crashed worker's busy projection becomes stale, without writing\nback over a replacement worker's projection, connecting to channels, or waking them.\nReachable peers forward the live listing; directory-only fallback listings clear busy rather than\nanimating from a stale cache, even for hosted channels.\n\nChannel data survives app replacement and upgrades. `ace backup` takes a verified SQLite snapshot\nof a local channel while it runs, alongside its catalog record. Project files and lane worktrees\nhave their own repository backup. Stored format changes require migrations; see [data](data.md).\n\nOpening a folder adds a project to the host's `projects.json`, independently of channel creation\nor model credentials. This is a list of local folders, not channel history. Existing catalog\nchannels also contribute their project paths. Only local owner connections can read or change\nthe opened-project list; teammates see the project information already present in channel listings.\nSetting up a known GitHub project is a local-only operation on that list: the host validates the\n`owner/name`, expands `~`, and runs `git clone` of `https://github.com//.git` with\nargument arrays. Public repositories therefore need no GitHub account, and an organization's SSO\npolicy on the gh token cannot block them; private ones use the host's existing Git credential\nhelpers. A destination that already holds a complete checkout of that repository is opened instead;\nany other non-empty folder is refused, and Ace never removes what a failed clone leaves behind.\n\nA channel's project path is the checkout it works in: its agents' working directory and the base\nof its lanes. That checkout may be a Git worktree, such as a lane or another tool's worktree. The\nhost groups every worktree under its repository's main checkout and labels it with the GitHub\nremote, so the app shows one project per repository across hosts without rewriting channel\nrecords. Opening a worktree adds its main checkout.\n\nModel credentials come from `ACE_`, ``, then the OS keychain, for each name pi-ai asks\nfor, such as `OPENAI_API_KEY`. Agent shells inherit the process environment. Participants allowed\nto invoke an agent can use its shell tools, so processes that run tools first move credential-like\nvariables out of the environment; only the key lookup can read them.\n\nWorkers resolve Keychain credentials on each model request, so adding, replacing, or removing a\nkey through the app or CLI takes effect without restarting workers. Keychain access errors are\ndistinct from missing keys. Settings exposes provider status and environment overrides, never\nstored key values; it validates new keys against the provider before saving them.\n\nThe default model for a chat's first agent run is a nonsecret preference in `settings.json` under\n`~/Library/Application Support/Ace` on macOS, or `$XDG_CONFIG_HOME/ace` on Linux. The app and CLI\nread the same preference; `ACE_MODEL` and an explicit per-channel model still take precedence.\nExisting chats keep their chosen model. Adding credentials later makes an unconfigured channel's\nagent available without recreating the channel or restarting its worker.\n\nHost configuration is captured before credential cleanup. A worker receives the host's launch\nenvironment, then seals credentials again before running tools. Source workers disable automatic\n`.env` loading, so an unrelated working directory cannot change their credentials or configuration.\n\nStopping the host closes listeners and workspace links, then closes active local workers and their\ntool processes without writing durable abort marks. Shutdown identifies workers through their live\nUnix sockets; a stale PID file must never cause an unrelated process to be signaled or a dormant\nworker to start. A receipt of suspended worker IDs lets the next host startup resume unfinished\nwork through pi without waiting for a client to reopen a channel.\n\n### Logs\n\nEvery host process writes JSON lines to `$ACE_HOME/logs/.jsonl`: `host` (gateway, peers,\ndirectory, workspace links), `channel-` (one per worker), and `cli`. Each process owns its file,\nwrites synchronously so the lines before a crash survive, and rotates at 10 MB keeping four files.\n`ace logs` merges them in time order and filters by `--channel`, `--trace`, `--level`, `--since`,\nand `--grep`; `--follow` tails them.\n\nIds tie lines together: `channel` and `chat` on everything a channel does, `trace` on each\ngateway request as it passes through peer hosts and into a worker, `submission` from a request to\nits outcome, and `task` and `call` on model responses and tool calls. Channels log requests, model\nresponses with usage and provider errors, and tool calls with durations; message text is not\nlogged, but tool arguments are, clipped to 2,000 characters. `debug` lines (listings, watches,\ndirectory syncs, workspace calls) are written only with `ACE_DEBUG=1`. Hosted services log the same\nrecords to Workers Logs.\n\n## Desktop\n\nOne `Ace.app` carries the desktop UI and **Ace Helper**, an independently running host executable.\nThe helper compiles with Bun 1.4 or newer and dispatches channel workers through the same executable.\nThe UI keeps Electrobun's bundled Bun version to match its native FFI callbacks. The helper resolves web\nassets from its application bundle and writes its log under the channel data directory. Closing a\nwindow or quitting the desktop leaves the helper running; reopening the UI verifies the host's\nprotocol, data directory, and a fresh proof of ownership before attaching.\n\nThe host stores a private owner token in `host.token` with mode 0600. The native UI supplies it only\nto its local webview; `ace open` supplies it in a URL fragment that the app immediately removes.\nThe first WebSocket handshake authenticates with this token and sets an HttpOnly, SameSite cookie\nfor page reloads. The loopback listener checks Host and Origin, and Settings requests are forbidden\non the tailnet listener, including requests from the owner's other machines. A health challenge\nbinds discovery to the owner token, listening port, and process before the desktop or CLI opens\nthe app. As with channels, this does not isolate Ace from tools running as the same OS user.\n\nLocal app windows report their current channel and tabs to the host while connected. The owner\ncan list these windows and rename one tab through the CLI. A rename targets a window, channel,\nand tab ID, so switching channels before the request arrives rejects it. The host returns success\nafter the target window applies the change. Tab names stay in the client's existing layout state;\nthey do not rename channels, chats, or another participant's tabs. The window registry is transient,\nand these operations use the authenticated loopback connection, never a tailnet peer.\n\nOn macOS, a bundled LaunchAgent runs Ace Helper as the logged-in user. A small native bridge calls\n`SMAppService` to register it after first-launch consent and expose its approval status. Registration\nstarts the helper immediately and at subsequent logins. A disabled background item is left for the\nuser to enable in System Settings. The stable service identifier is `dev.ace.desktop.helper`; the\nexecutable and desktop controls are named Ace Helper.\nmacOS groups the background permission under the parent app's name, Ace.\n\nThe desktop owns the native project picker and helper controls. Its webview uses a typed native\nbridge, authenticates each request with the owner token, and restricts navigation to the local app\norigin. Web links that open a new window go to the default browser. Settings exposes Start, Stop,\nand Restart through this bridge, and its controls remain available while the host is disconnected.\nStopping unregisters login hosting until the user enables it again. An authenticated command-line\nhost can serve the UI, but the desktop does not manage that process as Ace Helper.\n\nGit, shell, Tailscale, and directory diagnostics come from the host through the same local-only\nboundary as provider settings. The project picker selects a local Git checkout; project creation\nerrors remain in the form so the person can fix the path or provider setup.\n\nAgents inspect and operate native windows through an injected desktop capability. The desktop embeds\n[desktop-tools](https://github.com/githubnext/desktop-tools), a standalone package carrying a pinned,\npatched Peekaboo bridge, its signed client, and the request/result contract, inside Ace's UI process,\nwhich owns macOS Accessibility, Screen\nRecording, and Event Synthesizing permissions. The host invokes a bundled client over a local Unix socket. The bridge\naccepts only the client's exact identifier signed by Ace's team; the client verifies the host's\nsigning team. Tools expose application and window inventories, observation, element or screenshot\nclicks, scrolling, atomic drags, replacement of editable field values, text selection/insertion, and keys or shortcuts. Screenshot\npoints are normalized and mapped through the snapshot's native capture geometry. Control input uses background delivery bound to a\nsnapshot's exact process, window, and controls; every dispatched action requires a new observation.\nRead-only menu inventory uses signed native responses and application inventories before and after\nthe read to bind one observed process generation. Its possible native cache and unknown completeness\nremain explicit; an optional exact literal title path filters the returned subtree before channel\nhistory without granting input authority. The native traversal still reads the full menu and may\ntrigger application population callbacks. Native menu traversal is currently\nsynchronous and can delay GUI responsiveness or cancellation. Menu commands use a separate\nliteral-array native operation: fresh bounded AX reads select one enabled leaf, followed by one\npress without opening ancestors or making a separate activation request; the app or macOS may\nbring it forward in response. The signed result binds the original\napplication generation. Commands targeting the native Ace process itself are unsupported and\nrefused before input; its menu inventory remains available. Detached AX work retains the existing\nprocess mutation lane until the\nactual call returns, including after cancellation; ambiguous native timeout remains unsafe to\nrepeat. Command delivery is distinct from its application effect, and no automatic follow-up\nobservation changes that outcome.\nSeparate activation, quit, close, focus, minimize, restore, move, and resize tools accept generation-bound inventory targets, with exact\nwindow bounds where applicable. The native service revalidates those receipts before dispatch;\nactivation and focus explicitly change the foreground desktop. Inspection never activates a target\nimplicitly. App-only action receipts refresh inventories without inventing a selected window.\nNormal quit reports completion only after native termination confirmation; an accepted request that\nleaves the app running stays uncertain. It never retries, force-quits, or chooses a dialog response.\nExact-window close selects one supported background Accessibility route before input and never\nfalls through after dispatch. Confirmed disappearance survives later inventory failure; an accepted\nclose that remains open is uncertain with unsafe retry and fresh inventory when available.\nExplicit launch accepts an absolute app path or bundle ID and deliberately requests foreground\nlaunch/readiness through the native global mutation lane. The signed response binds the selector\nto the resulting process generation; later inventory failure preserves that result. Launch exposes\nno document/URL, extra-instance, or relaunch options. The app may still open after caller timeout\nor interruption, so uncertain launch is never replayed and native ownership lasts until it settles.\nExplicit item opening reuses that signed native launch route for one existing absolute path or\ncomplete URL, optionally selecting an app. Otherwise macOS chooses the default handler; no app\nis assumed before dispatch. The signed request includes the item URL and binds the returned\nprocess generation. Accepted delivery remains unverified item effect, including after successful\nreadiness and activation. Later app/window inventory cannot prove document loading or navigation,\nand failures after native submission remain uncertain without retry or dialog handling.\nMinimize verifies native window state and returns fresh inventory without capturing the minimized\nwindow; restoring it remains an explicit action with a refreshed target.\nMove and resize use native background Accessibility, verify resulting geometry, and return refreshed\nwindow targets; the original bounds remain part of the pre-mutation identity check.\nLiteral insertion uses one GUI-owned temporary plain-text paste, with the existing native mutation\nlane and clipboard transaction gate held through delivery and cleanup. The GUI preserves bounded\nprior clipboard contents privately and restores them only when no paste key was sent or the expected\nedit was observed in the same control. Uncertain consumption leaves the replacement or preserves newer contents; no\nrestore journal or automatic retry is created. Clipboard read policy is reported in This Mac.\nThe same clipboard gate retains a content-free reservation while a dispatched paste is unresolved.\nLater automated writes require observed consumption or termination of the exact receiver process\ngeneration. The reservation survives GUI restart; clipboard contents and comparison state do not.\nExplicit clipboard tools read complete bounded plain text, an image preview, or advertised local\nfile references, or persistently replace text, an image, or file references; they do not paste. Reads use the existing silent permission policy and require\na stable generation, without entering or releasing the mutation gate. The GUI copies one bounded\nimage representation, renders an oriented preview off its main actor, and verifies the generation\nagain. Source and preview metadata stay distinct; the bounded preview uses the existing image\nresult and durable history without clipboard files or a second store. File reads return exact\nadvertised URLs and decoded paths without filesystem access; macOS may filter references before\nexposing them to Ace. Image writes take an execution-host path: the host alone reads a bounded\nregular file, and the GUI decodes its immutable copy before publishing the original representation.\nOnly source metadata is returned. File-reference writes check path metadata on the host without\nreading contents or resolving links. The GUI prepares one file URL item per literal path, preserving\norder and duplicates, then publishes the complete bounded list with generation checks. Result metadata\ndescribes requested references and native publication, not a receiving application's eventual copy.\nWrites enter the same gate,\nincluding pending-paste admission, and expose content-free native outcomes without window inspection.\nExplicitly read content enters ordinary tool history as observed data; no permission layer is added.\nPi records their intent and never automatically replays an interrupted action. Results distinguish\ncompleted operations, refusals before dispatch, and uncertain delivery. The host bounds\naccessibility text and resizes screenshots before returning them. Explicit pixel inspection preserves\nexact-target capture checks and publishes a screenshot-only snapshot whose stored capture authorizes\nonly coordinate input in that exact window; failed observations retain their\nerror and report later target availability when it can be read. Quitting Ace stops desktop tools;\nAce Helper can keep channels running. Hosted channels forward the capability to their workspace.\nPi stores the result; channel clients project its images into the existing tool output. Peekaboo\ncoordinates concurrent native operations. An independent owner-controlled channel setting gates\nnative desktop tool dispatch for every chat, including the owner's agents and subagents. See\n[native desktop tools](desktop-tools.md) for setup, supported actions, and interruption behavior.\n\nAgents list, navigate, and inspect web pages through an injected browser capability. The host talks\nto a dedicated development browser directly over the Chrome DevTools Protocol on loopback. It finds\nthe browser only through `DevToolsActivePort` in the profile at `$ACE_HOME/browser`, so personal\nbrowsers and other debugging sessions are never reached; Ace does not launch or own that browser.\nA tab target is the browser ID from Chrome's endpoint path plus Chrome's target ID. Every call\nreconnects and refuses a replaced browser or closed tab instead of choosing another tab by URL,\ntitle, or position. Inspection returns the main document's bounded accessibility tree and a viewport\nJPEG with loader IDs before and after, keeping partial evidence when one part fails. Navigation is\nunsafe and sequential: it reports Chrome's answer (started, same document, download, or failed)\nwithout claiming readiness, and a navigation whose dispatch or answer is uncertain stays unknown. Hosted channels forward the\ncapability to their workspace, and pi stores the result like any other tool output. See\n[browser tools](browser-tools.md) for setup, limits, and outcomes.\n\nThe installed development app uses `dev.ace.desktop.dev`, port 4141, and `~/.local/state/ace-dev`,\nkeeping it separate from stable and Canary. Its preferences live under `Ace-dev`, and its Keychain\nservice is `ace-dev`. It is signed locally for `SMAppService`; distribution signing and\nnotarization are handled by the release pipeline. All development builds share that fixed app\nidentity and local signing identity, so macOS grants one Ace-dev permission entry. A separate\nprofile in the signed bundle derives each checkout's port, data, preferences, Keychain service,\nnative client identifier, and persistent WebKit partition from the checkout path, and only\nuses the host that `bun run dev` starts from the same checkout. It never registers Ace Helper.\nSource dev builds can run alongside Canary, but must not coexist with a registered installed\nAce-dev helper: macOS can resolve that shared service identity from another dev bundle. The dev runner opens the exact app\nthrough LaunchServices so macOS attributes permission checks to Ace-dev rather than its parent\nterminal or coding app, and tracks that instance for shutdown. `ACE_CONFIG_HOME` and\n`ACE_KEYCHAIN_SERVICE` can target an isolated profile for other smoke checks. Sparkle checks for updates while Ace is open;\ninstallation explicitly pauses and unregisters the helper before replacing the application. The\nrelaunched app restores hosting and resumes interrupted workers. See [updates](updates.md) for\nthe handoff, signed feeds, hosting, and release credentials.\n\n## Hosted channels\n\nTeams deploy `services/channel` to run the same `packages/channel` core in a Durable Object,\none per channel. Hosted describes channel placement, not an Ace-operated service.\nThe object provides what the host's worker provides locally (single ownership of the store,\nisolation, and routing by channel ID) and adds hibernation and placement off any one machine.\npi's portable SQLite core runs on the object's own SQL through `storage.ts`.\n\nA Durable Object has no file system or shell, so a hosted channel's tools run on a **workspace**:\nthe host that created it. That host dials out to the object and serves each chat's file and shell\ncalls from its lanes, using the same execution environment as a local worker\n(`packages/channel/src/workspace.ts`). The project checkout stays the source of truth. While the\nworkspace is disconnected, the channel stays reachable for chat, tools report the workspace as\noffline, and a call in flight when it drops is reported to the model as failed.\n\n- The workspace socket hibernates, so an idle hosted channel costs nothing while its host stays\n connected. Client sockets carry live pi event streams and keep the object awake.\n- While any chat is busy, a pending timer keeps the object resident: hibernating would drop\n in-flight workspace calls whose processes keep running on the workspace. Idle objects hibernate.\n An alarm still re-wakes an object the runtime resets during a run, so it resumes the run.\n- Hosts share the team's secret with the service (`ACE_SECRET` on hosts and Workers) and state each message's author. They verify their own users over the tailnet, so the\n service trusts hosts, not individual people.\n- Model keys are Worker secrets.\n- Busy transitions share the metadata/activity projection path over the workspace socket. Every\n workspace reconnect gets a current busy snapshot, including when the object was already open.\n The workspace host clears busy on disconnect and accepts it only while that link is connected;\n this listing hint is intentionally suppressed when the workspace is unavailable, even if the\n hosted channel can still run model-only work. It adds no client transcript subscriptions or\n keepalive timers to dormant hosted objects.\n\n### Moving channels\n\nThe owner moves an idle channel between its host and a hosting service with `ace move` or the\nchannel's Move to menu. The channel keeps its ID, lanes, and workspace; only where pi runs changes.\nThe pi store travels as one snapshot (`@ace/channel/transfer`): an allowlist of pi's tables at the\ncurrent schema, at most 32 MiB, with a SHA-256 digest that import verifies before it commits.\nExport refuses unfinished tasks or queued submissions, so a move never carries an active run.\n\nThe host fences the channel's record with `moving` first: no worker starts and no client connects\nthrough this host. A hosted channel keeps its workspace link until the service freezes it, so a run\nadmitted before the freeze is refused rather than interrupted. A running worker stops admitting requests, lets admitted ones finish, and\nexits only if the channel is idle. The service's `POST /channels/:id/transfer` takes `import`\n(stored inactive), `activate` (only for the imported digest), `freeze`, `export` (only while frozen),\nand `thaw`. Inactive and frozen objects persist that state and answer every other request with 409.\n\nMoving out exports the parked local store, imports it, then activates it; the local file stays in\nplace. Moving back freezes the hosted object, exports it, and verifies it into a new local file that\natomically replaces the parked one; the frozen object remains. A later move out re-imports into it.\nA failed step before activation lifts the fence. An unanswered activation keeps it, and repeating\nthe same move retries activation. Watches on the old placement end and clients reattach.\n\n## Shared services\n\nShared state that must outlive any one machine lives in cells: Durable Objects deployed to\nthe team's Cloudflare account, or celld on a team machine. The team deploys and operates these\nservices. Each service is named for its job.\n\n`services/directory` holds the team's hosts and where each channel lives. Every host publishes its\nwhole channel set on each change and every 30 seconds, then reads everyone's. It answers lookups\nonly: channel traffic goes to the channel's host over the tailnet, or to the hosted channel. So a\nchannel stays listed while its host is asleep. The app shows a local channel whose host is\nunreachable as offline, and reaches a hosted channel directly. Hosts find the directory through\n`ace directory ` and authenticate with the team's `ACE_SECRET`.\n\nLobbies (presence, notifications) are not built.\n\n## The team\n\nThe tailnet is the team and the sole authority for team membership and collaboration access.\nIts identities and access rules decide which people and machines can reach each other. Ace has\nno separate accounts, invitations, roles, or team access controls. Every human author is a\nTailscale login, so a person is the same participant on every host.\n\nThe channel owner can turn collaborator agent invocation on or off with `ace share on|off`\nor the channel header's agent-access toggle; channels start shared. It prevents new collaborator\ninvocations; active work continues until stopped or killed, and teammates keep reading and posting\nhuman messages. The teammate composer holds an invoking draft instead of sending it while sharing\nis off.\n\nA separate owner-controlled desktop-tools toggle gates native desktop tool dispatch for the entire\nchannel: owner and collaborator runs, all chats, and subagents. It starts enabled, including for\nexisting channels. Disabling it refuses subsequent native desktop calls, even within active runs;\nit does not cancel or undo calls already dispatched. Agent invocation and non-desktop tools remain\navailable according to the sharing setting. This is a native tools gate, not a shell security\nsandbox: agents still run as the host's user and shell commands can access that user's environment.\nThere are no per-participant desktop grants or per-call approval policies.\n\nBoth settings live in pi's `ace.settings` session document. Watch metadata events carry their\ncurrent values on every watch and committed change; name/summary revisions do not version these\nsettings. Clients send owner-only `{ op: \"desktop\", author, enabled: boolean }` to change the desktop\ngate; `info` and metadata watch events expose it as `desktop: boolean`. Older hosts omit it and\ncontinue their existing desktop behavior; the header shows an unknown, disabled control until a\nhost reports the setting.\n\nLocal owner tokens and browser-origin checks authenticate local connections. Team-deployed\nservices use `ACE_SECRET` to authenticate hosts and trust the participant identities those hosts\nsupply; the services do not check tailnet membership themselves. These mechanisms carry the\nteam's existing trust and do not define another way for a participant to join the team.\n\nEach host's gateway serves its owner's app over loopback. Its tailnet listeners name each caller\nwith `tailscale whois` and accept peer hosts or the owner's browser from an allowed origin.\nTeammates use their own host to reach shared channels. Local-only settings remain on loopback.\nHosts find online, untagged peers through `tailscale status`. A host shows its app every peer's\nchannels and proxies their requests; the peer that runs a channel stamps every author. Only a\nchannel's host creates it; only the host's owner, from any of their machines, archives, deletes,\nor kills.\n\n## Not yet built\n\nTerminals and previews, attachments, lobby cells, and external harnesses (Claude Code, Codex).\nHosted channels cannot message other channels yet. Projects without a GitHub remote are still keyed\nby a host's main checkout, so a teammate's copy of the same folder shows as a separate project.\n","editable",false,"branch","documentNavigation","repo","githubnext/ace2","repoId","938fe4cd-5320-4e4f-ac7c-87d4dad8490c","ownerId","org:89615882","site","nexthub","private","admin","settings","maintainer","triage","starred","stars",0,"watchers","watching","pinned","notify","views",[226,227,228,229,230,231,232,233,234,235,236,237,238],"navigation",{"_55":56,"_182":183,"_184":185,"_186":187,"_188":189,"_190":191,"_192":193},"sources",[],"viewer","meta",{"_174":175,"_176":177,"_178":179,"_43":32,"_180":14,"_181":32,"_49":50,"_51":50},"branches",[82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,14,167,168,169,170,171,172,173],"tags",[70,71,72,73,74,75,76,77,78,79,80,81],"cloneUrl","https://git.nexthub.sh/githubnext/ace2.git","desktop-canary-v0.0.10","desktop-canary-v0.0.11","desktop-canary-v0.0.12","desktop-canary-v0.0.13","desktop-canary-v0.0.14","desktop-canary-v0.0.15","desktop-canary-v0.0.16","desktop-canary-v0.0.18","desktop-canary-v0.0.21","desktop-canary-v0.0.7","desktop-canary-v0.0.8","desktop-canary-v0.0.9","amber-beacon/composer-effort","brisk-ember/github-avatars","brisk-grove/image-paste-91","calm-anchor/fix-streaming-draft-overlap","calm-grove/composer-agent-mode","cloud-pilot-ops/canary-0-0-17","cloud-pilot-ops/cloud-move","cloud-pilot-ops/cloud-pilot","codex/agentation-shortcut","codex/annotation-polish","codex/browser-pages","codex/canary-0-0-21","codex/canary-0.0.11","codex/channel-delete-close","codex/channel-watch-recovery","codex/clipboard-files-write","codex/composer-coordinate-check","codex/computer-use-validation","codex/desktop-actions","codex/desktop-app-search","codex/desktop-app-state","codex/desktop-availability","codex/desktop-click-variants","codex/desktop-clipboard","codex/desktop-clipboard-files","codex/desktop-clipboard-image","codex/desktop-clipboard-image-write","codex/desktop-clipboard-text","codex/desktop-drag","codex/desktop-keyboard","codex/desktop-launch","codex/desktop-locked-feedback","codex/desktop-menu-command","codex/desktop-menu-inventory","codex/desktop-minimize","codex/desktop-open","codex/desktop-pointer","codex/desktop-quit","codex/desktop-selection-keys","codex/desktop-tool-guidance","codex/desktop-tools-extraction","codex/desktop-window-close","codex/desktop-window-geometry","codex/desktop-windows","codex/dev-permission-identity","codex/durable-composer-drafts","codex/fix-message-clipping","codex/lane-base-96","codex/native-patch-prefix","codex/peekaboo","codex/peer-channel-messaging","codex/pixel-snapshot-authority","codex/publish-canary-0-0-21","codex/readme-security","codex/settings-refresh","codex/stale-click-refusal","codex/tab-renaming-api","codex/team-agent-access","codex/team-channel-sections","codex/team-dogfood-integration","codex/webkit-coordinate-window","codex/webkit-desktop-focus","deft-beacon/helper-isolation","deft-grove/align-avatar-byline","deft-grove/build-canary-0-0-18","deft-grove/canary-github-releases","deft-grove/ship-canary-0-0-18","deft-meadow/details-sidebar","fair-ember/canary-0-0-13","fair-ember/canary-0-0-14","fair-fjord/all-projects","feat/github-cache","feat/rebuild","fix/channel-credentials","glad-anchor/restore-message-queue","glad-ember/archive-inactive-channels","glad-fjord/project-identity","glad-orbit/channel-progress","glad-ridge/terminal-replay-input","hazy-anchor/github-row-actions","hazy-ember/channel-access-toggles","hazy-grove/all-projects-add-channel","local-project-setup/build-canary-0-0-20","local-project-setup/canary-0-0-20","local-project-setup/local-project-setup","mellow-ridge/canary-0-0-16","mellow-ridge/top-bar-drag-area","nimble-cedar/modal-top-offset","nimble-meadow/canary-0-0-15","remote-channel-load/build-canary-0-0-19","remote-channel-load/canary-0-0-19","remote-channel-load/fix-remote-channel-load","description","Ace: a collaborative coding environment on the team's own machines","owner","githubnext","section","","head","empty","pins",[208,209,210],"documents",{"_203":204,"_205":206},"code",{"_199":200,"_201":202},"automations",{"_196":197,"_198":-5},"delivery",{"_194":50,"_195":-5},"tag","9Rn62lcgXCFfpmCuooTjLxGyUf8","releases","applications","workflows",2,"deployments","commits",215,"changes",1,"counts",{"_207":206},"total",86,"issue",{"_211":201,"_213":224,"_15":201,"_215":225,"_53":217,"_218":32,"_219":217,"_220":202},{"_211":221,"_213":222,"_15":221,"_215":223,"_53":217,"_218":32,"_219":217,"_220":50},{"_211":212,"_213":214,"_15":212,"_215":216,"_53":217,"_218":32,"_219":217,"_220":206},"id","issues","name","Issues","filters",{},true,"saved","pinnable","count","tasks","Tasks",{},"Changes",{},{"_211":201,"_213":224,"_15":201,"_215":269,"_53":217,"_218":32,"_219":217},{"_211":221,"_213":222,"_15":221,"_215":268,"_53":217,"_218":32,"_219":217},{"_211":212,"_213":214,"_15":212,"_215":267,"_53":217,"_218":32,"_219":217},{"_211":264,"_213":265,"_15":264,"_215":266,"_53":32,"_218":32,"_219":217},{"_211":261,"_213":262,"_15":261,"_215":263,"_53":32,"_218":32,"_219":217},{"_211":196,"_213":259,"_15":188,"_215":260,"_53":32,"_218":32,"_219":217},{"_211":198,"_213":256,"_15":257,"_215":258,"_53":32,"_218":32,"_219":217},{"_211":194,"_213":254,"_15":194,"_215":255,"_53":32,"_218":32,"_219":217},{"_211":250,"_213":251,"_15":252,"_215":253,"_53":32,"_218":32,"_219":217},{"_211":184,"_213":248,"_15":184,"_215":249,"_53":32,"_218":32,"_219":32},{"_211":245,"_213":246,"_15":245,"_215":247,"_53":32,"_218":32,"_219":32},{"_211":242,"_213":243,"_15":242,"_215":244,"_53":32,"_218":32,"_219":32},{"_211":239,"_213":240,"_15":239,"_215":241,"_53":32,"_218":32,"_219":32},"decisions","Decisions",{},"changelog","Changelog",{},"roadmap","Roadmap",{},"Documents",{},"activity","Activity","insights",{},"Releases",{},"Deployments","automations/deployments",{},"Workflows",{},"discussions","Discussions",{},"goals","Goals",{},{},{},{},"groups","user","agents",[],"now",1794433491107,"sidebar","expanded"]