@kmugalkhod/lightcode 0.13.0 → 0.14.0

package/assets/web/index.html

@@ -7,12 +7,12 @@
     <meta name="theme-color" content="#0D1117" />
     <title>Lightcode</title>
     
-  <link rel="stylesheet" crossorigin href="./index-21aq5q6q.css"><script type="module" crossorigin src="./index-j5mzdh93.js"></script></head>
+  <link rel="stylesheet" crossorigin href="./index-2dshmdgm.css"><script type="module" crossorigin src="./index-x9zna9dg.js"></script></head>
   <body>
     <!--
       THESIS: One local coding workspace shared with the CLI; this surface rejects dashboard-card clutter and keeps the project conversation central.
       OWN-WORLD: Charcoal #0D1117/#121820/#18212B, hairline #273241, amber #F2A65A, workhorse system sans, and ui-monospace only for code and data.
-      STORY: Choose a Desktop project, create or resume a session, stream the work, and resolve approvals without leaving the conversation.
+      STORY: Choose a project from a familiar local folder, create or resume a session, stream the work, and resolve approvals without leaving the conversation.
       FIRST VIEWPORT: A 264px session rail, an amber workspace ribbon, and one centered conversation/composer; below 760px the rail becomes a drawer.
       FORM: Workspace-ribbon wayfinding, grounded candidate five and the assigned Operate structure; seed key bf554f40.
       FINISH: unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, and DESIGN.md

package/cli.js

@@ -124,7 +124,7 @@ var init_logger = __esm(() => {
 });
 
 // packages/shared/src/version.ts
-var lightcodeVersion = "0.13.0";
+var lightcodeVersion = "0.14.0";
 
 // packages/shared/src/index.ts
 var productName = "Lightcode";
@@ -10093,7 +10093,13 @@ var workspaceLocationIdSchema, workspaceLocationStateSchema, workspaceLocationSc
 var init_workspace_browser = __esm(() => {
   init_coding_agent_modes();
   init_permissions();
-  workspaceLocationIdSchema = z37.literal("desktop");
+  workspaceLocationIdSchema = z37.enum([
+    "desktop",
+    "home",
+    "documents",
+    "downloads",
+    "projects"
+  ]);
   workspaceLocationStateSchema = z37.enum([
     "unprobed",
     "available"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kmugalkhod/lightcode",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Lightcode — a local AI coding agent with terminal and browser interfaces.",
   "type": "module",
   "license": "MIT",

package/server.js

@@ -515,6 +515,9 @@ function loadWebAuthStateFromEnvironment(env = Bun.env) {
 function isPublicWebPath(pathname) {
   return pathname === "/healthz" || pathname === "/app" || pathname === "/app/" || pathname.startsWith("/app/");
 }
+function isPublicWebAppPath(pathname) {
+  return pathname === "/app" || pathname === "/app/" || pathname.startsWith("/app/");
+}
 function looksLikeBrowserRequest(request) {
   const headers = request.headers;
   if (headers.get("x-lightcode-client")?.toLowerCase() === "web") {
@@ -577,8 +580,9 @@ function createWebSecurityMiddleware(options = {}) {
       return jsonSecurityError(c, 403, "web_origin_forbidden", "The browser origin is not allowed.");
     }
     const fetchSite = request.headers.get("sec-fetch-site");
+    const isBootstrapDocumentNavigation = isPublicWebAppPath(pathname) && (request.method === "GET" || request.method === "HEAD") && request.headers.get("sec-fetch-mode") === "navigate" && request.headers.get("sec-fetch-dest") === "document";
     const allowedFetchSites = publicPath ? new Set(["same-origin", "none"]) : new Set(["same-origin"]);
-    if (browserRequest && fetchSite !== null && !allowedFetchSites.has(fetchSite)) {
+    if (browserRequest && fetchSite !== null && !allowedFetchSites.has(fetchSite) && !(fetchSite === "cross-site" && isBootstrapDocumentNavigation)) {
       return jsonSecurityError(c, 403, "web_fetch_forbidden", "Cross-site browser requests are not allowed.");
     }
     if (!publicPath && browserRequest) {
@@ -9522,7 +9526,13 @@ var workspaceLocationIdSchema, workspaceLocationStateSchema, workspaceLocationSc
 var init_workspace_browser = __esm(() => {
   init_coding_agent_modes();
   init_permissions();
-  workspaceLocationIdSchema = z38.literal("desktop");
+  workspaceLocationIdSchema = z38.enum([
+    "desktop",
+    "home",
+    "documents",
+    "downloads",
+    "projects"
+  ]);
   workspaceLocationStateSchema = z38.enum([
     "unprobed",
     "available"
@@ -16804,7 +16814,7 @@ import { Hono as Hono7 } from "hono";
 function pathImplementation(platform4) {
   return platform4 === "win32" ? path24.win32 : path24.posix;
 }
-function normalizeDesktopCandidate(candidate, platform4) {
+function normalizeKnownFolderCandidate(candidate, platform4) {
   if (candidate.includes("\x00")) {
     return null;
   }
@@ -16848,22 +16858,23 @@ async function readSmallUserDirsConfiguration(filePath) {
     });
   }
 }
-async function resolveWindowsDesktopKnownFolder(environment) {
+async function resolveWindowsKnownFolder(environment, folder) {
   try {
     const systemRootCandidate = environment.SystemRoot?.trim() || environment.WINDIR?.trim() || "C:\\Windows";
-    const windowsRoot = normalizeDesktopCandidate(systemRootCandidate, "win32");
+    const windowsRoot = normalizeKnownFolderCandidate(systemRootCandidate, "win32");
     if (!windowsRoot) {
       return null;
     }
     const systemDirectory = path24.win32.join(windowsRoot, "System32");
     const executable = path24.win32.join(systemDirectory, "WindowsPowerShell", "v1.0", "powershell.exe");
+    const folderExpression = folder === "desktop" ? "[Environment]::GetFolderPath([Environment+SpecialFolder]::DesktopDirectory)" : folder === "documents" ? "[Environment]::GetFolderPath([Environment+SpecialFolder]::MyDocuments)" : "[Environment]::ExpandEnvironmentVariables([string](Get-ItemProperty -LiteralPath 'HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders' -Name '{374DE290-123F-4565-9164-39C4925E467B}' -ErrorAction Stop).'{374DE290-123F-4565-9164-39C4925E467B}')";
     const child = Bun.spawn([
       executable,
       "-NoLogo",
       "-NoProfile",
       "-NonInteractive",
       "-Command",
-      "[Console]::OutputEncoding=[Text.UTF8Encoding]::new($false);[Console]::Write([Environment]::GetFolderPath([Environment+SpecialFolder]::DesktopDirectory))"
+      `[Console]::OutputEncoding=[Text.UTF8Encoding]::new($false);[Console]::Write(${folderExpression})`
     ], {
       cwd: systemDirectory,
       env: {
@@ -16900,13 +16911,13 @@ async function resolveWindowsDesktopKnownFolder(environment) {
     return null;
   }
 }
-function parseXdgDesktopDirectory(contents, homeDirectory) {
+function parseXdgUserDirectory(contents, homeDirectory, variableName) {
   for (const line of contents.split(/\r?\n/)) {
-    const match = line.match(/^\s*XDG_DESKTOP_DIR="([^"\r\n]*)"\s*$/);
-    if (!match) {
+    const match = line.match(/^\s*(XDG_(?:DESKTOP|DOCUMENTS|DOWNLOAD)_DIR)="([^"\r\n]*)"\s*$/);
+    if (!match || match[1] !== variableName) {
       continue;
     }
-    const configured = match[1];
+    const configured = match[2];
     if (!configured || configured.includes("\x00") || /[`]/.test(configured)) {
       return null;
     }
@@ -16926,6 +16937,28 @@ function parseXdgDesktopDirectory(contents, homeDirectory) {
   }
   return null;
 }
+async function firstUsableKnownFolder(candidates, platform4, probe) {
+  const seen = new Set;
+  for (const unvalidated of candidates) {
+    if (!unvalidated) {
+      continue;
+    }
+    const candidate = normalizeKnownFolderCandidate(unvalidated, platform4);
+    if (!candidate) {
+      continue;
+    }
+    const key = platform4 === "win32" ? candidate.toLowerCase() : candidate;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    const state = await probe(candidate);
+    if (state === "available" || state === "permission-denied") {
+      return candidate;
+    }
+  }
+  return null;
+}
 async function resolveDesktopDirectoryPath(options = {}) {
   const platform4 = options.platform ?? process.platform;
   const pathApi = pathImplementation(platform4);
@@ -16933,35 +16966,16 @@ async function resolveDesktopDirectoryPath(options = {}) {
   const homeDirectory = pathApi.normalize(options.homeDirectory ?? homedir4());
   const explicit = environment.LIGHTCODE_DESKTOP_PATH?.trim();
   if (explicit) {
-    const normalized = normalizeDesktopCandidate(explicit, platform4);
+    const normalized = normalizeKnownFolderCandidate(explicit, platform4);
     if (!normalized) {
       throw new WorkspaceRouteError("workspace_unavailable", "LIGHTCODE_DESKTOP_PATH must be an absolute folder path and cannot be a filesystem root.", 500, false);
     }
     return normalized;
   }
   const probe = options.probeDirectory ?? probeDirectory;
-  const firstAvailable = async (candidates) => {
-    const seen = new Set;
-    for (const unvalidated of candidates) {
-      const candidate = normalizeDesktopCandidate(unvalidated, platform4);
-      if (!candidate) {
-        continue;
-      }
-      const key = platform4 === "win32" ? candidate.toLowerCase() : candidate;
-      if (seen.has(key)) {
-        continue;
-      }
-      seen.add(key);
-      const state = await probe(candidate);
-      if (state === "available" || state === "permission-denied") {
-        return candidate;
-      }
-    }
-    return null;
-  };
   if (platform4 === "win32") {
     const userProfile = environment.USERPROFILE?.trim() || homeDirectory;
-    const knownFolder = await (options.resolveWindowsKnownFolder ?? (() => resolveWindowsDesktopKnownFolder(environment)))();
+    const knownFolder = await (options.resolveWindowsKnownFolder ?? (() => resolveWindowsKnownFolder(environment, "desktop")))();
     const candidates = [
       knownFolder,
       environment.OneDrive,
@@ -16977,16 +16991,16 @@ async function resolveDesktopDirectoryPath(options = {}) {
       ];
     });
     candidates.push(path24.win32.join(userProfile, "Desktop"));
-    return await firstAvailable(candidates) ?? path24.win32.join(homeDirectory, "Desktop");
+    return await firstUsableKnownFolder(candidates, platform4, probe) ?? path24.win32.join(homeDirectory, "Desktop");
   }
   if (platform4 === "linux") {
     const configHome = environment.XDG_CONFIG_HOME?.trim();
     const safeConfigHome = configHome && path24.posix.isAbsolute(configHome) ? path24.posix.normalize(configHome) : path24.posix.join(homeDirectory, ".config");
     const readConfiguration = options.readUserDirsConfiguration ?? readSmallUserDirsConfiguration;
     const contents = await readConfiguration(path24.posix.join(safeConfigHome, "user-dirs.dirs"));
-    const configured = contents ? parseXdgDesktopDirectory(contents, homeDirectory) : null;
+    const configured = contents ? parseXdgUserDirectory(contents, homeDirectory, "XDG_DESKTOP_DIR") : null;
     if (configured) {
-      const selected = await firstAvailable([configured]);
+      const selected = await firstUsableKnownFolder([configured], platform4, probe);
       if (selected) {
         return selected;
       }
@@ -16994,6 +17008,89 @@ async function resolveDesktopDirectoryPath(options = {}) {
   }
   return pathApi.join(homeDirectory, "Desktop");
 }
+async function resolveUserDirectoryPath(folder, options) {
+  const platform4 = options.platform ?? process.platform;
+  const pathApi = pathImplementation(platform4);
+  const environment = options.environment ?? Bun.env;
+  const homeDirectory = pathApi.normalize(options.homeDirectory ?? homedir4());
+  const displayName = folder === "documents" ? "Documents" : "Downloads";
+  const overrideName = folder === "documents" ? "LIGHTCODE_DOCUMENTS_PATH" : "LIGHTCODE_DOWNLOADS_PATH";
+  const explicit = environment[overrideName]?.trim();
+  if (explicit) {
+    const normalized = normalizeKnownFolderCandidate(explicit, platform4);
+    if (!normalized) {
+      throw new WorkspaceRouteError("workspace_unavailable", `${overrideName} must be an absolute folder path and cannot be a filesystem root.`, 500, false);
+    }
+    return normalized;
+  }
+  const probe = options.probeDirectory ?? probeDirectory;
+  if (platform4 === "win32") {
+    const knownFolder = await (options.resolveWindowsKnownFolder ?? (() => resolveWindowsKnownFolder(environment, folder)))();
+    const userProfile = environment.USERPROFILE?.trim() || homeDirectory;
+    const cloudRoots = [
+      environment.OneDrive,
+      environment.OneDriveConsumer,
+      environment.OneDriveCommercial
+    ];
+    const candidates = [
+      knownFolder,
+      ...cloudRoots.map((root) => root?.trim() ? path24.win32.join(root.trim(), displayName) : null),
+      path24.win32.join(userProfile, displayName),
+      path24.win32.join(homeDirectory, displayName)
+    ];
+    return await firstUsableKnownFolder(candidates, platform4, probe) ?? path24.win32.join(homeDirectory, displayName);
+  }
+  if (platform4 === "linux") {
+    const configHome = environment.XDG_CONFIG_HOME?.trim();
+    const safeConfigHome = configHome && path24.posix.isAbsolute(configHome) ? path24.posix.normalize(configHome) : path24.posix.join(homeDirectory, ".config");
+    const readConfiguration = options.readUserDirsConfiguration ?? readSmallUserDirsConfiguration;
+    const contents = await readConfiguration(path24.posix.join(safeConfigHome, "user-dirs.dirs"));
+    const configured = contents ? parseXdgUserDirectory(contents, homeDirectory, folder === "documents" ? "XDG_DOCUMENTS_DIR" : "XDG_DOWNLOAD_DIR") : null;
+    const selected = await firstUsableKnownFolder([configured], platform4, probe);
+    if (selected) {
+      return selected;
+    }
+  }
+  return pathApi.join(homeDirectory, displayName);
+}
+function resolveDocumentsDirectoryPath(options = {}) {
+  return resolveUserDirectoryPath("documents", options);
+}
+function resolveDownloadsDirectoryPath(options = {}) {
+  return resolveUserDirectoryPath("downloads", options);
+}
+async function resolveProjectsDirectoryPath(options = {}) {
+  const platform4 = options.platform ?? process.platform;
+  const pathApi = pathImplementation(platform4);
+  const environment = options.environment ?? Bun.env;
+  const homeDirectory = pathApi.normalize(options.homeDirectory ?? homedir4());
+  const explicit = environment.LIGHTCODE_PROJECTS_PATH?.trim();
+  if (explicit) {
+    const normalized = normalizeKnownFolderCandidate(explicit, platform4);
+    if (!normalized) {
+      throw new WorkspaceRouteError("workspace_unavailable", "LIGHTCODE_PROJECTS_PATH must be an absolute folder path and cannot be a filesystem root.", 500, false);
+    }
+    return normalized;
+  }
+  const probe = options.probeDirectory ?? probeDirectory;
+  const candidates = [
+    pathApi.join(homeDirectory, "Projects"),
+    pathApi.join(homeDirectory, "projects")
+  ];
+  const seen = new Set;
+  for (const candidate of candidates) {
+    const key = platform4 === "win32" ? candidate.toLowerCase() : candidate;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    const state = await probe(candidate);
+    if (state === "available" || state === "permission-denied") {
+      return candidate;
+    }
+  }
+  return candidates[0];
+}
 function filesystemErrorCode(error) {
   if (typeof error !== "object" || error === null) {
     return;
@@ -17053,6 +17150,9 @@ function isContainedPath2(root, candidate) {
 async function resolveKnownDirectory(directory) {
   try {
     const root = await fs8.realpath(path24.resolve(directory));
+    if (root === path24.parse(root).root) {
+      throw new WorkspaceRouteError("workspace_unavailable", "A filesystem root cannot be opened as a workspace location.", 500, false);
+    }
     const stats = await fs8.stat(root, { bigint: true });
     if (!stats.isDirectory()) {
       throw new WorkspaceRouteError("workspace_not_directory", "The selected path is not a directory.", 422, false);
@@ -17082,11 +17182,11 @@ async function assertRootIdentity({
     throw mapFilesystemError(error);
   }
 }
-async function symlinkFailure(root, candidate) {
+async function symlinkFailure(root, candidate, locationName) {
   try {
     const target = await fs8.realpath(candidate);
     if (!isContainedPath2(root, target)) {
-      return new WorkspaceRouteError("workspace_symlink_escape", "This symbolic link points outside the allowed Desktop location.", 403, false);
+      return new WorkspaceRouteError("workspace_symlink_escape", `This symbolic link points outside the allowed ${locationName} location.`, 403, false);
     }
     return new WorkspaceRouteError("workspace_symlink_not_traversable", "Symbolic links cannot be used to navigate the workspace browser.", 422, false);
   } catch (error) {
@@ -17096,12 +17196,12 @@ async function symlinkFailure(root, candidate) {
     return new WorkspaceRouteError("workspace_symlink_broken", "This symbolic link is broken and cannot be opened.", 422, false);
   }
 }
-async function resolveDirectoryFromSegments(root, segments) {
+async function resolveDirectoryFromSegments(root, segments, locationName) {
   let current = root;
   for (const segment of segments) {
     const candidate = path24.join(current, segment);
     if (!isContainedPath2(root, candidate)) {
-      throw new WorkspaceRouteError("workspace_symlink_escape", "The requested path is outside the allowed Desktop location.", 403, false);
+      throw new WorkspaceRouteError("workspace_symlink_escape", `The requested path is outside the allowed ${locationName} location.`, 403, false);
     }
     let stats;
     try {
@@ -17110,7 +17210,7 @@ async function resolveDirectoryFromSegments(root, segments) {
       throw mapFilesystemError(error);
     }
     if (stats.isSymbolicLink()) {
-      throw await symlinkFailure(root, candidate);
+      throw await symlinkFailure(root, candidate, locationName);
     }
     if (!stats.isDirectory()) {
       throw new WorkspaceRouteError("workspace_not_directory", "The selected path is not a directory.", 422, false);
@@ -17121,7 +17221,7 @@ async function resolveDirectoryFromSegments(root, segments) {
     throw mapFilesystemError(error);
   });
   if (!isContainedPath2(root, canonical)) {
-    throw new WorkspaceRouteError("workspace_symlink_escape", "The requested path is outside the allowed Desktop location.", 403, false);
+    throw new WorkspaceRouteError("workspace_symlink_escape", `The requested path is outside the allowed ${locationName} location.`, 403, false);
   }
   const metadata = await fs8.lstat(canonical, { bigint: true });
   if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
@@ -17251,17 +17351,78 @@ function trimOldestEntries(map, maximum) {
     map.delete(oldest);
   }
 }
+function configuredKnownLocationResolver(options, id, fallback) {
+  const configuredResolver = options.resolveLocationPaths?.[id];
+  if (configuredResolver) {
+    return configuredResolver;
+  }
+  const configuredPath = options.locationPaths?.[id];
+  if (configuredPath !== undefined) {
+    return async () => configuredPath;
+  }
+  return fallback;
+}
+function knownLocation(definition, state) {
+  return {
+    id: definition.id,
+    name: definition.name,
+    kind: "known-folder",
+    state,
+    pathLabel: definition.pathLabel
+  };
+}
 function createWorkspaceRoutes(options = {}) {
   const now = options.now ?? Date.now;
   const capabilityTtlMs = options.browserCapabilityTtlMs ?? defaultBrowserCapabilityTtlMs;
-  const getDesktopPath = options.resolveDesktopPath ?? (options.desktopPath ? async () => {
-    const normalized = normalizeDesktopCandidate(options.desktopPath, process.platform);
+  const getLegacyDesktopPath = options.resolveDesktopPath ?? (options.desktopPath ? async () => {
+    const normalized = normalizeKnownFolderCandidate(options.desktopPath, process.platform);
     if (!normalized) {
       throw new WorkspaceRouteError("workspace_unavailable", "The configured Desktop path must be absolute and cannot be a filesystem root.", 500, false);
     }
     return normalized;
   } : () => resolveDesktopDirectoryPath());
   const desktopPathLabel = options.desktopPathLabel ?? "Desktop";
+  const defaultHomePath = async () => homedir4();
+  const defaultDocumentsPath = () => resolveDocumentsDirectoryPath();
+  const defaultDownloadsPath = () => resolveDownloadsDirectoryPath();
+  const definitions = [
+    {
+      id: "desktop",
+      name: "Desktop",
+      rootName: "Desktop",
+      pathLabel: options.locationPathLabels?.desktop ?? desktopPathLabel,
+      resolvePath: configuredKnownLocationResolver(options, "desktop", getLegacyDesktopPath)
+    },
+    {
+      id: "home",
+      name: "Home (broad access)",
+      rootName: "Home",
+      pathLabel: options.locationPathLabels?.home ?? "Home",
+      resolvePath: configuredKnownLocationResolver(options, "home", defaultHomePath)
+    },
+    {
+      id: "documents",
+      name: "Documents",
+      rootName: "Documents",
+      pathLabel: options.locationPathLabels?.documents ?? "Documents",
+      resolvePath: configuredKnownLocationResolver(options, "documents", defaultDocumentsPath)
+    },
+    {
+      id: "downloads",
+      name: "Downloads",
+      rootName: "Downloads",
+      pathLabel: options.locationPathLabels?.downloads ?? "Downloads",
+      resolvePath: configuredKnownLocationResolver(options, "downloads", defaultDownloadsPath)
+    },
+    {
+      id: "projects",
+      name: "Projects",
+      rootName: "Projects",
+      pathLabel: options.locationPathLabels?.projects ?? "Projects",
+      resolvePath: configuredKnownLocationResolver(options, "projects", () => resolveProjectsDirectoryPath())
+    }
+  ];
+  const definitionsById = new Map(definitions.map((definition) => [definition.id, definition]));
   const createSession = options.createSession ?? createChatSession;
   const cursorSecret = randomBytes(32);
   const browserCapabilities = new Map;
@@ -17270,7 +17431,7 @@ function createWorkspaceRoutes(options = {}) {
     const capability2 = browserCapabilities.get(browserId);
     if (!capability2 || capability2.expiresAtMs <= now()) {
       browserCapabilities.delete(browserId);
-      throw new WorkspaceRouteError("browser_capability_expired", "This folder browser expired. Open Desktop again.", 410, true);
+      throw new WorkspaceRouteError("browser_capability_expired", capability2 ? `This folder browser expired. Open ${capability2.rootName} again.` : "This folder browser expired. Open a location again.", 410, true);
     }
     return capability2;
   };
@@ -17282,15 +17443,7 @@ function createWorkspaceRoutes(options = {}) {
     return grant;
   };
   return new Hono7().get("/locations", (c) => c.json(workspaceLocationsResponseSchema.parse({
-    locations: [
-      {
-        id: "desktop",
-        name: "Desktop",
-        kind: "known-folder",
-        state: "unprobed",
-        pathLabel: desktopPathLabel
-      }
-    ]
+    locations: definitions.map((definition) => knownLocation(definition, "unprobed"))
   }))).post("/browser/open", zValidator3("json", workspaceBrowserOpenRequestSchema, (result, c) => {
     if (!result.success) {
       return invalidRequestResponse(c);
@@ -17298,32 +17451,30 @@ function createWorkspaceRoutes(options = {}) {
   }), async (c) => {
     try {
       const { locationId } = c.req.valid("json");
-      if (locationId !== "desktop") {
+      const definition = definitionsById.get(locationId);
+      if (!definition) {
         throw new WorkspaceRouteError("location_not_found", "Workspace location not found.", 404, false);
       }
-      const discoveredDesktop = await getDesktopPath();
-      const safeDesktop = normalizeDesktopCandidate(discoveredDesktop, process.platform);
-      if (!safeDesktop) {
-        throw new WorkspaceRouteError("workspace_unavailable", "The resolved Desktop location is not a safe absolute folder path.", 500, false);
+      const discoveredPath = await definition.resolvePath();
+      const safePath = normalizeKnownFolderCandidate(discoveredPath, process.platform);
+      if (!safePath) {
+        throw new WorkspaceRouteError("workspace_unavailable", `The resolved ${definition.rootName} location is not a safe absolute folder path.`, 500, false);
       }
-      const resolved = await resolveKnownDirectory(safeDesktop);
+      const resolved = await resolveKnownDirectory(safePath);
       const browserId = crypto.randomUUID();
       const expiresAtMs = now() + capabilityTtlMs;
+      const location = knownLocation(definition, "available");
       browserCapabilities.set(browserId, {
         id: browserId,
         ...resolved,
+        location,
+        rootName: definition.rootName,
         expiresAtMs
       });
       trimOldestEntries(browserCapabilities, maximumBrowserCapabilities);
       return c.json(workspaceBrowserOpenResponseSchema.parse({
         browserId,
-        location: {
-          id: "desktop",
-          name: "Desktop",
-          kind: "known-folder",
-          state: "available",
-          pathLabel: desktopPathLabel
-        },
+        location,
         expiresAt: new Date(expiresAtMs).toISOString()
       }), 201);
     } catch (error) {
@@ -17343,7 +17494,7 @@ function createWorkspaceRoutes(options = {}) {
       const input = c.req.valid("json");
       const capability2 = getBrowserCapability(browserId);
       await assertRootIdentity(capability2);
-      const directory = await resolveDirectoryFromSegments(capability2.root, input.segments);
+      const directory = await resolveDirectoryFromSegments(capability2.root, input.segments, capability2.rootName);
       const beforeRead = await assertDirectoryIdentity(capability2.root, directory);
       const cursorBinding = {
         browserId,
@@ -17421,7 +17572,7 @@ function createWorkspaceRoutes(options = {}) {
       const { segments } = c.req.valid("json");
       const capability2 = getBrowserCapability(browserId);
       await assertRootIdentity(capability2);
-      const directory = await resolveDirectoryFromSegments(capability2.root, segments);
+      const directory = await resolveDirectoryFromSegments(capability2.root, segments, capability2.rootName);
       await assertDirectoryIdentity(capability2.root, directory);
       await options.beforeDirectoryOperation?.({
         operation: "select",
@@ -17430,8 +17581,11 @@ function createWorkspaceRoutes(options = {}) {
       await fs8.access(directory.path, fsConstants2.R_OK | fsConstants2.X_OK);
       const createdAt = new Date(now()).toISOString();
       const id = crypto.randomUUID();
-      const name = segments.at(-1) ?? "Desktop";
-      const pathLabel = [desktopPathLabel, ...segments].join("/");
+      const name = segments.at(-1) ?? capability2.rootName;
+      const pathLabel = [
+        capability2.location.pathLabel,
+        ...segments
+      ].join("/");
       const grant = {
         id,
         name,