@ricsam/r5d-worker 0.0.44 → 0.0.46

package/dist/mjs/main.mjs

@@ -246,7 +246,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 +273,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 +306,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)}`;
@@ -395,56 +417,72 @@ async function fetchSessionArtifactManifest(input) {
     label: "artifact"
   });
 }
+const sessionArtifactSyncQueues = /* @__PURE__ */ new Map();
 async function syncSessionArtifacts(input) {
-  const targetDir = sessionArtifactDir(input.artifactRoot, input.sessionId);
-  const artifacts = await fetchSessionArtifactManifest(input);
-  return syncRemoteFileSet({
-    targetDir,
-    files: artifacts,
-    label: "Artifact path",
-    download: (artifact) => downloadRemoteSyncedFile({
-      url: artifactDownloadUrl(input.baseUrl, input.projectId, input.branchName, input.sessionId, artifact.filename),
-      token: input.token,
+  const queueKey = `${path.resolve(input.artifactRoot)}\0${input.sessionId}`;
+  const previous = sessionArtifactSyncQueues.get(queueKey);
+  const queued = (previous ? previous.catch(() => "") : Promise.resolve("")).then(async () => {
+    const targetDir = sessionArtifactDir(input.artifactRoot, input.sessionId);
+    const artifacts = await fetchSessionArtifactManifest(input);
+    return syncRemoteFileSet({
       targetDir,
-      file: artifact,
-      label: "artifact"
-    })
+      files: artifacts,
+      label: "Artifact path",
+      download: (artifact) => downloadRemoteSyncedFile({
+        url: artifactDownloadUrl(input.baseUrl, input.projectId, input.branchName, input.sessionId, artifact.filename),
+        token: input.token,
+        targetDir,
+        file: artifact,
+        label: "artifact"
+      })
+    });
   });
+  sessionArtifactSyncQueues.set(queueKey, queued);
+  const release = () => {
+    if (sessionArtifactSyncQueues.get(queueKey) === queued) sessionArtifactSyncQueues.delete(queueKey);
+  };
+  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 {};
@@ -595,10 +633,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);
@@ -1055,13 +1146,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}`);
   }
@@ -1075,8 +1166,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 {
@@ -1085,8 +1176,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");
   }
@@ -1133,46 +1224,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"]);
@@ -1193,16 +1295,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;
@@ -1233,8 +1339,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}`);
   }
@@ -1280,17 +1386,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}`);
   }
@@ -1324,16 +1447,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}`);
   }
@@ -1351,11 +1491,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}`);
   }
@@ -1377,38 +1530,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) {
@@ -2047,6 +2182,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;
@@ -2055,6 +2191,7 @@ async function startWorker(options) {
   let periodicWorkspaceScanInFlight = false;
   let terminalReplayTimer;
   let workspaceSyncRequestsInFlight = 0;
+  let sessionArtifactSyncRequestsInFlight = 0;
   let cliUpdateInProgress = false;
   let reloadAfterClose = false;
   const workspaceSyncInput = (trigger, overrides = {}) => {
@@ -2074,37 +2211,64 @@ 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) => {
     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 githubRemoteUrl = githubRemoteUrlFor(baseUrl, manifest.projectId, manifest);
+      ensureVisibleGitCheckout({
+        projectRoot,
+        branchName: target.branchName,
+        githubRemoteUrl,
+        githubAuth: gitAuthForRemote(githubRemoteUrl, manifest.repoAuthHeader),
+        githubAuthHeader: manifest.repoAuthHeader,
+        defaultBranch: manifest.defaultBranch || "main",
+        reconcileExistingOrigin: Boolean(manifest.repoHttpUrl)
+      });
+      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;
+        let checkoutTargets = [];
+        if (shouldEnsureCheckouts) {
+          checkoutTargets = trigger.type === "connect" ? allManifestCheckouts() : [...pendingManifestCheckouts.values()];
+        }
+        pendingTargets = shouldEnsureCheckouts ? [...pendingManifestCheckouts.values()] : [];
+        const createdCheckouts = ensureVisibleWorkspaceCheckouts(checkoutTargets);
+        const newVisibleCheckoutByKey = /* @__PURE__ */ new Map();
+        for (const target of [...overrides.newVisibleCheckouts ?? [], ...createdCheckouts, ...pendingTargets]) {
+          newVisibleCheckoutByKey.set(manifestCheckoutKey(target.projectId, target.branchName), 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;
@@ -2197,9 +2361,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)` : ""}
 `
@@ -2210,8 +2391,15 @@ 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);
+              if (pendingManifestCheckouts.size > 0) {
+                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;
@@ -2251,6 +2439,34 @@ async function startWorker(options) {
         }
         return;
       }
+      if (message.type === "sync_session_artifacts") {
+        sessionArtifactSyncRequestsInFlight += 1;
+        try {
+          await syncSessionArtifacts({
+            baseUrl,
+            token,
+            projectId: message.projectId,
+            branchName: message.branchName,
+            sessionId: message.sessionId,
+            artifactRoot
+          });
+          sendWorkerMessage(ws, {
+            type: "session_artifacts_sync_result",
+            requestId: message.requestId,
+            sessionId: message.sessionId
+          });
+        } catch (error) {
+          sendWorkerMessage(ws, {
+            type: "session_artifacts_sync_result",
+            requestId: message.requestId,
+            sessionId: message.sessionId,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        } finally {
+          sessionArtifactSyncRequestsInFlight -= 1;
+        }
+        return;
+      }
       if (message.type === "workspace_incident_updated") {
         activeWorkspaceIncidentId = message.status === "remediating" || message.status === "waiting_for_worker" ? message.incidentId : null;
         previousPeriodicFingerprint = null;
@@ -2269,7 +2485,7 @@ async function startWorker(options) {
           });
           return;
         }
-        if (activeProcesses.size > 0 || activePtys.size > 0 || workspaceSyncRequestsInFlight > 0) {
+        if (activeProcesses.size > 0 || activePtys.size > 0 || workspaceSyncRequestsInFlight > 0 || sessionArtifactSyncRequestsInFlight > 0) {
           sendWorkerMessage(ws, {
             type: "update_clis_result",
             requestId: message.requestId,
@@ -2450,6 +2666,7 @@ async function startWorker(options) {
             projectRoot,
             syncRoot,
             artifactRoot,
+            planRoot,
             manifest
           });
           ws.send(