@ricsam/r5d-worker 0.0.45 → 0.0.47

package/dist/mjs/main.mjs

@@ -21,7 +21,8 @@ import {
   WORKSPACE_PERIODIC_SCAN_INTERVAL_MS,
   WorkspaceSyncSingleFlight,
   calculateWorkspaceDiffFingerprint,
-  synchronizeWorkspace
+  synchronizeWorkspace,
+  workspaceProjectsForSync
 } from "./workspace-sync.mjs";
 class WorkerServerUnavailableError extends Error {
   name = "WorkerServerUnavailableError";
@@ -246,7 +247,25 @@ async function readResponseText(response) {
   }
 }
 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];
+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);
+  if (!match) {
+    return null;
+  }
+  const ref = `$${match[1] ?? match[2]}`;
+  if (!BUILT_IN_TOOL_PATH_REFS.includes(ref)) {
+    throw new Error(`Unsupported tool path variable "${ref}". Supported variables: ${BUILT_IN_TOOL_PATH_REFS.join(", ")}.`);
+  }
+  return {
+    ref,
+    relativePath: match[3] ?? ""
+  };
+}
 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}`);
@@ -255,7 +274,7 @@ function validateArtifactSessionId(sessionId) {
 function assertInsideRoot(rootPath, candidatePath, label) {
   const relative = path.relative(rootPath, candidatePath);
   if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-    throw new Error(`${label} escapes sync directory`);
+    throw new Error(`${label} escapes its allowed root`);
   }
 }
 function sessionArtifactDir(artifactRoot, sessionId) {
@@ -288,7 +307,11 @@ function planEnv(planRoot, projectId, branchName, activePlanId) {
   return env;
 }
 function isArtifactEnvPath(filePath) {
-  return filePath === R5D_ARTIFACTS_DIR_REF || filePath.startsWith(`${R5D_ARTIFACTS_DIR_REF}/`);
+  try {
+    return parseBuiltInToolPath(filePath)?.ref === R5D_ARTIFACTS_DIR_REF;
+  } catch {
+    return false;
+  }
 }
 function artifactApiBasePath(projectId, branchName, sessionId) {
   return `/preview-api/${encodeURIComponent(projectId)}/${encodeURIComponent(branchName)}/artifacts/${encodeURIComponent(sessionId)}`;
@@ -422,40 +445,45 @@ async function syncSessionArtifacts(input) {
   void queued.then(release, release);
   return queued;
 }
-async function resolveArtifactEnvFilePath(input) {
-  if (!isArtifactEnvPath(input.filePath)) {
-    return null;
+async function prepareBuiltInToolPaths(input) {
+  const parsed = parseBuiltInToolPath(input.filePath);
+  if (!parsed) {
+    return void 0;
   }
-  if (!input.sessionId) {
-    throw new Error(`${R5D_ARTIFACTS_DIR_REF} paths require an active chat session`);
+  if (parsed.ref === R5D_ARTIFACTS_DIR_REF) {
+    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.`
+      );
+    }
+    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,
+        projectId: input.projectId,
+        branchName: input.branchName,
+        sessionId: input.sessionId,
+        artifactRoot: input.artifactRoot
+      })
+    };
   }
-  if (!input.filePath.startsWith(`${R5D_ARTIFACTS_DIR_REF}/`)) {
-    throw new Error(`Artifact path must reference a file under ${R5D_ARTIFACTS_DIR_REF}/`);
+  const plansDir = projectPlanDir(input.planRoot, input.projectId, input.branchName);
+  fs.mkdirSync(plansDir, { recursive: true });
+  if (parsed.ref === R5D_PLANS_DIR_REF) {
+    return { plansDir };
   }
-  const targetDir = await syncSessionArtifacts({
-    baseUrl: input.baseUrl,
-    token: input.token,
-    projectId: input.projectId,
-    branchName: input.branchName,
-    sessionId: input.sessionId,
-    artifactRoot: input.artifactRoot
-  });
-  const relativePath = path.posix.normalize(input.filePath.slice(`${R5D_ARTIFACTS_DIR_REF}/`.length));
-  if (!relativePath || relativePath === "." || relativePath.startsWith("../") || relativePath.includes("\0")) {
-    throw new Error(`Invalid artifact path: ${input.filePath}`);
+  if (!input.activePlanId) {
+    throw new Error(`${R5D_ACTIVE_PLAN_FILE_REF} paths require an active plan`);
   }
-  const absolutePath = path.resolve(targetDir, ...relativePath.split("/"));
-  assertInsideRoot(targetDir, absolutePath, "Artifact path");
+  validatePlanId(input.activePlanId);
   return {
-    absolutePath,
-    virtualPath: `${R5D_ARTIFACTS_DIR_REF}/${relativePath}`
+    plansDir,
+    activePlanFile: path.join(plansDir, `${input.activePlanId}.plan.md`)
   };
 }
-function rejectArtifactWritePath(filePath) {
-  if (isArtifactEnvPath(filePath)) {
-    throw new Error(`${R5D_ARTIFACTS_DIR_REF} attachments are read-only. Copy them into a project path before editing or creating files.`);
-  }
-}
 async function prepareArtifactEnvForShell(input) {
   if (!input.sessionId) {
     return {};
@@ -551,6 +579,14 @@ function validatePlanId(planId) {
     throw new Error(`Invalid plan id from server: ${planId}`);
   }
 }
+const NON_RECURSIVE_GIT_CONFIG_ARGS = [
+  "-c",
+  "submodule.recurse=false",
+  "-c",
+  "fetch.recurseSubmodules=false",
+  "-c",
+  "push.recurseSubmodules=false"
+];
 function gitExtraHeaderConfigKey(extraHeaderUrl) {
   return `http.${normalizeBaseUrl(extraHeaderUrl)}/.extraHeader`;
 }
@@ -558,10 +594,23 @@ function gitAuthArgs(auth) {
   if (!auth) {
     return [];
   }
-  return ["-c", `${gitExtraHeaderConfigKey(auth.extraHeaderUrl)}=${auth.header}`];
+  const scopedKey = gitExtraHeaderConfigKey(auth.extraHeaderUrl);
+  return ["-c", "http.extraHeader=", "-c", `${scopedKey}=`, "-c", `${scopedKey}=${auth.header}`];
+}
+const visibleCheckoutGitTestHarness = {
+  gitAuthArgs,
+  commandArgs: (args, auth) => ["git", ...NON_RECURSIVE_GIT_CONFIG_ARGS, ...gitAuthArgs(auth), ...args],
+  cloneArgs: (remoteUrl, branchPath) => ["clone", "--no-recurse-submodules", "--origin", "origin", remoteUrl, branchPath],
+  fetchArgs: (...args) => ["fetch", "--no-recurse-submodules", ...args]
+};
+function visibleCheckoutCloneArgs(remoteUrl, branchPath) {
+  return visibleCheckoutGitTestHarness.cloneArgs(remoteUrl, branchPath);
+}
+function visibleCheckoutFetchArgs(...args) {
+  return visibleCheckoutGitTestHarness.fetchArgs(...args);
 }
 function runGit(args, options = {}) {
-  const command = ["git", ...gitAuthArgs(options.auth), ...args];
+  const command = visibleCheckoutGitTestHarness.commandArgs(args, options.auth);
   const result = Bun.spawnSync(command, {
     cwd: options.cwd,
     stdout: "pipe",
@@ -606,10 +655,63 @@ function assertAllowedProjectPath(repoRelativePath, inputPath) {
     throw new Error(`Invalid project file path: ${inputPath}`);
   }
 }
-function resolveWorkerFilePath(branchPath, inputPath) {
+function assertPathInsideRealRoot(rootPath, candidatePath, label) {
+  const resolvedRoot = path.resolve(rootPath);
+  const resolvedCandidate = path.resolve(candidatePath);
+  assertInsideRoot(resolvedRoot, resolvedCandidate, label);
+  let existingPath = resolvedCandidate;
+  while (!fs.existsSync(existingPath)) {
+    const parentPath = path.dirname(existingPath);
+    if (parentPath === existingPath) {
+      throw new Error(`${label} root does not exist: ${rootPath}`);
+    }
+    existingPath = parentPath;
+  }
+  const realRoot = fs.realpathSync(resolvedRoot);
+  const realExistingPath = fs.realpathSync(existingPath);
+  assertInsideRoot(realRoot, realExistingPath, label);
+}
+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 normalizedRelativePath = normalizedPath === "." ? "" : normalizedPath;
+  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,
+    repoRelativePath: null,
+    scope: "virtual",
+    virtualRootPath: path.resolve(rootPath)
+  };
+}
+function resolveWorkerFilePath(branchPath, inputPath, builtInPaths) {
   if (typeof inputPath !== "string" || inputPath.length === 0 || inputPath.includes("\0")) {
     throw new Error(`File path must be a non-empty string. Got: ${JSON.stringify(inputPath)}`);
   }
+  const parsedBuiltInPath = parseBuiltInToolPath(inputPath);
+  if (parsedBuiltInPath) {
+    return resolveVirtualWorkerFilePath(inputPath, parsedBuiltInPath, builtInPaths);
+  }
   const resolvedBranchPath = path.resolve(branchPath);
   if (path.isAbsolute(inputPath)) {
     const absolutePath2 = path.resolve(inputPath);
@@ -652,8 +754,28 @@ function resolveWorkerFilePath(branchPath, inputPath) {
 function fallbackInternalRemoteUrl(baseUrl, projectId) {
   return new URL(`/git/${projectId}.git`, baseUrl).toString();
 }
-function githubRemoteUrlFor(baseUrl, projectId, manifest) {
-  return manifest?.repoHttpUrl ?? fallbackInternalRemoteUrl(baseUrl, projectId);
+function visibleCheckoutRemoteFor(input) {
+  const canonicalCheckout = input.manifest?.canonicalCheckouts?.find((checkout) => checkout.branchName === input.branchName);
+  const isCanonicalManifestBranch = Boolean(canonicalCheckout);
+  const usesCanonicalRemote = isCanonicalManifestBranch || !input.manifest?.repoHttpUrl;
+  if (usesCanonicalRemote) {
+    return {
+      remoteUrl: fallbackInternalRemoteUrl(input.baseUrl, input.projectId),
+      authHeader: `Authorization: Bearer ${input.token}`,
+      persistAuth: false,
+      reconcileExistingOrigin: isCanonicalManifestBranch,
+      requireRemoteBranch: isCanonicalManifestBranch,
+      requiredBaseCommit: canonicalCheckout?.scaffoldCommitHash ?? null
+    };
+  }
+  return {
+    remoteUrl: input.manifest?.repoHttpUrl ?? fallbackInternalRemoteUrl(input.baseUrl, input.projectId),
+    authHeader: input.manifest?.repoAuthHeader ?? null,
+    persistAuth: true,
+    reconcileExistingOrigin: Boolean(input.manifest?.repoHttpUrl),
+    requireRemoteBranch: false,
+    requiredBaseCommit: null
+  };
 }
 function gitExtraHeaderUrlForRemote(remoteUrl) {
   try {
@@ -682,6 +804,10 @@ function ensureOriginRemote(branchPath, remoteUrl) {
     runGit(["remote", "add", "origin", remoteUrl], { cwd: branchPath });
   }
 }
+function originRemoteUrl(branchPath) {
+  if (!tryGit(["remote", "get-url", "origin"], { cwd: branchPath })) return null;
+  return runGit(["remote", "get-url", "origin"], { cwd: branchPath });
+}
 function shellQuote(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
@@ -750,6 +876,18 @@ function configureVisibleGitHubAuth(branchPath, remoteUrl, authHeader) {
   }
   runGit(["config", `${gitExtraHeaderConfigKey(gitExtraHeaderUrlForRemote(remoteUrl))}`, authHeader], { cwd: branchPath });
 }
+function clearVisibleGitAuthentication(branchPath) {
+  let extraHeaderKeys = [];
+  try {
+    extraHeaderKeys = runGit(["config", "--local", "--name-only", "--get-regexp", "^http\\..*extraheader$"], { cwd: branchPath }).split(/\r?\n/).filter(Boolean);
+  } catch {
+  }
+  for (const key of extraHeaderKeys) {
+    tryGit(["config", "--local", "--unset-all", key], { cwd: branchPath });
+  }
+  runGit(["config", "--local", "--replace-all", "credential.helper", ""], { cwd: branchPath });
+  tryGit(["config", "--local", "--unset-all", "credential.useHttpPath"], { cwd: branchPath });
+}
 function dockerConfigPath() {
   return path.join(os.homedir(), ".docker", "config.json");
 }
@@ -838,18 +976,58 @@ function checkoutVisibleBranch(input) {
   });
   const clean = !hasWorktreeChanges(input.branchPath);
   if (remoteBranchExists && clean) {
-    runGit(["checkout", "-B", input.branchName, `origin/${input.branchName}`], { cwd: input.branchPath });
+    runGit(["checkout", "--no-recurse-submodules", "-B", input.branchName, `origin/${input.branchName}`], {
+      cwd: input.branchPath
+    });
     return;
   }
   if (branchExists) {
-    runGit(["checkout", input.branchName], { cwd: input.branchPath });
+    runGit(["checkout", "--no-recurse-submodules", input.branchName], { cwd: input.branchPath });
     return;
   }
   if (defaultRemoteExists) {
-    runGit(["checkout", "-B", input.branchName, `origin/${input.defaultBranch}`], { cwd: input.branchPath });
+    runGit(["checkout", "--no-recurse-submodules", "-B", input.branchName, `origin/${input.defaultBranch}`], {
+      cwd: input.branchPath
+    });
     return;
   }
-  runGit(["checkout", "-B", input.branchName], { cwd: input.branchPath });
+  runGit(["checkout", "--no-recurse-submodules", "-B", input.branchName], { cwd: input.branchPath });
+}
+function migrateExistingCheckoutToRequiredRemote(input) {
+  if (originRemoteUrl(input.branchPath) === input.remoteUrl) return;
+  if (hasWorktreeChanges(input.branchPath)) {
+    throw new Error(`Cannot migrate dirty checkout for ${input.branchName} to its canonical remote`);
+  }
+  runGit(
+    visibleCheckoutFetchArgs("--no-tags", input.remoteUrl, `+refs/heads/${input.branchName}:refs/remotes/origin/${input.branchName}`),
+    {
+      cwd: input.branchPath,
+      auth: input.remoteAuth
+    }
+  );
+  const canonicalRemoteRef = `refs/remotes/origin/${input.branchName}`;
+  if (!tryGit(["show-ref", "--verify", "--quiet", canonicalRemoteRef], { cwd: input.branchPath })) {
+    throw new Error(`Canonical branch ${input.branchName} is unavailable during checkout migration`);
+  }
+  if (input.requiredBaseCommit && (!tryGit(["cat-file", "-e", `${input.requiredBaseCommit}^{commit}`], { cwd: input.branchPath }) || !tryGit(["merge-base", "--is-ancestor", input.requiredBaseCommit, canonicalRemoteRef], { cwd: input.branchPath }))) {
+    throw new Error(`Canonical branch ${input.branchName} is not derived from required scaffold ${input.requiredBaseCommit}`);
+  }
+  if (tryGit(["rev-parse", "--verify", "HEAD"], { cwd: input.branchPath })) {
+    const previousHead = runGit(["rev-parse", "HEAD"], { cwd: input.branchPath });
+    runGit(["update-ref", `refs/r5d/pre-canonical-checkout/${previousHead}`, previousHead], { cwd: input.branchPath });
+  }
+  ensureOriginRemote(input.branchPath, input.remoteUrl);
+  runGit(["checkout", "--no-recurse-submodules", "-B", input.branchName, `origin/${input.branchName}`], {
+    cwd: input.branchPath
+  });
+}
+function assertCheckoutDerivedFromRequiredBase(input) {
+  const remoteRevision = `refs/remotes/origin/${input.branchName}`;
+  for (const revision of [remoteRevision, "HEAD"]) {
+    if (!tryGit(["cat-file", "-e", `${input.requiredBaseCommit}^{commit}`], { cwd: input.branchPath }) || !tryGit(["merge-base", "--is-ancestor", input.requiredBaseCommit, revision], { cwd: input.branchPath })) {
+      throw new Error(`Canonical checkout ${input.branchName} is not derived from required scaffold ${input.requiredBaseCommit}`);
+    }
+  }
 }
 function ensureVisibleGitCheckout(input) {
   validateBranchName(input.branchName);
@@ -859,40 +1037,114 @@ function ensureVisibleGitCheckout(input) {
   if (createdCheckout) {
     fs.rmSync(branchPath, { recursive: true, force: true });
     fs.mkdirSync(path.dirname(branchPath), { recursive: true });
-    if (!tryGit(["clone", "--origin", "origin", input.githubRemoteUrl, branchPath], { auth: input.githubAuth })) {
+    const cloned = tryGit(visibleCheckoutCloneArgs(input.remoteUrl, branchPath), {
+      auth: input.remoteAuth
+    });
+    if (!cloned && input.requireRemoteBranch) {
+      fs.rmSync(branchPath, { recursive: true, force: true });
+      throw new Error(`Failed to clone canonical checkout for branch ${input.branchName}`);
+    }
+    if (!cloned) {
       fs.mkdirSync(branchPath, { recursive: true });
       runGit(["init"], { cwd: branchPath });
     }
-    ensureOriginRemote(branchPath, input.githubRemoteUrl);
-    configureVisibleGitHubAuth(branchPath, input.githubRemoteUrl, input.githubAuthHeader);
+    ensureOriginRemote(branchPath, input.remoteUrl);
+    if (input.clearPersistentAuth) clearVisibleGitAuthentication(branchPath);
+    else configureVisibleGitHubAuth(branchPath, input.remoteUrl, input.persistentAuthHeader);
     configureVisibleGitIdentity(branchPath, visibleGitIdentity, runGit);
-    tryGit(["fetch", "origin", "--prune"], { cwd: branchPath, auth: input.githubAuth });
+    tryGit(visibleCheckoutFetchArgs("origin", "--prune"), { cwd: branchPath, auth: input.remoteAuth });
+    if (input.requireRemoteBranch && !tryGit(["show-ref", "--verify", "--quiet", `refs/remotes/origin/${input.branchName}`], { cwd: branchPath })) {
+      fs.rmSync(branchPath, { recursive: true, force: true });
+      throw new Error(`Canonical branch ${input.branchName} is unavailable after clone`);
+    }
     checkoutVisibleBranch({ branchPath, branchName: input.branchName, defaultBranch: input.defaultBranch });
+    if (input.requiredBaseCommit) {
+      try {
+        assertCheckoutDerivedFromRequiredBase({
+          branchPath,
+          branchName: input.branchName,
+          requiredBaseCommit: input.requiredBaseCommit
+        });
+      } catch (error) {
+        fs.rmSync(branchPath, { recursive: true, force: true });
+        throw error;
+      }
+    }
     return branchPath;
   }
+  if (input.requireRemoteBranch) {
+    if (input.allowRequiredRemoteMigration === false && originRemoteUrl(branchPath) !== input.remoteUrl) {
+      throw new Error(`Canonical checkout ${input.branchName} no longer uses its required remote`);
+    }
+    migrateExistingCheckoutToRequiredRemote({
+      branchPath,
+      branchName: input.branchName,
+      remoteUrl: input.remoteUrl,
+      remoteAuth: input.remoteAuth,
+      requiredBaseCommit: input.requiredBaseCommit
+    });
+    runGit(
+      visibleCheckoutFetchArgs("--no-tags", input.remoteUrl, `+refs/heads/${input.branchName}:refs/remotes/origin/${input.branchName}`),
+      {
+        cwd: branchPath,
+        auth: input.remoteAuth
+      }
+    );
+  }
   if (input.reconcileExistingOrigin) {
-    ensureOriginRemote(branchPath, input.githubRemoteUrl);
+    ensureOriginRemote(branchPath, input.remoteUrl);
+  }
+  if (input.requireRemoteBranch && !tryGit(["show-ref", "--verify", "--quiet", `refs/remotes/origin/${input.branchName}`], { cwd: branchPath })) {
+    throw new Error(`Existing checkout for ${input.branchName} does not contain its canonical remote branch`);
   }
-  configureVisibleGitHubAuth(branchPath, input.githubRemoteUrl, input.githubAuthHeader);
+  if (input.requiredBaseCommit) {
+    assertCheckoutDerivedFromRequiredBase({
+      branchPath,
+      branchName: input.branchName,
+      requiredBaseCommit: input.requiredBaseCommit
+    });
+  }
+  if (input.clearPersistentAuth) clearVisibleGitAuthentication(branchPath);
+  else configureVisibleGitHubAuth(branchPath, input.remoteUrl, input.persistentAuthHeader);
   configureVisibleGitIdentity(branchPath, visibleGitIdentity, runGit);
   return branchPath;
 }
 function ensureBranchWorkspace(input) {
   const defaultBranch = input.manifest?.defaultBranch || "main";
-  const githubRemoteUrl = githubRemoteUrlFor(input.baseUrl, input.projectId, input.manifest);
-  const githubAuth = gitAuthForRemote(githubRemoteUrl, input.manifest?.repoAuthHeader);
+  const remote = visibleCheckoutRemoteFor(input);
   return {
     branchPath: ensureVisibleGitCheckout({
       projectRoot: input.projectRoot,
       branchName: input.branchName,
-      githubRemoteUrl,
-      githubAuth,
-      githubAuthHeader: input.manifest?.repoAuthHeader ?? null,
+      remoteUrl: remote.remoteUrl,
+      remoteAuth: gitAuthForRemote(remote.remoteUrl, remote.authHeader),
+      persistentAuthHeader: remote.persistAuth ? remote.authHeader : null,
       defaultBranch,
-      reconcileExistingOrigin: Boolean(input.manifest?.repoHttpUrl)
+      reconcileExistingOrigin: remote.reconcileExistingOrigin,
+      requireRemoteBranch: remote.requireRemoteBranch,
+      requiredBaseCommit: remote.requiredBaseCommit,
+      clearPersistentAuth: !remote.persistAuth
     })
   };
 }
+function workspaceSyncCheckoutTargets(input) {
+  const selected = /* @__PURE__ */ new Map();
+  const add = (target) => {
+    selected.set(`${target.projectId}\0${target.branchName}`, target);
+  };
+  if (input.canonicalCheckoutOnly) {
+    add(input.canonicalCheckoutOnly);
+  } else if (input.includeAllManifestCheckouts) {
+    for (const project of input.projects) {
+      for (const branchName of project.branches) add({ projectId: project.projectId, branchName });
+    }
+  } else {
+    for (const target of input.pendingTargets) add(target);
+  }
+  return [...selected.values()].sort(
+    (left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName)
+  );
+}
 function resolveCommandCwd(branchPath, cwd) {
   if (!cwd) {
     return branchPath;
@@ -1066,13 +1318,13 @@ async function withFileMutationQueue(key, operation) {
   }
 }
 function mutationQueueKey(projectId, branchName, resolved) {
-  if (resolved.scope === "host") {
-    return `host:${path.normalize(resolved.absolutePath)}`;
+  if (resolved.scope !== "project") {
+    return `${resolved.scope}:${path.normalize(resolved.absolutePath)}`;
   }
   return `project:${projectId}:${branchName}:${path.posix.normalize(resolved.repoRelativePath)}`;
 }
-function readWorkerTextFile(branchPath, filePath, offset, limit) {
-  const resolved = resolveWorkerFilePath(branchPath, filePath);
+function readWorkerTextFile(branchPath, filePath, offset, limit, builtInPaths) {
+  const resolved = resolveWorkerFilePath(branchPath, filePath, builtInPaths);
   if (!fs.existsSync(resolved.absolutePath) || !fs.statSync(resolved.absolutePath).isFile()) {
     throw new Error(`File not found: ${resolved.displayPath}`);
   }
@@ -1086,8 +1338,8 @@ function readWorkerTextFile(branchPath, filePath, offset, limit) {
     ...formatted
   };
 }
-function writeWorkerTextFile(branchPath, filePath, content) {
-  const resolved = resolveWorkerFilePath(branchPath, filePath);
+function writeWorkerTextFile(branchPath, filePath, content, builtInPaths) {
+  const resolved = resolveWorkerFilePath(branchPath, filePath, builtInPaths);
   fs.mkdirSync(path.dirname(resolved.absolutePath), { recursive: true });
   fs.writeFileSync(resolved.absolutePath, content, "utf8");
   return {
@@ -1096,8 +1348,8 @@ function writeWorkerTextFile(branchPath, filePath, content) {
     gitBlobHash: getGitBlobHashForContent(content)
   };
 }
-function editWorkerTextFile(branchPath, filePath, edits) {
-  const resolved = resolveWorkerFilePath(branchPath, filePath);
+function editWorkerTextFile(branchPath, filePath, edits, builtInPaths) {
+  const resolved = resolveWorkerFilePath(branchPath, filePath, builtInPaths);
   if (!Array.isArray(edits) || edits.length === 0) {
     throw new Error("edit requires at least one replacement");
   }
@@ -1144,46 +1396,57 @@ function editWorkerTextFile(branchPath, filePath, edits) {
   };
 }
 async function executeReadFileOperation(input) {
-  const artifact = await resolveArtifactEnvFilePath({
+  const builtInPaths = await prepareBuiltInToolPaths({
     filePath: input.message.filePath,
     baseUrl: input.baseUrl,
     token: input.token,
     projectId: input.projectId,
     branchName: input.message.branchName,
     sessionId: input.message.sessionId,
-    artifactRoot: input.artifactRoot
+    activePlanId: input.message.activePlanId,
+    artifactRoot: input.artifactRoot,
+    planRoot: input.planRoot,
+    access: "read"
   });
-  if (artifact) {
-    if (!fs.existsSync(artifact.absolutePath) || !fs.statSync(artifact.absolutePath).isFile()) {
-      throw new Error(`File not found: ${artifact.virtualPath}`);
-    }
-    const buffer = fs.readFileSync(artifact.absolutePath);
-    const formatted = formatLineNumberedContent(buffer.toString("utf8"), input.message.offset, input.message.limit);
-    return {
-      type: "read",
-      kind: "text",
-      file: artifact.virtualPath,
-      gitBlobHash: getGitBlobHashForContent(buffer),
-      ...formatted
-    };
-  }
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  return readWorkerTextFile(workspace.branchPath, input.message.filePath, input.message.offset, input.message.limit);
+  return readWorkerTextFile(workspace.branchPath, input.message.filePath, input.message.offset, input.message.limit, builtInPaths);
 }
 async function executeWriteFileOperation(input) {
-  rejectArtifactWritePath(input.message.filePath);
+  const builtInPaths = await prepareBuiltInToolPaths({
+    filePath: input.message.filePath,
+    baseUrl: input.baseUrl,
+    token: input.token,
+    projectId: input.projectId,
+    branchName: input.message.branchName,
+    sessionId: input.message.sessionId,
+    activePlanId: input.message.activePlanId,
+    artifactRoot: input.artifactRoot,
+    planRoot: input.planRoot,
+    access: "write"
+  });
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  const resolved = resolveWorkerFilePath(workspace.branchPath, input.message.filePath);
+  const resolved = resolveWorkerFilePath(workspace.branchPath, input.message.filePath, builtInPaths);
   return withFileMutationQueue(mutationQueueKey(input.projectId, input.message.branchName, resolved), async () => {
-    return writeWorkerTextFile(workspace.branchPath, input.message.filePath, input.message.content);
+    return writeWorkerTextFile(workspace.branchPath, input.message.filePath, input.message.content, builtInPaths);
   });
 }
 async function executeEditFileOperation(input) {
-  rejectArtifactWritePath(input.message.filePath);
+  const builtInPaths = await prepareBuiltInToolPaths({
+    filePath: input.message.filePath,
+    baseUrl: input.baseUrl,
+    token: input.token,
+    projectId: input.projectId,
+    branchName: input.message.branchName,
+    sessionId: input.message.sessionId,
+    activePlanId: input.message.activePlanId,
+    artifactRoot: input.artifactRoot,
+    planRoot: input.planRoot,
+    access: "write"
+  });
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  const resolved = resolveWorkerFilePath(workspace.branchPath, input.message.filePath);
+  const resolved = resolveWorkerFilePath(workspace.branchPath, input.message.filePath, builtInPaths);
   return withFileMutationQueue(mutationQueueKey(input.projectId, input.message.branchName, resolved), async () => {
-    return editWorkerTextFile(workspace.branchPath, input.message.filePath, input.message.edits);
+    return editWorkerTextFile(workspace.branchPath, input.message.filePath, input.message.edits, builtInPaths);
   });
 }
 const IGNORED_ENTRY_NAMES = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", ".next", ".cache", "coverage", "target"]);
@@ -1204,16 +1467,20 @@ function normalizeFindPattern(pattern) {
 function walkWorkerEntries(branchPath, start) {
   const entries = [];
   const visitedDirectories = /* @__PURE__ */ new Set();
+  const realVirtualRoot = start.scope === "virtual" ? fs.realpathSync(start.virtualRootPath) : null;
   const visit = (absolutePath, isRoot) => {
     let stat;
     try {
       stat = fs.statSync(absolutePath);
+      if (realVirtualRoot) {
+        assertInsideRoot(realVirtualRoot, fs.realpathSync(absolutePath), `${start.displayPath} path`);
+      }
     } catch (error) {
       if (isRoot) throw error;
       return;
     }
-    const displayPath = start.scope === "project" ? toProjectDisplayPath(branchPath, absolutePath) : path.resolve(absolutePath);
     const hostRelativePath = path.relative(start.absolutePath, absolutePath).split(path.sep).join(path.posix.sep);
+    const displayPath = start.scope === "project" ? toProjectDisplayPath(branchPath, absolutePath) : start.scope === "virtual" ? hostRelativePath ? `${start.displayPath}/${hostRelativePath}` : start.displayPath : path.resolve(absolutePath);
     const matchPath = start.scope === "project" ? displayPath : hostRelativePath || path.basename(start.absolutePath);
     entries.push({ absolutePath, displayPath, matchPath, stat });
     if (!stat.isDirectory()) return;
@@ -1244,8 +1511,8 @@ function walkWorkerEntries(branchPath, start) {
 function isProbablyText(bytes) {
   return !bytes.subarray(0, Math.min(bytes.length, 4096)).includes(0);
 }
-function grepWorkerFiles(branchPath, input) {
-  const start = resolveWorkerFilePath(branchPath, input.path ?? ".");
+function grepWorkerFiles(branchPath, input, builtInPaths) {
+  const start = resolveWorkerFilePath(branchPath, input.path ?? ".", builtInPaths);
   if (!fs.existsSync(start.absolutePath)) {
     throw new Error(`Path not found: ${start.displayPath}`);
   }
@@ -1291,17 +1558,34 @@ function grepWorkerFiles(branchPath, input) {
   };
 }
 async function executeGrepOperation(input) {
-  const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  return grepWorkerFiles(workspace.branchPath, {
-    pattern: input.message.pattern,
-    path: input.message.path,
-    glob: input.message.glob,
-    caseSensitive: input.message.caseSensitive,
-    limit: input.message.limit
+  const toolPath = input.message.path ?? ".";
+  const builtInPaths = await prepareBuiltInToolPaths({
+    filePath: toolPath,
+    baseUrl: input.baseUrl,
+    token: input.token,
+    projectId: input.projectId,
+    branchName: input.message.branchName,
+    sessionId: input.message.sessionId,
+    activePlanId: input.message.activePlanId,
+    artifactRoot: input.artifactRoot,
+    planRoot: input.planRoot,
+    access: "read"
   });
+  const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
+  return grepWorkerFiles(
+    workspace.branchPath,
+    {
+      pattern: input.message.pattern,
+      path: input.message.path,
+      glob: input.message.glob,
+      caseSensitive: input.message.caseSensitive,
+      limit: input.message.limit
+    },
+    builtInPaths
+  );
 }
-function findWorkerFiles(branchPath, input) {
-  const start = resolveWorkerFilePath(branchPath, input.path ?? ".");
+function findWorkerFiles(branchPath, input, builtInPaths) {
+  const start = resolveWorkerFilePath(branchPath, input.path ?? ".", builtInPaths);
   if (!fs.existsSync(start.absolutePath) || !fs.statSync(start.absolutePath).isDirectory()) {
     throw new Error(`Directory not found: ${start.displayPath}`);
   }
@@ -1335,16 +1619,33 @@ function findWorkerFiles(branchPath, input) {
   };
 }
 async function executeFindOperation(input) {
-  const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  return findWorkerFiles(workspace.branchPath, {
-    pattern: input.message.pattern,
-    path: input.message.path,
-    entryType: input.message.entryType,
-    limit: input.message.limit
+  const toolPath = input.message.path ?? ".";
+  const builtInPaths = await prepareBuiltInToolPaths({
+    filePath: toolPath,
+    baseUrl: input.baseUrl,
+    token: input.token,
+    projectId: input.projectId,
+    branchName: input.message.branchName,
+    sessionId: input.message.sessionId,
+    activePlanId: input.message.activePlanId,
+    artifactRoot: input.artifactRoot,
+    planRoot: input.planRoot,
+    access: "read"
   });
+  const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
+  return findWorkerFiles(
+    workspace.branchPath,
+    {
+      pattern: input.message.pattern,
+      path: input.message.path,
+      entryType: input.message.entryType,
+      limit: input.message.limit
+    },
+    builtInPaths
+  );
 }
-function listWorkerDirectory(branchPath, inputPath = ".", inputLimit) {
-  const resolved = resolveWorkerFilePath(branchPath, inputPath);
+function listWorkerDirectory(branchPath, inputPath = ".", inputLimit, builtInPaths) {
+  const resolved = resolveWorkerFilePath(branchPath, inputPath, builtInPaths);
   if (!fs.existsSync(resolved.absolutePath) || !fs.statSync(resolved.absolutePath).isDirectory()) {
     throw new Error(`Directory not found: ${resolved.displayPath}`);
   }
@@ -1362,11 +1663,24 @@ function listWorkerDirectory(branchPath, inputPath = ".", inputLimit) {
   };
 }
 async function executeLsOperation(input) {
+  const toolPath = input.message.path ?? ".";
+  const builtInPaths = await prepareBuiltInToolPaths({
+    filePath: toolPath,
+    baseUrl: input.baseUrl,
+    token: input.token,
+    projectId: input.projectId,
+    branchName: input.message.branchName,
+    sessionId: input.message.sessionId,
+    activePlanId: input.message.activePlanId,
+    artifactRoot: input.artifactRoot,
+    planRoot: input.planRoot,
+    access: "read"
+  });
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  return listWorkerDirectory(workspace.branchPath, input.message.path, input.message.limit);
+  return listWorkerDirectory(workspace.branchPath, input.message.path, input.message.limit, builtInPaths);
 }
-function readWorkerImageFile(branchPath, filePath) {
-  const resolved = resolveWorkerFilePath(branchPath, filePath);
+function readWorkerImageFile(branchPath, filePath, builtInPaths) {
+  const resolved = resolveWorkerFilePath(branchPath, filePath, builtInPaths);
   if (!fs.existsSync(resolved.absolutePath) || !fs.statSync(resolved.absolutePath).isFile()) {
     throw new Error(`File not found: ${resolved.displayPath}`);
   }
@@ -1388,38 +1702,20 @@ function readWorkerImageFile(branchPath, filePath) {
   };
 }
 async function executeViewFileBytesOperation(input) {
-  const artifact = await resolveArtifactEnvFilePath({
+  const builtInPaths = await prepareBuiltInToolPaths({
     filePath: input.message.filePath,
     baseUrl: input.baseUrl,
     token: input.token,
     projectId: input.projectId,
     branchName: input.message.branchName,
     sessionId: input.message.sessionId,
-    artifactRoot: input.artifactRoot
+    activePlanId: input.message.activePlanId,
+    artifactRoot: input.artifactRoot,
+    planRoot: input.planRoot,
+    access: "read"
   });
-  if (artifact) {
-    if (!fs.existsSync(artifact.absolutePath) || !fs.statSync(artifact.absolutePath).isFile()) {
-      throw new Error(`File not found: ${artifact.virtualPath}`);
-    }
-    const extension = path.extname(artifact.absolutePath).toLowerCase();
-    const mediaType = extension === ".jpg" || extension === ".jpeg" ? "image/jpeg" : extension === ".png" ? "image/png" : null;
-    if (!mediaType) {
-      throw new Error("read supports PNG and JPEG image inputs only");
-    }
-    const bytes = fs.readFileSync(artifact.absolutePath);
-    const dimensions = readImageDimensions(bytes, mediaType);
-    return {
-      type: "view_file_bytes",
-      filePath: artifact.virtualPath,
-      mediaType,
-      base64: bytes.toString("base64"),
-      fileSizeBytes: bytes.length,
-      width: dimensions.width,
-      height: dimensions.height
-    };
-  }
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  return readWorkerImageFile(workspace.branchPath, input.message.filePath);
+  return readWorkerImageFile(workspace.branchPath, input.message.filePath, builtInPaths);
 }
 async function executeOperation(input) {
   switch (input.message.type) {
@@ -2058,6 +2354,7 @@ async function startWorker(options) {
   fs.mkdirSync(artifactRoot, { recursive: true });
   fs.mkdirSync(planRoot, { recursive: true });
   const manifestByProjectId = /* @__PURE__ */ new Map();
+  const pendingManifestCheckouts = /* @__PURE__ */ new Map();
   const workspaceSyncSingleFlight = new WorkspaceSyncSingleFlight();
   let workspaceRemoteUrl = null;
   let activeWorkspaceIncidentId = null;
@@ -2071,6 +2368,7 @@ async function startWorker(options) {
   let reloadAfterClose = false;
   const workspaceSyncInput = (trigger, overrides = {}) => {
     if (!workspaceRemoteUrl) throw new Error("Worker workspace manifest has not been received");
+    const projects = workspaceProjectsForSync([...manifestByProjectId.values()], trigger);
     return {
       workerLabel: label,
       remoteUrl: workspaceRemoteUrl,
@@ -2078,7 +2376,7 @@ async function startWorker(options) {
       projectsRoot,
       plansRoot: planRoot,
       shadowRoot: workspaceShadowRoot,
-      projects: [...manifestByProjectId.values()],
+      projects,
       trigger,
       ...overrides
     };
@@ -2086,37 +2384,89 @@ async function startWorker(options) {
   const sendWorkspaceSyncResult = (requestId, result) => {
     sendWorkerMessage(ws, { type: "workspace_sync_result", requestId, result });
   };
-  const ensureAllVisibleWorkspaceCheckouts = () => {
+  const manifestCheckoutKey = (projectId, branchName) => `${projectId}\0${branchName}`;
+  const allManifestCheckouts = () => [...manifestByProjectId.values()].flatMap(
+    (manifest) => manifest.branches.map((branchName) => ({ projectId: manifest.projectId, branchName }))
+  );
+  const ensureVisibleWorkspaceCheckouts = (targets, options2 = {}) => {
     const created = [];
-    for (const manifest of manifestByProjectId.values()) {
-      for (const branchName of manifest.branches) {
-        const branchPath = path.join(projectRootFor(projectsRoot, manifest.projectId, manifestByProjectId), branchName);
-        const existed = fs.existsSync(path.join(branchPath, ".git"));
-        const githubRemoteUrl = githubRemoteUrlFor(baseUrl, manifest.projectId, manifest);
-        ensureVisibleGitCheckout({
-          projectRoot: projectRootFor(projectsRoot, manifest.projectId, manifestByProjectId),
-          branchName,
-          githubRemoteUrl,
-          githubAuth: gitAuthForRemote(githubRemoteUrl, manifest.repoAuthHeader),
-          githubAuthHeader: manifest.repoAuthHeader,
-          defaultBranch: manifest.defaultBranch || "main",
-          reconcileExistingOrigin: Boolean(manifest.repoHttpUrl)
-        });
-        if (!existed) created.push({ projectId: manifest.projectId, branchName });
+    for (const target of targets) {
+      const manifest = manifestByProjectId.get(target.projectId);
+      const key = manifestCheckoutKey(target.projectId, target.branchName);
+      if (!manifest || !manifest.branches.includes(target.branchName)) {
+        pendingManifestCheckouts.delete(key);
+        continue;
       }
+      const projectRoot = projectRootFor(projectsRoot, manifest.projectId, manifestByProjectId);
+      const branchPath = path.join(projectRoot, target.branchName);
+      const existed = hasNormalVisibleGitDir(branchPath);
+      const remote = visibleCheckoutRemoteFor({
+        baseUrl,
+        token,
+        projectId: manifest.projectId,
+        branchName: target.branchName,
+        manifest
+      });
+      ensureVisibleGitCheckout({
+        projectRoot,
+        branchName: target.branchName,
+        remoteUrl: remote.remoteUrl,
+        remoteAuth: gitAuthForRemote(remote.remoteUrl, remote.authHeader),
+        persistentAuthHeader: remote.persistAuth ? remote.authHeader : null,
+        defaultBranch: manifest.defaultBranch || "main",
+        reconcileExistingOrigin: remote.reconcileExistingOrigin,
+        requireRemoteBranch: remote.requireRemoteBranch,
+        requiredBaseCommit: remote.requiredBaseCommit,
+        allowRequiredRemoteMigration: !(options2.strictCanonicalRevalidation && remote.requireRemoteBranch),
+        clearPersistentAuth: !remote.persistAuth
+      });
+      if (!existed) created.push(target);
     }
     return created;
   };
   const runRequestedWorkspaceSync = async (requestId, trigger, overrides = {}) => {
     workspaceSyncRequestsInFlight += 1;
     try {
-      const newVisibleCheckouts = trigger.type === "connect" ? ensureAllVisibleWorkspaceCheckouts() : [];
-      const result = await workspaceSyncSingleFlight.run(
-        workspaceSyncInput(trigger, {
+      let pendingTargets = [];
+      const result = await workspaceSyncSingleFlight.runPrepared(() => {
+        const shouldEnsureCheckouts = !overrides.skipVisibleMirror && !overrides.resetToCanonical;
+        const syncProjects = workspaceProjectsForSync([...manifestByProjectId.values()], trigger);
+        const allowedCheckoutKeys = new Set(
+          syncProjects.flatMap((project) => project.branches.map((branchName) => manifestCheckoutKey(project.projectId, branchName)))
+        );
+        const scopedPendingTargets = [...pendingManifestCheckouts.values()].filter(
+          (target) => allowedCheckoutKeys.has(manifestCheckoutKey(target.projectId, target.branchName))
+        );
+        let checkoutTargets = [];
+        if (shouldEnsureCheckouts) {
+          checkoutTargets = workspaceSyncCheckoutTargets({
+            projects: syncProjects,
+            pendingTargets: scopedPendingTargets,
+            includeAllManifestCheckouts: trigger.type === "connect",
+            ...trigger.canonicalCheckoutOnly && trigger.projectId && trigger.branchName ? { canonicalCheckoutOnly: { projectId: trigger.projectId, branchName: trigger.branchName } } : {}
+          });
+        }
+        pendingTargets = shouldEnsureCheckouts ? scopedPendingTargets : [];
+        const createdCheckouts = ensureVisibleWorkspaceCheckouts(checkoutTargets, {
+          strictCanonicalRevalidation: true
+        });
+        const newVisibleCheckoutByKey = /* @__PURE__ */ new Map();
+        for (const target of [...overrides.newVisibleCheckouts ?? [], ...createdCheckouts, ...pendingTargets]) {
+          const key = manifestCheckoutKey(target.projectId, target.branchName);
+          if (allowedCheckoutKeys.has(key)) newVisibleCheckoutByKey.set(key, target);
+        }
+        const newVisibleCheckouts = [...newVisibleCheckoutByKey.values()];
+        return workspaceSyncInput(trigger, {
           ...overrides,
           ...newVisibleCheckouts.length > 0 ? { newVisibleCheckouts } : {}
-        })
-      );
+        });
+      });
+      if (result.outcome === "no_change" || result.outcome === "published" || result.outcome === "updated" || result.outcome === "conflict_reset") {
+        for (const target of pendingTargets) {
+          const key = manifestCheckoutKey(target.projectId, target.branchName);
+          if (pendingManifestCheckouts.get(key) === target) pendingManifestCheckouts.delete(key);
+        }
+      }
       previousPeriodicFingerprint = null;
       sendWorkspaceSyncResult(requestId, result);
       return result;
@@ -2179,7 +2529,8 @@ async function startWorker(options) {
         version: getWorkerVersion(),
         r5dctlVersion: readInstalledCliVersion("r5dctl"),
         capabilities: {
-          updateClis: true
+          updateClis: true,
+          canonicalResolverCheckout: true
         },
         projectRoot: projectsRoot,
         artifactRoot,
@@ -2209,9 +2560,26 @@ async function startWorker(options) {
         configureGitHubAuth(message.githubCredential);
         visibleGitIdentity = message.gitIdentity;
         workspaceRemoteUrl = message.workspaceRemoteUrl;
+        const previousCheckoutKeys = new Set(
+          allManifestCheckouts().map(({ projectId, branchName }) => manifestCheckoutKey(projectId, branchName))
+        );
         const migratedProjectIds = migrateLegacyProjectRoots(projectsRoot, message.projects);
         manifestByProjectId.clear();
         for (const project of message.projects) manifestByProjectId.set(project.projectId, project);
+        const currentCheckouts = allManifestCheckouts();
+        const currentCheckoutKeys = new Set(
+          currentCheckouts.map(({ projectId, branchName }) => manifestCheckoutKey(projectId, branchName))
+        );
+        for (const key of pendingManifestCheckouts.keys()) {
+          if (!currentCheckoutKeys.has(key)) pendingManifestCheckouts.delete(key);
+        }
+        for (const checkout of currentCheckouts) {
+          const key = manifestCheckoutKey(checkout.projectId, checkout.branchName);
+          if (previousCheckoutKeys.has(key)) continue;
+          const branchPath = path.join(projectRootFor(projectsRoot, checkout.projectId, manifestByProjectId), checkout.branchName);
+          if (!hasNormalVisibleGitDir(branchPath)) pendingManifestCheckouts.set(key, checkout);
+        }
+        previousPeriodicFingerprint = null;
         process.stdout.write(
           `[r5d-worker] workspace manifest: ${message.projects.length} projects${migratedProjectIds.length > 0 ? `; migrated ${migratedProjectIds.length} project checkout root(s)` : ""}
 `
@@ -2222,8 +2590,23 @@ async function startWorker(options) {
             if (!workspaceRemoteUrl || activeWorkspaceIncidentId || cliUpdateInProgress || periodicWorkspaceScanInFlight) return;
             periodicWorkspaceScanInFlight = true;
             void (async () => {
-              const input = workspaceSyncInput({ type: "periodic" });
-              const fingerprint = await workspaceSyncSingleFlight.fingerprint(input);
+              const genericCheckoutKeys = new Set(
+                workspaceProjectsForSync([...manifestByProjectId.values()], { type: "periodic" }).flatMap(
+                  (project) => project.branches.map((branchName) => manifestCheckoutKey(project.projectId, branchName))
+                )
+              );
+              const hasPendingGenericCheckout = [...pendingManifestCheckouts.values()].some(
+                (target) => genericCheckoutKeys.has(manifestCheckoutKey(target.projectId, target.branchName))
+              );
+              if (hasPendingGenericCheckout) {
+                previousPeriodicFingerprint = null;
+                await runRequestedWorkspaceSync(crypto.randomUUID(), {
+                  type: "periodic",
+                  detail: "workspace manifest additions"
+                });
+                return;
+              }
+              const fingerprint = await workspaceSyncSingleFlight.fingerprintPrepared(() => workspaceSyncInput({ type: "periodic" }));
               if (fingerprint === emptyFingerprint) {
                 previousPeriodicFingerprint = null;
                 return;
@@ -2490,6 +2873,7 @@ async function startWorker(options) {
             projectRoot,
             syncRoot,
             artifactRoot,
+            planRoot,
             manifest
           });
           ws.send(
@@ -2631,5 +3015,8 @@ export {
   resolveHostShell,
   resolveWorkerFilePath,
   syncSessionArtifacts,
+  visibleCheckoutGitTestHarness,
+  visibleCheckoutRemoteFor,
+  workspaceSyncCheckoutTargets,
   writeWorkerTextFile
 };