@ricsam/r5d-worker 0.0.37 → 0.0.38

package/README.md

@@ -10,7 +10,7 @@ r5d-worker --version
 The worker uses the existing `r5dctl` config file and accepts `R5D_WORKER_TOKEN` or `R5D_API_KEY`. Project checkouts are managed under:
 
 ```text
-~/.r5d/projects/<namespace-repo>/<branch-name>
+~/.r5d/projects/<namespace>/<project>/<branch-name>
 ```
 
 Web shells and agent shell commands receive a server-issued `r5dctl` credential automatically. The credential is scoped to the signed-in user and revoked when the shell or command finishes, so commands such as `r5dctl auth status` do not require a separate login on the worker host.
@@ -19,6 +19,10 @@ When the user has signed in with GitHub, web shells and agent commands also rece
 
 Visible branch checkouts are the user/agent workbench. Their `origin` remains the connected GitHub repository for manual Git work. r5d internal sync git metadata lives separately under `~/.r5d/sync`; when a worker connects, every idle registered branch is force-synchronized from that internal remote. The same destructive sync can be requested for a live worker from User Settings.
 
+Branch names managed by r5d use lowercase letters, numbers, internal hyphens, and slash-separated segments, for example `ft/esm-support`. They may contain at most 45 characters. On the first start after upgrading to the nested checkout layout, the worker atomically moves each unambiguous legacy `<namespace>-<project>` directory to `<namespace>/<project>`. If both paths exist, it preserves both and stops with recovery instructions.
+
+The nested-layout release is a breaking worker/server cutover. Run `bun run workspace:checkout-preflight` against the production database, stop and upgrade workers to the required version, deploy the matching server, and then reconnect workers. Older workers are rejected before WebSocket upgrade rather than receiving an incompatible manifest.
+
 Worker labels are mandatory and unique per user. Choose labels that describe host capabilities, such as `macos`, `linux`, `ios`, or `ec2-build`.
 
 `r5d-worker start` keeps a lightweight supervisor process attached to the launching terminal or service. When both r5d CLIs are updated from User Settings, the connected runtime verifies the installed versions, exits with a reload signal, and the supervisor reconnects using the new worker package. Updates only run while the worker has no active commands or shells.

package/dist/cjs/main.cjs

@@ -56,12 +56,12 @@ var import_git_identity = require("./git-identity.cjs");
 var import_heartbeat = require("./heartbeat.cjs");
 var import_process_tree = require("./process-tree.cjs");
 var import_supervisor = require("./supervisor.cjs");
+var import_managed_paths = require("./managed-paths.cjs");
 var import_workspace_sync = require("./workspace-sync.cjs");
 const import_meta = {};
 const DEFAULT_BASE_URL = "https://r5d.dev";
 const WORKER_PACKAGE_NAME = "@ricsam/r5d-worker";
 const LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$/;
-const BRANCH_RE = /^[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9]$|^[A-Za-z0-9]$/;
 const DEFAULT_READ_LIMIT = 2e3;
 const DEFAULT_READ_MAX_BYTES = 5e4;
 const MAX_LINE_LENGTH = 2e3;
@@ -604,9 +604,7 @@ function validateProjectId(projectId) {
   }
 }
 function validateBranchName(branchName) {
-  if (branchName !== "main" && !BRANCH_RE.test(branchName)) {
-    throw new Error(`Invalid branch name from server: ${branchName}`);
-  }
+  (0, import_managed_paths.validateManagedBranchName)(branchName);
 }
 function validatePlanId(planId) {
   if (!/^[a-z0-9][a-z0-9-]*$/.test(planId)) {
@@ -2088,10 +2086,13 @@ function websocketUrl(baseUrl, label) {
   const url = new URL("/worker/ws", baseUrl);
   url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
   url.searchParams.set("label", label);
+  url.searchParams.set("version", getWorkerVersion());
   return url.toString();
 }
 function projectRootFor(projectsRoot, projectId, manifestByProjectId) {
-  return import_node_path.default.join(projectsRoot, manifestByProjectId.get(projectId)?.repoSlug ?? projectId);
+  const manifest = manifestByProjectId.get(projectId);
+  if (!manifest) throw new Error(`Project ${projectId} is missing from the worker workspace manifest`);
+  return (0, import_managed_paths.managedProjectRoot)(projectsRoot, manifest.checkoutPathSegments);
 }
 async function startWorker(options) {
   const config = readConfig(options.configPath);
@@ -2285,10 +2286,13 @@ async function startWorker(options) {
         configureGitHubAuth(message.githubCredential);
         visibleGitIdentity = message.gitIdentity;
         workspaceRemoteUrl = message.workspaceRemoteUrl;
+        const migratedProjectIds = (0, import_managed_paths.migrateLegacyProjectRoots)(projectsRoot, message.projects);
         manifestByProjectId.clear();
         for (const project of message.projects) manifestByProjectId.set(project.projectId, project);
-        process.stdout.write(`[r5d-worker] workspace manifest: ${message.projects.length} projects
-`);
+        process.stdout.write(
+          `[r5d-worker] workspace manifest: ${message.projects.length} projects${migratedProjectIds.length > 0 ? `; migrated ${migratedProjectIds.length} project checkout root(s)` : ""}
+`
+        );
         if (!periodicWorkspaceScan) {
           const emptyFingerprint = (0, import_node_crypto.createHash)("sha256").update("").digest("hex");
           periodicWorkspaceScan = setInterval(() => {

package/dist/cjs/managed-paths.cjs

@@ -0,0 +1,158 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var managed_paths_exports = {};
+__export(managed_paths_exports, {
+  BRANCH_NAME_MAX_LENGTH: () => BRANCH_NAME_MAX_LENGTH,
+  BRANCH_NAME_PATTERN: () => BRANCH_NAME_PATTERN,
+  assertPathInside: () => assertPathInside,
+  legacyProjectSlug: () => legacyProjectSlug,
+  managedBranchPath: () => managedBranchPath,
+  managedProjectRoot: () => managedProjectRoot,
+  migrateLegacyProjectRoots: () => migrateLegacyProjectRoots,
+  validateCheckoutPathSegments: () => validateCheckoutPathSegments,
+  validateManagedBranchName: () => validateManagedBranchName
+});
+module.exports = __toCommonJS(managed_paths_exports);
+var import_node_fs = __toESM(require("node:fs"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+const BRANCH_NAME_MAX_LENGTH = 45;
+const BRANCH_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*$/;
+const PROJECT_SEGMENT_PATTERN = /^[a-z0-9._-]+$/;
+const WINDOWS_RESERVED_PATH_SEGMENT = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+function validateManagedBranchName(branchName) {
+  if (typeof branchName !== "string" || branchName.length === 0) {
+    throw new Error("Branch name is required");
+  }
+  if (branchName.length > BRANCH_NAME_MAX_LENGTH) {
+    throw new Error(`Branch name must be ${BRANCH_NAME_MAX_LENGTH} characters or fewer`);
+  }
+  if (!BRANCH_NAME_PATTERN.test(branchName)) {
+    throw new Error(`Invalid branch name from server: ${branchName}`);
+  }
+  const reserved = branchName.split("/").find((segment) => WINDOWS_RESERVED_PATH_SEGMENT.test(segment));
+  if (reserved) {
+    throw new Error(`Invalid branch name from server: reserved path segment '${reserved}'`);
+  }
+}
+function validateCheckoutPathSegments(value) {
+  if (!Array.isArray(value) || value.length !== 2) {
+    throw new Error("Invalid checkout path from server: expected namespace and project segments");
+  }
+  const segments = value;
+  for (const segment of segments) {
+    if (typeof segment !== "string" || !PROJECT_SEGMENT_PATTERN.test(segment) || segment !== segment.toLowerCase() || segment === "." || segment === ".." || segment === ".git" || segment.endsWith(".") || WINDOWS_RESERVED_PATH_SEGMENT.test(segment)) {
+      throw new Error(`Invalid checkout path segment from server: ${String(segment)}`);
+    }
+  }
+  return [segments[0], segments[1]];
+}
+function assertPathInside(root, candidate, label) {
+  const resolvedRoot = import_node_path.default.resolve(root);
+  const resolvedCandidate = import_node_path.default.resolve(candidate);
+  const relative = import_node_path.default.relative(resolvedRoot, resolvedCandidate);
+  if (relative === ".." || relative.startsWith(`..${import_node_path.default.sep}`) || import_node_path.default.isAbsolute(relative)) {
+    throw new Error(`${label} escapes its managed root: ${candidate}`);
+  }
+}
+function assertNoSymlinkComponents(root, candidate) {
+  assertPathInside(root, candidate, "Checkout path");
+  const relative = import_node_path.default.relative(import_node_path.default.resolve(root), import_node_path.default.resolve(candidate));
+  let current = import_node_path.default.resolve(root);
+  for (const component of relative.split(import_node_path.default.sep).filter(Boolean)) {
+    current = import_node_path.default.join(current, component);
+    if (!import_node_fs.default.existsSync(current)) break;
+    if (import_node_fs.default.lstatSync(current).isSymbolicLink()) {
+      throw new Error(`Checkout path contains a symbolic link: ${current}`);
+    }
+  }
+}
+function managedProjectRoot(projectsRoot, checkoutPathSegments) {
+  const segments = validateCheckoutPathSegments(checkoutPathSegments);
+  const result = import_node_path.default.join(projectsRoot, ...segments);
+  assertNoSymlinkComponents(projectsRoot, result);
+  return result;
+}
+function managedBranchPath(projectsRoot, checkoutPathSegments, branchName) {
+  validateManagedBranchName(branchName);
+  const projectRoot = managedProjectRoot(projectsRoot, checkoutPathSegments);
+  const result = import_node_path.default.join(projectRoot, ...branchName.split("/"));
+  assertNoSymlinkComponents(projectRoot, result);
+  return result;
+}
+function legacyProjectSlug(projectPath, projectId) {
+  return (projectPath || projectId).trim().toLowerCase().replace(/[^a-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "") || projectId;
+}
+function migrateLegacyProjectRoots(projectsRoot, projects) {
+  const resolvedRoot = import_node_path.default.resolve(projectsRoot);
+  const legacyOwners = /* @__PURE__ */ new Map();
+  const nestedOwners = /* @__PURE__ */ new Map();
+  const moves = [];
+  for (const project of projects) {
+    const nestedRoot = managedProjectRoot(resolvedRoot, project.checkoutPathSegments);
+    const legacySlug = legacyProjectSlug(project.projectPath, project.projectId);
+    const legacyRoot = import_node_path.default.join(resolvedRoot, legacySlug);
+    assertNoSymlinkComponents(resolvedRoot, legacyRoot);
+    const existingLegacyOwner = legacyOwners.get(legacyRoot);
+    if (existingLegacyOwner) {
+      throw new Error(`Projects ${existingLegacyOwner} and ${project.projectId} collide at legacy checkout path '${legacyRoot}'`);
+    }
+    legacyOwners.set(legacyRoot, project.projectId);
+    const existingNestedOwner = nestedOwners.get(nestedRoot);
+    if (existingNestedOwner) {
+      throw new Error(`Projects ${existingNestedOwner} and ${project.projectId} collide at checkout path '${nestedRoot}'`);
+    }
+    nestedOwners.set(nestedRoot, project.projectId);
+    const legacyExists = import_node_fs.default.existsSync(legacyRoot);
+    const nestedExists = import_node_fs.default.existsSync(nestedRoot);
+    if (legacyExists && nestedExists) {
+      throw new Error(
+        `Checkout migration is ambiguous for ${project.projectPath}: both '${legacyRoot}' and '${nestedRoot}' exist. Preserve the desired checkout and remove or relocate the other path before reconnecting the worker.`
+      );
+    }
+    if (legacyExists) moves.push({ projectId: project.projectId, legacyRoot, nestedRoot });
+  }
+  for (const move of moves) {
+    import_node_fs.default.mkdirSync(import_node_path.default.dirname(move.nestedRoot), { recursive: true });
+    assertNoSymlinkComponents(resolvedRoot, import_node_path.default.dirname(move.nestedRoot));
+    import_node_fs.default.renameSync(move.legacyRoot, move.nestedRoot);
+  }
+  return moves.map((move) => move.projectId);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BRANCH_NAME_MAX_LENGTH,
+  BRANCH_NAME_PATTERN,
+  assertPathInside,
+  legacyProjectSlug,
+  managedBranchPath,
+  managedProjectRoot,
+  migrateLegacyProjectRoots,
+  validateCheckoutPathSegments,
+  validateManagedBranchName
+});

package/dist/cjs/package.json

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

package/dist/cjs/workspace-sync.cjs

@@ -45,6 +45,7 @@ module.exports = __toCommonJS(workspace_sync_exports);
 var import_node_crypto = require("node:crypto");
 var import_node_fs = __toESM(require("node:fs"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
+var import_managed_paths = require("./managed-paths.cjs");
 const WORKSPACE_BRANCH = "main";
 const MAX_WORKSPACE_SYNC_DIFF_BYTES = 5 * 1024 * 1024;
 const WORKSPACE_PERIODIC_SCAN_INTERVAL_MS = 5e3;
@@ -92,7 +93,7 @@ function workspacePlansRelativePath(projectId, branchName) {
   return import_node_path.default.posix.join("plans", projectId, encodeWorkspaceBranch(branchName));
 }
 function visibleProjectBranchPath(projectsRoot, manifest, branchName) {
-  return import_node_path.default.join(projectsRoot, manifest.repoSlug || manifest.projectId, branchName);
+  return (0, import_managed_paths.managedBranchPath)(projectsRoot, manifest.checkoutPathSegments, branchName);
 }
 function localPlansBranchPath(plansRoot, projectId, branchName) {
   return import_node_path.default.join(plansRoot, projectId, branchName);

package/dist/mjs/main.mjs

@@ -9,6 +9,7 @@ import { configureVisibleGitIdentity } from "./git-identity.mjs";
 import { hasWorkerHeartbeatTimedOut, WORKER_HEARTBEAT_INTERVAL_MS } from "./heartbeat.mjs";
 import { terminateProcessTree } from "./process-tree.mjs";
 import { superviseWorkerRuntime, WORKER_RELOAD_EXIT_CODE, WORKER_RUNTIME_ENV } from "./supervisor.mjs";
+import { managedProjectRoot, migrateLegacyProjectRoots, validateManagedBranchName } from "./managed-paths.mjs";
 import {
   WORKSPACE_PERIODIC_SCAN_INTERVAL_MS,
   WorkspaceSyncSingleFlight,
@@ -18,7 +19,6 @@ import {
 const DEFAULT_BASE_URL = "https://r5d.dev";
 const WORKER_PACKAGE_NAME = "@ricsam/r5d-worker";
 const LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$/;
-const BRANCH_RE = /^[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9]$|^[A-Za-z0-9]$/;
 const DEFAULT_READ_LIMIT = 2e3;
 const DEFAULT_READ_MAX_BYTES = 5e4;
 const MAX_LINE_LENGTH = 2e3;
@@ -561,9 +561,7 @@ function validateProjectId(projectId) {
   }
 }
 function validateBranchName(branchName) {
-  if (branchName !== "main" && !BRANCH_RE.test(branchName)) {
-    throw new Error(`Invalid branch name from server: ${branchName}`);
-  }
+  validateManagedBranchName(branchName);
 }
 function validatePlanId(planId) {
   if (!/^[a-z0-9][a-z0-9-]*$/.test(planId)) {
@@ -2045,10 +2043,13 @@ function websocketUrl(baseUrl, label) {
   const url = new URL("/worker/ws", baseUrl);
   url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
   url.searchParams.set("label", label);
+  url.searchParams.set("version", getWorkerVersion());
   return url.toString();
 }
 function projectRootFor(projectsRoot, projectId, manifestByProjectId) {
-  return path.join(projectsRoot, manifestByProjectId.get(projectId)?.repoSlug ?? projectId);
+  const manifest = manifestByProjectId.get(projectId);
+  if (!manifest) throw new Error(`Project ${projectId} is missing from the worker workspace manifest`);
+  return managedProjectRoot(projectsRoot, manifest.checkoutPathSegments);
 }
 async function startWorker(options) {
   const config = readConfig(options.configPath);
@@ -2242,10 +2243,13 @@ async function startWorker(options) {
         configureGitHubAuth(message.githubCredential);
         visibleGitIdentity = message.gitIdentity;
         workspaceRemoteUrl = message.workspaceRemoteUrl;
+        const migratedProjectIds = migrateLegacyProjectRoots(projectsRoot, message.projects);
         manifestByProjectId.clear();
         for (const project of message.projects) manifestByProjectId.set(project.projectId, project);
-        process.stdout.write(`[r5d-worker] workspace manifest: ${message.projects.length} projects
-`);
+        process.stdout.write(
+          `[r5d-worker] workspace manifest: ${message.projects.length} projects${migratedProjectIds.length > 0 ? `; migrated ${migratedProjectIds.length} project checkout root(s)` : ""}
+`
+        );
         if (!periodicWorkspaceScan) {
           const emptyFingerprint = createHash("sha256").update("").digest("hex");
           periodicWorkspaceScan = setInterval(() => {

package/dist/mjs/managed-paths.mjs

@@ -0,0 +1,116 @@
+import fs from "node:fs";
+import path from "node:path";
+const BRANCH_NAME_MAX_LENGTH = 45;
+const BRANCH_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*$/;
+const PROJECT_SEGMENT_PATTERN = /^[a-z0-9._-]+$/;
+const WINDOWS_RESERVED_PATH_SEGMENT = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+function validateManagedBranchName(branchName) {
+  if (typeof branchName !== "string" || branchName.length === 0) {
+    throw new Error("Branch name is required");
+  }
+  if (branchName.length > BRANCH_NAME_MAX_LENGTH) {
+    throw new Error(`Branch name must be ${BRANCH_NAME_MAX_LENGTH} characters or fewer`);
+  }
+  if (!BRANCH_NAME_PATTERN.test(branchName)) {
+    throw new Error(`Invalid branch name from server: ${branchName}`);
+  }
+  const reserved = branchName.split("/").find((segment) => WINDOWS_RESERVED_PATH_SEGMENT.test(segment));
+  if (reserved) {
+    throw new Error(`Invalid branch name from server: reserved path segment '${reserved}'`);
+  }
+}
+function validateCheckoutPathSegments(value) {
+  if (!Array.isArray(value) || value.length !== 2) {
+    throw new Error("Invalid checkout path from server: expected namespace and project segments");
+  }
+  const segments = value;
+  for (const segment of segments) {
+    if (typeof segment !== "string" || !PROJECT_SEGMENT_PATTERN.test(segment) || segment !== segment.toLowerCase() || segment === "." || segment === ".." || segment === ".git" || segment.endsWith(".") || WINDOWS_RESERVED_PATH_SEGMENT.test(segment)) {
+      throw new Error(`Invalid checkout path segment from server: ${String(segment)}`);
+    }
+  }
+  return [segments[0], segments[1]];
+}
+function assertPathInside(root, candidate, label) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedCandidate = path.resolve(candidate);
+  const relative = path.relative(resolvedRoot, resolvedCandidate);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`${label} escapes its managed root: ${candidate}`);
+  }
+}
+function assertNoSymlinkComponents(root, candidate) {
+  assertPathInside(root, candidate, "Checkout path");
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  let current = path.resolve(root);
+  for (const component of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, component);
+    if (!fs.existsSync(current)) break;
+    if (fs.lstatSync(current).isSymbolicLink()) {
+      throw new Error(`Checkout path contains a symbolic link: ${current}`);
+    }
+  }
+}
+function managedProjectRoot(projectsRoot, checkoutPathSegments) {
+  const segments = validateCheckoutPathSegments(checkoutPathSegments);
+  const result = path.join(projectsRoot, ...segments);
+  assertNoSymlinkComponents(projectsRoot, result);
+  return result;
+}
+function managedBranchPath(projectsRoot, checkoutPathSegments, branchName) {
+  validateManagedBranchName(branchName);
+  const projectRoot = managedProjectRoot(projectsRoot, checkoutPathSegments);
+  const result = path.join(projectRoot, ...branchName.split("/"));
+  assertNoSymlinkComponents(projectRoot, result);
+  return result;
+}
+function legacyProjectSlug(projectPath, projectId) {
+  return (projectPath || projectId).trim().toLowerCase().replace(/[^a-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "") || projectId;
+}
+function migrateLegacyProjectRoots(projectsRoot, projects) {
+  const resolvedRoot = path.resolve(projectsRoot);
+  const legacyOwners = /* @__PURE__ */ new Map();
+  const nestedOwners = /* @__PURE__ */ new Map();
+  const moves = [];
+  for (const project of projects) {
+    const nestedRoot = managedProjectRoot(resolvedRoot, project.checkoutPathSegments);
+    const legacySlug = legacyProjectSlug(project.projectPath, project.projectId);
+    const legacyRoot = path.join(resolvedRoot, legacySlug);
+    assertNoSymlinkComponents(resolvedRoot, legacyRoot);
+    const existingLegacyOwner = legacyOwners.get(legacyRoot);
+    if (existingLegacyOwner) {
+      throw new Error(`Projects ${existingLegacyOwner} and ${project.projectId} collide at legacy checkout path '${legacyRoot}'`);
+    }
+    legacyOwners.set(legacyRoot, project.projectId);
+    const existingNestedOwner = nestedOwners.get(nestedRoot);
+    if (existingNestedOwner) {
+      throw new Error(`Projects ${existingNestedOwner} and ${project.projectId} collide at checkout path '${nestedRoot}'`);
+    }
+    nestedOwners.set(nestedRoot, project.projectId);
+    const legacyExists = fs.existsSync(legacyRoot);
+    const nestedExists = fs.existsSync(nestedRoot);
+    if (legacyExists && nestedExists) {
+      throw new Error(
+        `Checkout migration is ambiguous for ${project.projectPath}: both '${legacyRoot}' and '${nestedRoot}' exist. Preserve the desired checkout and remove or relocate the other path before reconnecting the worker.`
+      );
+    }
+    if (legacyExists) moves.push({ projectId: project.projectId, legacyRoot, nestedRoot });
+  }
+  for (const move of moves) {
+    fs.mkdirSync(path.dirname(move.nestedRoot), { recursive: true });
+    assertNoSymlinkComponents(resolvedRoot, path.dirname(move.nestedRoot));
+    fs.renameSync(move.legacyRoot, move.nestedRoot);
+  }
+  return moves.map((move) => move.projectId);
+}
+export {
+  BRANCH_NAME_MAX_LENGTH,
+  BRANCH_NAME_PATTERN,
+  assertPathInside,
+  legacyProjectSlug,
+  managedBranchPath,
+  managedProjectRoot,
+  migrateLegacyProjectRoots,
+  validateCheckoutPathSegments,
+  validateManagedBranchName
+};

package/dist/mjs/package.json

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

package/dist/mjs/workspace-sync.mjs

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { managedBranchPath } from "./managed-paths.mjs";
 const WORKSPACE_BRANCH = "main";
 const MAX_WORKSPACE_SYNC_DIFF_BYTES = 5 * 1024 * 1024;
 const WORKSPACE_PERIODIC_SCAN_INTERVAL_MS = 5e3;
@@ -48,7 +49,7 @@ function workspacePlansRelativePath(projectId, branchName) {
   return path.posix.join("plans", projectId, encodeWorkspaceBranch(branchName));
 }
 function visibleProjectBranchPath(projectsRoot, manifest, branchName) {
-  return path.join(projectsRoot, manifest.repoSlug || manifest.projectId, branchName);
+  return managedBranchPath(projectsRoot, manifest.checkoutPathSegments, branchName);
 }
 function localPlansBranchPath(plansRoot, projectId, branchName) {
   return path.join(plansRoot, projectId, branchName);

package/dist/types/managed-paths.d.ts

@@ -0,0 +1,15 @@
+export declare const BRANCH_NAME_MAX_LENGTH = 45;
+export declare const BRANCH_NAME_PATTERN: RegExp;
+export type CheckoutPathSegments = [namespace: string, project: string];
+export type ManagedProjectManifestPath = {
+    projectId: string;
+    projectPath: string;
+    checkoutPathSegments: CheckoutPathSegments;
+};
+export declare function validateManagedBranchName(branchName: string): void;
+export declare function validateCheckoutPathSegments(value: unknown): CheckoutPathSegments;
+export declare function assertPathInside(root: string, candidate: string, label: string): void;
+export declare function managedProjectRoot(projectsRoot: string, checkoutPathSegments: unknown): string;
+export declare function managedBranchPath(projectsRoot: string, checkoutPathSegments: unknown, branchName: string): string;
+export declare function legacyProjectSlug(projectPath: string, projectId: string): string;
+export declare function migrateLegacyProjectRoots(projectsRoot: string, projects: ManagedProjectManifestPath[]): string[];

package/dist/types/workspace-sync.d.ts

@@ -1,9 +1,10 @@
+import { type CheckoutPathSegments } from "./managed-paths";
 export declare const WORKSPACE_BRANCH = "main";
 export declare const MAX_WORKSPACE_SYNC_DIFF_BYTES: number;
 export declare const WORKSPACE_PERIODIC_SCAN_INTERVAL_MS = 5000;
 export type WorkspaceProjectManifestEntry = {
     projectId: string;
-    repoSlug: string;
+    checkoutPathSegments: CheckoutPathSegments;
     projectPath: string;
     repoHttpUrl: string | null;
     repoAuthHeader: string | null;

package/package.json

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