feat(mirror): project files can stay on the client while agents run on the host

apps/desktop/src/settings/DesktopClientSettings.test.ts

@@ -39,6 +39,7 @@ const clientSettings: ClientSettings = {
   planModeEnabled: false,
   showSkillsInSlashMenu: false,
   providerModelPreferences: {},
+  reactGrabEnabled: false,
   sidebarAutoSettleAfterDays: 3,
   sidebarAutoSettleOnMerge: true,
   sidebarProjectGroupingMode: "repository_path",

apps/server/integration/OrchestrationEngineHarness.integration.ts

@@ -47,6 +47,7 @@ import {
 import { ProviderService } from "../src/provider/Services/ProviderService.ts";
 import { AnalyticsService } from "../src/telemetry/Services/AnalyticsService.ts";
 import { CheckpointReactorLive } from "../src/orchestration/Layers/CheckpointReactor.ts";
+import * as MirrorServiceModule from "../src/mirror/MirrorService.ts";
 import * as RepositoryIdentityResolver from "../src/project/RepositoryIdentityResolver.ts";
 import { OrchestrationEngineLive } from "../src/orchestration/Layers/OrchestrationEngine.ts";
 import { OrchestrationProjectionPipelineLive } from "../src/orchestration/Layers/ProjectionPipeline.ts";
@@ -64,6 +65,7 @@ import {
   type OrchestrationEngineShape,
 } from "../src/orchestration/Services/OrchestrationEngine.ts";
 import { ThreadDeletionReactor } from "../src/orchestration/Services/ThreadDeletionReactor.ts";
+import { MirrorProjectDeletionReactor } from "../src/orchestration/Services/MirrorProjectDeletionReactor.ts";
 import { OrchestrationReactor } from "../src/orchestration/Services/OrchestrationReactor.ts";
 import { ProjectionSnapshotQuery } from "../src/orchestration/Services/ProjectionSnapshotQuery.ts";
 import {
@@ -333,12 +335,14 @@ export const makeOrchestrationIntegrationHarness = (
       generateThreadTitle: () => Effect.succeed({ title: "New thread" }),
     } as unknown as TextGenerationShape);
     const providerCommandReactorLayer = ProviderCommandReactorLive.pipe(
+      Layer.provideMerge(MirrorServiceModule.layerTest),
       Layer.provideMerge(runtimeServicesLayer),
       Layer.provideMerge(gitWorkflowLayer),
       Layer.provideMerge(textGenerationLayer),
       Layer.provideMerge(serverSettingsLayer),
     );
     const checkpointReactorLayer = CheckpointReactorLive.pipe(
+      Layer.provideMerge(MirrorServiceModule.layerTest),
       Layer.provideMerge(runtimeServicesLayer),
       Layer.provideMerge(
         Layer.succeed(VcsStatusBroadcaster, {
@@ -376,6 +380,12 @@ export const makeOrchestrationIntegrationHarness = (
           drainThrough: () => Effect.void,
         }),
       ),
+      Layer.provideMerge(
+        Layer.succeed(MirrorProjectDeletionReactor, {
+          start: () => Effect.void,
+          drain: Effect.void,
+        }),
+      ),
       Layer.provideMerge(
         Layer.succeed(AgentAwarenessRelay.AgentAwarenessRelay, {
           publishThread: () => Effect.void,

apps/server/src/auth/RpcAuthorization.ts

@@ -1,5 +1,6 @@
 import {
   AuthAccessReadScope,
+  AuthMirrorSyncScope,
   AuthOrchestrationOperateScope,
   AuthOrchestrationReadScope,
   AuthRelayReadScope,
@@ -121,6 +122,18 @@ export const RPC_REQUIRED_SCOPES = {
   [WS_METHODS.previewAutomationConnect]: AuthOrchestrationOperateScope,
   [WS_METHODS.previewAutomationRespond]: AuthOrchestrationOperateScope,
   [WS_METHODS.previewAutomationFocusHost]: AuthOrchestrationOperateScope,
+  // Minting a peer credential is part of mirror setup, not access
+  // administration: the issued token is scoped to mirror:sync only, so a
+  // standard-paired client that can already run agents may create it.
+  [WS_METHODS.mirrorCreatePeerCredential]: AuthOrchestrationOperateScope,
+  [WS_METHODS.mirrorAttach]: AuthOrchestrationOperateScope,
+  [WS_METHODS.mirrorDetach]: AuthOrchestrationOperateScope,
+  // Listing this device's shared folders is read-only introspection.
+  [WS_METHODS.mirrorListLinks]: AuthOrchestrationReadScope,
+  [WS_METHODS.mirrorConnect]: AuthMirrorSyncScope,
+  [WS_METHODS.mirrorRespond]: AuthMirrorSyncScope,
+  [WS_METHODS.mirrorRequestSync]: AuthOrchestrationOperateScope,
+  [WS_METHODS.subscribeMirrorStatus]: AuthOrchestrationReadScope,
   [WS_METHODS.subscribePreviewEvents]: AuthOrchestrationReadScope,
   [WS_METHODS.subscribeDiscoveredLocalServers]: AuthOrchestrationReadScope,
   [WS_METHODS.subscribeServerConfig]: AuthOrchestrationReadScope,

apps/server/src/config.ts

@@ -37,6 +37,7 @@ export interface ServerDerivedPaths {
   readonly environmentThemesDir: string;
   readonly providerStatusCacheDir: string;
   readonly worktreesDir: string;
+  readonly mirrorsDir: string;
   readonly attachmentsDir: string;
   readonly logsDir: string;
   readonly serverLogPath: string;
@@ -124,6 +125,7 @@ export const deriveServerPaths = Effect.fn(function* (
     environmentThemesDir: join(stateDir, "themes"),
     providerStatusCacheDir,
     worktreesDir: join(baseDir, "worktrees"),
+    mirrorsDir: join(baseDir, "mirrors"),
     attachmentsDir,
     logsDir,
     serverLogPath: join(logsDir, "server.log"),
@@ -150,6 +152,7 @@ export const ensureServerDirectories = Effect.fn(function* (derivedPaths: Server
       fs.makeDirectory(derivedPaths.terminalLogsDir, { recursive: true }),
       fs.makeDirectory(derivedPaths.attachmentsDir, { recursive: true }),
       fs.makeDirectory(derivedPaths.worktreesDir, { recursive: true }),
+      fs.makeDirectory(derivedPaths.mirrorsDir, { recursive: true }),
       fs.makeDirectory(path.dirname(derivedPaths.keybindingsConfigPath), { recursive: true }),
       fs.makeDirectory(path.dirname(derivedPaths.settingsPath), { recursive: true }),
       fs.makeDirectory(derivedPaths.providerStatusCacheDir, { recursive: true }),

apps/server/src/environment/ServerEnvironment.ts

@@ -159,6 +159,7 @@ export const make = Effect.gen(function* () {
       threadPinning: true,
       threadPinReorder: true,
       threadTitleRegeneration: true,
+      projectMirroring: true,
       threadPullRequestLinking: true,
       ...(serverSelfUpdate === null ? {} : { serverSelfUpdate }),
       ...(serverSelfUpdate === "boot-service" ? { serverSelfUpdateProgress: true } : {}),

apps/server/src/http.ts

@@ -29,6 +29,7 @@ import { OtlpTracer } from "effect/unstable/observability";
 
 import * as ServerConfig from "./config.ts";
 import { ASSET_ROUTE_PREFIX, resolveAsset } from "./assets/AssetAccess.ts";
+import { MIRROR_BUNDLE_ROUTE_PREFIX, MirrorBundleTransfer } from "./mirror/MirrorBundleTransfer.ts";
 import {
   ATTACHMENT_UPLOAD_ROUTE_PREFIX,
   storeAttachmentUpload,
@@ -290,6 +291,88 @@ export const assetRouteLayer = HttpRouter.add(
   }),
 );
 
+/**
+ * Git bundle transfer for project mirroring. The HMAC-signed single-use
+ * token in the path is the entire authorization (the asset-access pattern):
+ * origin agents PUT sync/seed bundles up and GET apply-back bundles down.
+ * Bundle bytes deliberately bypass the JSON RPC WebSocket.
+ */
+const resolveBundleTransfer = (direction: "upload" | "download") =>
+  Effect.gen(function* () {
+    const request = yield* HttpServerRequest.HttpServerRequest;
+    const url = HttpServerRequest.toURL(request);
+    if (Option.isNone(url)) return null;
+    const token = url.value.pathname.slice(`${MIRROR_BUNDLE_ROUTE_PREFIX}/`.length);
+    if (token.length === 0 || token.includes("/")) return null;
+    const transfer = yield* MirrorBundleTransfer;
+    return yield* transfer.resolve(token, direction);
+  });
+
+export const mirrorBundleRouteLayer = Layer.mergeAll(
+  HttpRouter.add(
+    "GET",
+    `${MIRROR_BUNDLE_ROUTE_PREFIX}/*`,
+    Effect.gen(function* () {
+      const resolved = yield* resolveBundleTransfer("download");
+      if (resolved === null) {
+        return HttpServerResponse.text("Not Found", { status: 404 });
+      }
+      return yield* HttpServerResponse.file(resolved.bundlePath, {
+        status: 200,
+        headers: {
+          "Cache-Control": "no-store",
+          "X-Content-Type-Options": "nosniff",
+        },
+      }).pipe(
+        Effect.orElseSucceed(() =>
+          HttpServerResponse.text("Internal Server Error", { status: 500 }),
+        ),
+      );
+    }),
+  ),
+  HttpRouter.add(
+    "PUT",
+    `${MIRROR_BUNDLE_ROUTE_PREFIX}/*`,
+    Effect.gen(function* () {
+      const resolved = yield* resolveBundleTransfer("upload");
+      if (resolved === null) {
+        return HttpServerResponse.text("Not Found", { status: 404 });
+      }
+      const request = yield* HttpServerRequest.HttpServerRequest;
+      const fileSystem = yield* FileSystem.FileSystem;
+      const transfer = yield* MirrorBundleTransfer;
+      // Feed the live status stream: count bytes as they land so seeding
+      // and syncing can show transfer progress.
+      const contentLength = Number.parseInt(request.headers["content-length"] ?? "", 10);
+      const totalBytes = Number.isFinite(contentLength) && contentLength > 0 ? contentLength : null;
+      let receivedBytes = 0;
+      const counted = request.stream.pipe(
+        Stream.tap((chunk) => {
+          receivedBytes += chunk.byteLength;
+          return transfer.trackUpload({
+            projectId: resolved.projectId,
+            syncId: resolved.syncId,
+            bytes: receivedBytes,
+            totalBytes,
+          });
+        }),
+      );
+      const written = yield* Stream.run(counted, fileSystem.sink(resolved.bundlePath)).pipe(
+        Effect.result,
+        Effect.ensuring(transfer.clearUpload(resolved.syncId)),
+      );
+      if (written._tag === "Failure") {
+        yield* fileSystem.remove(resolved.bundlePath, { force: true }).pipe(Effect.ignore);
+        yield* Effect.logWarning("Mirror bundle upload failed mid-stream.", {
+          syncId: resolved.syncId,
+        });
+        return HttpServerResponse.text("Bad Request", { status: 400 });
+      }
+      return HttpServerResponse.empty({ status: 204 });
+    }),
+  ),
+);
+
 export const attachmentUploadRouteLayer = HttpRouter.add(
   "POST",
   `${ATTACHMENT_UPLOAD_ROUTE_PREFIX}/*`,