feat(workspace): browser-based workspace creation handoff

packages/opencode/src/altimate/workspace/state.ts

@@ -21,24 +21,6 @@ const CACHE_VERSION = 1
 
 const log = Log.create({ service: "altimate-workspace-state" })
 
-/** Canonicalize a directory into a stable cache key so callers passing
- * ``/tmp/foo``, ``/private/tmp/foo`` (macOS symlink), ``/tmp/foo/``, or a
- * relative path all read/write the same row. Uses ``path.resolve`` first so
- * relative inputs anchor to cwd, then ``realpathSync`` to collapse symlinks
- * and trailing separators. Falls back to the resolved-only form when the
- * path doesn't exist on disk (e.g. cache written for a repo that has since
- * moved) — better a stable-if-unresolved key than an exception that skips
- * the cache entirely. (cubic + kilo cycle 6 — different clients keyed the
- * same project under different paths.) */
-function canonicalDirKey(directory: string): string {
-  const resolved = path.resolve(directory)
-  try {
-    return realpathSync(resolved)
-  } catch {
-    return resolved
-  }
-}
-
 export interface CachedBinding {
   datamateId: number
   datamateName: string
@@ -109,6 +91,32 @@ function readCache(): CacheFile | null {
   }
 }
 
+/** True when every key in the cache is already the canonical form of itself
+ * (i.e. no earlier-CLI-build unresolved keys remain). Cheap side condition
+ * so we can skip the per-read migration once the cache has been rewritten. */
+function isCanonicalized(cache: CacheFile): boolean {
+  for (const k of Object.keys(cache.bindings)) {
+    if (canonicalizeKey(k) !== k) return false
+  }
+  return true
+}
+
+/** One-shot migration: rewrite the cache with canonical keys, collapsing any
+ * pair that resolves to the same target (last-writer-wins by ``linkedAt``).
+ * After this runs the O(n) lookup-time rescan in ``readLocalBinding`` is
+ * dead code — every subsequent read hits the direct key lookup. */
+function migrateToCanonicalKeys(cache: CacheFile): CacheFile {
+  const migrated: Record<string, CachedBinding> = {}
+  for (const [k, v] of Object.entries(cache.bindings)) {
+    const canon = canonicalizeKey(k)
+    const existing = migrated[canon]
+    if (!existing || existing.linkedAt <= v.linkedAt) migrated[canon] = v
+  }
+  const next: CacheFile = { ...cache, bindings: migrated }
+  writeCache(next)
+  return next
+}
+
 function writeCache(cache: CacheFile): void {
   const p = cachePath()
   Filesystem.writeJsonAtomic(p, cache)
@@ -124,6 +132,18 @@ function writeCache(cache: CacheFile): void {
   }
 }
 
+/** Canonicalize a directory path so cache lookups survive symlink differences
+ * (macOS ``/tmp`` → ``/private/tmp`` is the common case). Writers and readers
+ * must both funnel through this or a shell-cwd write silently misses when the
+ * TUI's canonicalized ``state.path.directory`` looks it back up. */
+function canonicalizeKey(directory: string): string {
+  try {
+    return realpathSync(path.resolve(directory))
+  } catch {
+    return path.resolve(directory)
+  }
+}
+
 async function tenantKey(): Promise<{ tenant: string; apiUrl: string } | null> {
   // Best-effort: ``AltimateApi.getCredentials`` can throw ``SyntaxError`` on
   // a corrupt credentials JSON, ``ZodError`` on schema drift, or a raw
@@ -145,15 +165,27 @@ async function tenantKey(): Promise<{ tenant: string; apiUrl: string } | null> {
 }
 
 /** Read the local binding for ``directory`` — only returns a hit when the
- * cache's stored (tenant, apiUrl) matches the current credentials. Directory
- * is canonicalized so raw / symlink / trailing-slash variants collide. */
+ * cache's stored (tenant, apiUrl) matches the current credentials. Runs a
+ * one-shot migration to canonical keys on the first read that finds an
+ * unresolved key (macOS ``/tmp`` → ``/private/tmp``), then relies on direct
+ * lookup for the process's remaining lifetime. */
 export async function readLocalBinding(directory: string): Promise<CachedBinding | null> {
   const key = await tenantKey()
   if (!key) return null
-  const cache = readCache()
+  let cache = readCache()
   if (!cache) return null
   if (cache.tenant !== key.tenant || cache.apiUrl !== key.apiUrl) return null
-  return cache.bindings[canonicalDirKey(directory)] ?? null
+  const canon = canonicalizeKey(directory)
+  const direct = cache.bindings[canon]
+  if (direct) return direct
+  // Cache miss: check if the cache still has any non-canonical keys and
+  // migrate the whole file once. After migration the lookup is a plain
+  // property access on every future read.
+  if (!isCanonicalized(cache)) {
+    cache = migrateToCanonicalKeys(cache)
+    return cache.bindings[canon] ?? null
+  }
+  return null
 }
 
 export async function recordApprovedBinding(
@@ -166,14 +198,15 @@ export async function recordApprovedBinding(
   // truth (the server-side binding is). If the state directory is read-only
   // or the disk is full, callers otherwise report "link failed" and prompt
   // duplicate retries against a workspace that IS bound server-side.
-  // (cubic round 3.)
+  // (cubic round 3.) canonicalizeKey resolves symlinks so writes and reads
+  // funnel through the same key (macOS ``/tmp`` → ``/private/tmp``).
   try {
     const existing = readCache()
     const cache: CacheFile =
       existing && existing.tenant === key.tenant && existing.apiUrl === key.apiUrl
         ? existing
         : { version: CACHE_VERSION, tenant: key.tenant, apiUrl: key.apiUrl, bindings: {} }
-    cache.bindings[canonicalDirKey(directory)] = binding
+    cache.bindings[canonicalizeKey(directory)] = binding
     writeCache(cache)
   } catch (err) {
     log.warn("could not persist workspace binding cache", {

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

@@ -32,9 +32,15 @@ import {
   projectNameFromRemote,
   resolveProjectIdentifier,
 } from "@/altimate/workspace/detect"
+import {
+  openWorkspaceBrowserHandoff,
+  resolveWorkspaceWebUrl,
+  type HandoffResult,
+} from "@/altimate/workspace/browser-handoff"
 import { recordApprovedBinding } from "@/altimate/workspace/state"
 
 const CREATE_NEW_SENTINEL = "__create_new__"
+const SET_UP_IN_BROWSER_SENTINEL = "__browser_handoff__"
 
 export const LinkCommand = cmd({
   command: "link",
@@ -118,13 +124,41 @@ export const LinkCommand = cmd({
     const currentId = existing?.datamate.id
     const currentName = existing?.datamate.name
 
+    // Only offer the browser-based handoff when the deployment supports it
+    // (freemium only today). Enterprise / localhost / custom-domain callers
+    // silently fall back to the CLI-side quick create.
+    const creds = await AltimateApi.getCredentials()
+    const browserAvailable =
+      resolveWorkspaceWebUrl(creds.altimateUrl, creds.altimateInstanceName) !== null
+
     const options: Array<{ value: string; label: string; hint?: string }> = [
+      // Only offer browser handoff for UNLINKED projects (CodeRabbit cycle 5).
+      // ``runBrowserHandoff`` creates a fresh workspace and calls
+      // ``bindExisting``, which 409s when there's already an active binding —
+      // leaving the browser-created workspace stranded and no rebind actually
+      // happening. If the project is already linked, the caller wants a
+      // rebind path (offered elsewhere in this menu), not create-and-bind.
+      //
+      // Also gate on ``preCheckOk`` (Kilo cycle 6): when the pre-check itself
+      // failed (network / 5xx), ``existing`` stays null but the project MAY
+      // be linked server-side. Offering the browser flow then would run the
+      // same 409 → stranded-workspace path. Better to hide the option until
+      // the caller can confirm the binding state.
+      ...(browserAvailable && !existing && preCheckOk
+        ? [
+            {
+              value: SET_UP_IN_BROWSER_SENTINEL,
+              label: `＋ Set up in browser "${autoName}"`,
+              hint: "Approve in the Altimate SaaS; CLI links your project automatically.",
+            },
+          ]
+        : []),
       {
         value: CREATE_NEW_SENTINEL,
-        label: `＋ Create a new workspace "${autoName}"`,
+        label: `＋ Create a quick workspace "${autoName}" here`,
         hint: existing
-          ? "Creates a new workspace and repoints this project to it."
-          : "Named from this project; rename in the SaaS after.",
+          ? "Creates a new workspace and repoints this project to it (no browser step)."
+          : "No browser step; configure integrations later in the SaaS.",
       },
       ...list.map((dm) => ({
         value: String(dm.id),
@@ -146,6 +180,11 @@ export const LinkCommand = cmd({
       return
     }
 
+    if (pick === SET_UP_IN_BROWSER_SENTINEL) {
+      await runBrowserHandoff(identifier, autoName, args.directory)
+      return
+    }
+
     if (pick === CREATE_NEW_SENTINEL) {
       await createThenBindOrRebind(identifier, autoName, args.directory, existing)
       return
@@ -161,12 +200,124 @@ export const LinkCommand = cmd({
   },
 })
 
-/** "＋ Create a new workspace" flow. When the project is already linked, this
- * MUST rebind after create — otherwise the new workspace is a real (billable)
- * SaaS resource the CLI knows nothing about and the project is still bound to
- * the old workspace (M2 in the consensus review). When rebind fails, the
- * error message tells the user the workspace was created and how to recover;
- * we do NOT silently swallow the orphan. */
+/** Browser-based create-and-bind flow. Same handoff module the TUI post-scan
+ * dialog uses; on success, the CLI calls the existing bind endpoint to link
+ * the current project to the newly-created workspace. When the project is
+ * already linked, bindExisting will 409; the caller re-runs and picks
+ * "＋ Create a quick workspace here" instead to trigger the create-and-rebind
+ * path. (Full create-then-rebind via the browser flow is deferred — the
+ * SaaS approval screen doesn't yet know how to receive a "rebind after
+ * create" instruction from the CLI.) */
+async function runBrowserHandoff(
+  identifier: ProjectIdentifier,
+  projectName: string,
+  directory: string,
+): Promise<void> {
+  const spin = prompts.spinner()
+  spin.start("Waiting for browser approval...")
+  const result: HandoffResult = await openWorkspaceBrowserHandoff({ identifier, projectName })
+  if (!result.ok) {
+    spin.stop(handoffFailureMessage(result), 1)
+    process.exitCode = 1
+    return
+  }
+  // M6 in the consensus review: re-verify credentials before binding. The
+  // browser window can stay open for up to 15 minutes; an account switch in
+  // that window would otherwise bind a callback validated for tenant A
+  // under tenant B (workspace ids are tenant-schema-local).
+  try {
+    const fresh = await AltimateApi.getCredentials()
+    if (
+      fresh.altimateInstanceName !== result.credentials.tenant ||
+      fresh.altimateUrl !== result.credentials.apiUrl
+    ) {
+      spin.stop(
+        `Credentials changed while the browser was open (was ${result.credentials.tenant}, now ${fresh.altimateInstanceName}). Re-run to link this project.`,
+        1,
+      )
+      process.exitCode = 1
+      return
+    }
+  } catch {
+    spin.stop("Lost Altimate credentials while the browser was open — sign in and re-run.", 1)
+    process.exitCode = 1
+    return
+  }
+  spin.stop(`Workspace approved. Binding to project...`)
+  const bindSpin = prompts.spinner()
+  bindSpin.start("Linking workspace...")
+  try {
+    const res = await WorkspaceApi.bindExisting(result.workspaceId, identifier)
+    await recordApprovedBinding(directory, {
+      datamateId: res.binding.datamate_id,
+      datamateName: res.binding.datamate_name,
+      repoRemote: res.binding.repo_remote,
+      projectPath: res.binding.project_path,
+      linkedAt: Date.now(),
+    })
+    bindSpin.stop(`Linked to "${res.binding.datamate_name}".`)
+    const manageUrl = await manageUrlFor(res.binding.datamate_id)
+    if (manageUrl) prompts.log.info(`Manage it at: ${manageUrl}`)
+    prompts.outro("Done.")
+  } catch (err) {
+    bindSpin.stop("Link failed.", 1)
+    if (err instanceof ConflictError) {
+      prompts.log.error(
+        `This project is already linked to "${err.detail.existing_datamate_name ?? "another workspace"}". 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.`,
+      )
+    } else if (err instanceof NotFoundError) {
+      prompts.log.error("Workspace not found — the tenant or workspace may have changed.")
+    } else if (err instanceof ForbiddenError) {
+      prompts.log.error("Only the workspace owner can bind projects to it.")
+    } else {
+      prompts.log.error(err instanceof Error ? err.message : String(err))
+    }
+    process.exitCode = 1
+  }
+}
+
+/** Best-effort manage-workspace URL for the current credentials. Returns null
+ * on BYOK / unresolvable deployments — callers omit the "Manage it at" line. */
+async function manageUrlFor(workspaceId: number): Promise<string | null> {
+  try {
+    const creds = await AltimateApi.getCredentials()
+    const base = resolveWorkspaceWebUrl(creds.altimateUrl, creds.altimateInstanceName)
+    if (!base) return null
+    return `${base.toString().replace(/\/$/, "")}/w/${workspaceId}`
+  } catch {
+    return null
+  }
+}
+
+function handoffFailureMessage(result: Extract<HandoffResult, { ok: false }>): string {
+  switch (result.reason) {
+    case "unavailable":
+      return "Browser handoff isn't available for this deployment."
+    case "not_configured":
+      return "Altimate credentials not configured — sign in first."
+    case "timeout":
+      return "Timed out waiting for browser approval (15 min)."
+    case "cancelled":
+      return "Cancelled by user."
+    case "tenant_mismatch":
+      return result.message ?? "Workspace was set up in a different tenant than the CLI's credentials."
+    case "port_exhausted":
+      return result.message ?? "Loopback ports 7317-7325 all in use."
+    case "browser_open_failed":
+      return `Could not open browser${result.authorizeUrl ? `. Open manually: ${result.authorizeUrl}` : "."}`
+    case "aborted":
+      return result.message ?? "Browser handoff was cancelled."
+    default:
+      return result.message ?? "Browser handoff failed."
+  }
+}
+
+/** "＋ Create a quick workspace here" flow. When the project is already
+ * linked, this MUST rebind after create — otherwise the new workspace is a
+ * real (billable) SaaS resource the CLI knows nothing about and the project
+ * is still bound to the old workspace (M2 in the consensus review). When
+ * rebind fails, the error message tells the user the workspace was created
+ * and how to recover; we do NOT silently swallow the orphan. */
 async function createThenBindOrRebind(
   identifier: ProjectIdentifier,
   name: string,
@@ -349,6 +500,8 @@ async function bindOrRebind(
         ? `Re-linked to "${res.binding.datamate_name}".`
         : `Linked to "${res.binding.datamate_name}".`,
     )
+    const manageUrl = await manageUrlFor(res.binding.datamate_id)
+    if (manageUrl) prompts.log.info(`Manage it at: ${manageUrl}`)
     prompts.outro("Done.")
   } catch (err) {
     spin.stop(isRebind ? `Re-link failed.` : `Link failed.`, 1)

packages/opencode/src/plugin/tui/altimate/index.ts

@@ -15,6 +15,7 @@ import PromptEnhance from "./prompt-enhance"
 import SkillOps from "./skill-ops"
 import TraceViewer from "./trace-viewer"
 import Workspace from "./workspace"
+import WorkspaceSidebar from "./workspace-sidebar"
 
 // Feature plugins are registered here as they are ported from the pre-merge sources on `main`
 // (see the ADR re-home plan). Each lives in its own file under this directory and default-exports
@@ -26,10 +27,11 @@ import Workspace from "./workspace"
 //   import Workspace from "./workspace"
 export function altimateTuiPlugins(_flags: Pick<RuntimeFlags.Info, "experimentalEventSystem">): BuiltinTuiPlugin[] {
   const base = [ProviderCredentials, PromptEnhance, SkillOps, TraceViewer]
-  // Workspace TUI plugin is pilot-gated: only registered for users who
-  // opted into ALTIMATE_WORKSPACE. Otherwise the post-scan dialog + the
-  // altimate.workspace.link palette command would ship to 100% of users
-  // regardless of the flag setting. (M1 in the consensus review.)
-  return Flag.ALTIMATE_WORKSPACE ? [...base, Workspace] : base
+  // Workspace TUI plugin + right-pane sidebar tile are pilot-gated: only
+  // registered for users who opted into ALTIMATE_WORKSPACE. Otherwise the
+  // post-scan dialog, the altimate.workspace.link palette command, and the
+  // sidebar's 30s poll would ship to 100% of users regardless of the flag
+  // setting. (M1 in the consensus review.)
+  return Flag.ALTIMATE_WORKSPACE ? [...base, Workspace, WorkspaceSidebar] : base
 }
 // altimate_change end