fix(workspace): explain a link to a teammate's private workspace; warn that quick workspaces are private

- A 409 whose `existing_datamate_name` is withheld means the project is linked
  to a workspace the caller cannot see. `link` (three paths) and the TUI (three
  toasts) said "another workspace claimed this project while you were choosing"
  / "another workspace", sending users round a retry loop. They now say it is
  most likely a teammate's private workspace and to ask its owner to share it.
- `link`'s quick create warns that only the creator can see the new workspace,
  so teammates who clone the repo are told it is unlinked until it is shared.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: anandgupta42

packages/opencode/src/altimate/workspace/api-client.ts

@@ -93,6 +93,18 @@ export class NotConfiguredError extends Error {
   }
 }
 
+/** A 409 whose `existing_datamate_name` is withheld: the server hides the name of a workspace
+ * the caller cannot see, which is almost always a teammate's private one. Reading that as a race
+ * ("another workspace claimed this project while you were choosing") sent users round a retry
+ * loop with no way out. */
+export const HIDDEN_BINDING_MESSAGE =
+  "This project is already linked to a workspace you can't see, most likely a teammate's private one. " +
+  "Ask its owner to share it with you in the Altimate web app, or to unlink the project, then run `altimate-code link` again."
+
+export function isHiddenBindingConflict(err: unknown): boolean {
+  return err instanceof ConflictError && !err.detail.existing_datamate_name
+}
+
 export class ConflictError extends Error {
   constructor(public readonly detail: ConflictDetail) {
     super(detail.message)

packages/opencode/src/cli/cmd/link.ts

@@ -18,6 +18,8 @@ import { AltimateApi } from "@/altimate/api/client"
 import {
   WorkspaceApi,
   ConflictError,
+  HIDDEN_BINDING_MESSAGE,
+  isHiddenBindingConflict,
   ForbiddenError,
   NotConfiguredError,
   NotFoundError,
@@ -416,7 +418,9 @@ async function runBrowserHandoff(
     prompts.outro("Done.")
   } catch (err) {
     bindSpin.stop("Link failed.", 1)
-    if (err instanceof ConflictError) {
+    if (isHiddenBindingConflict(err)) {
+      prompts.log.error(`${HIDDEN_BINDING_MESSAGE} Workspace "${projectName}" was created but is not linked.`)
+    } else if (err instanceof ConflictError) {
       const existingName = conflictExistingName(err.detail)
       prompts.log.error(
         `This project is already linked to "${existingName}". Workspace "${projectName}" was created but is not linked — re-run \`altimate-code link\` and pick a different action to switch, or delete the new workspace in the SaaS.`,
@@ -536,6 +540,8 @@ export async function createThenBindOrRebind(
           `The workspace could not be created: ${err.message}. Nothing was created, and this ` +
             `project is still linked to "${stripControlChars(existing.datamate.name)}".`,
         )
+      } else if (isHiddenBindingConflict(err)) {
+        prompts.log.error(`${HIDDEN_BINDING_MESSAGE} Nothing was created.`)
       } else {
         const existingName = conflictExistingName(err.detail)
         prompts.log.error(
@@ -610,6 +616,9 @@ export async function createThenBindOrRebind(
     linkedAt: Date.now(),
   }, { awaitBackfill: true })
   prompts.log.info(seedMessage(seed))
+  // The quick create is private, and the server hides a private workspace's link from
+  // everyone else: a teammate who clones this repo is told it is unlinked.
+  prompts.log.warn(QUICK_WORKSPACE_PRIVATE_NOTE)
   // ``createAndBind`` hands back a manage_url; the unbound create does not, so
   // derive it from credentials exactly as the rest of this file does. Null on
   // BYOK / unresolvable deployments — then there is simply nothing to show.
@@ -743,7 +752,9 @@ async function bindOrRebind(
     prompts.outro("Done.")
   } catch (err) {
     spin.stop(isRebind ? `Re-link failed.` : `Link failed.`, 1)
-    if (err instanceof ConflictError) {
+    if (isHiddenBindingConflict(err)) {
+      prompts.log.error(HIDDEN_BINDING_MESSAGE)
+    } else if (err instanceof ConflictError) {
       const existingName = conflictExistingName(err.detail)
       prompts.log.error(`Already linked to "${existingName}". Re-run \`altimate-code link\` to switch.`)
     } else if (err instanceof PreconditionFailedError) {
@@ -759,6 +770,9 @@ async function bindOrRebind(
   }
 }
 
+export const QUICK_WORKSPACE_PRIVATE_NOTE =
+  "Only you can see this workspace. Share it from its page in the Altimate web app so teammates who clone this repo are attached to it too."
+
 /** What `link` says about this machine's saved memory after the bind. A seed that left
  * blocks behind used to print the same line as one that stored everything. */
 export function seedMessage(seed: SeedOutcome | null): string {

packages/opencode/src/plugin/tui/altimate/workspace.tsx

@@ -33,6 +33,7 @@ import { inertWorkspaceName } from "@/altimate/workspace/workspace-name"
 import { createSignal, onCleanup, onMount } from "solid-js"
 import {
   ConflictError,
+  HIDDEN_BINDING_MESSAGE,
   ForbiddenError,
   NotFoundError,
   PreconditionFailedError,
@@ -419,7 +420,9 @@ async function runBrowserHandoff(
     if (err instanceof ConflictError) {
       api.ui.toast({
         variant: "warning",
-        message: `This project is already linked to "${err.detail.existing_datamate_name ?? "another workspace"}". Run \`altimate-code link\` to change.`,
+        message: err.detail.existing_datamate_name
+          ? `This project is already linked to "${err.detail.existing_datamate_name}". Run \`altimate-code link\` to change.`
+          : HIDDEN_BINDING_MESSAGE,
       })
     } else if (err instanceof NotFoundError) {
       api.ui.toast({
@@ -896,7 +899,9 @@ function PickerDialog(props: PickerProps) {
         // The picker doesn't have a "Re-link" option; the referral used to
         // point at OfferDialog's Re-link, which doesn't exist either. Point
         // at the concrete next action instead. (kilo cycle 6.)
-        msg = `Already linked to "${err.detail.existing_datamate_name ?? "another workspace"}". Re-run \`altimate-code link\` to change the workspace.`
+        msg = err.detail.existing_datamate_name
+          ? `Already linked to "${err.detail.existing_datamate_name}". Re-run \`altimate-code link\` to change the workspace.`
+          : HIDDEN_BINDING_MESSAGE
       } else if (err instanceof PreconditionFailedError) {
         msg = "Someone else re-linked this project — reload and try again."
       } else if (err instanceof NotFoundError) {
@@ -1091,7 +1096,9 @@ async function bindOrRebindInline(
   } catch (err) {
     let msg: string
     if (err instanceof ConflictError) {
-      msg = `Already linked to "${err.detail.existing_datamate_name ?? "another workspace"}".`
+      msg = err.detail.existing_datamate_name
+        ? `Already linked to "${err.detail.existing_datamate_name}".`
+        : HIDDEN_BINDING_MESSAGE
     } else if (err instanceof PreconditionFailedError) {
       msg = "Someone else re-linked this project — reload and try again."
     } else if (err instanceof NotFoundError) {

packages/opencode/test/altimate/workspace/link-seed-message.test.ts

@@ -14,3 +14,14 @@ test("link reports a completed seed and memory that is off without a retry hint"
   expect(seedMessage({ status: "off", sent: 0, pending: 0 })).not.toContain("Sync")
   expect(seedMessage(null)).not.toContain("Sync")
 })
+
+test("a 409 that withholds the workspace name is explained as a teammate's private workspace, not a race", async () => {
+  const { ConflictError, isHiddenBindingConflict, HIDDEN_BINDING_MESSAGE } = await import(
+    "../../../src/altimate/workspace/api-client"
+  )
+  expect(isHiddenBindingConflict(new ConflictError({ existing_datamate_name: null } as any))).toBe(true)
+  expect(isHiddenBindingConflict(new ConflictError({} as any))).toBe(true)
+  expect(isHiddenBindingConflict(new ConflictError({ existing_datamate_name: "team" } as any))).toBe(false)
+  expect(isHiddenBindingConflict(new Error("x"))).toBe(false)
+  expect(HIDDEN_BINDING_MESSAGE).toContain("share it with you")
+})