refactor: centralize workspace name resolution

Move workspace name length/collision rules into shared helpers so
create/rename/fork paths consistently enforce the same constraints:

- Add WORKSPACE_NAME_MAX_LENGTH constant and use in validation + task names
- Add buildWorkspaceNameWithSuffix() for length-safe suffixing
- Add resolveWorkspaceName() with collision strategies (error/random/numeric)
- Update create/rename/fork flows to use resolver and avoid name collisions
- Ensure auto-fork truncates base names to keep within 64-char limit

Tests:
- Added workspaceNaming + workspaceNameResolver unit tests
- Updated forkNameGenerator tests for length handling
- Updated workspaceValidation tests to use shared constant

Author: ammar-agent

src/common/utils/validation/workspaceValidation.test.ts

@@ -1,3 +1,4 @@
+import { WORKSPACE_NAME_MAX_LENGTH } from "@/constants/workspaceNaming";
 import { validateWorkspaceName } from "./workspaceValidation";
 
 describe("validateWorkspaceName", () => {
@@ -35,7 +36,7 @@ describe("validateWorkspaceName", () => {
     });
 
     test("accepts 64 characters", () => {
-      const name = "a".repeat(64);
+      const name = "a".repeat(WORKSPACE_NAME_MAX_LENGTH);
       expect(validateWorkspaceName(name).valid).toBe(true);
     });
   });
@@ -48,10 +49,10 @@ describe("validateWorkspaceName", () => {
     });
 
     test("rejects names over 64 characters", () => {
-      const name = "a".repeat(65);
+      const name = "a".repeat(WORKSPACE_NAME_MAX_LENGTH + 1);
       const result = validateWorkspaceName(name);
       expect(result.valid).toBe(false);
-      expect(result.error).toContain("64 characters");
+      expect(result.error).toContain(`${WORKSPACE_NAME_MAX_LENGTH} characters`);
     });
 
     test("rejects uppercase letters", () => {

src/common/utils/validation/workspaceValidation.ts

@@ -4,13 +4,18 @@
  * - Can only contain: lowercase letters, digits, underscore, hyphen
  * - Pattern: [a-z0-9_-]{1,64}
  */
+import { WORKSPACE_NAME_MAX_LENGTH } from "@/constants/workspaceNaming";
+
 export function validateWorkspaceName(name: string): { valid: boolean; error?: string } {
   if (!name || name.length === 0) {
     return { valid: false, error: "Workspace name cannot be empty" };
   }
 
-  if (name.length > 64) {
-    return { valid: false, error: "Workspace name cannot exceed 64 characters" };
+  if (name.length > WORKSPACE_NAME_MAX_LENGTH) {
+    return {
+      valid: false,
+      error: `Workspace name cannot exceed ${WORKSPACE_NAME_MAX_LENGTH} characters`,
+    };
   }
 
   const validPattern = /^[a-z0-9_-]+$/;

src/common/utils/workspaceNaming.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "bun:test";
+import { WORKSPACE_NAME_MAX_LENGTH } from "@/constants/workspaceNaming";
+import { buildWorkspaceNameWithSuffix } from "./workspaceNaming";
+
+describe("workspaceNaming", () => {
+  it("should append suffix without truncation when base fits", () => {
+    expect(buildWorkspaceNameWithSuffix("short-name", 2)).toBe("short-name-2");
+  });
+
+  it("should truncate base to respect maximum length", () => {
+    const base = "a".repeat(WORKSPACE_NAME_MAX_LENGTH);
+    const result = buildWorkspaceNameWithSuffix(base, 2);
+    expect(result.length).toBe(WORKSPACE_NAME_MAX_LENGTH);
+    expect(result.endsWith("-2")).toBe(true);
+  });
+});

src/common/utils/workspaceNaming.ts

@@ -0,0 +1,13 @@
+import { WORKSPACE_NAME_MAX_LENGTH } from "@/constants/workspaceNaming";
+
+/**
+ * Build a workspace name with a suffix, trimming the base to fit length limits.
+ */
+export function buildWorkspaceNameWithSuffix(baseName: string, suffix: string | number): string {
+  const suffixText = String(suffix);
+  const reservedLength = suffixText.length + 1; // +1 for '-'
+  const maxBaseLength = Math.max(1, WORKSPACE_NAME_MAX_LENGTH - reservedLength);
+  const truncatedBase =
+    baseName.length > maxBaseLength ? baseName.slice(0, maxBaseLength) : baseName;
+  return `${truncatedBase}-${suffixText}`;
+}

src/constants/workspaceNaming.ts

@@ -0,0 +1,4 @@
+/**
+ * Workspace naming limits and constraints.
+ */
+export const WORKSPACE_NAME_MAX_LENGTH = 64;

src/node/services/forkNameGenerator.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "bun:test";
+import { WORKSPACE_NAME_MAX_LENGTH } from "@/constants/workspaceNaming";
 import {
   parseWorkspaceName,
   parseWorkspaceTitle,
@@ -72,6 +73,13 @@ describe("forkNameGenerator", () => {
       expect(generateForkName("sidebar")).toBe("sidebar-2");
     });
 
+    it("should truncate base to fit suffix within limits", () => {
+      const base = "a".repeat(WORKSPACE_NAME_MAX_LENGTH);
+      const result = generateForkName(base);
+      expect(result.length).toBe(WORKSPACE_NAME_MAX_LENGTH);
+      expect(result.endsWith("-2")).toBe(true);
+    });
+
     it("should increment suffix for subsequent forks", () => {
       expect(generateForkName("bugs-asd23-2")).toBe("bugs-asd23-3");
       expect(generateForkName("bugs-asd23-3")).toBe("bugs-asd23-4");

src/node/services/forkNameGenerator.ts

@@ -7,6 +7,8 @@
  *   Fork 2: title "Fixing bugs 3", name "bugs-asd23-3"
  */
 
+import { buildWorkspaceNameWithSuffix } from "@/common/utils/workspaceNaming";
+
 /**
  * Extract the base name and current suffix from a workspace name.
  * Returns { base, suffix } where suffix is the numeric fork count (0 if not a fork).
@@ -61,7 +63,7 @@ export function parseWorkspaceTitle(title: string): { base: string; suffix: numb
 export function generateForkName(sourceName: string): string {
   const { base, suffix } = parseWorkspaceName(sourceName);
   const nextSuffix = suffix === 0 ? 2 : suffix + 1;
-  return `${base}-${nextSuffix}`;
+  return buildWorkspaceNameWithSuffix(base, nextSuffix);
 }
 
 /**
@@ -90,7 +92,7 @@ export function generateForkTitleWithSuffix(sourceTitle: string, suffix: number)
  */
 export function generateForkNameWithSuffix(sourceName: string, suffix: number): string {
   const { base } = parseWorkspaceName(sourceName);
-  return `${base}-${suffix}`;
+  return buildWorkspaceNameWithSuffix(base, suffix);
 }
 
 /**
@@ -102,7 +104,7 @@ export function findNextForkSuffix(sourceName: string, existingNames: Set<string
   let nextSuffix = currentSuffix === 0 ? 2 : currentSuffix + 1;
 
   // Find next available suffix
-  while (existingNames.has(`${base}-${nextSuffix}`)) {
+  while (existingNames.has(buildWorkspaceNameWithSuffix(base, nextSuffix))) {
     nextSuffix++;
   }
 

src/node/services/taskService.ts

@@ -20,6 +20,7 @@ import { createRuntimeForWorkspace } from "@/node/runtime/runtimeHelpers";
 import { createRuntime, runBackgroundInit } from "@/node/runtime/runtimeFactory";
 import type { InitLogger, WorkspaceCreationResult } from "@/node/runtime/Runtime";
 import { validateWorkspaceName } from "@/common/utils/validation/workspaceValidation";
+import { WORKSPACE_NAME_MAX_LENGTH } from "@/constants/workspaceNaming";
 import { Ok, Err, type Result } from "@/common/types/result";
 import type { TaskSettings } from "@/common/types/tasks";
 import { DEFAULT_TASK_SETTINGS } from "@/common/types/tasks";
@@ -171,14 +172,16 @@ function sanitizeAgentTypeForName(agentType: string): string {
 function buildAgentWorkspaceName(agentType: string, workspaceId: string): string {
   const safeType = sanitizeAgentTypeForName(agentType);
   const base = `agent_${safeType}_${workspaceId}`;
-  // Hard cap to validation limit (64). Ensure stable suffix is preserved.
-  if (base.length <= 64) return base;
+  // Hard cap to validation limit. Ensure stable suffix is preserved.
+  if (base.length <= WORKSPACE_NAME_MAX_LENGTH) return base;
 
   const suffix = `_${workspaceId}`;
-  const maxPrefixLen = 64 - suffix.length;
+  const maxPrefixLen = WORKSPACE_NAME_MAX_LENGTH - suffix.length;
   const prefix = `agent_${safeType}`.slice(0, Math.max(0, maxPrefixLen));
   const name = `${prefix}${suffix}`;
-  return name.length <= 64 ? name : `agent_${workspaceId}`.slice(0, 64);
+  return name.length <= WORKSPACE_NAME_MAX_LENGTH
+    ? name
+    : `agent_${workspaceId}`.slice(0, WORKSPACE_NAME_MAX_LENGTH);
 }
 
 function getIsoNow(): string {

src/node/services/workspaceNameResolver.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "bun:test";
+import { WORKSPACE_NAME_MAX_LENGTH } from "@/constants/workspaceNaming";
+import { resolveWorkspaceName } from "./workspaceNameResolver";
+
+describe("workspaceNameResolver", () => {
+  it("should reject invalid workspace names", () => {
+    const result = resolveWorkspaceName("Invalid-Name", new Set(), { type: "error" });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toContain("Use only");
+    }
+  });
+
+  it("should return the requested name when no collision exists", () => {
+    const result = resolveWorkspaceName("valid-name", new Set(), { type: "error" });
+    expect(result).toEqual({ success: true, data: { name: "valid-name" } });
+  });
+
+  it("should error on collisions when using error strategy", () => {
+    const result = resolveWorkspaceName("existing", new Set(["existing"]), { type: "error" });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toContain("already exists");
+    }
+  });
+
+  it("should generate numeric suffix for forks", () => {
+    const result = resolveWorkspaceName("feature", new Set(["feature", "feature-2"]), {
+      type: "numeric-suffix",
+    });
+    expect(result).toEqual({ success: true, data: { name: "feature-3", suffix: 3 } });
+  });
+
+  it("should generate random suffix within length limits", () => {
+    const base = "a".repeat(WORKSPACE_NAME_MAX_LENGTH);
+    const existingNames = new Set([base]);
+    const originalRandom = Math.random;
+    try {
+      Math.random = () => 0.123456;
+      const result = resolveWorkspaceName(base, existingNames, {
+        type: "random-suffix",
+        maxAttempts: 1,
+      });
+      expect(result.success).toBe(true);
+      if (!result.success) return;
+      expect(result.data.name.length).toBe(WORKSPACE_NAME_MAX_LENGTH);
+      expect(result.data.name.endsWith("-4fzy")).toBe(true);
+    } finally {
+      Math.random = originalRandom;
+    }
+  });
+});

src/node/services/workspaceNameResolver.ts

@@ -0,0 +1,75 @@
+import { Err, Ok, type Result } from "@/common/types/result";
+import { validateWorkspaceName } from "@/common/utils/validation/workspaceValidation";
+import { buildWorkspaceNameWithSuffix } from "@/common/utils/workspaceNaming";
+import { findNextForkSuffix, generateForkNameWithSuffix } from "@/node/services/forkNameGenerator";
+
+export type WorkspaceNameCollisionStrategy =
+  | { type: "error" }
+  | { type: "random-suffix"; maxAttempts: number }
+  | { type: "numeric-suffix" };
+
+export interface WorkspaceNameResolution {
+  name: string;
+  suffix?: number;
+}
+
+function generateRandomSuffix(): string {
+  return Math.random().toString(36).substring(2, 6);
+}
+
+function validateResolvedName(name: string): Result<string> {
+  const validation = validateWorkspaceName(name);
+  if (!validation.valid) {
+    return Err(validation.error ?? "Invalid workspace name");
+  }
+  return Ok(name);
+}
+
+/**
+ * Resolve a workspace name using a collision strategy and shared validation rules.
+ */
+export function resolveWorkspaceName(
+  requestedName: string,
+  existingNames: Set<string>,
+  strategy: WorkspaceNameCollisionStrategy
+): Result<WorkspaceNameResolution> {
+  const validation = validateWorkspaceName(requestedName);
+  if (!validation.valid) {
+    return Err(validation.error ?? "Invalid workspace name");
+  }
+
+  if (strategy.type === "numeric-suffix") {
+    const suffix = findNextForkSuffix(requestedName, existingNames);
+    const candidate = generateForkNameWithSuffix(requestedName, suffix);
+    const resolved = validateResolvedName(candidate);
+    if (!resolved.success) {
+      return Err(resolved.error);
+    }
+    return Ok({ name: resolved.data, suffix });
+  }
+
+  if (!existingNames.has(requestedName)) {
+    return Ok({ name: requestedName });
+  }
+
+  if (strategy.type === "error") {
+    return Err(`Workspace with name "${requestedName}" already exists`);
+  }
+
+  const attemptedNames = new Set(existingNames);
+  for (let attempt = 0; attempt < strategy.maxAttempts; attempt++) {
+    const suffix = generateRandomSuffix();
+    const candidate = buildWorkspaceNameWithSuffix(requestedName, suffix);
+    if (attemptedNames.has(candidate)) {
+      continue;
+    }
+    attemptedNames.add(candidate);
+    const resolved = validateResolvedName(candidate);
+    if (!resolved.success) {
+      return Err(resolved.error);
+    }
+    return Ok({ name: resolved.data });
+  }
+
+  return Err(`Unable to resolve unique workspace name for "${requestedName}"`);
+}