feat: Aether cloud provider — run T3 Code agents in isolated microVMs

[pranav100000]

What this adds

A first-class Aether provider for T3 Code: run any T3 Code agent (Claude Code, Codex, …) in an isolated cloud microVM instead of locally — one click, no VPS, no Tailscale, and no long cold start. T3 Code stays the client; the agent, workspace, and a live preview all run in the VM.

Highlights:

• Provider driver wired into the existing provider registry (settings, model catalog).
• REST task client + WS transport + full event mapper so cloud turns stream into the normal T3 Code timeline.
• Turn lifecycle + mirror-sync engine + write guards — durable-authoritative settlement so checkpoint diffs render correctly.
• Question/plan responses, revert ledger, model switch.
• Cloud port previews surfaced in the composer (public HTTPS, per-workspace token — no Tailscale).
• Cloud terminal — attach a real shell in the workspace VM, with reconnect on transient drops.

Shape

Built as a clean, reviewable commit chain:

1. provider driver skeleton — settings, registration, vendored catalog
2. REST task client + adapter session core
3. workspace attach, WS transport, full event mapper
4. turn lifecycle, mirror sync engine, write guards
5. question/plan responses, revert ledger, model switch
6. durable-authoritative turn settlement (checkpoint diffs)
7. cloud port previews in the composer
8. cloud terminal — attach a shell in the workspace VM (+ reconnect)

~86 files, largely isolated under apps/server/src/provider/Layers/aether/* plus a thin provider registration; packages/contracts additions are additive.

Opening as a draft to start the conversation — happy to split it or adjust to fit however you'd want this to land.

Note

Add Aether cloud provider to run T3 Code agents in isolated microVMs

• Introduces a new aether provider driver (AetherDriver.ts) backed by a REST client (restClient.ts), a WebSocket agent stream (workspaceSocket.ts), and a stateful event mapper (eventMapper.ts) that converts Aether WS/REST events into deterministic ProviderRuntimeEvents.
• Adds a mirror sync engine (mirrorSync.ts) that resets the local git worktree to the VM's declared state by reconstructing and applying a unified diff from structured Aether diff payloads, including safe binary file handling.
• Introduces AetherMirrorRegistry and guards (AetherMirrorGuards.ts) that reject git mutations, worktree removals, and filesystem writes targeting directories owned by an active cloud session, returning structured GitCommandError or ProjectWriteFileError responses.
• Routes per-thread terminal RPCs to a new AetherTerminalManager (AetherTerminalManager.ts) for cloud-backed threads, with WebSocket reconnection, exponential backoff, and keep-alive pings.
• Adds a thread.worktree.attach-managed internal orchestration command, a worktree_managed column (migration 041), and UI surfaces including provider selection, settings schema, port-preview CTAs in timeline and mobile work log, and an AetherIcon.
• Risk: git and filesystem operations on Aether-owned paths now fail with refusal errors rather than executing; local TerminalManager falls back for non-Aether threads but routing is now conditional.

^{Macroscope summarized 2bb0a73.}

---

Note

High Risk
Changes orchestration persistence, session start preflight behavior, and new RPC refusal paths for active Aether mirrors; incorrect worktreeManaged handling could reset user uncommitted work or leave mirrors writable mid-session.

Overview
This slice extends the Aether cloud-provider work with fork-safe CI, driver-owned worktree tracking, mirror write guards, and mobile port-preview UX.

CI / release: Main CI jobs move from Blacksmith runners to ubuntu-24.04 / macos-latest with longer timeouts. Relay deploy and scheduled nightly release are gated to pingdotgg/t3code so forks do not hit upstream production credentials or publish nightlies.

Worktree provenance (worktreeManaged): Threads gain a persisted flag (migration 041, projection SQL/repos) distinguishing worktrees the bootstrap created from paths the user already had. A server-only thread.worktree.attach-managed command marks driver-owned paths via thread.meta-updated; thread.meta.update derives the marker when the path stays the same (e.g. branch rename) and clears it on re-attach. ProviderCommandReactor passes managedWorktree: true into startSession only when the flag is set so Aether can skip clean-tree preflight without touching user dirty checkouts.

Runtime / UI: port.opened is ingested into activities and mapped on mobile to work-log rows with portPreview (globe icon, Open preview opens the URL). Mobile also keeps free-text-only user-input questions (empty options) so submissions are not partial.

Aether infrastructure (partial in diff): New AetherMirrorRegistry + AetherMirrorGuards refuse local VCS mutations, removeWorktree targets, and typed projects.writeFile while a mirror cwd is claimed. AetherDriver registers the REST/adapter stack; CloudTerminalConnector defines the optional remote PTY capability. Mobile adds an aether ProviderIcon.

^{Reviewed by Cursor Bugbot for commit 2bb0a73. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: edf7452a-98b5-4cef-af49-df511d72e9c8

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

🟡 Medium aether/portPreview.ts:48

buildAetherPreviewUrl always emits https:// for any non-localhost domain, so an HTTP-only self-hosted API base like http://127.0.0.1:8080 or http://aether.internal yields an https:// preview URL that fails to connect. The protocol is inferred solely from whether the derived host starts with localhost, ignoring the actual protocol of apiBaseUrl. Consider deriving the preview protocol from the parsed apiBaseUrl protocol (or accepting it as an explicit parameter) instead of hardcoding based on the hostname.

-  const protocol = domain.startsWith("localhost") ? "http" : "https";
+  const apiProtocol = new URL(input.apiBaseUrl).protocol.replace(/:$/, "");
+  const protocol = domain.startsWith("localhost") ? "http" : apiProtocol === "http" ? "http" : "https";

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/provider/Layers/aether/portPreview.ts around line 48:

`buildAetherPreviewUrl` always emits `https://` for any non-`localhost` domain, so an HTTP-only self-hosted API base like `http://127.0.0.1:8080` or `http://aether.internal` yields an `https://` preview URL that fails to connect. The protocol is inferred solely from whether the derived host starts with `localhost`, ignoring the actual protocol of `apiBaseUrl`. Consider deriving the preview protocol from the parsed `apiBaseUrl` protocol (or accepting it as an explicit parameter) instead of hardcoding based on the hostname.

[macroscopeapp]

🟡 Medium aether/mirrorSync.ts:178

renderTextFilePatch interpolates raw file paths directly into unified-diff header lines like diff --git a/${oldPath} b/${newPath} without Git's path-quoting rules. A repository path containing a newline, backslash, double quote, or other special character produces a malformed patch header, so git apply rejects the cumulative diff and the engine permanently pauses mirror sync for that thread. Consider applying Git's path-escaping (the \" and \\ doubling plus the \"...\" quoting form with \n-escaped newlines) before interpolating paths, or reject paths that require quoting as a PauseSync rather than emitting a patch git apply cannot parse.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/provider/Layers/aether/mirrorSync.ts around line 178:

`renderTextFilePatch` interpolates raw file paths directly into unified-diff header lines like `diff --git a/${oldPath} b/${newPath}` without Git's path-quoting rules. A repository path containing a newline, backslash, double quote, or other special character produces a malformed patch header, so `git apply` rejects the cumulative diff and the engine permanently pauses mirror sync for that thread. Consider applying Git's path-escaping (the `\"` and `\\` doubling plus the `\"...\"` quoting form with `\n`-escaped newlines) before interpolating paths, or reject paths that require quoting as a `PauseSync` rather than emitting a patch `git apply` cannot parse.

[macroscopeapp]

🟠 High Layers/AetherAdapter.ts:1229

In REST-only mode (socket === undefined), ensureTaskPipeline returns immediately without calling context.reconcile. On resume of a task whose status is processing, context.activeTurn is initially undefined and turn adoption only happens inside processMapperEvents — which is driven by the reconcile that was just skipped. startSettlePoll is also never armed because its loop condition checks context.activeTurn and context.deferredTurns, both empty at this point. The result is a resumed processing session receives no durable feed updates or turn settlement until the user sends another message, even though the comment on line 1231 states the settle backstop poll is the only feed in REST-only mode. Consider triggering an initial reconcile (and arming the settle poll when adoption is pending) before returning in the REST-only branch.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/provider/Layers/AetherAdapter.ts around line 1229:

In REST-only mode (`socket === undefined`), `ensureTaskPipeline` returns immediately without calling `context.reconcile`. On resume of a task whose status is `processing`, `context.activeTurn` is initially `undefined` and turn adoption only happens inside `processMapperEvents` — which is driven by the reconcile that was just skipped. `startSettlePoll` is also never armed because its loop condition checks `context.activeTurn` and `context.deferredTurns`, both empty at this point. The result is a resumed processing session receives no durable feed updates or turn settlement until the user sends another message, even though the comment on line 1231 states the settle backstop poll is the only feed in REST-only mode. Consider triggering an initial `reconcile` (and arming the settle poll when adoption is pending) before returning in the REST-only branch.

[macroscopeapp]

🟠 High aether/mirrorSync.ts:516

applyBinaries processes each binary entry one at a time, so cumulative diffs with overlapping old/new paths across entries corrupt the mirror. For example, if one entry renames a→b and a later entry deletes b, the rename writes b and the subsequent deletion removes it — the sync then fingerprints and reports success with b missing. The entries are validated in a two-phase pass but written in a single interleaved loop, so removals from later entries clobber new paths written by earlier ones. Consider removing all old paths in a separate pass before writing any new targets.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/provider/Layers/aether/mirrorSync.ts around line 516:

`applyBinaries` processes each binary entry one at a time, so cumulative diffs with overlapping old/new paths across entries corrupt the mirror. For example, if one entry renames `a`→`b` and a later entry deletes `b`, the rename writes `b` and the subsequent deletion removes it — the sync then fingerprints and reports success with `b` missing. The entries are validated in a two-phase pass but written in a single interleaved loop, so removals from later entries clobber new paths written by earlier ones. Consider removing all old paths in a separate pass before writing any new targets.

[macroscopeapp]

🟠 High provider/AetherMirrorRegistry.ts:30

ownsCwd, ownsTargetPath, and ownsPathWithin return false when a mirror is registered via its real path but an RPC passes a symlinked path to the same checkout. The write guard is bypassed, allowing mutation of the driver-owned mirror that the registry is meant to protect. normalize uses only NodePath.resolve, which collapses ../. but does not resolve filesystem symlinks, so the registered real path and the symlinked lookup path produce different keys. Consider canonicalizing with realpath (or the nearest existing parent's realpath) on both registration and lookup.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/provider/AetherMirrorRegistry.ts around line 30:

`ownsCwd`, `ownsTargetPath`, and `ownsPathWithin` return `false` when a mirror is registered via its real path but an RPC passes a symlinked path to the same checkout. The write guard is bypassed, allowing mutation of the driver-owned mirror that the registry is meant to protect. `normalize` uses only `NodePath.resolve`, which collapses `..`/`.` but does not resolve filesystem symlinks, so the registered real path and the symlinked lookup path produce different keys. Consider canonicalizing with `realpath` (or the nearest existing parent's `realpath`) on both registration and lookup.

[macroscopeapp]

🟡 Medium textGeneration/AetherTextGeneration.ts:67

stubBranchName sanitizes the message up to 64 chars before appending -${isoDate}, then sanitizes the combined string with the same 64-char limit. When the message slug is already 64 chars, the second sanitizeBranchFragment call truncates the entire date suffix, so stubBranchName returns identical branches for different dates and can collide with an existing branch. Reserve space for the date suffix before truncating the message slug.

+export function stubBranchName(message: string, isoDate: string): string {
+  const dateSuffix = `-${isoDate}`;
+  const messageSlug = sanitizeBranchFragment(message).slice(0, 64 - dateSuffix.length);
+  return sanitizeBranchFragment(`${messageSlug}${dateSuffix}`);
+}

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/textGeneration/AetherTextGeneration.ts around lines 67-69:

`stubBranchName` sanitizes the message up to 64 chars before appending `-${isoDate}`, then sanitizes the combined string with the same 64-char limit. When the message slug is already 64 chars, the second `sanitizeBranchFragment` call truncates the entire date suffix, so `stubBranchName` returns identical branches for different dates and can collide with an existing branch. Reserve space for the date suffix before truncating the message slug.

[macroscopeapp]

🟠 High aether/terminalConnection.ts:275

The create and resize sends in attachOnce call socket.send(...) directly. If send throws (e.g., the socket closed immediately after openSocket succeeded), the throw is an Effect defect rather than a typed error. runLifecycle catches only typed errors via Effect.catch, so the fork dies without failing ready, and openAetherTerminalConnection blocks forever at Deferred.await(ready). Consider wrapping the pre-ready send calls in Effect.try so a throw fails ready as a typed error.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/provider/Layers/aether/terminalConnection.ts around line 275:

The create and resize sends in `attachOnce` call `socket.send(...)` directly. If `send` throws (e.g., the socket closed immediately after `openSocket` succeeded), the throw is an Effect defect rather than a typed error. `runLifecycle` catches only typed errors via `Effect.catch`, so the fork dies without failing `ready`, and `openAetherTerminalConnection` blocks forever at `Deferred.await(ready)`. Consider wrapping the pre-ready `send` calls in `Effect.try` so a throw fails `ready` as a typed error.

[macroscopeapp]

🔴 Critical aether/mirrorSync.ts:463

resolveInMirror validates only the lexical path, so a binary newPath that names an existing symlink inside the checkout passes validation. fs.writeFile follows the symlink and writes outside cwd, letting a hostile or compromised workspace overwrite arbitrary files writable by the server process. The same applies to fs.mkdir(NodePath.dirname(target)), which can create directories outside the checkout through a symlinked parent. Consider resolving and validating the real filesystem path (or using symlink-safe open semantics) before any write.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/provider/Layers/aether/mirrorSync.ts around line 463:

`resolveInMirror` validates only the lexical path, so a binary `newPath` that names an existing symlink inside the checkout passes validation. `fs.writeFile` follows the symlink and writes outside `cwd`, letting a hostile or compromised workspace overwrite arbitrary files writable by the server process. The same applies to `fs.mkdir(NodePath.dirname(target))`, which can create directories outside the checkout through a symlinked parent. Consider resolving and validating the real filesystem path (or using symlink-safe open semantics) before any write.

[macroscopeapp]

🟡 Medium aether/workspaceSocket.ts:808

When the router receives a closed signal, it enqueues the signal to routed and exits without failing the entries in pending. If onConnected or onEvent is currently awaiting requestGitDiff or readWorkspaceFile, the consumer cannot process the queued closed until that handler returns — but the in-flight request cannot return until its 30-second timeout. A dropped socket therefore stalls disconnect notification and reconnection for up to requestTimeoutMs instead of immediately failing with AetherWorkspaceDetachedError. The router should fail all pending deferreds as soon as it observes closed, before enqueuing the signal to routed.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/provider/Layers/aether/workspaceSocket.ts around line 808:

When the router receives a `closed` signal, it enqueues the signal to `routed` and exits without failing the entries in `pending`. If `onConnected` or `onEvent` is currently awaiting `requestGitDiff` or `readWorkspaceFile`, the consumer cannot process the queued `closed` until that handler returns — but the in-flight request cannot return until its 30-second timeout. A dropped socket therefore stalls disconnect notification and reconnection for up to `requestTimeoutMs` instead of immediately failing with `AetherWorkspaceDetachedError`. The router should fail all pending deferreds as soon as it observes `closed`, before enqueuing the signal to `routed`.

[macroscopeapp]

Reviewed the new Aether provider service code against the Effect service conventions. Six concrete issues, all in files added by this PR: a standalone service-shape interface, service instances injected into a production factory, Effect.catchTag instead of Effect.catchTags, and three error-modeling sites that stringify a cause into detail/message or drop the underlying error entirely. Everything else (namespace subpath imports, make/layer exports, no ManagedRuntime/runPromise in domain code) looks consistent with the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

🟠 High terminal/AetherTerminalManager.ts:475

In attachStream, the listener is added to target.listeners before the initial snapshot or error replay is sent. If either of those listener calls defects, or if the attach fiber is interrupted before the unsubscribe function is returned, the stale listener stays in the set. Subsequent terminal output is delivered to all listeners inside drainLoop; when delivery hits the dead listener it raises a defect, terminating the drain fiber. After that, all further output for that terminal stops being recorded or delivered to the remaining healthy clients. The fix is to remove the listener from the set when the initial delivery fails or when the attach is interrupted, so the scope guarantees cleanup even when no unsubscribe function is returned.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/terminal/AetherTerminalManager.ts around line 475:

In `attachStream`, the listener is added to `target.listeners` before the initial snapshot or error replay is sent. If either of those listener calls defects, or if the attach fiber is interrupted before the unsubscribe function is returned, the stale listener stays in the set. Subsequent terminal output is delivered to all listeners inside `drainLoop`; when delivery hits the dead listener it raises a defect, terminating the drain fiber. After that, all further output for that terminal stops being recorded or delivered to the remaining healthy clients. The fix is to remove the listener from the set when the initial delivery fails or when the attach is interrupted, so the scope guarantees cleanup even when no unsubscribe function is returned.

[macroscopeapp]

🟠 High aether/workspaceSocket.ts:703

The socket loop treats a non-throwing socket.send(subscribe) as proof that the subscription succeeded: it immediately resets consecutiveFailures, sets everConnected = true, and invokes onConnected, which starts reconciliation. But a server can close right after the open event — the close signal is already in the queue — and WebSocket.send() silently discards data when the socket is in CLOSING/CLOSED state. The code proceeds to run onConnected reconciliation against a dead connection, and any correlated git/files request issued there waits the full requestTimeoutMs (30s default) before the queued close is consumed and reconnection begins. The closed signal should be consumed before declaring the connection live, or the subscribe/onConnected work should race against the already-queued close rather than treating a non-throwing send as a successful subscription.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/provider/Layers/aether/workspaceSocket.ts around line 703:

The socket loop treats a non-throwing `socket.send(subscribe)` as proof that the subscription succeeded: it immediately resets `consecutiveFailures`, sets `everConnected = true`, and invokes `onConnected`, which starts reconciliation. But a server can close right after the `open` event — the close signal is already in the queue — and `WebSocket.send()` silently discards data when the socket is in `CLOSING`/`CLOSED` state. The code proceeds to run `onConnected` reconciliation against a dead connection, and any correlated git/files request issued there waits the full `requestTimeoutMs` (30s default) before the queued close is consumed and reconnection begins. The `closed` signal should be consumed before declaring the connection live, or the subscribe/`onConnected` work should race against the already-queued close rather than treating a non-throwing `send` as a successful subscription.

[macroscopeapp]

🟠 High terminal/AetherTerminalManager.ts:570

close deletes the session from sessions (line 574) before closeOne runs, so if closeOne fails or is interrupted before teardownConnection, the live cloud shell and socket are orphaned — the manager's shutdown finalizer only closes sessions still in the map. The session must be removed from the map only after teardown is guaranteed.

      for (const key of keys) {
        const session = sessions.get(key);
        if (!session) continue;
        yield* closeOne(session);
+        sessions.delete(key);
      }

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/terminal/AetherTerminalManager.ts around lines 570-577:

`close` deletes the session from `sessions` (line 574) before `closeOne` runs, so if `closeOne` fails or is interrupted before `teardownConnection`, the live cloud shell and socket are orphaned — the manager's shutdown finalizer only closes sessions still in the map. The session must be removed from the map only after teardown is guaranteed.

[macroscopeapp]

Effect service conventions review of the Aether provider changes at this head.

The findings from the previous run (standalone AetherTerminalManagerShape, service instances passed into makeAetherAdapter, catchTag, and the errors that lost their cause) are unchanged at this commit and are not re-posted — later commits on this branch address them.

One new item below, in packages/contracts/src/project.ts.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Follow-up review of the convention fixes since the last run (4427f33, 8155f4c, 3ae2e17). Three items remain in the changed scope: two wrapper detail fields still derive their message from the stringified/underlying error, and the mirror-refusal refactor dropped the legacy decoded-message passthrough for the project file errors.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

🟠 High Layers/AetherAdapter.ts:2312

interruptTurn ignores its _turnId argument and always stops whatever turn is currently active. If an interrupt for turn A arrives after A has settled and turn B has started, this handler calls stopTask and interrupts B instead of rejecting the stale turn id. The supplied turnId should be checked against the active and deferred turns before stopping the remote task.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/provider/Layers/AetherAdapter.ts around line 2312:

`interruptTurn` ignores its `_turnId` argument and always stops whatever turn is currently active. If an interrupt for turn A arrives after A has settled and turn B has started, this handler calls `stopTask` and interrupts B instead of rejecting the stale turn id. The supplied `turnId` should be checked against the active and deferred turns before stopping the remote task.

[macroscopeapp]

🟠 High Layers/AetherAdapter.ts:2058

sendTurn calls createTask without an idempotency key. If Aether commits the task but the 202 response is lost (timeout, dropped connection), the effect fails before context.taskId is assigned on line 2073. Retrying the same first turn sees context.taskId === undefined and creates a second cloud task, leaving the original task orphaned and executing the prompt twice. Consider adding an idempotency key to createTask so a retry after a lost 202 resolves to the original task instead of creating a duplicate.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/provider/Layers/AetherAdapter.ts around line 2058:

`sendTurn` calls `createTask` without an idempotency key. If Aether commits the task but the 202 response is lost (timeout, dropped connection), the effect fails before `context.taskId` is assigned on line 2073. Retrying the same first turn sees `context.taskId === undefined` and creates a second cloud task, leaving the original task orphaned and executing the prompt twice. Consider adding an idempotency key to `createTask` so a retry after a lost 202 resolves to the original task instead of creating a duplicate.