@ricsam/r5d-worker 0.0.101 → 0.0.103

package/dist/mjs/main.mjs

@@ -34,6 +34,8 @@ import {
   runWorkspaceCommand
 } from "./workspace-command-sync-policy.mjs";
 import { WorkspaceMutationGate } from "./workspace-mutation-gate.mjs";
+import { WorkspaceProjectionLedger } from "./workspace-projection-ledger.mjs";
+import { WorkspaceSyncCoalescer } from "./workspace-sync-coalescer.mjs";
 import { checkoutPathMovePublicationComplete, preserveProjectCheckoutPathMove } from "./workspace-path-move.mjs";
 import { busyProjectConfigurationChangeIds, deferredProjectConfigurationPendingBranches } from "./workspace-project-config-policy.mjs";
 import { creatorLocalProjectBranchIsAuthorized, workerProjectBranchDisposition } from "./workspace-preserve-only-policy.mjs";
@@ -58,7 +60,7 @@ import { assertDisjointManagedRoots, managedProjectRoot, validateManagedBranchNa
 import {
   applyObservedProjectMirrorHeads,
   assertProjectMirrorHeadsPushed,
-  computeLocalProjectMirrorRefsToken,
+  computeLocalProjectMirrorRefsTokens,
   createOrRetryLinkedProjectBranch,
   deleteLinkedProjectBranch,
   deleteProjectMirrorBranch,
@@ -71,7 +73,10 @@ import {
   pushProjectMirrorHeads,
   removeProjectWorktrees
 } from "./project-worktrees.mjs";
-import { projectMirrorFetchDecision } from "./project-mirror-fetch-policy.mjs";
+import {
+  parseProjectMirrorRefsTokensMessage,
+  planProjectMirrorObservationFetch
+} from "./project-mirror-fetch-policy.mjs";
 import {
   PROJECT_SNAPSHOT_RECOVERY_HELPER_COMMAND,
   recoverProjectSnapshotsInChild,
@@ -182,6 +187,12 @@ const workspaceSyncSingleFlight = {
   acquireMutation() {
     return workspaceMutationGate.acquireMutation();
   },
+  runBranchMutation(operation) {
+    return workspaceMutationGate.runBranchMutation(operation);
+  },
+  branchMutationQueuePosition() {
+    return workspaceMutationGate.branchMutationQueuePosition();
+  },
   afterCurrent() {
     return workspaceSyncQueue;
   }
@@ -312,6 +323,7 @@ const workerPtyTestHarness = {
   removeEnvFiles: removePtyEnvFiles,
   resolveEnvFileReferences: resolvePtyEnvFileReferences,
   commandHasWorkspaceEffect: workerCommandHasWorkspaceEffect,
+  targetProcessEnv,
   canonicalSyncTerminalHead,
   ptyIsWorkspaceBusy: workerPtyIsWorkspaceBusy,
   parseLinuxForegroundBusy: parseLinuxPtyForegroundBusy
@@ -319,21 +331,12 @@ const workerPtyTestHarness = {
 function defaultConfigPath() {
   return path.join(os.homedir(), ".config", "r5d", "r5dctl", "config.json");
 }
-function defaultProjectsRoot() {
-  return path.join(os.homedir(), ".r5d", "projects");
-}
-function defaultSyncRoot() {
-  return path.join(os.homedir(), ".r5d", "sync");
-}
-function defaultArtifactRoot() {
-  return path.join(os.homedir(), ".r5d", "artifacts");
-}
-function defaultPlanRoot() {
-  return path.join(os.homedir(), ".r5d", "plans");
+function defaultRootDir() {
+  return path.join(os.homedir(), ".r5d");
 }
 function printHelp() {
   process.stdout.write(`Usage:
-  r5d-worker start --label <label> [--base-url <url>] [--token <token>] [--api-key <key>]
+  r5d-worker start --label <label> [--root <dir>] [--base-url <url>] [--token <token>] [--api-key <key>]
   r5d-worker --version
 
 Options:
@@ -342,10 +345,7 @@ Options:
   --token <token>       r5d worker token
   --api-key <key>       r5d API key
   --config <path>       Config path (default ~/.config/r5d/r5dctl/config.json)
-  --project-root <dir>  Override projects checkout root (default ~/.r5d/projects)
-  --sync-root <dir>     Override r5d internal sync git root (default ~/.r5d/sync)
-  --artifact-root <dir> Override session artifact root (default from R5D_ARTIFACTS_ROOT or ~/.r5d/artifacts)
-  --plan-root <dir>     Override synced plan root (default from R5D_PLANS_ROOT or ~/.r5d/plans)
+  --root <dir>          Override worker data root (default from R5D_ROOT or ~/.r5d)
   -v, --version         Show r5d-worker version
   -h, --help            Show this help
 `);
@@ -460,24 +460,9 @@ function parseArgs(argv) {
       options.label = label;
       continue;
     }
-    const projectRoot = readOption("--project-root");
-    if (projectRoot !== void 0) {
-      options.projectRoot = projectRoot;
-      continue;
-    }
-    const syncRoot = readOption("--sync-root");
-    if (syncRoot !== void 0) {
-      options.syncRoot = syncRoot;
-      continue;
-    }
-    const artifactRoot = readOption("--artifact-root");
-    if (artifactRoot !== void 0) {
-      options.artifactRoot = artifactRoot;
-      continue;
-    }
-    const planRoot = readOption("--plan-root");
-    if (planRoot !== void 0) {
-      options.planRoot = planRoot;
+    const rootDir = readOption("--root");
+    if (rootDir !== void 0) {
+      options.rootDir = rootDir;
       continue;
     }
     rest.push(arg);
@@ -522,11 +507,9 @@ async function readResponseText(response) {
     return "";
   }
 }
-const R5D_ARTIFACTS_DIR_REF = "$R5D_ARTIFACTS_DIR";
-const R5D_PLANS_DIR_REF = "$R5D_PLANS_DIR";
-const R5D_ACTIVE_PLAN_FILE_REF = "$R5D_ACTIVE_PLAN_FILE";
-const R5D_PLANS_DIR_ENV = "R5D_PLANS_DIR";
-const BUILT_IN_TOOL_PATH_REFS = [R5D_ARTIFACTS_DIR_REF, R5D_PLANS_DIR_REF, R5D_ACTIVE_PLAN_FILE_REF];
+const R5D_ROOT_REF = "$R5D_ROOT";
+const R5D_ROOT_ENV = "R5D_ROOT";
+const BUILT_IN_TOOL_PATH_REFS = [R5D_ROOT_REF];
 function parseBuiltInToolPath(inputPath) {
   const normalized = inputPath.replace(/\\/g, "/");
   const match = /^\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))(?:\/(.*))?$/.exec(normalized);
@@ -542,6 +525,26 @@ function parseBuiltInToolPath(inputPath) {
     relativePath: match[3] ?? ""
   };
 }
+function expandRootPathSegments(relativePath, builtInPaths) {
+  const values = {
+    R5D_SESSION_ID: builtInPaths.sessionId,
+    R5D_PROJECT_ID: builtInPaths.projectId,
+    R5D_BRANCH_NAME: builtInPaths.branchName,
+    R5D_ACTIVE_PLAN_ID: builtInPaths.activePlanId
+  };
+  let expandedPath = relativePath;
+  for (const [variableName, value] of Object.entries(values)) {
+    const variablePattern = new RegExp(`\\$(?:\\{${variableName}\\}|${variableName})(?=\\/|\\.|$)`, "g");
+    if (!variablePattern.test(expandedPath)) continue;
+    if (!value) throw new Error(`$${variableName} is unavailable for this worker path`);
+    expandedPath = expandedPath.replace(variablePattern, value);
+  }
+  const unsupportedVariable = /\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/.exec(expandedPath);
+  if (unsupportedVariable) {
+    throw new Error(`Unsupported ${R5D_ROOT_REF} path variable "$${unsupportedVariable[1] ?? unsupportedVariable[2]}"`);
+  }
+  return expandedPath.split("/").filter(Boolean);
+}
 function validateArtifactSessionId(sessionId) {
   if (!/^(migration-)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(sessionId)) {
     throw new Error(`Invalid artifact session id: ${sessionId}`);
@@ -557,14 +560,6 @@ function sessionArtifactDir(artifactRoot, sessionId) {
   validateArtifactSessionId(sessionId);
   return path.join(artifactRoot, sessionId);
 }
-function artifactEnv(artifactRoot, sessionId) {
-  if (!sessionId) {
-    return {};
-  }
-  return {
-    R5D_ARTIFACTS_DIR: sessionArtifactDir(artifactRoot, sessionId)
-  };
-}
 function projectPlanDir(planRoot, projectId, branchName) {
   validateProjectId(projectId);
   validateBranchName(branchName);
@@ -577,21 +572,18 @@ function targetPlanDir(planRoot, target) {
   }
   return path.join(planRoot, "workspace");
 }
-function planEnv(planRoot, target, activePlanId) {
-  const plansDir = targetPlanDir(planRoot, target);
-  const env = {
-    [R5D_PLANS_DIR_ENV]: plansDir
-  };
+function planEnv(activePlanId) {
+  const env = {};
   if (activePlanId) {
     validatePlanId(activePlanId);
     env.R5D_ACTIVE_PLAN_ID = activePlanId;
-    env.R5D_ACTIVE_PLAN_FILE = path.join(plansDir, `${activePlanId}.plan.md`);
   }
   return env;
 }
 function isArtifactEnvPath(filePath) {
   try {
-    return parseBuiltInToolPath(filePath)?.ref === R5D_ARTIFACTS_DIR_REF;
+    const parsed = parseBuiltInToolPath(filePath);
+    return parsed?.ref === R5D_ROOT_REF && parsed.relativePath.split("/").filter(Boolean)[0] === "artifacts";
   } catch {
     return false;
   }
@@ -733,48 +725,46 @@ async function prepareBuiltInToolPaths(input) {
   if (!parsed) {
     return void 0;
   }
-  if (parsed.ref === R5D_ARTIFACTS_DIR_REF) {
+  const builtInPaths = {
+    rootDir: input.rootDir,
+    sessionId: input.sessionId,
+    activePlanId: input.activePlanId,
+    ...input.target.type === "project" ? { projectId: input.target.projectId, branchName: input.target.branchName } : {}
+  };
+  const rootPathSegments = expandRootPathSegments(parsed.relativePath, builtInPaths);
+  if (rootPathSegments[0] === "artifacts") {
     if (input.access === "write") {
       throw new Error(
-        `${R5D_ARTIFACTS_DIR_REF} attachments are read-only. Copy them into a project path before editing or creating files.`
+        `${R5D_ROOT_REF}/artifacts attachments are read-only. Copy them into a project path before editing or creating files.`
       );
     }
-    if (!input.sessionId) {
-      throw new Error(`${R5D_ARTIFACTS_DIR_REF} paths require an active chat session`);
-    }
-    return {
-      artifactsDir: await syncSessionArtifacts({
-        baseUrl: input.baseUrl,
-        token: input.token,
-        sessionId: input.sessionId,
-        artifactRoot: input.artifactRoot
-      })
-    };
-  }
-  const plansDir = targetPlanDir(input.planRoot, input.target);
-  fs.mkdirSync(plansDir, { recursive: true });
-  if (parsed.ref === R5D_PLANS_DIR_REF) {
-    return { plansDir };
+    const referencedSessionId = rootPathSegments[1];
+    if (!referencedSessionId) return builtInPaths;
+    validateArtifactSessionId(referencedSessionId);
+    await syncSessionArtifacts({
+      baseUrl: input.baseUrl,
+      token: input.token,
+      sessionId: referencedSessionId,
+      artifactRoot: path.join(input.rootDir, "artifacts")
+    });
   }
-  if (!input.activePlanId) {
-    throw new Error(`${R5D_ACTIVE_PLAN_FILE_REF} paths require an active plan`);
+  if (rootPathSegments[0] === "plans") {
+    fs.mkdirSync(targetPlanDir(path.join(input.rootDir, "plans"), input.target), { recursive: true });
   }
-  validatePlanId(input.activePlanId);
-  return {
-    plansDir,
-    activePlanFile: path.join(plansDir, `${input.activePlanId}.plan.md`)
-  };
+  return builtInPaths;
 }
 async function prepareArtifactEnvForShell(input) {
+  const env = { [R5D_ROOT_ENV]: input.rootDir };
   if (!input.sessionId) {
-    return {};
+    return env;
   }
+  const artifactRoot = path.join(input.rootDir, "artifacts");
   try {
     await syncSessionArtifacts({
       baseUrl: input.baseUrl,
       token: input.token,
       sessionId: input.sessionId,
-      artifactRoot: input.artifactRoot
+      artifactRoot
     });
   } catch (error) {
     process.stderr.write(
@@ -782,16 +772,14 @@ async function prepareArtifactEnvForShell(input) {
 `
     );
   }
-  const artifactsDir = sessionArtifactDir(input.artifactRoot, input.sessionId);
+  const artifactsDir = sessionArtifactDir(artifactRoot, input.sessionId);
   fs.mkdirSync(artifactsDir, { recursive: true });
-  return {
-    R5D_ARTIFACTS_DIR: artifactsDir
-  };
+  return env;
 }
 function preparePlanEnvForShell(input) {
-  const plansDir = targetPlanDir(input.planRoot, input.target);
+  const plansDir = targetPlanDir(path.join(input.rootDir, "plans"), input.target);
   fs.mkdirSync(plansDir, { recursive: true });
-  return planEnv(input.planRoot, input.target, input.activePlanId);
+  return planEnv(input.activePlanId);
 }
 async function verifyR5dctlAuth(baseUrl, token, workerLabel) {
   const statusUrl = new URL("/api/r5dctl/auth/status", baseUrl);
@@ -959,30 +947,17 @@ function resolveVirtualWorkerFilePath(inputPath, parsed, builtInPaths) {
   if (parsed.relativePath.split("/").includes("..")) {
     throw new Error(`Invalid ${parsed.ref} path: ${inputPath}`);
   }
-  let rootPath;
-  let absolutePath;
-  if (parsed.ref === R5D_ARTIFACTS_DIR_REF) {
-    rootPath = builtInPaths?.artifactsDir;
-  } else if (parsed.ref === R5D_PLANS_DIR_REF) {
-    rootPath = builtInPaths?.plansDir;
-  } else {
-    if (parsed.relativePath) {
-      throw new Error(`${R5D_ACTIVE_PLAN_FILE_REF} must reference the active plan file directly`);
-    }
-    rootPath = builtInPaths?.plansDir;
-    absolutePath = builtInPaths?.activePlanFile;
-  }
-  if (!rootPath || parsed.ref === R5D_ACTIVE_PLAN_FILE_REF && !absolutePath) {
-    const requirement = parsed.ref === R5D_ARTIFACTS_DIR_REF ? "an active chat session" : "an active plan";
-    throw new Error(`${parsed.ref} paths require ${requirement}`);
-  }
-  const normalizedPath = parsed.relativePath ? path.posix.normalize(parsed.relativePath).replace(/^\/+|\/+$/g, "") : "";
+  const rootPath = builtInPaths?.rootDir;
+  if (!rootPath) throw new Error(`${R5D_ROOT_REF} paths require an available worker root`);
+  const expandedPath = expandRootPathSegments(parsed.relativePath, builtInPaths);
+  if (expandedPath.includes("..")) throw new Error(`Invalid ${parsed.ref} path: ${inputPath}`);
+  const normalizedPath = expandedPath.length > 0 ? path.posix.normalize(expandedPath.join("/")).replace(/^\/+|\/+$/g, "") : "";
   const normalizedRelativePath = normalizedPath === "." ? "" : normalizedPath;
-  absolutePath ??= normalizedRelativePath ? path.resolve(rootPath, ...normalizedRelativePath.split("/")) : path.resolve(rootPath);
+  const absolutePath = normalizedRelativePath ? path.resolve(rootPath, ...normalizedRelativePath.split("/")) : path.resolve(rootPath);
   assertPathInsideRealRoot(rootPath, absolutePath, `${parsed.ref} path`);
   return {
     absolutePath,
-    displayPath: normalizedRelativePath ? `${parsed.ref}/${normalizedRelativePath}` : parsed.ref,
+    displayPath: parsed.relativePath ? `${parsed.ref}/${parsed.relativePath}` : parsed.ref,
     repoRelativePath: null,
     scope: "virtual",
     virtualRootPath: path.resolve(rootPath)
@@ -2226,8 +2201,7 @@ async function executeReadFileOperation(input) {
     token: input.token,
     sessionId: input.message.sessionId,
     activePlanId: input.message.activePlanId,
-    artifactRoot: input.artifactRoot,
-    planRoot: input.planRoot,
+    rootDir: input.rootDir,
     access: "read"
   });
   return readWorkerTextFile(input.resolvedTarget.rootPath, input.message.filePath, input.message.offset, input.message.limit, builtInPaths);
@@ -2240,8 +2214,7 @@ async function executeWriteFileOperation(input) {
     token: input.token,
     sessionId: input.message.sessionId,
     activePlanId: input.message.activePlanId,
-    artifactRoot: input.artifactRoot,
-    planRoot: input.planRoot,
+    rootDir: input.rootDir,
     access: "write"
   });
   input.assertAdmission();
@@ -2259,8 +2232,7 @@ async function executeEditFileOperation(input) {
     token: input.token,
     sessionId: input.message.sessionId,
     activePlanId: input.message.activePlanId,
-    artifactRoot: input.artifactRoot,
-    planRoot: input.planRoot,
+    rootDir: input.rootDir,
     access: "write"
   });
   input.assertAdmission();
@@ -2387,8 +2359,7 @@ async function executeGrepOperation(input) {
     token: input.token,
     sessionId: input.message.sessionId,
     activePlanId: input.message.activePlanId,
-    artifactRoot: input.artifactRoot,
-    planRoot: input.planRoot,
+    rootDir: input.rootDir,
     access: "read"
   });
   return grepWorkerFiles(
@@ -2446,8 +2417,7 @@ async function executeFindOperation(input) {
     token: input.token,
     sessionId: input.message.sessionId,
     activePlanId: input.message.activePlanId,
-    artifactRoot: input.artifactRoot,
-    planRoot: input.planRoot,
+    rootDir: input.rootDir,
     access: "read"
   });
   return findWorkerFiles(
@@ -2488,8 +2458,7 @@ async function executeLsOperation(input) {
     token: input.token,
     sessionId: input.message.sessionId,
     activePlanId: input.message.activePlanId,
-    artifactRoot: input.artifactRoot,
-    planRoot: input.planRoot,
+    rootDir: input.rootDir,
     access: "read"
   });
   return listWorkerDirectory(input.resolvedTarget.rootPath, input.message.path, input.message.limit, builtInPaths);
@@ -2595,8 +2564,7 @@ async function executeViewFileBytesOperation(input) {
     token: input.token,
     sessionId: input.message.sessionId,
     activePlanId: input.message.activePlanId,
-    artifactRoot: input.artifactRoot,
-    planRoot: input.planRoot,
+    rootDir: input.rootDir,
     access: "read"
   });
   return readWorkerImageFile(input.resolvedTarget.rootPath, input.message.filePath, builtInPaths);
@@ -2636,27 +2604,30 @@ function targetIdentityEnv(target) {
     R5D_BRANCH_NAME: ""
   };
 }
+function targetProcessEnv(rootDir, target) {
+  return { [R5D_ROOT_ENV]: rootDir, ...targetIdentityEnv(target) };
+}
 async function prepareShellEnvForTarget(input) {
   const artifactProcessEnv = await prepareArtifactEnvForShell({
     baseUrl: input.baseUrl,
     token: input.token,
     sessionId: input.sessionId,
-    artifactRoot: input.artifactRoot
+    rootDir: input.rootDir
   });
   if (input.target.type === "workspace" && input.target.rootProfile === "canonical_sync") {
     return {
       ...artifactProcessEnv,
-      ...targetIdentityEnv(input.target)
+      ...targetProcessEnv(input.rootDir, input.target)
     };
   }
   return {
     ...artifactProcessEnv,
     ...preparePlanEnvForShell({
       target: input.target,
-      planRoot: input.planRoot,
+      rootDir: input.rootDir,
       activePlanId: input.activePlanId
     }),
-    ...targetIdentityEnv(input.target)
+    ...targetProcessEnv(input.rootDir, input.target)
   };
 }
 async function executeCommand(input) {
@@ -2671,13 +2642,12 @@ async function executeCommand(input) {
   };
   input.setPreparationHeartbeatLease(true);
   try {
-    const targetProcessEnv = await prepareShellEnvForTarget({
+    const targetProcessEnv2 = await prepareShellEnvForTarget({
       target: input.resolvedTarget.target,
       baseUrl: input.baseUrl,
       token: input.token,
       sessionId: input.message.sessionId,
-      artifactRoot: input.artifactRoot,
-      planRoot: input.planRoot,
+      rootDir: input.rootDir,
       activePlanId: input.message.env?.R5D_ACTIVE_PLAN_ID
     });
     const cwd = resolveCommandCwd(input.resolvedTarget.rootPath, input.message.cwd);
@@ -2687,7 +2657,7 @@ async function executeCommand(input) {
       stdout: "pipe",
       stderr: "pipe",
       detached: true,
-      env: workerChildProcessEnvironment([githubProcessEnv(), input.message.env ?? {}, targetProcessEnv])
+      env: workerChildProcessEnvironment([githubProcessEnv(), input.message.env ?? {}, targetProcessEnv2])
     });
     spawnedProcess = subprocess;
     credentialBearingProcessGroups.set(subprocess.pid, subprocess);
@@ -2776,13 +2746,12 @@ async function executeStreamingCommand(input) {
       });
       return;
     }
-    const targetProcessEnv = await prepareShellEnvForTarget({
+    const targetProcessEnv2 = await prepareShellEnvForTarget({
       target: input.resolvedTarget.target,
       baseUrl: input.baseUrl,
       token: input.token,
       sessionId: input.message.sessionId,
-      artifactRoot: input.artifactRoot,
-      planRoot: input.planRoot,
+      rootDir: input.rootDir,
       activePlanId: input.message.env?.R5D_ACTIVE_PLAN_ID
     });
     const cwd = resolveCommandCwd(input.resolvedTarget.rootPath, input.message.cwd);
@@ -2796,7 +2765,7 @@ async function executeStreamingCommand(input) {
       stdout: "pipe",
       stderr: "pipe",
       detached: true,
-      env: workerChildProcessEnvironment([githubProcessEnv(), input.message.env ?? {}, targetProcessEnv])
+      env: workerChildProcessEnvironment([githubProcessEnv(), input.message.env ?? {}, targetProcessEnv2])
     });
     spawnedProcess = subprocess;
     credentialBearingProcessGroups.set(subprocess.pid, subprocess);
@@ -3260,10 +3229,10 @@ async function openPty(input) {
   }
   const planProcessEnv = !(input.resolvedTarget.target.type === "workspace" && input.resolvedTarget.target.rootProfile === "canonical_sync") ? preparePlanEnvForShell({
     target: input.resolvedTarget.target,
-    planRoot: input.planRoot,
+    rootDir: input.rootDir,
     activePlanId: input.message.env?.R5D_ACTIVE_PLAN_ID
   }) : {};
-  const targetProcessEnv = targetIdentityEnv(input.resolvedTarget.target);
+  const targetEnv = targetProcessEnv(input.rootDir, input.resolvedTarget.target);
   const shell = resolveHostShell(input.message.command);
   const outputCoalescer = createPtyOutputCoalescer({
     send: (data) => {
@@ -3295,7 +3264,7 @@ async function openPty(input) {
           githubProcessEnv(),
           resolvePtyEnvFileReferences(input.message.env ?? {}, stagedEnvFiles),
           planProcessEnv,
-          targetProcessEnv,
+          targetEnv,
           shell.env ?? {}
         ])
       },
@@ -3468,12 +3437,13 @@ async function startWorker(options) {
   initializeCredentialStoreDirectoryOnce();
   const label = requireValue(options.label, "Missing required --label <label>");
   validateLabel(label);
-  const projectsRoot = path.resolve(options.projectRoot ?? defaultProjectsRoot());
-  const syncRoot = path.resolve(options.syncRoot ?? process.env.R5D_SYNC_ROOT ?? defaultSyncRoot());
+  const rootDir = path.resolve(options.rootDir ?? process.env.R5D_ROOT ?? defaultRootDir());
+  const projectsRoot = path.join(rootDir, "projects");
+  const syncRoot = path.join(rootDir, "sync");
   const workspaceShadowRoot = path.join(syncRoot, "workspace");
   const projectWorktreeSnapshotsRoot = path.join(syncRoot, "project-worktree-snapshots");
-  const artifactRoot = path.resolve(options.artifactRoot ?? process.env.R5D_ARTIFACTS_ROOT ?? defaultArtifactRoot());
-  const planRoot = path.resolve(options.planRoot ?? process.env.R5D_PLANS_ROOT ?? defaultPlanRoot());
+  const artifactRoot = path.join(rootDir, "artifacts");
+  const planRoot = path.join(rootDir, "plans");
   assertDisjointManagedRoots([
     { label: "projects root", rootPath: projectsRoot },
     { label: "sync root", rootPath: syncRoot },
@@ -3482,13 +3452,7 @@ async function startWorker(options) {
   ]);
   process.stdout.write(`[r5d-worker] label: ${label}
 `);
-  process.stdout.write(`[r5d-worker] projects root: ${projectsRoot}
-`);
-  process.stdout.write(`[r5d-worker] sync root: ${syncRoot}
-`);
-  process.stdout.write(`[r5d-worker] artifact root: ${artifactRoot}
-`);
-  process.stdout.write(`[r5d-worker] plan root: ${planRoot}
+  process.stdout.write(`[r5d-worker] root: ${rootDir}
 `);
   process.stdout.write(`[r5d-worker] server: ${baseUrl}
 `);
@@ -3513,9 +3477,29 @@ async function startWorker(options) {
   const reconciledProjectConfigFingerprints = /* @__PURE__ */ new Map();
   const lastObservedProjectHeads = /* @__PURE__ */ new Map();
   const advertisedProjectMirrorRefsTokens = /* @__PURE__ */ new Map();
+  const advertisedProjectMirrorMountTokens = /* @__PURE__ */ new Map();
+  let advertisedWorkspaceHead;
   const fetchedProjectMirrorRefsTokens = /* @__PURE__ */ new Map();
-  const lastProjectMirrorFetchAtMs = /* @__PURE__ */ new Map();
+  const fetchedProjectMirrorMountTokens = /* @__PURE__ */ new Map();
   const projectMirrorFetchSkippingEnabled = process.env.R5D_PROJECT_MIRROR_FETCH_SKIP !== "0";
+  const forgetLocalProjectMirrorRefsTokens = (projectId, branchName) => {
+    fetchedProjectMirrorRefsTokens.delete(projectId);
+    if (branchName === void 0) fetchedProjectMirrorMountTokens.delete(projectId);
+    else fetchedProjectMirrorMountTokens.get(projectId)?.delete(branchName);
+  };
+  const recordLocalProjectMirrorRefsTokens = async (project) => {
+    try {
+      const tokens = await computeLocalProjectMirrorRefsTokens({
+        projectRoot: configuredProjectRoot(projectsRoot, project),
+        primaryBranchName: primaryProjectBranch(project),
+        mounts: project.branches.map(({ branchId, branchName }) => ({ branchId, branchName }))
+      });
+      fetchedProjectMirrorRefsTokens.set(project.projectId, tokens.project);
+      fetchedProjectMirrorMountTokens.set(project.projectId, tokens.mounts);
+    } catch {
+      forgetLocalProjectMirrorRefsTokens(project.projectId);
+    }
+  };
   const pendingMirrorDeletes = /* @__PURE__ */ new Map();
   let workspaceRemoteUrl = null;
   let workspaceCredentialHelper = null;
@@ -3530,6 +3514,7 @@ async function startWorker(options) {
   let workspacePeriodicTimer;
   let pendingAutomaticTrigger;
   const pendingCreatedBranchPublicationNotBefore = /* @__PURE__ */ new Map();
+  const workspaceProjectionLedger = new WorkspaceProjectionLedger();
   let automaticSyncInFlight = false;
   let terminalReplayTimer;
   let workspaceSyncRequestsInFlight = 0;
@@ -3899,7 +3884,7 @@ async function startWorker(options) {
       workspaceRelativePath: "workspace-plans",
       sourceMode: "all",
       hydrateDeletionMode: "all",
-      // Workspace-level agents receive this directory through R5D_PLANS_DIR.
+      // Workspace-level agents reach this directory through $R5D_ROOT/plans.
       // Keep both projection and hydration away from it while any visible-
       // projects process, PTY, or built-in write/edit is active or reserved.
       busy: () => {
@@ -3937,7 +3922,10 @@ async function startWorker(options) {
         deleteWhenSourceMissing: true
       });
     }
-    return mounts;
+    return mounts.map((mount) => {
+      const lastProjectedMutationToken = workspaceProjectionLedger.lastProjectedToken(mount);
+      return lastProjectedMutationToken === void 0 ? mount : { ...mount, lastProjectedMutationToken };
+    });
   };
   const workspaceLocalHead = async () => {
     if (!fs.existsSync(path.join(workspaceShadowRoot, ".git"))) return null;
@@ -4162,17 +4150,7 @@ async function startWorker(options) {
       for (const result of results) {
         lastObservedProjectHeads.set(projectBranchKey(project.projectId, result.branchName), result.head);
       }
-      try {
-        fetchedProjectMirrorRefsTokens.set(
-          project.projectId,
-          await computeLocalProjectMirrorRefsToken({
-            projectRoot: configuredProjectRoot(projectsRoot, project),
-            primaryBranchName: primaryProjectBranch(project)
-          })
-        );
-      } catch {
-        fetchedProjectMirrorRefsTokens.delete(project.projectId);
-      }
+      await recordLocalProjectMirrorRefsTokens(project);
     }
     const publishedTombstoneIds = [
       ...new Set(
@@ -4198,7 +4176,7 @@ async function startWorker(options) {
           credentialHelper: deletion.credentialHelper,
           credentialUsername: deletion.credentialUsername
         });
-        fetchedProjectMirrorRefsTokens.delete(deletion.projectId);
+        forgetLocalProjectMirrorRefsTokens(deletion.projectId, deletion.branchName);
       }
       if (deletion.tombstoneId && !deletion.projectDeleted) {
         projectWorkspaceState = projectWorkspaceStateStore.recordMirrorRefDeletion({
@@ -4210,8 +4188,8 @@ async function startWorker(options) {
       if (deletion.projectDeleted && !projectConfigById.has(deletion.projectId) && ![...pendingMirrorDeletes.values()].some((pending) => pending.projectId === deletion.projectId)) {
         removeProjectCredentialStore(deletion.projectId);
         advertisedProjectMirrorRefsTokens.delete(deletion.projectId);
-        fetchedProjectMirrorRefsTokens.delete(deletion.projectId);
-        lastProjectMirrorFetchAtMs.delete(deletion.projectId);
+        advertisedProjectMirrorMountTokens.delete(deletion.projectId);
+        forgetLocalProjectMirrorRefsTokens(deletion.projectId);
       }
       lastObservedProjectHeads.delete(key);
     }
@@ -4220,39 +4198,20 @@ async function startWorker(options) {
     const connection = projectConnection(project);
     const projectRoot = configuredProjectRoot(projectsRoot, project);
     const primaryBranchName = primaryProjectBranch(project);
-    if (options2.refreshRemote) {
-      const advertisedBeforeFetch = advertisedProjectMirrorRefsTokens.get(project.projectId);
-      const observations = await observeProjectMirrorHeads({
-        projectRoot,
-        primaryBranchName,
-        branchNames: project.branches.map(({ branchName }) => branchName),
-        mirrorUrl: connection.mirrorUrl,
-        credentialHelper: connection.credentialHelper,
-        credentialUsername: connection.mirrorCredentialUsername,
-        allowNonFastForward: options2.allowNonFastForward,
-        branchIds: new Map(project.branches.map(({ branchId, branchName }) => [branchName, branchId]))
-      });
-      if (advertisedBeforeFetch === void 0) fetchedProjectMirrorRefsTokens.delete(project.projectId);
-      else fetchedProjectMirrorRefsTokens.set(project.projectId, advertisedBeforeFetch);
-      lastProjectMirrorFetchAtMs.set(project.projectId, Date.now());
-      return { projectId: project.projectId, projectRoot, primaryBranchName, observations };
-    }
-    return {
-      projectId: project.projectId,
+    const observations = await observeProjectMirrorHeads({
       projectRoot,
       primaryBranchName,
-      observations: await observeProjectMirrorHeads({
-        projectRoot,
-        primaryBranchName,
-        branchNames: project.branches.map(({ branchName }) => branchName),
-        mirrorUrl: connection.mirrorUrl,
-        credentialHelper: connection.credentialHelper,
-        credentialUsername: connection.mirrorCredentialUsername,
-        allowNonFastForward: options2.allowNonFastForward,
-        branchIds: new Map(project.branches.map(({ branchId, branchName }) => [branchName, branchId])),
-        refreshRemote: false
-      })
-    };
+      branchNames: project.branches.map(({ branchName }) => branchName),
+      mirrorUrl: connection.mirrorUrl,
+      credentialHelper: connection.credentialHelper,
+      credentialUsername: connection.mirrorCredentialUsername,
+      allowNonFastForward: options2.allowNonFastForward,
+      branchIds: new Map(project.branches.map(({ branchId, branchName }) => [branchName, branchId])),
+      refreshRemote: options2.fetch.scope !== "none",
+      ...options2.fetch.scope === "mounts" ? { fetchOnlyBranches: new Set(options2.fetch.mounts.map(({ branchName }) => branchName)) } : {}
+    });
+    if (options2.fetch.scope !== "none") await recordLocalProjectMirrorRefsTokens(project);
+    return { projectId: project.projectId, projectRoot, primaryBranchName, observations };
   };
   const observeProjectHeadsBeforeOuterWorkspace = async (input) => {
     const observationStartedAt = Date.now();
@@ -4263,28 +4222,39 @@ async function startWorker(options) {
       if (input.failClosed) {
         const bundles2 = [];
         for (const project of eligibleProjects) {
-          bundles2.push(await observeSingleProjectMirrorBundle(project, { allowNonFastForward: input.allowNonFastForward, refreshRemote: true }));
+          bundles2.push(
+            await observeSingleProjectMirrorBundle(project, {
+              allowNonFastForward: input.allowNonFastForward,
+              fetch: { scope: "project", reason: "fail_closed" }
+            })
+          );
         }
         return bundles2;
       }
-      let fetchedCount = 0;
+      let wholeMirrorFetches = 0;
+      let scopedMirrorFetches = 0;
+      let fetchedMounts = 0;
+      let eligibleMounts = 0;
       const bundles = await mapWithConcurrencyLimit(
         eligibleProjects,
         PROJECT_MIRROR_OBSERVE_CONCURRENCY,
         async (project) => {
           try {
-            const decision = projectMirrorFetchDecision({
-              advertisedToken: advertisedProjectMirrorRefsTokens.get(project.projectId),
-              fetchedToken: fetchedProjectMirrorRefsTokens.get(project.projectId),
-              lastFetchAtMs: lastProjectMirrorFetchAtMs.get(project.projectId),
-              nowMs: Date.now(),
+            const fetch2 = planProjectMirrorObservationFetch({
+              branchNames: project.branches.map(({ branchName }) => branchName),
+              advertisedProjectToken: advertisedProjectMirrorRefsTokens.get(project.projectId),
+              advertisedMountTokens: advertisedProjectMirrorMountTokens.get(project.projectId),
+              fetchedProjectToken: fetchedProjectMirrorRefsTokens.get(project.projectId),
+              fetchedMountTokens: fetchedProjectMirrorMountTokens.get(project.projectId) ?? /* @__PURE__ */ new Map(),
               skippingEnabled: projectMirrorFetchSkippingEnabled
             });
-            if (decision.fetch) fetchedCount += 1;
-            return await observeSingleProjectMirrorBundle(project, {
-              allowNonFastForward: input.allowNonFastForward,
-              refreshRemote: decision.fetch
-            });
+            eligibleMounts += project.branches.length;
+            if (fetch2.scope === "project") wholeMirrorFetches += 1;
+            if (fetch2.scope === "mounts") {
+              scopedMirrorFetches += 1;
+              fetchedMounts += fetch2.mounts.length;
+            }
+            return await observeSingleProjectMirrorBundle(project, { allowNonFastForward: input.allowNonFastForward, fetch: fetch2 });
           } catch (error) {
             process.stderr.write(
               `[r5d-worker] failed to observe project mirror heads before workspace update: ${error instanceof Error ? error.message : String(error)}
@@ -4294,9 +4264,9 @@ async function startWorker(options) {
           }
         }
       );
-      if (fetchedCount > 0) {
+      if (wholeMirrorFetches + scopedMirrorFetches > 0) {
         process.stderr.write(
-          `[r5d-worker] project mirror observation fetched ${fetchedCount} of ${eligibleProjects.length} mirror(s)
+          `[r5d-worker] project mirror observation fetched ${wholeMirrorFetches + scopedMirrorFetches} of ${eligibleProjects.length} mirror(s) (${wholeMirrorFetches} whole, ${scopedMirrorFetches} scoped to ${fetchedMounts} of ${eligibleMounts} mount(s))
 `
         );
       }
@@ -4410,6 +4380,7 @@ async function startWorker(options) {
     }
     const configuredMounts = buildWorkspaceMounts();
     if (input.resetToCanonical) {
+      workspaceProjectionLedger.reset();
       const resetHasBusyLiveMount = configuredMounts.some(
         (mount) => !(mount.deleteWhenSourceMissing && !fs.existsSync(mount.sourcePath)) && mount.busy?.()
       );
@@ -4452,6 +4423,7 @@ async function startWorker(options) {
     }
     const outerRemediation = input.trigger.type === "remediation" || input.trigger.type === "remediation_confirm";
     const mounts = outerRemediation ? workspaceGitMountsForRemediation(configuredMounts) : configuredMounts;
+    if (outerRemediation) workspaceProjectionLedger.reset();
     const observedProjectHeads = outerRemediation ? [] : await observeProjectHeadsBeforeOuterWorkspace({ allowNonFastForward: false, failClosed: false });
     const expectedMirrorHeads = /* @__PURE__ */ new Map();
     for (const bundle of observedProjectHeads) {
@@ -4478,6 +4450,10 @@ async function startWorker(options) {
       allowLargeDiff: input.confirmedLargeDiff,
       skipMountMirror: outerRemediation,
       requiredAncestorHeads: input.requiredAncestorHeads,
+      // Same gate as the mirror fetches: while the server's read of the hidden
+      // workspace head equals the head this clone last fetched or pushed, the
+      // cycle's workspace head fetches would transfer nothing.
+      advertisedRemoteHead: projectMirrorFetchSkippingEnabled && !outerRemediation ? advertisedWorkspaceHead : void 0,
       assertStillAdmitted: input.assertStillAdmitted,
       afterWorkspacePublished: outerRemediation ? void 0 : async ({ activeMountIds, publishedHead }) => {
         await pushChangedProjectHeads(activeMountIds, publishedHead, publicationHeads, expectedMirrorHeads, inboundMoveMountIds);
@@ -4499,7 +4475,11 @@ async function startWorker(options) {
         result.localHead ?? result.remoteHead
       );
     }
-    return mapWorkspaceGitResult(input.attemptId, input.trigger, result);
+    const mapped = await mapWorkspaceGitResult(input.attemptId, input.trigger, result);
+    if (!outerRemediation) {
+      workspaceProjectionLedger.recordCycle({ result: mapped, mounts, projectedMutationTokens: result.projectedMutationTokens });
+    }
+    return mapped;
   };
   const sendWorkspaceSyncResult = (requestId, result) => {
     try {
@@ -4537,17 +4517,143 @@ async function startWorker(options) {
     }, unsafeWorkspaceSyncRecoveryBounceDelayMs(attempt));
     timer.unref();
   };
+  const captureWorkspaceSyncAdmission = () => ({
+    generation: workerAdmissionGeneration,
+    activeIncidentId: activeWorkspaceIncidentId,
+    deferredIncidentId: deferredWorkspaceConfiguration?.incidentId ?? null
+  });
+  const workspaceSyncAdmissionSnapshotsMatch = (left, right) => left.generation === right.generation && left.activeIncidentId === right.activeIncidentId && left.deferredIncidentId === right.deferredIncidentId;
+  const assertWorkspaceSyncStillAdmitted = (admitted, trigger) => {
+    if (!workspaceSyncAdmissionSnapshotsMatch(admitted, captureWorkspaceSyncAdmission()) || currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN || !deferredWorkspaceSyncTriggerIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, trigger)) {
+      throw new WorkspaceSyncAdmissionChangedError("Workspace synchronization admission changed while asynchronous work was in flight");
+    }
+  };
+  const executeWorkspaceSyncCycle = async (input) => {
+    const attemptId = input.attemptId;
+    lastWorkspaceSyncMirrorObservationMs = 0;
+    if (!deferredWorkspaceSyncTriggerIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, input.trigger)) {
+      return await failedWorkspaceSyncResult(
+        attemptId,
+        input.trigger,
+        new Error(
+          `Workspace synchronization was fenced while queued by incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId ?? "unknown"}`
+        )
+      );
+    }
+    try {
+      input.assertStillAdmitted();
+      const hasDurableBranchDeletion = projectWorkspaceState.tombstones.some((tombstone) => tombstone.kind === "branch");
+      return await performWorkspaceSync({
+        attemptId,
+        trigger: input.trigger,
+        confirmedLargeDiff: input.confirmedLargeDiff === true || hasDurableBranchDeletion,
+        confirmationReason: input.confirmationReason ?? (hasDurableBranchDeletion ? "durable project branch deletion" : void 0),
+        resetToCanonical: input.resetToCanonical,
+        requiredAncestorHeads: input.requiredAncestorHeads,
+        assertStillAdmitted: input.assertStillAdmitted
+      });
+    } catch (error) {
+      workspaceProjectionLedger.reset();
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const hydrationRecoverable = workspaceSyncFailureHydrationIsSafe({
+        error,
+        resetToCanonical: input.resetToCanonical === true,
+        inspectRecoverableHydration: () => workspaceGitHydrationIsRecoverable(workspaceShadowRoot, buildWorkspaceMounts())
+      });
+      if (hydrationRecoverable) {
+        if (error instanceof WorkspaceSyncAdmissionChangedError) {
+          process.stderr.write(
+            `[r5d-worker] workspace synchronization was cancelled with every mount at a recorded basis; the next cycle converges it: ${errorMessage}
+`
+          );
+        }
+        return await failedWorkspaceSyncResult(attemptId, input.trigger, error);
+      }
+      const fenced = fenceUnsafeWorkspaceSyncFailure({
+        hydrationRecoverable,
+        resetToCanonical: input.resetToCanonical === true,
+        recoveryAttempts: unsafeWorkspaceSyncRecoveryAttempts,
+        maxRecoveryAttempts: WORKSPACE_UNSAFE_SYNC_MAX_RECOVERY_ATTEMPTS,
+        hasRetainableWork: activeProcesses.size > 0 || credentialBearingProcessGroups.size > 0 || activePtys.size > 0 || pendingProcessTerminals.size > 0,
+        bouncePending: unsafeWorkspaceSyncBouncePending,
+        invalidateExecution: () => {
+          workspaceConfigured = false;
+          advanceWorkerAdmissionGeneration();
+        },
+        scheduleRecoveryBounce: () => {
+          unsafeWorkspaceSyncRecoveryAttempts += 1;
+          scheduleUnsafeWorkspaceSyncRecoveryBounce(errorMessage);
+        },
+        fatalExit: (exitCode) => {
+          process.stderr.write(
+            `[r5d-worker] workspace synchronization failed without a recoverable hydration basis; exiting for exact recovery after ${unsafeWorkspaceSyncRecoveryAttempts} in-process recovery attempt(s): ${errorMessage}
+`
+          );
+          process.exit(exitCode);
+        },
+        exitCode: 1
+      });
+      if (fenced === "recovery_pending") {
+        process.stderr.write(
+          `[r5d-worker] workspace synchronization failed without a recoverable hydration basis while in-process recovery is already pending: ${errorMessage}
+`
+        );
+      }
+      return {
+        ...await failedWorkspaceSyncResult(attemptId, input.trigger, error),
+        failureReason: "unsafe_hydration",
+        recoveryAttempt: unsafeWorkspaceSyncRecoveryAttempts
+      };
+    }
+  };
+  const REMEDIATION_TRIGGER_TYPES = /* @__PURE__ */ new Set(["remediation", "remediation_confirm", "remediation_reset"]);
+  const isOrdinaryWorkspaceSyncRequest = (input) => input.confirmedLargeDiff !== true && input.resetToCanonical !== true && !(input.requiredAncestorHeads && input.requiredAncestorHeads.length > 0) && !REMEDIATION_TRIGGER_TYPES.has(input.trigger.type);
+  const LOCAL_ACTIVITY_TRIGGER_TYPES = /* @__PURE__ */ new Set([
+    "write",
+    "edit",
+    "shell_inline",
+    "process_terminal",
+    "process_cancel"
+  ]);
+  const answerOrdinaryWorkspaceSyncFromLastCycle = (requests) => {
+    if (!workspaceConfigured) return null;
+    return workspaceProjectionLedger.answerFromLastCycle({
+      // A workspace-rooted command carries no project target because it may
+      // have touched any checkout.
+      targetMountIds: requests.map(
+        ({ trigger }) => LOCAL_ACTIVITY_TRIGGER_TYPES.has(trigger.type) && trigger.projectId && trigger.branchName ? projectMountId(trigger.projectId, trigger.branchName) : null
+      ),
+      mounts: buildWorkspaceMounts(),
+      pendingDeletions: pendingMirrorDeletes.size > 0 || projectWorkspaceState.pendingTreeDeletions.length > 0 || projectWorkspaceState.pendingMirrorRefDeletions.length > 0
+    });
+  };
+  const ordinaryWorkspaceSyncCoalescer = new WorkspaceSyncCoalescer({
+    runExclusive: (operation) => workspaceSyncSingleFlight.runExclusive(operation),
+    runBatch: async (requests) => {
+      const startedAtMs = Date.now();
+      const admission = captureWorkspaceSyncAdmission();
+      const staleAttemptIds = /* @__PURE__ */ new Set();
+      const admitted = [];
+      for (const request of requests) {
+        if (workspaceSyncAdmissionSnapshotsMatch(request.admission, admission)) admitted.push(request);
+        else staleAttemptIds.add(request.attemptId);
+      }
+      const leader = admitted[0];
+      if (!leader) return { result: null, ranCycle: false, startedAtMs, finishedAtMs: Date.now(), prepareMs: 0, staleAttemptIds };
+      const answered = answerOrdinaryWorkspaceSyncFromLastCycle(admitted);
+      if (answered) return { result: answered, ranCycle: false, startedAtMs, finishedAtMs: Date.now(), prepareMs: 0, staleAttemptIds };
+      const result = await executeWorkspaceSyncCycle({
+        attemptId: leader.attemptId,
+        trigger: leader.trigger,
+        assertStillAdmitted: () => assertWorkspaceSyncStillAdmitted(admission, leader.trigger)
+      });
+      return { result, ranCycle: true, startedAtMs, finishedAtMs: Date.now(), prepareMs: lastWorkspaceSyncMirrorObservationMs, staleAttemptIds };
+    }
+  });
   const runWorkspaceSync = async (input) => {
     const attemptId = input.attemptId ?? crypto.randomUUID();
     const requestedAt = Date.now();
-    const admittedGeneration = workerAdmissionGeneration;
-    const admittedActiveIncidentId = activeWorkspaceIncidentId;
-    const admittedDeferredIncidentId = deferredWorkspaceConfiguration?.incidentId ?? null;
-    const assertStillAdmitted = () => {
-      if (admittedGeneration !== workerAdmissionGeneration || admittedActiveIncidentId !== activeWorkspaceIncidentId || admittedDeferredIncidentId !== (deferredWorkspaceConfiguration?.incidentId ?? null) || currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN || !deferredWorkspaceSyncTriggerIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, input.trigger)) {
-        throw new WorkspaceSyncAdmissionChangedError("Workspace synchronization admission changed while asynchronous work was in flight");
-      }
-    };
+    const admission = captureWorkspaceSyncAdmission();
     if (!deferredWorkspaceSyncTriggerIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, input.trigger)) {
       const result2 = {
         ...await failedWorkspaceSyncResult(
@@ -4573,104 +4679,47 @@ async function startWorker(options) {
       }
       ws.send(JSON.stringify({ type: "workspace_sync_started", attemptId }));
     }
-    let queueEnteredAt = requestedAt;
-    let syncStartedAt = requestedAt;
+    let queueMs = 0;
+    let prepareMs = 0;
+    let synchronizeMs = 0;
     workspaceSyncRequestsInFlight += 1;
     let result;
     try {
-      result = await workspaceSyncSingleFlight.runExclusive(async () => {
-        queueEnteredAt = Date.now();
-        syncStartedAt = Date.now();
-        lastWorkspaceSyncMirrorObservationMs = 0;
-        if (!deferredWorkspaceSyncTriggerIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, input.trigger)) {
-          return await failedWorkspaceSyncResult(
-            attemptId,
-            input.trigger,
-            new Error(
-              `Workspace synchronization was fenced while queued by incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId ?? "unknown"}`
-            )
-          );
-        }
-        try {
-          assertStillAdmitted();
-          const hasDurableBranchDeletion = projectWorkspaceState.tombstones.some((tombstone) => tombstone.kind === "branch");
-          return await performWorkspaceSync({
+      if (isOrdinaryWorkspaceSyncRequest(input)) {
+        const settlement = await ordinaryWorkspaceSyncCoalescer.request({ attemptId, trigger: input.trigger, admission });
+        queueMs = settlement.startedAtMs - requestedAt;
+        prepareMs = settlement.prepareMs;
+        synchronizeMs = settlement.finishedAtMs - settlement.startedAtMs;
+        result = settlement.staleAttemptIds.has(attemptId) || settlement.result === null ? await failedWorkspaceSyncResult(
+          attemptId,
+          input.trigger,
+          new Error("Workspace synchronization admission changed while the request was queued")
+        ) : { ...settlement.result, attemptId, trigger: input.trigger };
+      } else {
+        result = await workspaceSyncSingleFlight.runExclusive(async () => {
+          const startedAt = Date.now();
+          queueMs = startedAt - requestedAt;
+          const cycleResult = await executeWorkspaceSyncCycle({
             attemptId,
             trigger: input.trigger,
-            confirmedLargeDiff: input.confirmedLargeDiff === true || hasDurableBranchDeletion,
-            confirmationReason: input.confirmationReason ?? (hasDurableBranchDeletion ? "durable project branch deletion" : void 0),
+            confirmedLargeDiff: input.confirmedLargeDiff,
+            confirmationReason: input.confirmationReason,
             resetToCanonical: input.resetToCanonical,
             requiredAncestorHeads: input.requiredAncestorHeads,
-            assertStillAdmitted
-          });
-        } catch (error) {
-          const errorMessage = error instanceof Error ? error.message : String(error);
-          const hydrationRecoverable = workspaceSyncFailureHydrationIsSafe({
-            error,
-            resetToCanonical: input.resetToCanonical === true,
-            inspectRecoverableHydration: () => workspaceGitHydrationIsRecoverable(workspaceShadowRoot, buildWorkspaceMounts())
-          });
-          if (hydrationRecoverable) {
-            if (error instanceof WorkspaceSyncAdmissionChangedError) {
-              process.stderr.write(
-                `[r5d-worker] workspace synchronization was cancelled with every mount at a recorded basis; the next cycle converges it: ${errorMessage}
-`
-              );
-            }
-            return await failedWorkspaceSyncResult(attemptId, input.trigger, error);
-          }
-          const fenced = fenceUnsafeWorkspaceSyncFailure({
-            hydrationRecoverable,
-            resetToCanonical: input.resetToCanonical === true,
-            recoveryAttempts: unsafeWorkspaceSyncRecoveryAttempts,
-            maxRecoveryAttempts: WORKSPACE_UNSAFE_SYNC_MAX_RECOVERY_ATTEMPTS,
-            hasRetainableWork: activeProcesses.size > 0 || credentialBearingProcessGroups.size > 0 || activePtys.size > 0 || pendingProcessTerminals.size > 0,
-            bouncePending: unsafeWorkspaceSyncBouncePending,
-            invalidateExecution: () => {
-              workspaceConfigured = false;
-              advanceWorkerAdmissionGeneration();
-            },
-            scheduleRecoveryBounce: () => {
-              unsafeWorkspaceSyncRecoveryAttempts += 1;
-              scheduleUnsafeWorkspaceSyncRecoveryBounce(errorMessage);
-            },
-            fatalExit: (exitCode) => {
-              process.stderr.write(
-                `[r5d-worker] workspace synchronization failed without a recoverable hydration basis; exiting for exact recovery after ${unsafeWorkspaceSyncRecoveryAttempts} in-process recovery attempt(s): ${errorMessage}
-`
-              );
-              process.exit(exitCode);
-            },
-            exitCode: 1
+            assertStillAdmitted: () => assertWorkspaceSyncStillAdmitted(admission, input.trigger)
           });
-          if (fenced === "recovery_pending") {
-            process.stderr.write(
-              `[r5d-worker] workspace synchronization failed without a recoverable hydration basis while in-process recovery is already pending: ${errorMessage}
-`
-            );
-          }
-          return {
-            ...await failedWorkspaceSyncResult(attemptId, input.trigger, error),
-            failureReason: "unsafe_hydration",
-            recoveryAttempt: unsafeWorkspaceSyncRecoveryAttempts
-          };
-        }
-      });
+          prepareMs = lastWorkspaceSyncMirrorObservationMs;
+          synchronizeMs = Date.now() - startedAt;
+          return cycleResult;
+        });
+      }
     } finally {
       workspaceSyncRequestsInFlight -= 1;
     }
     if (result.outcome !== "failed") unsafeWorkspaceSyncRecoveryAttempts = 0;
-    const finishedAt = Date.now();
     result = {
       ...result,
-      telemetry: {
-        totalMs: finishedAt - requestedAt,
-        queueMs: queueEnteredAt - requestedAt,
-        // Duration of the pre-outer mirror-head observation phase; near zero
-        // on a cycle whose token-gated observation skipped every fetch.
-        prepareMs: lastWorkspaceSyncMirrorObservationMs,
-        synchronizeMs: finishedAt - syncStartedAt
-      }
+      telemetry: { totalMs: Date.now() - requestedAt, queueMs, prepareMs, synchronizeMs }
     };
     if (input.sendResult !== false) sendWorkspaceSyncResult(input.requestId, result);
     sendLifecycleProgress(
@@ -4940,6 +4989,7 @@ async function startWorker(options) {
           );
         }
         workspaceConfigured = false;
+        workspaceProjectionLedger.reset();
         const preserveOnlyBranches = message.projects.flatMap(
           (project) => project.preserveOnlyBranches.map(({ branchId, branchName }) => ({ branchId, projectId: project.projectId, branchName }))
         );
@@ -4949,6 +4999,16 @@ async function startWorker(options) {
             preserveOnlyBranches
           });
         }
+        for (const project of message.projects) {
+          for (const branch of project.branches) {
+            const pending2 = projectWorkspaceState.locallyPendingCreatedBranches.find(
+              (candidate) => candidate.projectId === project.projectId && candidate.branchName === branch.branchName
+            );
+            if (pending2 && pending2.branchId === branch.branchId) {
+              projectWorkspaceState = projectWorkspaceStateStore.clearPendingCreatedBranch(pending2);
+            }
+          }
+        }
         const stillPendingCreatedBranches = new Map(
           projectWorkspaceState.locallyPendingCreatedBranches.map((branch) => [
             pendingCreatedBranchKey(branch.projectId, branch.branchName),
@@ -5390,11 +5450,10 @@ async function startWorker(options) {
           workspaceConfigResetToCanonicalV1: true,
           projectBranchDeletionFastAckV1: true,
           projectMirrorLeaseV1: true,
-          projectMirrorRefsTokensV1: true
+          projectMirrorRefsTokensV1: true,
+          projectBranchWorkingTreeModeV1: true
         },
-        projectRoot: projectsRoot,
-        artifactRoot,
-        planRoot
+        root: rootDir
       }
     };
     ws.send(JSON.stringify(hello));
@@ -5429,14 +5488,12 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "project_mirror_refs_tokens") {
+        const advertised = parseProjectMirrorRefsTokensMessage(message);
         advertisedProjectMirrorRefsTokens.clear();
-        if (message.tokens && typeof message.tokens === "object") {
-          for (const [projectId, token2] of Object.entries(message.tokens)) {
-            if (typeof token2 === "string" && /^[0-9a-f]{64}$/.test(token2)) {
-              advertisedProjectMirrorRefsTokens.set(projectId, token2);
-            }
-          }
-        }
+        for (const [projectId, token2] of advertised.projectTokens) advertisedProjectMirrorRefsTokens.set(projectId, token2);
+        advertisedProjectMirrorMountTokens.clear();
+        for (const [projectId, tokens] of advertised.mountTokens) advertisedProjectMirrorMountTokens.set(projectId, tokens);
+        advertisedWorkspaceHead = advertised.workspaceHead;
         return;
       }
       if (message.type === "workspace_config") {
@@ -5509,13 +5566,21 @@ async function startWorker(options) {
           });
           return;
         }
+        sendWorkerMessage(ws, {
+          type: "operation_queued",
+          requestId: message.requestId,
+          queuePosition: workspaceSyncSingleFlight.branchMutationQueuePosition()
+        });
         try {
+          if (message.workingTree !== "carry" && message.workingTree !== "clean") {
+            throw new Error('Project branch creation requires workingTree "carry" or "clean"');
+          }
           const pendingBranch = {
             branchId: message.branchId,
             projectId: message.projectId,
             branchName: message.targetBranch
           };
-          const created = await workspaceSyncSingleFlight.runMutation(() => {
+          const created = await workspaceSyncSingleFlight.runBranchMutation(() => {
             if (workspaceOperationsAreFenced(deferredWorkspaceConfiguration, activeWorkspaceIncidentId)) {
               throw new Error(
                 `Project branch creation was fenced while queued by workspace incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId}`
@@ -5556,6 +5621,7 @@ async function startWorker(options) {
                 primaryBranchName: primaryProjectBranch(project),
                 sourceBranchName: message.sourceBranch,
                 branchName: message.targetBranch,
+                workingTree: message.workingTree,
                 pendingRetry: pendingWasRecorded
               });
               gitBranchCreated = true;
@@ -5612,9 +5678,14 @@ async function startWorker(options) {
           });
           return;
         }
+        sendWorkerMessage(ws, {
+          type: "operation_queued",
+          requestId: message.requestId,
+          queuePosition: workspaceSyncSingleFlight.branchMutationQueuePosition()
+        });
         try {
           const deletionKey = projectBranchKey(message.projectId, message.branchName);
-          const deletionNeedsSync = await workspaceSyncSingleFlight.runMutation(() => {
+          const deletionNeedsSync = await workspaceSyncSingleFlight.runBranchMutation(() => {
             if (workspaceOperationsAreFenced(deferredWorkspaceConfiguration, activeWorkspaceIncidentId)) {
               throw new Error(
                 `Project branch deletion was fenced while queued by workspace incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId}`
@@ -5645,6 +5716,9 @@ async function startWorker(options) {
               projectId: message.projectId,
               branchName: message.branchName
             });
+            if (pendingLocalBranch) {
+              projectWorkspaceState = projectWorkspaceStateStore.clearPendingCreatedBranch(pendingLocalBranch);
+            }
             pendingCreatedBranchPublicationNotBefore.delete(pendingCreatedBranchKey(message.projectId, message.branchName));
             if (pendingMirrorDeletes.has(deletionKey)) return true;
             stageProjectBranchDeletion(project, message.branchName, true);
@@ -5922,7 +5996,7 @@ async function startWorker(options) {
             ws,
             message,
             resolvedTarget,
-            planRoot,
+            rootDir,
             assertAdmission: assertMessageAdmission,
             ...releaseWorkspaceMutation ? { releaseWorkspaceMutation } : {},
             ...targetMayMutateVisibleWorkspace(message.target) ? {
@@ -6020,8 +6094,7 @@ async function startWorker(options) {
               resolvedTarget,
               baseUrl,
               token,
-              artifactRoot,
-              planRoot,
+              rootDir,
               setPreparationHeartbeatLease: (active) => {
                 sendWorkerMessageFromCurrentSource(ws, {
                   type: "heartbeat_lease",
@@ -6090,8 +6163,7 @@ async function startWorker(options) {
               resolvedTarget,
               baseUrl,
               token,
-              artifactRoot,
-              planRoot,
+              rootDir,
               setPreparationHeartbeatLease: (active) => {
                 sendWorkerMessageFromCurrentSource(ws, {
                   type: "heartbeat_lease",
@@ -6173,8 +6245,7 @@ async function startWorker(options) {
               resolvedTarget,
               baseUrl,
               token,
-              artifactRoot,
-              planRoot,
+              rootDir,
               assertAdmission: assertMessageAdmission
             });
           });