@ricsam/r5d-worker 0.0.14 → 0.0.15

package/dist/cjs/main.cjs

@@ -32,7 +32,9 @@ __export(main_exports, {
   ensureVisibleGitCheckout: () => ensureVisibleGitCheckout,
   isArtifactEnvPath: () => isArtifactEnvPath,
   prepareArtifactEnvForShell: () => prepareArtifactEnvForShell,
+  preparePlanEnvForShell: () => preparePlanEnvForShell,
   resolveProjectFilePath: () => resolveProjectFilePath,
+  syncProjectPlans: () => syncProjectPlans,
   syncSessionArtifacts: () => syncSessionArtifacts
 });
 module.exports = __toCommonJS(main_exports);
@@ -71,6 +73,9 @@ function defaultSyncRoot() {
 function defaultArtifactRoot() {
   return import_node_path.default.join(import_node_os.default.homedir(), ".r5d", "artifacts");
 }
+function defaultPlanRoot() {
+  return import_node_path.default.join(import_node_os.default.homedir(), ".r5d", "plans");
+}
 function printHelp() {
   process.stdout.write(`Usage:
   r5d-worker start --label <label> [--base-url <url>] [--token <token>] [--api-key <key>]
@@ -85,6 +90,7 @@ Options:
   --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)
   -v, --version         Show r5d-worker version
   -h, --help            Show this help
 `);
@@ -206,6 +212,11 @@ function parseArgs(argv) {
       options.artifactRoot = artifactRoot;
       continue;
     }
+    const planRoot = readOption("--plan-root");
+    if (planRoot !== void 0) {
+      options.planRoot = planRoot;
+      continue;
+    }
     rest.push(arg);
   }
   if (options.version) {
@@ -249,6 +260,7 @@ async function readResponseText(response) {
   }
 }
 const R5D_ARTIFACTS_DIR_REF = "$R5D_ARTIFACTS_DIR";
+const R5D_PLANS_DIR_ENV = "R5D_PLANS_DIR";
 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}`);
@@ -257,7 +269,7 @@ function validateArtifactSessionId(sessionId) {
 function assertInsideRoot(rootPath, candidatePath, label) {
   const relative = import_node_path.default.relative(rootPath, candidatePath);
   if (relative === ".." || relative.startsWith(`..${import_node_path.default.sep}`) || import_node_path.default.isAbsolute(relative)) {
-    throw new Error(`${label} escapes the artifact directory`);
+    throw new Error(`${label} escapes sync directory`);
   }
 }
 function sessionArtifactDir(artifactRoot, sessionId) {
@@ -272,6 +284,23 @@ function artifactEnv(artifactRoot, sessionId) {
     R5D_ARTIFACTS_DIR: sessionArtifactDir(artifactRoot, sessionId)
   };
 }
+function projectPlanDir(planRoot, projectId, branchName) {
+  validateProjectId(projectId);
+  validateBranchName(branchName);
+  return import_node_path.default.join(planRoot, projectId, branchName);
+}
+function planEnv(planRoot, projectId, branchName, activePlanId) {
+  const plansDir = projectPlanDir(planRoot, projectId, branchName);
+  const env = {
+    [R5D_PLANS_DIR_ENV]: plansDir
+  };
+  if (activePlanId) {
+    validatePlanId(activePlanId);
+    env.R5D_ACTIVE_PLAN_ID = activePlanId;
+    env.R5D_ACTIVE_PLAN_FILE = import_node_path.default.join(plansDir, `${activePlanId}.plan.md`);
+  }
+  return env;
+}
 function isArtifactEnvPath(filePath) {
   return filePath === R5D_ARTIFACTS_DIR_REF || filePath.startsWith(`${R5D_ARTIFACTS_DIR_REF}/`);
 }
@@ -284,99 +313,150 @@ function artifactManifestUrl(baseUrl, projectId, branchName, sessionId) {
 function artifactDownloadUrl(baseUrl, projectId, branchName, sessionId, filename) {
   return new URL(`${artifactApiBasePath(projectId, branchName, sessionId)}/${encodeURIComponent(filename)}`, baseUrl);
 }
+function planApiBasePath(projectId, branchName) {
+  return `/preview-api/${encodeURIComponent(projectId)}/${encodeURIComponent(branchName)}/plans`;
+}
+function planManifestUrl(baseUrl, projectId, branchName) {
+  return new URL(planApiBasePath(projectId, branchName), baseUrl);
+}
+function planDownloadUrl(baseUrl, projectId, branchName, filename) {
+  return new URL(`${planApiBasePath(projectId, branchName)}/${encodeURIComponent(filename)}`, baseUrl);
+}
 function sha256Path(filePath) {
   return (0, import_node_crypto.createHash)("sha256").update(import_node_fs.default.readFileSync(filePath)).digest("hex");
 }
-function parseSessionArtifactManifest(value) {
-  if (!value || typeof value !== "object" || !Array.isArray(value.artifacts)) {
-    throw new Error("Artifact manifest response is invalid");
+function parseRemoteFileManifest(value, collectionKey, label) {
+  if (!value || typeof value !== "object" || !Array.isArray(value[collectionKey])) {
+    throw new Error(`${label} manifest response is invalid`);
   }
-  return value.artifacts.map((entry) => {
+  return value[collectionKey].map((entry) => {
     if (!entry || typeof entry !== "object") {
-      throw new Error("Artifact manifest entry is invalid");
+      throw new Error(`${label} manifest entry is invalid`);
     }
-    const artifact = entry;
-    if (typeof artifact.filename !== "string" || artifact.filename.includes("/") || artifact.filename.includes("\\")) {
-      throw new Error("Artifact manifest entry has an invalid filename");
+    const file = entry;
+    if (typeof file.filename !== "string" || file.filename.includes("/") || file.filename.includes("\\")) {
+      throw new Error(`${label} manifest entry has an invalid filename`);
     }
-    if (typeof artifact.size !== "number" || !Number.isFinite(artifact.size) || artifact.size < 0) {
-      throw new Error(`Artifact manifest entry has an invalid size: ${artifact.filename}`);
+    if (typeof file.size !== "number" || !Number.isFinite(file.size) || file.size < 0) {
+      throw new Error(`${label} manifest entry has an invalid size: ${file.filename}`);
     }
-    if (typeof artifact.sha256 !== "string" || !/^[a-f0-9]{64}$/i.test(artifact.sha256)) {
-      throw new Error(`Artifact manifest entry has an invalid sha256: ${artifact.filename}`);
+    if (typeof file.sha256 !== "string" || !/^[a-f0-9]{64}$/i.test(file.sha256)) {
+      throw new Error(`${label} manifest entry has an invalid sha256: ${file.filename}`);
     }
     return {
-      filename: artifact.filename,
-      size: artifact.size,
-      sha256: artifact.sha256.toLowerCase()
+      filename: file.filename,
+      size: file.size,
+      sha256: file.sha256.toLowerCase()
     };
   });
 }
-async function fetchSessionArtifactManifest(input) {
-  const response = await fetch(artifactManifestUrl(input.baseUrl, input.projectId, input.branchName, input.sessionId), {
+async function fetchRemoteFileManifest(input) {
+  const response = await fetch(input.url, {
     headers: {
       Authorization: `Bearer ${input.token}`
     }
   });
   if (!response.ok) {
     const detail = (await readResponseText(response)).trim();
-    throw new Error(`Failed to fetch artifact manifest (${response.status})${detail ? `: ${detail}` : ""}`);
+    throw new Error(`Failed to fetch ${input.label} manifest (${response.status})${detail ? `: ${detail}` : ""}`);
   }
-  return parseSessionArtifactManifest(await response.json());
+  return parseRemoteFileManifest(await response.json(), input.collectionKey, input.label);
 }
-async function downloadSessionArtifact(input) {
-  const targetDir = sessionArtifactDir(input.artifactRoot, input.sessionId);
-  const targetPath = import_node_path.default.join(targetDir, input.artifact.filename);
-  assertInsideRoot(targetDir, targetPath, "Artifact path");
-  const response = await fetch(
-    artifactDownloadUrl(input.baseUrl, input.projectId, input.branchName, input.sessionId, input.artifact.filename),
-    {
-      headers: {
-        Authorization: `Bearer ${input.token}`
-      }
+async function downloadRemoteSyncedFile(input) {
+  const targetPath = import_node_path.default.join(input.targetDir, input.file.filename);
+  assertInsideRoot(input.targetDir, targetPath, input.label);
+  const response = await fetch(input.url, {
+    headers: {
+      Authorization: `Bearer ${input.token}`
     }
-  );
+  });
   if (!response.ok) {
     const detail = (await readResponseText(response)).trim();
-    throw new Error(`Failed to download artifact ${input.artifact.filename} (${response.status})${detail ? `: ${detail}` : ""}`);
+    throw new Error(`Failed to download ${input.label} ${input.file.filename} (${response.status})${detail ? `: ${detail}` : ""}`);
   }
   const buffer = Buffer.from(await response.arrayBuffer());
   const receivedHash = (0, import_node_crypto.createHash)("sha256").update(buffer).digest("hex");
-  if (receivedHash !== input.artifact.sha256) {
-    throw new Error(`Downloaded artifact ${input.artifact.filename} failed sha256 verification`);
+  if (receivedHash !== input.file.sha256) {
+    throw new Error(`Downloaded ${input.label} ${input.file.filename} failed sha256 verification`);
   }
-  if (buffer.length !== input.artifact.size) {
-    throw new Error(`Downloaded artifact ${input.artifact.filename} has unexpected size`);
+  if (buffer.length !== input.file.size) {
+    throw new Error(`Downloaded ${input.label} ${input.file.filename} has unexpected size`);
   }
   const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
   import_node_fs.default.writeFileSync(tempPath, buffer);
   import_node_fs.default.renameSync(tempPath, targetPath);
 }
-async function syncSessionArtifacts(input) {
-  const targetDir = sessionArtifactDir(input.artifactRoot, input.sessionId);
-  import_node_fs.default.mkdirSync(targetDir, { recursive: true });
-  const artifacts = await fetchSessionArtifactManifest(input);
-  const manifestNames = new Set(artifacts.map((artifact) => artifact.filename));
-  for (const artifact of artifacts) {
-    const localPath = import_node_path.default.join(targetDir, artifact.filename);
-    assertInsideRoot(targetDir, localPath, "Artifact path");
+async function syncRemoteFileSet(input) {
+  import_node_fs.default.mkdirSync(input.targetDir, { recursive: true });
+  const manifestNames = new Set(input.files.map((file) => file.filename));
+  for (const file of input.files) {
+    const localPath = import_node_path.default.join(input.targetDir, file.filename);
+    assertInsideRoot(input.targetDir, localPath, input.label);
     if (import_node_fs.default.existsSync(localPath)) {
       const stats = import_node_fs.default.statSync(localPath);
-      if (stats.isFile() && stats.size === artifact.size && sha256Path(localPath) === artifact.sha256) {
+      if (stats.isFile() && stats.size === file.size && sha256Path(localPath) === file.sha256) {
         continue;
       }
       import_node_fs.default.rmSync(localPath, { recursive: true, force: true });
     }
-    await downloadSessionArtifact({ ...input, artifact });
+    await input.download(file);
   }
-  for (const localName of import_node_fs.default.readdirSync(targetDir)) {
+  for (const localName of import_node_fs.default.readdirSync(input.targetDir)) {
     if (!manifestNames.has(localName)) {
-      const localPath = import_node_path.default.join(targetDir, localName);
-      assertInsideRoot(targetDir, localPath, "Artifact path");
+      const localPath = import_node_path.default.join(input.targetDir, localName);
+      assertInsideRoot(input.targetDir, localPath, input.label);
       import_node_fs.default.rmSync(localPath, { recursive: true, force: true });
     }
   }
-  return targetDir;
+  return input.targetDir;
+}
+async function fetchSessionArtifactManifest(input) {
+  return fetchRemoteFileManifest({
+    url: artifactManifestUrl(input.baseUrl, input.projectId, input.branchName, input.sessionId),
+    token: input.token,
+    collectionKey: "artifacts",
+    label: "artifact"
+  });
+}
+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,
+      targetDir,
+      file: artifact,
+      label: "artifact"
+    })
+  });
+}
+async function fetchProjectPlanManifest(input) {
+  return fetchRemoteFileManifest({
+    url: planManifestUrl(input.baseUrl, input.projectId, input.branchName),
+    token: input.token,
+    collectionKey: "plans",
+    label: "plan"
+  });
+}
+async function syncProjectPlans(input) {
+  const targetDir = projectPlanDir(input.planRoot, input.projectId, input.branchName);
+  const plans = await fetchProjectPlanManifest(input);
+  return syncRemoteFileSet({
+    targetDir,
+    files: plans,
+    label: "Plan path",
+    download: (plan) => downloadRemoteSyncedFile({
+      url: planDownloadUrl(input.baseUrl, input.projectId, input.branchName, plan.filename),
+      token: input.token,
+      targetDir,
+      file: plan,
+      label: "plan"
+    })
+  });
 }
 async function resolveArtifactEnvFilePath(input) {
   if (!isArtifactEnvPath(input.filePath)) {
@@ -435,6 +515,19 @@ async function prepareArtifactEnvForShell(input) {
     R5D_ARTIFACTS_DIR: artifactsDir
   };
 }
+async function preparePlanEnvForShell(input) {
+  try {
+    await syncProjectPlans(input);
+  } catch (error) {
+    process.stderr.write(
+      `[r5d-worker] plan sync skipped for ${input.projectId}/${input.branchName}: ${error instanceof Error ? error.message : String(error)}
+`
+    );
+  }
+  const plansDir = projectPlanDir(input.planRoot, input.projectId, input.branchName);
+  import_node_fs.default.mkdirSync(plansDir, { recursive: true });
+  return planEnv(input.planRoot, input.projectId, input.branchName, input.activePlanId);
+}
 async function verifyR5dctlAuth(baseUrl, token) {
   const statusUrl = new URL("/api/r5dctl/auth/status", baseUrl);
   let response;
@@ -479,11 +572,24 @@ function validateLabel(label) {
     throw new Error("Worker label must start with a letter or number and may contain letters, numbers, dots, underscores, and hyphens");
   }
 }
+function validateProjectId(projectId) {
+  if (projectId === "local" || projectId === "local-code") {
+    return;
+  }
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(projectId)) {
+    throw new Error(`Invalid project id from server: ${projectId}`);
+  }
+}
 function validateBranchName(branchName) {
   if (branchName !== "main" && !BRANCH_RE.test(branchName)) {
     throw new Error(`Invalid branch name from server: ${branchName}`);
   }
 }
+function validatePlanId(planId) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(planId)) {
+    throw new Error(`Invalid plan id from server: ${planId}`);
+  }
+}
 function gitExtraHeaderConfigKey(extraHeaderUrl) {
   return `http.${normalizeBaseUrl(extraHeaderUrl)}/.extraHeader`;
 }
@@ -1532,6 +1638,14 @@ async function executeCommand(input) {
       sessionId: input.message.sessionId,
       artifactRoot: input.artifactRoot
     });
+    const planProcessEnv = await preparePlanEnvForShell({
+      baseUrl: input.baseUrl,
+      token: input.token,
+      projectId: input.projectId,
+      branchName: input.message.branchName,
+      planRoot: input.planRoot,
+      activePlanId: input.message.env?.R5D_ACTIVE_PLAN_ID
+    });
     const cwd = resolveCommandCwd(workspace.branchPath, input.message.cwd);
     const subprocess = Bun.spawn(input.message.argv, {
       cwd,
@@ -1542,7 +1656,8 @@ async function executeCommand(input) {
         ...containerRegistryEnv(),
         ...input.message.env ?? {},
         ...internalGitProcessEnv(workspace, input.message.env),
-        ...artifactProcessEnv
+        ...artifactProcessEnv,
+        ...planProcessEnv
       }
     });
     activeProcesses.set(input.message.runId, { process: subprocess, command: input.message.argv });
@@ -1613,6 +1728,14 @@ async function executeStreamingCommand(input) {
       sessionId: input.message.sessionId,
       artifactRoot: input.artifactRoot
     });
+    const planProcessEnv = await preparePlanEnvForShell({
+      baseUrl: input.baseUrl,
+      token: input.token,
+      projectId: input.projectId,
+      branchName: input.message.branchName,
+      planRoot: input.planRoot,
+      activePlanId: input.message.env?.R5D_ACTIVE_PLAN_ID
+    });
     const cwd = resolveCommandCwd(workspace.branchPath, input.message.cwd);
     const subprocess = Bun.spawn(input.message.argv, {
       cwd,
@@ -1623,7 +1746,8 @@ async function executeStreamingCommand(input) {
         ...containerRegistryEnv(),
         ...input.message.env ?? {},
         ...internalGitProcessEnv(workspace, input.message.env),
-        ...artifactProcessEnv
+        ...artifactProcessEnv,
+        ...planProcessEnv
       }
     });
     activeProcesses.set(input.message.runId, { process: subprocess, command: input.message.argv });
@@ -1875,7 +1999,7 @@ function resolveHostShell() {
   }
   return { file: process.env.SHELL || "/bin/bash", args: ["-l"] };
 }
-function openPty(input) {
+async function openPty(input) {
   try {
     const branchPath = ensureBranchWorkspace({
       projectId: input.projectId,
@@ -1886,6 +2010,14 @@ function openPty(input) {
       branchName: input.message.branchName,
       manifest: input.manifest
     });
+    const planProcessEnv = await preparePlanEnvForShell({
+      baseUrl: input.baseUrl,
+      token: input.token,
+      projectId: input.projectId,
+      branchName: input.message.branchName,
+      planRoot: input.planRoot,
+      activePlanId: input.message.env?.R5D_ACTIVE_PLAN_ID
+    });
     const shell = resolveHostShell();
     const ptyProcess = createNodePtyBridge({
       file: shell.file,
@@ -1899,6 +2031,7 @@ function openPty(input) {
           ...process.env,
           ...containerRegistryEnv(),
           ...input.message.env ?? {},
+          ...planProcessEnv,
           R5D_PROJECT_ID: input.projectId,
           R5D_BRANCH_NAME: input.message.branchName
         }
@@ -1999,6 +2132,7 @@ async function startWorker(options) {
   const projectsRoot = import_node_path.default.resolve(options.projectRoot ?? defaultProjectsRoot());
   const syncRoot = import_node_path.default.resolve(options.syncRoot ?? process.env.R5D_SYNC_ROOT ?? defaultSyncRoot());
   const artifactRoot = import_node_path.default.resolve(options.artifactRoot ?? process.env.R5D_ARTIFACTS_ROOT ?? defaultArtifactRoot());
+  const planRoot = import_node_path.default.resolve(options.planRoot ?? process.env.R5D_PLANS_ROOT ?? defaultPlanRoot());
   process.stdout.write(`[r5d-worker] label: ${label}
 `);
   process.stdout.write(`[r5d-worker] projects root: ${projectsRoot}
@@ -2006,6 +2140,8 @@ async function startWorker(options) {
   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] server: ${baseUrl}
 `);
@@ -2014,6 +2150,7 @@ async function startWorker(options) {
   import_node_fs.default.mkdirSync(projectsRoot, { recursive: true });
   import_node_fs.default.mkdirSync(syncRoot, { recursive: true });
   import_node_fs.default.mkdirSync(artifactRoot, { recursive: true });
+  import_node_fs.default.mkdirSync(planRoot, { recursive: true });
   const manifestByProjectId = /* @__PURE__ */ new Map();
   const ws = new WebSocket(websocketUrl(baseUrl, label), {
     headers: {
@@ -2030,7 +2167,8 @@ async function startWorker(options) {
         pid: process.pid,
         version: getWorkerVersion(),
         projectRoot: projectsRoot,
-        artifactRoot
+        artifactRoot,
+        planRoot
       }
     };
     ws.send(JSON.stringify(hello));
@@ -2066,6 +2204,20 @@ async function startWorker(options) {
                   branchName,
                   manifest: project
                 });
+                try {
+                  await syncProjectPlans({
+                    baseUrl,
+                    token,
+                    projectId: project.projectId,
+                    branchName,
+                    planRoot
+                  });
+                } catch (error) {
+                  process.stderr.write(
+                    `[r5d-worker] plan sync skipped for ${project.projectId}/${branchName}: ${error instanceof Error ? error.message : String(error)}
+`
+                  );
+                }
               });
             } catch (error) {
               process.stderr.write(
@@ -2104,7 +2256,7 @@ async function startWorker(options) {
         const projectRoot = projectRootFor(projectsRoot, message.projectId, manifestByProjectId);
         process.stdout.write(`[r5d-worker] pty ${message.ptyId}: ${message.projectId}/${message.branchName}
 `);
-        openPty({ ws, message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, manifest });
+        await openPty({ ws, message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, planRoot, manifest });
         return;
       }
       if (message.type === "pty_input") {
@@ -2127,7 +2279,7 @@ async function startWorker(options) {
         const result = await withBranchLock(
           message.projectId,
           message.branchName,
-          () => executeCommand({ message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, manifest })
+          () => executeCommand({ message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, planRoot, manifest })
         );
         ws.send(JSON.stringify(result));
         return;
@@ -2146,7 +2298,7 @@ async function startWorker(options) {
           void withBranchLock(
             message.projectId,
             message.branchName,
-            () => executeStreamingCommand({ ws, message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, manifest })
+            () => executeStreamingCommand({ ws, message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, planRoot, manifest })
           ).catch((error) => {
             sendWorkerMessage(ws, {
               type: "exec_start_error",
@@ -2252,6 +2404,8 @@ if (isCliEntrypoint()) {
   ensureVisibleGitCheckout,
   isArtifactEnvPath,
   prepareArtifactEnvForShell,
+  preparePlanEnvForShell,
   resolveProjectFilePath,
+  syncProjectPlans,
   syncSessionArtifacts
 });

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "type": "commonjs"
 }

package/dist/mjs/main.mjs

@@ -33,6 +33,9 @@ function defaultSyncRoot() {
 function defaultArtifactRoot() {
   return path.join(os.homedir(), ".r5d", "artifacts");
 }
+function defaultPlanRoot() {
+  return path.join(os.homedir(), ".r5d", "plans");
+}
 function printHelp() {
   process.stdout.write(`Usage:
   r5d-worker start --label <label> [--base-url <url>] [--token <token>] [--api-key <key>]
@@ -47,6 +50,7 @@ Options:
   --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)
   -v, --version         Show r5d-worker version
   -h, --help            Show this help
 `);
@@ -168,6 +172,11 @@ function parseArgs(argv) {
       options.artifactRoot = artifactRoot;
       continue;
     }
+    const planRoot = readOption("--plan-root");
+    if (planRoot !== void 0) {
+      options.planRoot = planRoot;
+      continue;
+    }
     rest.push(arg);
   }
   if (options.version) {
@@ -211,6 +220,7 @@ async function readResponseText(response) {
   }
 }
 const R5D_ARTIFACTS_DIR_REF = "$R5D_ARTIFACTS_DIR";
+const R5D_PLANS_DIR_ENV = "R5D_PLANS_DIR";
 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}`);
@@ -219,7 +229,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 the artifact directory`);
+    throw new Error(`${label} escapes sync directory`);
   }
 }
 function sessionArtifactDir(artifactRoot, sessionId) {
@@ -234,6 +244,23 @@ function artifactEnv(artifactRoot, sessionId) {
     R5D_ARTIFACTS_DIR: sessionArtifactDir(artifactRoot, sessionId)
   };
 }
+function projectPlanDir(planRoot, projectId, branchName) {
+  validateProjectId(projectId);
+  validateBranchName(branchName);
+  return path.join(planRoot, projectId, branchName);
+}
+function planEnv(planRoot, projectId, branchName, activePlanId) {
+  const plansDir = projectPlanDir(planRoot, projectId, branchName);
+  const env = {
+    [R5D_PLANS_DIR_ENV]: plansDir
+  };
+  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) {
   return filePath === R5D_ARTIFACTS_DIR_REF || filePath.startsWith(`${R5D_ARTIFACTS_DIR_REF}/`);
 }
@@ -246,99 +273,150 @@ function artifactManifestUrl(baseUrl, projectId, branchName, sessionId) {
 function artifactDownloadUrl(baseUrl, projectId, branchName, sessionId, filename) {
   return new URL(`${artifactApiBasePath(projectId, branchName, sessionId)}/${encodeURIComponent(filename)}`, baseUrl);
 }
+function planApiBasePath(projectId, branchName) {
+  return `/preview-api/${encodeURIComponent(projectId)}/${encodeURIComponent(branchName)}/plans`;
+}
+function planManifestUrl(baseUrl, projectId, branchName) {
+  return new URL(planApiBasePath(projectId, branchName), baseUrl);
+}
+function planDownloadUrl(baseUrl, projectId, branchName, filename) {
+  return new URL(`${planApiBasePath(projectId, branchName)}/${encodeURIComponent(filename)}`, baseUrl);
+}
 function sha256Path(filePath) {
   return createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
 }
-function parseSessionArtifactManifest(value) {
-  if (!value || typeof value !== "object" || !Array.isArray(value.artifacts)) {
-    throw new Error("Artifact manifest response is invalid");
+function parseRemoteFileManifest(value, collectionKey, label) {
+  if (!value || typeof value !== "object" || !Array.isArray(value[collectionKey])) {
+    throw new Error(`${label} manifest response is invalid`);
   }
-  return value.artifacts.map((entry) => {
+  return value[collectionKey].map((entry) => {
     if (!entry || typeof entry !== "object") {
-      throw new Error("Artifact manifest entry is invalid");
+      throw new Error(`${label} manifest entry is invalid`);
     }
-    const artifact = entry;
-    if (typeof artifact.filename !== "string" || artifact.filename.includes("/") || artifact.filename.includes("\\")) {
-      throw new Error("Artifact manifest entry has an invalid filename");
+    const file = entry;
+    if (typeof file.filename !== "string" || file.filename.includes("/") || file.filename.includes("\\")) {
+      throw new Error(`${label} manifest entry has an invalid filename`);
     }
-    if (typeof artifact.size !== "number" || !Number.isFinite(artifact.size) || artifact.size < 0) {
-      throw new Error(`Artifact manifest entry has an invalid size: ${artifact.filename}`);
+    if (typeof file.size !== "number" || !Number.isFinite(file.size) || file.size < 0) {
+      throw new Error(`${label} manifest entry has an invalid size: ${file.filename}`);
     }
-    if (typeof artifact.sha256 !== "string" || !/^[a-f0-9]{64}$/i.test(artifact.sha256)) {
-      throw new Error(`Artifact manifest entry has an invalid sha256: ${artifact.filename}`);
+    if (typeof file.sha256 !== "string" || !/^[a-f0-9]{64}$/i.test(file.sha256)) {
+      throw new Error(`${label} manifest entry has an invalid sha256: ${file.filename}`);
     }
     return {
-      filename: artifact.filename,
-      size: artifact.size,
-      sha256: artifact.sha256.toLowerCase()
+      filename: file.filename,
+      size: file.size,
+      sha256: file.sha256.toLowerCase()
     };
   });
 }
-async function fetchSessionArtifactManifest(input) {
-  const response = await fetch(artifactManifestUrl(input.baseUrl, input.projectId, input.branchName, input.sessionId), {
+async function fetchRemoteFileManifest(input) {
+  const response = await fetch(input.url, {
     headers: {
       Authorization: `Bearer ${input.token}`
     }
   });
   if (!response.ok) {
     const detail = (await readResponseText(response)).trim();
-    throw new Error(`Failed to fetch artifact manifest (${response.status})${detail ? `: ${detail}` : ""}`);
+    throw new Error(`Failed to fetch ${input.label} manifest (${response.status})${detail ? `: ${detail}` : ""}`);
   }
-  return parseSessionArtifactManifest(await response.json());
+  return parseRemoteFileManifest(await response.json(), input.collectionKey, input.label);
 }
-async function downloadSessionArtifact(input) {
-  const targetDir = sessionArtifactDir(input.artifactRoot, input.sessionId);
-  const targetPath = path.join(targetDir, input.artifact.filename);
-  assertInsideRoot(targetDir, targetPath, "Artifact path");
-  const response = await fetch(
-    artifactDownloadUrl(input.baseUrl, input.projectId, input.branchName, input.sessionId, input.artifact.filename),
-    {
-      headers: {
-        Authorization: `Bearer ${input.token}`
-      }
+async function downloadRemoteSyncedFile(input) {
+  const targetPath = path.join(input.targetDir, input.file.filename);
+  assertInsideRoot(input.targetDir, targetPath, input.label);
+  const response = await fetch(input.url, {
+    headers: {
+      Authorization: `Bearer ${input.token}`
     }
-  );
+  });
   if (!response.ok) {
     const detail = (await readResponseText(response)).trim();
-    throw new Error(`Failed to download artifact ${input.artifact.filename} (${response.status})${detail ? `: ${detail}` : ""}`);
+    throw new Error(`Failed to download ${input.label} ${input.file.filename} (${response.status})${detail ? `: ${detail}` : ""}`);
   }
   const buffer = Buffer.from(await response.arrayBuffer());
   const receivedHash = createHash("sha256").update(buffer).digest("hex");
-  if (receivedHash !== input.artifact.sha256) {
-    throw new Error(`Downloaded artifact ${input.artifact.filename} failed sha256 verification`);
+  if (receivedHash !== input.file.sha256) {
+    throw new Error(`Downloaded ${input.label} ${input.file.filename} failed sha256 verification`);
   }
-  if (buffer.length !== input.artifact.size) {
-    throw new Error(`Downloaded artifact ${input.artifact.filename} has unexpected size`);
+  if (buffer.length !== input.file.size) {
+    throw new Error(`Downloaded ${input.label} ${input.file.filename} has unexpected size`);
   }
   const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
   fs.writeFileSync(tempPath, buffer);
   fs.renameSync(tempPath, targetPath);
 }
-async function syncSessionArtifacts(input) {
-  const targetDir = sessionArtifactDir(input.artifactRoot, input.sessionId);
-  fs.mkdirSync(targetDir, { recursive: true });
-  const artifacts = await fetchSessionArtifactManifest(input);
-  const manifestNames = new Set(artifacts.map((artifact) => artifact.filename));
-  for (const artifact of artifacts) {
-    const localPath = path.join(targetDir, artifact.filename);
-    assertInsideRoot(targetDir, localPath, "Artifact path");
+async function syncRemoteFileSet(input) {
+  fs.mkdirSync(input.targetDir, { recursive: true });
+  const manifestNames = new Set(input.files.map((file) => file.filename));
+  for (const file of input.files) {
+    const localPath = path.join(input.targetDir, file.filename);
+    assertInsideRoot(input.targetDir, localPath, input.label);
     if (fs.existsSync(localPath)) {
       const stats = fs.statSync(localPath);
-      if (stats.isFile() && stats.size === artifact.size && sha256Path(localPath) === artifact.sha256) {
+      if (stats.isFile() && stats.size === file.size && sha256Path(localPath) === file.sha256) {
         continue;
       }
       fs.rmSync(localPath, { recursive: true, force: true });
     }
-    await downloadSessionArtifact({ ...input, artifact });
+    await input.download(file);
   }
-  for (const localName of fs.readdirSync(targetDir)) {
+  for (const localName of fs.readdirSync(input.targetDir)) {
     if (!manifestNames.has(localName)) {
-      const localPath = path.join(targetDir, localName);
-      assertInsideRoot(targetDir, localPath, "Artifact path");
+      const localPath = path.join(input.targetDir, localName);
+      assertInsideRoot(input.targetDir, localPath, input.label);
       fs.rmSync(localPath, { recursive: true, force: true });
     }
   }
-  return targetDir;
+  return input.targetDir;
+}
+async function fetchSessionArtifactManifest(input) {
+  return fetchRemoteFileManifest({
+    url: artifactManifestUrl(input.baseUrl, input.projectId, input.branchName, input.sessionId),
+    token: input.token,
+    collectionKey: "artifacts",
+    label: "artifact"
+  });
+}
+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,
+      targetDir,
+      file: artifact,
+      label: "artifact"
+    })
+  });
+}
+async function fetchProjectPlanManifest(input) {
+  return fetchRemoteFileManifest({
+    url: planManifestUrl(input.baseUrl, input.projectId, input.branchName),
+    token: input.token,
+    collectionKey: "plans",
+    label: "plan"
+  });
+}
+async function syncProjectPlans(input) {
+  const targetDir = projectPlanDir(input.planRoot, input.projectId, input.branchName);
+  const plans = await fetchProjectPlanManifest(input);
+  return syncRemoteFileSet({
+    targetDir,
+    files: plans,
+    label: "Plan path",
+    download: (plan) => downloadRemoteSyncedFile({
+      url: planDownloadUrl(input.baseUrl, input.projectId, input.branchName, plan.filename),
+      token: input.token,
+      targetDir,
+      file: plan,
+      label: "plan"
+    })
+  });
 }
 async function resolveArtifactEnvFilePath(input) {
   if (!isArtifactEnvPath(input.filePath)) {
@@ -397,6 +475,19 @@ async function prepareArtifactEnvForShell(input) {
     R5D_ARTIFACTS_DIR: artifactsDir
   };
 }
+async function preparePlanEnvForShell(input) {
+  try {
+    await syncProjectPlans(input);
+  } catch (error) {
+    process.stderr.write(
+      `[r5d-worker] plan sync skipped for ${input.projectId}/${input.branchName}: ${error instanceof Error ? error.message : String(error)}
+`
+    );
+  }
+  const plansDir = projectPlanDir(input.planRoot, input.projectId, input.branchName);
+  fs.mkdirSync(plansDir, { recursive: true });
+  return planEnv(input.planRoot, input.projectId, input.branchName, input.activePlanId);
+}
 async function verifyR5dctlAuth(baseUrl, token) {
   const statusUrl = new URL("/api/r5dctl/auth/status", baseUrl);
   let response;
@@ -441,11 +532,24 @@ function validateLabel(label) {
     throw new Error("Worker label must start with a letter or number and may contain letters, numbers, dots, underscores, and hyphens");
   }
 }
+function validateProjectId(projectId) {
+  if (projectId === "local" || projectId === "local-code") {
+    return;
+  }
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(projectId)) {
+    throw new Error(`Invalid project id from server: ${projectId}`);
+  }
+}
 function validateBranchName(branchName) {
   if (branchName !== "main" && !BRANCH_RE.test(branchName)) {
     throw new Error(`Invalid branch name from server: ${branchName}`);
   }
 }
+function validatePlanId(planId) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(planId)) {
+    throw new Error(`Invalid plan id from server: ${planId}`);
+  }
+}
 function gitExtraHeaderConfigKey(extraHeaderUrl) {
   return `http.${normalizeBaseUrl(extraHeaderUrl)}/.extraHeader`;
 }
@@ -1494,6 +1598,14 @@ async function executeCommand(input) {
       sessionId: input.message.sessionId,
       artifactRoot: input.artifactRoot
     });
+    const planProcessEnv = await preparePlanEnvForShell({
+      baseUrl: input.baseUrl,
+      token: input.token,
+      projectId: input.projectId,
+      branchName: input.message.branchName,
+      planRoot: input.planRoot,
+      activePlanId: input.message.env?.R5D_ACTIVE_PLAN_ID
+    });
     const cwd = resolveCommandCwd(workspace.branchPath, input.message.cwd);
     const subprocess = Bun.spawn(input.message.argv, {
       cwd,
@@ -1504,7 +1616,8 @@ async function executeCommand(input) {
         ...containerRegistryEnv(),
         ...input.message.env ?? {},
         ...internalGitProcessEnv(workspace, input.message.env),
-        ...artifactProcessEnv
+        ...artifactProcessEnv,
+        ...planProcessEnv
       }
     });
     activeProcesses.set(input.message.runId, { process: subprocess, command: input.message.argv });
@@ -1575,6 +1688,14 @@ async function executeStreamingCommand(input) {
       sessionId: input.message.sessionId,
       artifactRoot: input.artifactRoot
     });
+    const planProcessEnv = await preparePlanEnvForShell({
+      baseUrl: input.baseUrl,
+      token: input.token,
+      projectId: input.projectId,
+      branchName: input.message.branchName,
+      planRoot: input.planRoot,
+      activePlanId: input.message.env?.R5D_ACTIVE_PLAN_ID
+    });
     const cwd = resolveCommandCwd(workspace.branchPath, input.message.cwd);
     const subprocess = Bun.spawn(input.message.argv, {
       cwd,
@@ -1585,7 +1706,8 @@ async function executeStreamingCommand(input) {
         ...containerRegistryEnv(),
         ...input.message.env ?? {},
         ...internalGitProcessEnv(workspace, input.message.env),
-        ...artifactProcessEnv
+        ...artifactProcessEnv,
+        ...planProcessEnv
       }
     });
     activeProcesses.set(input.message.runId, { process: subprocess, command: input.message.argv });
@@ -1837,7 +1959,7 @@ function resolveHostShell() {
   }
   return { file: process.env.SHELL || "/bin/bash", args: ["-l"] };
 }
-function openPty(input) {
+async function openPty(input) {
   try {
     const branchPath = ensureBranchWorkspace({
       projectId: input.projectId,
@@ -1848,6 +1970,14 @@ function openPty(input) {
       branchName: input.message.branchName,
       manifest: input.manifest
     });
+    const planProcessEnv = await preparePlanEnvForShell({
+      baseUrl: input.baseUrl,
+      token: input.token,
+      projectId: input.projectId,
+      branchName: input.message.branchName,
+      planRoot: input.planRoot,
+      activePlanId: input.message.env?.R5D_ACTIVE_PLAN_ID
+    });
     const shell = resolveHostShell();
     const ptyProcess = createNodePtyBridge({
       file: shell.file,
@@ -1861,6 +1991,7 @@ function openPty(input) {
           ...process.env,
           ...containerRegistryEnv(),
           ...input.message.env ?? {},
+          ...planProcessEnv,
           R5D_PROJECT_ID: input.projectId,
           R5D_BRANCH_NAME: input.message.branchName
         }
@@ -1961,6 +2092,7 @@ async function startWorker(options) {
   const projectsRoot = path.resolve(options.projectRoot ?? defaultProjectsRoot());
   const syncRoot = path.resolve(options.syncRoot ?? process.env.R5D_SYNC_ROOT ?? defaultSyncRoot());
   const artifactRoot = path.resolve(options.artifactRoot ?? process.env.R5D_ARTIFACTS_ROOT ?? defaultArtifactRoot());
+  const planRoot = path.resolve(options.planRoot ?? process.env.R5D_PLANS_ROOT ?? defaultPlanRoot());
   process.stdout.write(`[r5d-worker] label: ${label}
 `);
   process.stdout.write(`[r5d-worker] projects root: ${projectsRoot}
@@ -1968,6 +2100,8 @@ async function startWorker(options) {
   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] server: ${baseUrl}
 `);
@@ -1976,6 +2110,7 @@ async function startWorker(options) {
   fs.mkdirSync(projectsRoot, { recursive: true });
   fs.mkdirSync(syncRoot, { recursive: true });
   fs.mkdirSync(artifactRoot, { recursive: true });
+  fs.mkdirSync(planRoot, { recursive: true });
   const manifestByProjectId = /* @__PURE__ */ new Map();
   const ws = new WebSocket(websocketUrl(baseUrl, label), {
     headers: {
@@ -1992,7 +2127,8 @@ async function startWorker(options) {
         pid: process.pid,
         version: getWorkerVersion(),
         projectRoot: projectsRoot,
-        artifactRoot
+        artifactRoot,
+        planRoot
       }
     };
     ws.send(JSON.stringify(hello));
@@ -2028,6 +2164,20 @@ async function startWorker(options) {
                   branchName,
                   manifest: project
                 });
+                try {
+                  await syncProjectPlans({
+                    baseUrl,
+                    token,
+                    projectId: project.projectId,
+                    branchName,
+                    planRoot
+                  });
+                } catch (error) {
+                  process.stderr.write(
+                    `[r5d-worker] plan sync skipped for ${project.projectId}/${branchName}: ${error instanceof Error ? error.message : String(error)}
+`
+                  );
+                }
               });
             } catch (error) {
               process.stderr.write(
@@ -2066,7 +2216,7 @@ async function startWorker(options) {
         const projectRoot = projectRootFor(projectsRoot, message.projectId, manifestByProjectId);
         process.stdout.write(`[r5d-worker] pty ${message.ptyId}: ${message.projectId}/${message.branchName}
 `);
-        openPty({ ws, message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, manifest });
+        await openPty({ ws, message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, planRoot, manifest });
         return;
       }
       if (message.type === "pty_input") {
@@ -2089,7 +2239,7 @@ async function startWorker(options) {
         const result = await withBranchLock(
           message.projectId,
           message.branchName,
-          () => executeCommand({ message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, manifest })
+          () => executeCommand({ message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, planRoot, manifest })
         );
         ws.send(JSON.stringify(result));
         return;
@@ -2108,7 +2258,7 @@ async function startWorker(options) {
           void withBranchLock(
             message.projectId,
             message.branchName,
-            () => executeStreamingCommand({ ws, message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, manifest })
+            () => executeStreamingCommand({ ws, message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, planRoot, manifest })
           ).catch((error) => {
             sendWorkerMessage(ws, {
               type: "exec_start_error",
@@ -2213,6 +2363,8 @@ export {
   ensureVisibleGitCheckout,
   isArtifactEnvPath,
   prepareArtifactEnvForShell,
+  preparePlanEnvForShell,
   resolveProjectFilePath,
+  syncProjectPlans,
   syncSessionArtifacts
 };

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "type": "module"
 }

package/dist/types/main.d.ts

@@ -8,6 +8,13 @@ export declare function syncSessionArtifacts(input: {
     sessionId: string;
     artifactRoot: string;
 }): Promise<string>;
+export declare function syncProjectPlans(input: {
+    baseUrl: string;
+    token: string;
+    projectId: string;
+    branchName: string;
+    planRoot: string;
+}): Promise<string>;
 export declare function prepareArtifactEnvForShell(input: {
     baseUrl: string;
     token: string;
@@ -16,6 +23,14 @@ export declare function prepareArtifactEnvForShell(input: {
     sessionId?: string;
     artifactRoot: string;
 }): Promise<Record<string, string>>;
+export declare function preparePlanEnvForShell(input: {
+    baseUrl: string;
+    token: string;
+    projectId: string;
+    branchName: string;
+    planRoot: string;
+    activePlanId?: string;
+}): Promise<Record<string, string>>;
 type GitAuth = {
     extraHeaderUrl: string;
     header: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",