[{"_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",{"_40":41,"_270":-5,"_271":-5,"_272":273},"routes/repo",{"_33":-7,"_34":35,"_36":37,"_38":39,"_40":41,"_42":31,"_43":31,"_44":31,"_45":31,"_46":31,"_47":31,"_48":49,"_50":49,"_51":31,"_52":-7,"_53":-7,"_54":55,"_56":57,"_58":59,"_60":-5,"_61":62,"_63":64,"_65":66,"_67":68},"routes/repo.blob",{"_13":14,"_15":16,"_17":18,"_19":20,"_21":14,"_22":23,"_24":-5,"_25":26,"_27":28,"_28":29,"_30":31,"_32":14},"ref","6ec1747bc4eea490ded7798aae4fac2ef38a2f65","path","docs/desktop.md","oid","9dff41a9da7532087c53531515b6b9c740b61f40","size",18133,"commit","mounts",[],"source","plain",{"_13":14,"_15":16},"kind","text","# Desktop plan\n\nShip one `Ace.app` with a desktop client and an independent background host named **Ace Helper**.\nThe app carries its runtimes; opening it from Finder requires neither a source checkout nor an\n`.env` file. Channel workers and pi's durable storage keep their existing ownership.\n\n## Project and navigation contract\n\nKeep the existing Ace shell and shared UI components. The left navigation has Dashboard and\nChannels; native window controls have their own space above it. Cmd+O opens a native folder\npicker and adds the chosen folder as a project. Opening a project needs no provider key, creates\nno channel, and remains available after a restart. Repository import is a later feature.\n\nDashboard and Channels share the project picker. A dashboard request or New channel creates a\nchannel in the selected project. Switching projects restores each project's selected channel.\nSettings live in the account menu and Cmd+comma. Cmd+B toggles navigation; Cmd+Shift+B toggles the\nchannel sidebar. Project paths are scoped to their host until repository-based identity lands.\n\n## Process and installation contract\n\n- The desktop connects to Ace Helper. Closing or quitting the desktop leaves hosting available.\n- Ace Helper runs as the logged-in user. On macOS, `SMAppService` manages its bundled LaunchAgent.\n The executable and human-facing controls use the name **Ace Helper**; its stable service\n identifier is `dev.ace.desktop.helper`.\n macOS groups its background permission under the parent app's name, **Ace**.\n- One worker owns each active channel. Dormant channels remain files, and only pi stores their\n messages, runs, and chats.\n- Host shutdown closes workers without durable cancellation. Kill retains its existing meaning.\n- Login registration is visible and reversible. A disabled background item must not be silently\n re-enabled. Sleep and logout can take local channels offline.\n- CLI and desktop use the same catalog and credentials. Keep `~/.local/state/ace` for channel data;\n store nonsecret preferences under `~/Library/Application Support/Ace` on macOS.\n- Resolve application resources from the bundle and keep writable state outside it. Development\n builds have a distinct service identity so they do not replace the installed helper.\n\n## Milestones\n\n1. **Packaged host foundation and Ace Helper.** Resolve runtime configuration before credential\n cleanup; carry configuration and credentials correctly into channel workers; discover Tailscale\n when launched without a terminal; verify host identity before connecting; package the helper\n and its macOS service registration. Validate the helper from an isolated application bundle.\n2. **Provider and host settings.** Add provider key entry, validation, replacement, and removal\n using the OS keychain; distinguish missing credentials from denied keychain access; propagate\n changes to running workers. Add nonsecret host preferences shared with the CLI. Restrict local\n settings operations to the owner's authenticated connection.\n3. **First-run and lifecycle UX.** Add the project folder picker, tool diagnostics, Tailscale\n status, and background-hosting controls. Handle service approval, reconnect, clean shutdown,\n and restart recovery without requiring a terminal.\n4. **Distribution.** Sign and notarize all executables, coordinate updates with the helper and\n workers, and verify access to projects and keychain entries across upgrades. The signing\n pipeline must handle the space in `Ace Helper` when passing executable names and paths.\n\n## Validation\n\nUse real Bun processes, real provider credentials, and isolated channel data. Do not add mocked\nproviders or a second state store. Check source and packaged worker startup, a real model/tool\nrun, resource paths containing spaces, and operation without a source checkout or `.env` file.\nVerify that unrelated listeners are rejected, owner authentication and origin checks hold, and\nthe desktop can reconnect to its helper.\n\nBefore distribution, verify the signed app from `/Applications` in a clean macOS account: provider\nsetup, project access, teammate access after the UI exits, login registration and removal, sleep\nand wake, and an update with existing channel history. Check **Ace Helper** in Activity Monitor\nand Ace's grouped permission in macOS background-item settings.\n\n## Progress\n\n- Created the `desktop` lane on branch `feat/desktop`.\n- Implemented the first milestone: a compiled Ace Helper with a bundled LaunchAgent, native\n registration and approval status, host identity checks, bundle-relative resources, preserved\n worker configuration and credentials, and Tailscale discovery outside a terminal.\n- The desktop connects to the helper, keeps hosting independent of its window, and exposes\n Ace Helper settings and its log. Development builds use a separate service, port, and catalog.\n- Passed repository type and lint checks and built the macOS development app. From a temporary\n app under `/Applications`, registered the real LaunchAgent and completed a real Anthropic\n model and shell-tool run using the existing Keychain credential. An unrelated `.env` containing\n an invalid key did not affect the run, and the tool environment contained no provider key.\n- Also verified source workers, explicit credential inheritance into compiled workers, web\n assets at paths containing spaces, rejection of an unrelated listener, and continued hosting\n after the client disconnected. Unregistered and removed the temporary app and channel data.\n- Implemented provider Settings for Anthropic and OpenAI: checked saves, connection checks,\n replacement, removal confirmation, and clear missing, overridden, or inaccessible Keychain\n states. A rejected replacement preserves the saved key. Only provider status reaches the UI.\n- Removed the credential cache so live workers see new and removed keys on their next model\n request. The app refreshes its model choices after settings changes. Default models persist\n outside the bundle and are shared with `ace model` and new CLI channels.\n- Added an owner token, authenticated host discovery, Host and Origin checks, and a local-only\n settings boundary. `ace open` opens the authenticated browser client; provider keys never\n enter URL fragments or browser storage.\n- Rejected forged discovery responses, discovery relays from a different port, and settings\n access over a real Tailscale connection even when the peer had the host owner's identity.\n- Verified real Anthropic model/tool runs from source and the installed bundle, live-worker key\n updates without a restart, shared CLI preferences, and invalid-key rejection by Anthropic and\n OpenAI. React Doctor reported 100/100 with no issues.\n- Checked the packaged UI's invalid-key feedback, saved-key state, connection check, default-model\n selector, Settings shortcut, window reopening, and native background-settings link. Kept the UI\n on Electrobun's bundled Bun to preserve native callback compatibility; the helper independently\n carries Bun 1.4 for SQLite. Confirmed macOS groups the background item under the app's name.\n- Replacing the helper in place inside an installed ad-hoc test bundle triggered a macOS launch\n constraint rejection. A later smoke check verified unregistering the old helper and replacing\n the whole bundle with fresh files at the same path: the existing app and service identity,\n projects, and channels survived. Updating the existing Ace-dev install still hit the rejection,\n so fresh files alone do not make ad-hoc upgrades reliable. Development builds accept an\n Apple-issued identity through `ACE_CODESIGN_IDENTITY`. Startup dialogs include the full failure\n message. The signed 0.0.2 update passed authenticated helper startup after refreshing the app's\n LaunchServices registration, preserving the existing channel and both provider Keychain items.\n- The final fresh install under `/Applications` passed authenticated startup and native Settings,\n ignored the unrelated `.env`, and kept the helper available after the UI exited. Removed the\n temporary apps, service registrations, Keychain entries, and channel data.\n- Rebased the lane onto main's directory and hosted-channel routing changes (`9f4d528`). Preserved\n the shared `ACE_SECRET` lookup, nonsecret host configuration, and offline channel listings.\n- Implemented the third milestone: a native project folder picker, inline setup errors, Git and\n shell checks, Tailscale and directory status, and Start, Stop, and Restart controls in This Mac.\n Native controls require the owner token and remain usable while the helper is stopped. The\n desktop distinguishes a source CLI host from its managed helper before changing processes.\n- Host shutdown now closes active workers and their tools without cancelling pi's durable work,\n closes hosted workspace links, and stops discovery and directory activity. It identifies live\n workers through their sockets rather than trusting PID files, and leaves dormant channels alone.\n- Passed type and lint checks. A real Anthropic run with an active shell tool survived a host\n restart: shutdown removed its worker and tool, and a new worker resumed the run. Also verified\n pending-request cleanup, stale PID safety, and that shutdown does not start dormant workers.\n- React Doctor scored the latest changes 92/100, with one control-flow complexity warning in\n the This Mac settings component.\n- Ran both shared services in real local Workers. Verified directory publication after credential\n sealing, offline listings, routing to a directory-only hosted channel, and denial of local\n diagnostics to a real tailnet peer.\n- From an isolated app under `/Applications`, verified picker cancellation and paths with spaces\n and commas, missing-key and invalid-project feedback, a compiled-worker Anthropic/tool run using\n Keychain, native Settings, Stop/Start/Restart, and transcript recovery. Quit now ends both the UI\n runtime and desktop launcher while Ace Helper stays running.\n- Restored the existing Ace navigation and native appearance, window-control placement,\n vibrancy, minimum window size, and title-bar zoom. Replaced the channel-first setup form with\n Cmd+O project opening, a project dashboard, and project-scoped channel selection.\n- Project metadata persists independently of channels and credentials. Real source checks\n verified canonical paths, duplicate opening, restart recovery, no implicit channel creation,\n and rejection of project operations and project broadcasts over a real tailnet connection.\n- Packaged UI checks covered native Cmd+O, opening projects before provider setup, channel\n creation, project switching, and a real Anthropic shell-tool reply. Fixed a render loop by\n caching object snapshots in the shared local-storage hook.\n- Follow-up work is tracked in the [dogfooding](https://github.com/githubnext/ace2/issues/5) and\n [desktop distribution](https://github.com/githubnext/ace2/issues/7) meta issues. Team directory\n configuration and providers beyond Anthropic/OpenAI still use the CLI; directory status in\n Settings is read-only.\n\n## UI testing\n\nTest a checkout's desktop changes with `bun run dev` from its `apps/desktop`. It builds that\ncheckout's `Ace-dev.app`, starts the checkout's own host from source, and opens the app against it.\nThe host serves the checkout's freshly built `apps/app/dist`. Quitting the app stops the host and\nits workers; Ctrl-C or SIGTERM to the command quits the app first. If the host exits, the window\ncloses. The command blocks while the app runs, so an agent starts it in the background and stops\nit by quitting the app or signalling the command, not the host.\n\nEach checkout's build has its own bundle identifier, `dev.ace.desktop.dev.`, derived from the\ncheckout path. It uses its own `~/.local/state/ace-dev-` data, `Ace-dev-` preferences,\n`ace-dev-` Keychain service, WebKit storage, and a port from 4200 to 4999. Other `ACE_*`\nsettings in the environment are ignored, except `ACE_PORT` to move the run off a port used by\nanother checkout and `ACE_*_API_KEY` credentials. A run refuses any listener already on its port.\nThe profile starts without provider keys; add one in Settings or pass it in the environment. It\npersists across runs until you delete those directories, its Keychain entries, and\n`~/Library/WebKit/dev.ace.desktop.dev.`.\n\nThese builds never register or attach to Ace Helper. Without their host they report that it is\nmissing and quit, and helper controls in the menu and Settings are unavailable. Opening a checkout's\nbuild from Finder works only while its `bun run dev` host is running. Use the installed Ace-dev or\nCanary to test Ace Helper itself.\n\nDevelopment builds sign every executable with one identity: `ACE_CODESIGN_IDENTITY` when set,\notherwise the repository's local Git setting `ace.codesignIdentity`, otherwise ad hoc. Set the\nGit value once per Mac to an Apple Development SHA-1 from `security find-identity -v -p codesigning`;\nuse the SHA-1 because several certificates can share a name:\n\n```sh\ngit config ace.codesignIdentity \n```\n\nIt is stored in the repository's `.git/config`, which all its worktrees and lanes share, so agents and\nbackground builds use it without exporting anything. It is never committed; contributors without it\nbuild ad hoc, and `ACE_CODESIGN_IDENTITY=-` forces an ad-hoc build. With an Apple Development\nsignature, codesign's default designated requirement names the bundle identifier and the\ncertificate, so macOS privacy permissions and Keychain access granted to a checkout's build carry\nacross its rebuilds, while other checkouts, which have other identifiers, still need their own.\nNative desktop inspection of the app also requires a team signature.\n\nOn first launch, press Cmd+O to open a project folder. Verify that the dashboard opens with no\nprovider key and that opening a folder creates no channel. Add a provider key in Settings before\nstarting an agent. Check the Dashboard and Channels navigation, project switching, key validation\nand replacement, picker cancellation, and starting a channel. Quit and run it again; its channel\nhistory should remain available.\n\n### Installed Ace-dev\n\nThe installed `/Applications/Ace-dev.app` uses `dev.ace.desktop.dev`, port 4141, the `ace-dev`\ncatalog and Keychain service, and `~/Library/Application Support/Ace-dev` for preferences. It runs\nAce Helper through `SMAppService`. Build it only from a checkout based on the current `origin/main`:\n\n```sh\nACE_DEV_INSTALL=1 bun scripts/build.ts dev\n```\n\nUse the same valid Apple Development identity, from `ace.codesignIdentity` or\n`ACE_CODESIGN_IDENTITY`, for every install. macOS records a launch constraint from the\nregistered helper's signature, so an ad-hoc or differently signed replacement fails with a launch\nconstraint violation. The build refuses ad-hoc signing. Apple recommends an\n[Apple-issued identity for both the app and helper](https://developer.apple.com/forums/thread/799910).\n\nTo replace it, stop Ace Helper in Settings → This Mac, which unregisters it, and quit Ace. Remove\nthe old bundle and move the new one from `dist/dev-macos-arm64` into `/Applications` as a complete\ndirectory; do not overwrite executables inside the installed bundle or leave copies with the\n`dev.ace.desktop.dev` identifier elsewhere, because launchd can resolve the helper from any\nregistered copy. Refresh its registration with\n`/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f /Applications/Ace-dev.app`,\nthen open Ace and enable Ace Helper. In Settings → This Mac, try restarting the helper, then stopping\nand starting it. Keep the `ace-dev` data, preferences, and Keychain service. Changing the signing\nidentity may require approving Keychain access again. This build is signed locally, not notarized.\n\n## Browser development\n\n`ace serve` serves the built app; use `ace open` from another terminal to authenticate a browser.\nFor Vite, set `ACE_APP_URL=http://127.0.0.1:1111` when running both commands, and run `bun app dev`.\nThe explicit app URL authorizes that development origin; the Vite proxy rewrites Host to the\nlocal gateway. Desktop builds use their bundled web assets by default.\n\n## Rename a tab from an agent or the CLI\n\nAn Ace agent can use its shell tool to discover open local windows and rename a tab. From this\ncheckout, run:\n\n```sh\nbun ace tabs --json\nbun ace tab rename

\"Build checks\"\n```\n\nChoose the intended window and tab from the listing. The channel ID is required because tab IDs\nbelong to that channel's layout; a request fails if the window has switched channels. The result\ncontains the updated window after its layout accepts the rename. Names are trimmed and limited\nto 80 characters. Pass `\"\"` as the name to restore the tab's default label. The same commands are\navailable as `ace tabs` and `ace tab rename` when the CLI is on `PATH`.\nThe Chat tab keeps the channel's name; use `ace rename` to change that name instead.\n\nThe commands connect to an already running local host and never start one. Use its `ACE_HOME`\nprofile and pass `--port ` when it differs from `ACE_PORT` or the default 4140. For example,\nthe installed canary uses `ACE_HOME=\"$HOME/.local/state/ace-canary\"` and `--port 4142`; the development\napp uses `ACE_HOME=\"$HOME/.local/state/ace-dev\"` and `--port 4141`. Authentication checks the host's\nidentity and protocol before connecting. Listing or renaming tabs over the tailnet is unavailable.\n\nOnly the explicitly selected window changes live. Names use the existing saved layout for that\nchannel in the browser profile; another window sharing that profile can load the saved name on\nreload, and a later layout save from either window can overwrite the other's saved labels.\nIndependent window persistence is tracked in [#45](https://github.com/githubnext/ace2/issues/45).\nA tab label does not change the channel's durable name or another participant's view.\nClosed windows and windows without an open channel do not appear in the listing.\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",{"_54":55,"_182":183,"_184":185,"_186":187,"_188":189,"_190":191,"_192":193},"sources",[],"viewer","meta",{"_174":175,"_176":177,"_178":179,"_42":31,"_180":166,"_181":31,"_48":49,"_50":49},"branches",[81,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,167,168,169,170,171,172,173],"tags",[69,70,71,72,73,74,75,76,77,78,79,80],"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","main","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":49,"_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,"_52":217,"_218":31,"_219":217,"_220":202},{"_211":221,"_213":222,"_15":221,"_215":223,"_52":217,"_218":31,"_219":217,"_220":49},{"_211":212,"_213":214,"_15":212,"_215":216,"_52":217,"_218":31,"_219":217,"_220":206},"id","issues","name","Issues","filters",{},true,"saved","pinnable","count","tasks","Tasks",{},"Changes",{},{"_211":201,"_213":224,"_15":201,"_215":269,"_52":217,"_218":31,"_219":217},{"_211":221,"_213":222,"_15":221,"_215":268,"_52":217,"_218":31,"_219":217},{"_211":212,"_213":214,"_15":212,"_215":267,"_52":217,"_218":31,"_219":217},{"_211":264,"_213":265,"_15":264,"_215":266,"_52":31,"_218":31,"_219":217},{"_211":261,"_213":262,"_15":261,"_215":263,"_52":31,"_218":31,"_219":217},{"_211":196,"_213":259,"_15":188,"_215":260,"_52":31,"_218":31,"_219":217},{"_211":198,"_213":256,"_15":257,"_215":258,"_52":31,"_218":31,"_219":217},{"_211":194,"_213":254,"_15":194,"_215":255,"_52":31,"_218":31,"_219":217},{"_211":250,"_213":251,"_15":252,"_215":253,"_52":31,"_218":31,"_219":217},{"_211":184,"_213":248,"_15":184,"_215":249,"_52":31,"_218":31,"_219":31},{"_211":245,"_213":246,"_15":245,"_215":247,"_52":31,"_218":31,"_219":31},{"_211":242,"_213":243,"_15":242,"_215":244,"_52":31,"_218":31,"_219":31},{"_211":239,"_213":240,"_15":239,"_215":241,"_52":31,"_218":31,"_219":31},"decisions","Decisions",{},"changelog","Changelog",{},"roadmap","Roadmap",{},"Documents",{},"activity","Activity","insights",{},"Releases",{},"Deployments","automations/deployments",{},"Workflows",{},"discussions","Discussions",{},"goals","Goals",{},{},{},{},"groups","user","agents",[],"now",1794436279408,"sidebar","expanded"]