From a926d19779a67aa8c098dda2ae6d75a062d306d3 Mon Sep 17 00:00:00 2001
From: Haider <haider@altimate.ai>
Date: Fri, 14 Aug 2026 17:36:57 +0530
Subject: [PATCH 1/7] feat(workspace): browser-based workspace creation handoff
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a browser handoff for creating and linking a Workspace: CLI opens the
SaaS approval modal on `<tenant>.ws.myaltimate.com/create-and-link` with the
current project's context (git remote or path + auto-derived name), user
approves, the SaaS creates a workspace and delivers its ID back to the CLI
via a loopback callback (same pattern as gateway sign-in). CLI then binds
the current project to that workspace via the existing `POST /bind`.

Additive to `feat/agent-workspaces` — every pre-existing option in the
post-scan dialog and `altimate-code link` picker (Create quick workspace,
Link to existing, Skip, workspace-picker rows) continues to work unchanged.
The new "Set up in browser" option auto-hides when the deployment isn't
supported (localhost, enterprise, custom domain) — freemium only for pilot.

- New `packages/opencode/src/altimate/workspace/browser-handoff.ts`:
  loopback listener (own instance per flow, port walk 7317..7325 with
  natural fallback past a live OAuth listener), tenant-mismatch guard,
  typed failure reasons. Duplicates the loopback pattern from
  `altimate.ts` deliberately — shared-helper refactor is a follow-up
  ticket once both flows have prod experience.
- Post-scan `OfferDialog`: adds "Set up in browser (recommended)" as the
  default when available, sitting alongside the existing options.
- `altimate-code link` picker: adds "＋ Set up in browser" as the first
  row when available.
- Handles browser-open failures with a copy-URL fallback; 15-min timeout;
  explicit cancel via SaaS-delivered `?error=cancelled`.

Tests: 14 new unit tests for browser-handoff (URL resolution, pre-flight
failures, end-to-end via dependency-injected browser opener, port walk
past a squatting listener). 32/32 workspace + plugin tests pass.
---
 .../src/altimate/workspace/browser-handoff.ts | 341 ++++++++++++++++++
 packages/opencode/src/cli/cmd/link.ts         | 135 ++++++-
 .../src/plugin/tui/altimate/workspace.tsx     | 199 +++++++++-
 .../workspace/browser-handoff.test.ts         | 261 ++++++++++++++
 4 files changed, 907 insertions(+), 29 deletions(-)
 create mode 100644 packages/opencode/src/altimate/workspace/browser-handoff.ts
 create mode 100644 packages/opencode/test/altimate/workspace/browser-handoff.test.ts

diff --git a/packages/opencode/src/altimate/workspace/browser-handoff.ts b/packages/opencode/src/altimate/workspace/browser-handoff.ts
new file mode 100644
index 000000000..78a0bc7ab
--- /dev/null
+++ b/packages/opencode/src/altimate/workspace/browser-handoff.ts
@@ -0,0 +1,341 @@
+// altimate_change - new file
+//
+// Browser-based workspace creation handoff. CLI opens Ralph's SaaS approval
+// modal at ``<tenant>.ws.myaltimate.com/create-and-link`` with the current
+// project's context, user approves, the SaaS creates a workspace and delivers
+// its ID back to the CLI via a loopback callback. The CLI then binds the
+// current project to that workspace via the existing
+// ``POST /datamate-project-bindings/bind`` endpoint.
+//
+// This module deliberately DUPLICATES the loopback listener pattern from
+// ``altimate/plugin/altimate.ts`` rather than sharing a helper — the two flows
+// are similar enough that a naive extraction would trade duplication for
+// coupling on state/global lifecycle. Refactor to a shared helper is a
+// follow-up ticket once both flows have prod experience; the port range
+// (7317..7325) is walked independently by each listener instance so a live
+// OAuth server on 7317 forces workspace-handoff to bind 7318 without either
+// close operation affecting the other.
+//
+// See docs `workspace-browser-handoff-plan-v3.md` for the design context.
+import { createServer, type Server } from "http"
+import { randomBytes } from "crypto"
+import open from "open"
+
+import { AltimateApi } from "@/altimate/api/client"
+import { Log } from "@/altimate/util/log"
+
+import type { ProjectIdentifier } from "./api-client"
+
+// Freemium is the only deployment served by the workspace stack today. When
+// altimate-backend goes multi-deployment (enterprise), extend this to a small
+// mapping. Returning null means "not supported here" — the CLI hides the
+// browser-handoff option entirely rather than open a broken URL.
+const FREEMIUM_API_HOST = "api.myaltimate.com"
+const FREEMIUM_WORKSPACE_HOST = "ws.myaltimate.com"
+
+// Loopback port range for the workspace-bound callback. Shared with the OAuth
+// sign-in listener in altimate.ts — each listener walks independently, so a
+// live OAuth server on 7317 forces us to 7318 (or later) transparently.
+const CALLBACK_PORT_MIN = 7317
+const CALLBACK_PORT_MAX = 7325
+
+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000
+const DELIVERY_HTML_SUCCESS = `<!doctype html><meta charset="utf-8"><title>Altimate Code</title>
+<body style="font-family:system-ui;text-align:center;padding:64px">
+<h2>Workspace ready</h2><p>Return to your terminal to finish linking.</p>
+<script>setTimeout(()=>window.close(),1500)</script></body>`
+
+const log = Log.create({ service: "altimate-workspace-handoff" })
+
+function escapeHtml(s: string): string {
+  return s.replace(
+    /[&<>"']/g,
+    (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c] as string,
+  )
+}
+
+function htmlError(msg: string): string {
+  return `<!doctype html><meta charset="utf-8"><title>Altimate Code</title>
+<body style="font-family:system-ui;text-align:center;padding:64px">
+<h2>Workspace handoff failed</h2><p>${escapeHtml(msg)}</p>
+<p>Please return to your terminal and try again.</p></body>`
+}
+
+export type HandoffFailureReason =
+  | "unavailable" // resolveWorkspaceWebUrl returned null (not freemium)
+  | "not_configured" // CLI credentials not present
+  | "timeout" // 15-min window expired
+  | "cancelled" // user hit Cancel in the browser
+  | "tenant_mismatch" // callback tenant != credentials tenant
+  | "port_exhausted" // 7317..7325 all in use
+  | "browser_open_failed"
+  | "error"
+
+export interface HandoffSuccess {
+  ok: true
+  workspaceId: number
+  tenant: string
+}
+export interface HandoffFailure {
+  ok: false
+  reason: HandoffFailureReason
+  message?: string
+  authorizeUrl?: string // set for browser_open_failed so caller can copy-paste
+}
+export type HandoffResult = HandoffSuccess | HandoffFailure
+
+/** Compute the workspace-stack URL for a given API host + tenant, or null if
+ * this deployment isn't supported (localhost, enterprise, custom domain).
+ *
+ * Dev escape hatch: ``ALTIMATE_WORKSPACE_WEB_URL`` overrides the map lookup
+ * when set (must be a well-formed URL). Used for local integration testing
+ * against a non-freemium SaaS instance. Not something production users touch. */
+export function resolveWorkspaceWebUrl(altimateUrl: string, tenant: string): URL | null {
+  const override = process.env["ALTIMATE_WORKSPACE_WEB_URL"]
+  if (override) {
+    try {
+      return new URL(override)
+    } catch {
+      return null
+    }
+  }
+  try {
+    const apiHost = new URL(altimateUrl).host
+    if (apiHost !== FREEMIUM_API_HOST) return null
+    return new URL(`https://${tenant}.${FREEMIUM_WORKSPACE_HOST}`)
+  } catch {
+    return null
+  }
+}
+
+interface HandoffPending {
+  state: string
+  expectedTenant: string
+  resolve: (v: HandoffSuccess) => void
+  reject: (err: Error & { handoffReason?: HandoffFailureReason }) => void
+}
+
+function markReason<E extends Error>(err: E, reason: HandoffFailureReason): E & { handoffReason: HandoffFailureReason } {
+  return Object.assign(err, { handoffReason: reason })
+}
+
+/** Start a per-flow loopback listener on the first available port in the
+ * shared 7317..7325 range. Own server, own pending map — no coupling to the
+ * OAuth listener in altimate.ts. */
+async function startListener(pending: HandoffPending): Promise<{ server: Server; port: number }> {
+  const server = createServer((req, res) => {
+    const port = (server.address() as { port?: number } | null)?.port ?? CALLBACK_PORT_MIN
+    const url = new URL(req.url || "/", `http://127.0.0.1:${port}`)
+    if (url.pathname !== "/workspace-bound") {
+      res.writeHead(404)
+      res.end("Not found")
+      return
+    }
+
+    const respond = (status: number, body: string) => {
+      res.writeHead(status, { "Content-Type": "text/html" })
+      res.end(body)
+    }
+
+    // Validate state FIRST — a request without the right state can neither
+    // cancel nor deliver anything.
+    const state = url.searchParams.get("state")
+    if (!state || state !== pending.state) {
+      respond(400, htmlError("Invalid or unknown workspace-handoff state"))
+      return
+    }
+
+    // Respond BEFORE resolving/rejecting the pending flow — the reject path
+    // closes the listener via closeListener(), which can race with the
+    // response flush and leave the client fetch hanging. Order matters.
+    const error = url.searchParams.get("error")
+    if (error) {
+      const reason: HandoffFailureReason = error === "cancelled" ? "cancelled" : "error"
+      respond(200, htmlError(error === "cancelled" ? "Cancelled by user" : error))
+      pending.reject(markReason(new Error(error), reason))
+      return
+    }
+
+    const workspaceIdRaw = url.searchParams.get("workspace_id")
+    const tenant = url.searchParams.get("tenant")
+    if (!workspaceIdRaw || !tenant) {
+      const msg = "Missing workspace_id or tenant in callback"
+      respond(400, htmlError(msg))
+      pending.reject(markReason(new Error(msg), "error"))
+      return
+    }
+
+    if (tenant !== pending.expectedTenant) {
+      // Cross-tenant defence: user created the workspace in a tenant that
+      // doesn't match the CLI's credentials. Refuse the bind — the workspace
+      // ID is tenant-schema-local so binding here would 404 or, worse, hit an
+      // unrelated workspace in the CLI's tenant.
+      const msg = `Workspace was created in tenant "${tenant}" but the CLI is signed into "${pending.expectedTenant}"`
+      respond(400, htmlError(msg))
+      pending.reject(markReason(new Error(msg), "tenant_mismatch"))
+      return
+    }
+
+    const workspaceId = Number(workspaceIdRaw)
+    if (!Number.isFinite(workspaceId) || workspaceId <= 0) {
+      const msg = `Invalid workspace_id: ${workspaceIdRaw}`
+      respond(400, htmlError(msg))
+      pending.reject(markReason(new Error(msg), "error"))
+      return
+    }
+
+    respond(200, DELIVERY_HTML_SUCCESS)
+    pending.resolve({ ok: true, workspaceId, tenant })
+  })
+
+  // Walk 7317..7325 — each server instance is independent, so a squatting
+  // OAuth listener on 7317 just makes us bind 7318.
+  const tried: number[] = []
+  let lastErr: NodeJS.ErrnoException | undefined
+  for (let port = CALLBACK_PORT_MIN; port <= CALLBACK_PORT_MAX; port++) {
+    tried.push(port)
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const onErr = (err: NodeJS.ErrnoException) => reject(err)
+        server.once("error", onErr)
+        server.listen(port, "127.0.0.1", () => {
+          server.removeListener("error", onErr)
+          resolve()
+        })
+      })
+      return { server, port }
+    } catch (err) {
+      lastErr = err as NodeJS.ErrnoException
+      // Defensive cleanup in case any listeners linger after a rejected bind.
+      server.removeAllListeners("error")
+      if (lastErr.code !== "EADDRINUSE") break
+    }
+  }
+
+  server.close()
+  const code = lastErr?.code
+  throw markReason(
+    new Error(
+      code === "EADDRINUSE"
+        ? `Every port in ${CALLBACK_PORT_MIN}-${CALLBACK_PORT_MAX} is in use (tried ${tried.join(", ")}). Close what's using them (e.g. \`lsof -i :${CALLBACK_PORT_MIN}\`) and try again.`
+        : `Could not start the workspace-handoff server: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`,
+    ),
+    "port_exhausted",
+  )
+}
+
+export interface OpenBrowserHandoffInput {
+  identifier: ProjectIdentifier
+  projectName: string
+}
+
+/** Full browser-handoff flow. Returns the created/picked workspace ID on
+ * success, or a typed failure reason on any error path. Never throws — every
+ * error is expressed as ``{ok: false, reason}`` so the caller can toast the
+ * appropriate message. */
+export async function openWorkspaceBrowserHandoff(input: OpenBrowserHandoffInput): Promise<HandoffResult> {
+  return runHandoffWithOpener(input, (url) => open(url).then(() => undefined))
+}
+
+/** Same as ``openWorkspaceBrowserHandoff`` but takes the browser-open callback
+ * as a dependency so tests can inject a fake that fires the loopback callback
+ * synchronously instead of launching a real browser. Not exported from the
+ * package barrel — only tests import this directly. */
+export async function runHandoffWithOpener(
+  input: OpenBrowserHandoffInput,
+  openBrowser: (url: string) => Promise<void>,
+): Promise<HandoffResult> {
+  if (!(await AltimateApi.isConfigured().catch(() => false))) {
+    return { ok: false, reason: "not_configured" }
+  }
+  const creds = await AltimateApi.getCredentials()
+  const webUrl = resolveWorkspaceWebUrl(creds.altimateUrl, creds.altimateInstanceName)
+  if (!webUrl) return { ok: false, reason: "unavailable" }
+
+  const state = randomBytes(16).toString("hex")
+
+  // Register pending, then bind the listener. Timeout owns rejection with
+  // reason "timeout"; the listener's own reject paths mark their own reasons.
+  let listenerHandle: { server: Server; port: number } | undefined
+  const closeListener = () => {
+    if (listenerHandle) {
+      try {
+        listenerHandle.server.close()
+      } catch {
+        /* best effort */
+      }
+      listenerHandle = undefined
+    }
+  }
+
+  const settled = new Promise<HandoffResult>((resolve) => {
+    const pending: HandoffPending = {
+      state,
+      expectedTenant: creds.altimateInstanceName,
+      resolve: (v) => {
+        closeListener()
+        clearTimeout(timeoutHandle)
+        resolve(v)
+      },
+      reject: (err) => {
+        closeListener()
+        clearTimeout(timeoutHandle)
+        const reason = (err as { handoffReason?: HandoffFailureReason }).handoffReason ?? "error"
+        const authorizeUrl = (err as { authorizeUrl?: string }).authorizeUrl
+        resolve({
+          ok: false,
+          reason,
+          message: err.message,
+          ...(authorizeUrl ? { authorizeUrl } : {}),
+        })
+      },
+    }
+    const timeoutHandle = setTimeout(() => {
+      pending.reject(markReason(new Error("Timed out waiting for browser workspace handoff"), "timeout"))
+    }, DEFAULT_TIMEOUT_MS)
+
+    ;(async () => {
+      try {
+        listenerHandle = await startListener(pending)
+      } catch (err) {
+        const reason = (err as { handoffReason?: HandoffFailureReason }).handoffReason ?? "error"
+        pending.reject(markReason(err as Error, reason))
+        return
+      }
+
+      // Import buildCliContext lazily so this module doesn't pull altimate.ts
+      // into every consumer's import graph at load time.
+      const { buildCliContext } = await import("../plugin/altimate")
+      const cliContext = await buildCliContext().catch((err) => {
+        log.warn("buildCliContext failed; proceeding without", { err: String(err) })
+        return ""
+      })
+
+      const redirect = `http://127.0.0.1:${listenerHandle.port}/workspace-bound`
+      const target = new URL("/create-and-link", webUrl)
+      target.searchParams.set("client", "altimate-code")
+      target.searchParams.set("redirect", redirect)
+      target.searchParams.set("state", state)
+      if (input.identifier.repoRemote) target.searchParams.set("project_remote", input.identifier.repoRemote)
+      if (input.identifier.projectPath) target.searchParams.set("project_path", input.identifier.projectPath)
+      target.searchParams.set("project_name", input.projectName)
+      const authorizeUrl = cliContext
+        ? `${target.toString()}#cli_context=${encodeURIComponent(cliContext)}`
+        : target.toString()
+
+      try {
+        await openBrowser(authorizeUrl)
+      } catch (err) {
+        // Browser open failed. Preserve the URL so the caller can copy-paste.
+        pending.reject(
+          Object.assign(
+            markReason(new Error(`Could not open browser: ${err instanceof Error ? err.message : String(err)}`), "browser_open_failed"),
+            { authorizeUrl },
+          ),
+        )
+      }
+    })()
+  })
+
+  return settled
+}
diff --git a/packages/opencode/src/cli/cmd/link.ts b/packages/opencode/src/cli/cmd/link.ts
index 3c9371d73..b251ec0c1 100644
--- a/packages/opencode/src/cli/cmd/link.ts
+++ b/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,29 @@ 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 }> = [
+      ...(browserAvailable
+        ? [
+            {
+              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 +168,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 +188,102 @@ 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
+  }
+  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,
diff --git a/packages/opencode/src/plugin/tui/altimate/workspace.tsx b/packages/opencode/src/plugin/tui/altimate/workspace.tsx
index 440fa8412..0d039465a 100644
--- a/packages/opencode/src/plugin/tui/altimate/workspace.tsx
+++ b/packages/opencode/src/plugin/tui/altimate/workspace.tsx
@@ -37,6 +37,11 @@ import {
   type ProjectBindingLookup,
   type ProjectIdentifier,
 } from "@/altimate/workspace/api-client"
+import {
+  openWorkspaceBrowserHandoff,
+  resolveWorkspaceWebUrl,
+  type HandoffResult,
+} from "@/altimate/workspace/browser-handoff"
 import {
   projectNameFromPath,
   projectNameFromRemote,
@@ -50,6 +55,16 @@ const PLUGIN_ID = "altimate:workspace"
 
 const log = Log.create({ service: "altimate-workspace" })
 
+/** True when the browser-based workspace-creation handoff is available for
+ * the current credentials (freemium only today). Wrapped so both the post-scan
+ * flow and the on-demand `altimate-code link` picker can hide the option
+ * consistently when the deployment isn't supported. */
+async function isBrowserHandoffAvailable(): Promise<boolean> {
+  if (!(await AltimateApi.isConfigured().catch(() => false))) return false
+  const creds = await AltimateApi.getCredentials()
+  return resolveWorkspaceWebUrl(creds.altimateUrl, creds.altimateInstanceName) !== null
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Skip latch (TUI-only). Uses TuiPluginApi.kv — persistent across sessions
 // via packages/tui/src/context/kv.tsx (state/kv.json). The `altimate link`
@@ -132,6 +147,12 @@ interface OfferProps {
   api: TuiPluginApi
   identifier: ProjectIdentifier
   defaultName: string
+  /** True when this deployment supports the browser-based workspace-creation
+   * handoff (i.e. ``resolveWorkspaceWebUrl`` returned non-null for the current
+   * credentials). Resolved by the caller so the dialog doesn't need to await
+   * on mount. When false, the "Set up in browser" option is hidden and the
+   * dialog falls back to the pre-browser-handoff behavior. */
+  browserAvailable: boolean
   /** (tenant, apiUrl) scope for the Skip latch. Resolved once by the caller
    * so the sync ``onSelect`` handler can call ``recordSkip`` without a
    * mid-render await. Null when creds are unavailable — latch falls back
@@ -141,36 +162,52 @@ interface OfferProps {
 
 function OfferDialog(props: OfferProps) {
   const identLabel = () => props.identifier.repoRemote ?? props.identifier.projectPath ?? "this project"
+  const options = [
+    ...(props.browserAvailable
+      ? [
+          {
+            title: "Set up in browser (recommended)",
+            value: "browser",
+            description: `Approve and name "${props.defaultName}" in the Altimate SaaS; the CLI links your project automatically.`,
+          },
+        ]
+      : []),
+    {
+      title: "Create quick workspace here",
+      value: "create",
+      description: `Auto-named "${props.defaultName}" from this repo — no browser step. Configure integrations later in the SaaS.`,
+    },
+    {
+      title: "Link to an existing workspace",
+      value: "link",
+      description: "Attach this project to a workspace you already own.",
+    },
+    {
+      title: "Skip for now",
+      value: "skip",
+      description: "Won't ask again for 7 days.",
+    },
+  ]
+  const defaultValue = props.browserAvailable ? "browser" : "create"
   return (
     <props.api.ui.DialogSelect
       title={`Set up a workspace for this project? (${identLabel()})`}
-      options={[
-        {
-          title: "Create a new workspace",
-          value: "create",
-          description: `Auto-named "${props.defaultName}" from this repo — rename in the SaaS.`,
-        },
-        {
-          title: "Link to an existing workspace",
-          value: "link",
-          description: "Attach this project to a workspace you already own.",
-        },
-        {
-          title: "Skip for now",
-          value: "skip",
-          description: "Won't ask again for 7 days.",
-        },
-      ]}
-      current="create"
+      options={options}
+      current={defaultValue}
       onSelect={(option) => {
         if (option.value === "skip") {
           recordSkip(props.api, props.identifier, props.latchScope, Date.now())
           props.api.ui.dialog.clear()
           return
         }
+        if (option.value === "browser") {
+          void runBrowserHandoff(props.api, props.identifier, props.defaultName)
+          return
+        }
         if (option.value === "create") {
-          // Auto-name from git repo — no name prompt. The SaaS UI is the place to
-          // rename / configure; the CLI's job is just to establish the binding.
+          // Local direct-create — the CLI-only fallback. The SaaS UI is the
+          // place to rename / configure; this branch establishes the binding
+          // without a browser round-trip.
           void createAndBindInline(props.api, props.identifier, props.defaultName)
           return
         }
@@ -183,6 +220,120 @@ function OfferDialog(props: OfferProps) {
   )
 }
 
+/** Post-scan / on-demand browser-handoff runner. Opens the SaaS approval
+ * modal, waits for the callback, and binds the current project to the
+ * returned workspace via the existing ``POST /bind`` endpoint. Every failure
+ * mode surfaces as a toast; the user can always fall back to another option
+ * by re-invoking the dialog. */
+async function runBrowserHandoff(
+  api: TuiPluginApi,
+  identifier: ProjectIdentifier,
+  projectName: string,
+): Promise<void> {
+  api.ui.dialog.clear()
+  api.ui.toast({
+    variant: "info",
+    message: "Opening browser to set up your workspace — return here once you approve.",
+  })
+  const result: HandoffResult = await openWorkspaceBrowserHandoff({ identifier, projectName })
+  if (!result.ok) {
+    toastHandoffFailure(api, result)
+    return
+  }
+  // Handoff succeeded — bind the project to the returned workspace via the
+  // existing bind endpoint. Same code path as PickerDialog's attach mode.
+  try {
+    const res = await WorkspaceApi.bindExisting(result.workspaceId, identifier)
+    await recordApprovedBinding(api.state.path.directory, {
+      datamateId: res.binding.datamate_id,
+      datamateName: res.binding.datamate_name,
+      repoRemote: res.binding.repo_remote,
+      projectPath: res.binding.project_path,
+      linkedAt: Date.now(),
+    })
+    api.ui.toast({
+      variant: "success",
+      message: `Linked to workspace "${res.binding.datamate_name}".`,
+    })
+  } catch (err) {
+    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.`,
+      })
+    } else if (err instanceof NotFoundError) {
+      api.ui.toast({
+        variant: "error",
+        message: "Workspace not found — the tenant or workspace may have changed. Try again.",
+      })
+    } else if (err instanceof ForbiddenError) {
+      api.ui.toast({
+        variant: "error",
+        message: "Only the workspace owner can bind projects to it.",
+      })
+    } else {
+      api.ui.toast({
+        variant: "error",
+        message: err instanceof Error ? err.message : "Failed to bind workspace",
+      })
+    }
+  }
+}
+
+function toastHandoffFailure(api: TuiPluginApi, result: Extract<HandoffResult, { ok: false }>): void {
+  switch (result.reason) {
+    case "unavailable":
+      // Should not happen if browserAvailable was checked, but guard anyway.
+      api.ui.toast({
+        variant: "warning",
+        message: "Browser-based workspace setup isn't available for this deployment. Use \"Create quick workspace here\" instead.",
+      })
+      break
+    case "not_configured":
+      api.ui.toast({
+        variant: "error",
+        message: "Altimate credentials not configured — sign in first, then re-run.",
+      })
+      break
+    case "timeout":
+      api.ui.toast({
+        variant: "warning",
+        message: "Workspace setup timed out (15 min). Re-run when you're ready.",
+      })
+      break
+    case "cancelled":
+      api.ui.toast({
+        variant: "info",
+        message: "Workspace setup cancelled.",
+      })
+      break
+    case "tenant_mismatch":
+      api.ui.toast({
+        variant: "error",
+        message: result.message ?? "Workspace was set up under a different account than the CLI is signed into.",
+      })
+      break
+    case "port_exhausted":
+      api.ui.toast({
+        variant: "error",
+        message: result.message ?? "Local ports 7317-7325 all in use — free one and try again.",
+      })
+      break
+    case "browser_open_failed":
+      api.ui.toast({
+        variant: "error",
+        message: `Could not open browser. ${result.authorizeUrl ? `Open this URL manually: ${result.authorizeUrl}` : ""}`,
+        duration: 15_000,
+      })
+      break
+    default:
+      api.ui.toast({
+        variant: "error",
+        message: result.message ?? "Workspace setup failed.",
+      })
+  }
+}
+
 async function createAndBindInline(
   api: TuiPluginApi,
   identifier: ProjectIdentifier,
@@ -747,6 +898,12 @@ async function runFlow(api: TuiPluginApi, directory: string): Promise<void> {
     ? projectNameFromRemote(identifier.repoRemote)
     : projectNameFromPath(identifier.projectPath)
 
+  // Whether the browser-based handoff is available for this deployment. The
+  // OfferDialog hides the "Set up in browser" option when false, silently
+  // falling back to the pre-browser-handoff behavior. Compute here (once,
+  // async) so the dialog itself stays sync.
+  const browserAvailable = await isBrowserHandoffAvailable()
+
   let serverBinding: ProjectBindingLookup | null | undefined
   try {
     serverBinding = await WorkspaceApi.getBindingForProject(identifier)
@@ -799,6 +956,7 @@ async function runFlow(api: TuiPluginApi, directory: string): Promise<void> {
         api={api}
         identifier={identifier}
         defaultName={defaultName}
+        browserAvailable={browserAvailable}
         latchScope={latchScope}
       />
     ))
@@ -840,6 +998,7 @@ async function runFlow(api: TuiPluginApi, directory: string): Promise<void> {
       api={api}
       identifier={identifier}
       defaultName={defaultName}
+      browserAvailable={browserAvailable}
       latchScope={latchScope}
     />
   ))
diff --git a/packages/opencode/test/altimate/workspace/browser-handoff.test.ts b/packages/opencode/test/altimate/workspace/browser-handoff.test.ts
new file mode 100644
index 000000000..386e89b58
--- /dev/null
+++ b/packages/opencode/test/altimate/workspace/browser-handoff.test.ts
@@ -0,0 +1,261 @@
+// altimate_change - new file
+// Unit coverage for the browser-based workspace-creation handoff.
+// (packages/opencode/src/altimate/workspace/browser-handoff.ts.)
+//
+// Uses ``runHandoffWithOpener`` (dependency-injected browser-open callback)
+// so tests fire a synthetic callback at the live loopback listener instead of
+// launching a real browser. The listener itself binds to 127.0.0.1, walks
+// 7317..7325, and processes real HTTP requests — this is genuine end-to-end
+// coverage for the callback validation path.
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { createServer } from "node:net"
+
+import { AltimateApi } from "../../../src/altimate/api/client"
+import {
+  openWorkspaceBrowserHandoff,
+  resolveWorkspaceWebUrl,
+  runHandoffWithOpener,
+} from "../../../src/altimate/workspace/browser-handoff"
+
+// ── credential stubbing ─────────────────────────────────────────────────────
+const originalIsConfigured = AltimateApi.isConfigured
+const originalGetCreds = AltimateApi.getCredentials
+type Creds = Awaited<ReturnType<typeof AltimateApi.getCredentials>>
+function stubCreds(tenant: string, apiUrl: string) {
+  ;(AltimateApi as unknown as { isConfigured: () => Promise<boolean> }).isConfigured =
+    async () => true
+  ;(AltimateApi as unknown as { getCredentials: () => Promise<Creds> }).getCredentials =
+    async () =>
+      ({
+        altimateInstanceName: tenant,
+        altimateUrl: apiUrl,
+        altimateApiKey: "dummy",
+      }) as Creds
+}
+function unstubCreds() {
+  ;(AltimateApi as unknown as { isConfigured: typeof originalIsConfigured }).isConfigured =
+    originalIsConfigured
+  ;(AltimateApi as unknown as { getCredentials: typeof originalGetCreds }).getCredentials =
+    originalGetCreds
+}
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+/** Parse the authorize URL the CLI wants to open; extract the loopback port
+ * and CSRF state so tests can fire the crafted callback at the right address. */
+function parseHandoffUrl(url: string): { port: number; state: string; redirect: string } {
+  const u = new URL(url)
+  const redirect = u.searchParams.get("redirect")!
+  const state = u.searchParams.get("state")!
+  const port = Number(new URL(redirect).port)
+  return { port, state, redirect }
+}
+
+async function fireCallback(redirect: string, params: Record<string, string>): Promise<void> {
+  const target = new URL(redirect)
+  for (const [k, v] of Object.entries(params)) target.searchParams.set(k, v)
+  const res = await fetch(target.toString(), { method: "GET" })
+  // Drain body so the connection can close and let the CLI's `close()`
+  // proceed without hanging on lingering sockets.
+  await res.text().catch(() => "")
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// resolveWorkspaceWebUrl — the deployment-support gate
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("resolveWorkspaceWebUrl", () => {
+  test("freemium API host resolves to <tenant>.ws.myaltimate.com", () => {
+    const url = resolveWorkspaceWebUrl("https://api.myaltimate.com", "acme")
+    expect(url).not.toBeNull()
+    expect(url!.toString()).toBe("https://acme.ws.myaltimate.com/")
+  })
+
+  test("localhost API returns null (browser flow not supported in dev)", () => {
+    expect(resolveWorkspaceWebUrl("http://localhost:5001", "acme")).toBeNull()
+  })
+
+  test("enterprise API host returns null", () => {
+    expect(resolveWorkspaceWebUrl("https://acme.getaltimate.com", "acme")).toBeNull()
+  })
+
+  test("malformed URL returns null instead of throwing", () => {
+    expect(resolveWorkspaceWebUrl("not-a-url", "acme")).toBeNull()
+    expect(resolveWorkspaceWebUrl("", "acme")).toBeNull()
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// openWorkspaceBrowserHandoff — pre-flight failures (do not open a browser)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("openWorkspaceBrowserHandoff pre-flight", () => {
+  afterEach(() => unstubCreds())
+
+  test("returns {unavailable} for localhost credentials", async () => {
+    stubCreds("acme", "http://localhost:5001")
+    const result = await openWorkspaceBrowserHandoff({
+      identifier: { repoRemote: "git@github.com:acme/x.git", projectPath: "/x" },
+      projectName: "x",
+    })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe("unavailable")
+  })
+
+  test("returns {not_configured} when credentials are missing", async () => {
+    ;(AltimateApi as unknown as { isConfigured: () => Promise<boolean> }).isConfigured =
+      async () => false
+    const result = await openWorkspaceBrowserHandoff({
+      identifier: { projectPath: "/x" },
+      projectName: "x",
+    })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe("not_configured")
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// End-to-end via runHandoffWithOpener — real loopback, injected browser-open
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("runHandoffWithOpener end-to-end", () => {
+  beforeEach(() => stubCreds("acme", "https://api.myaltimate.com"))
+  afterEach(() => unstubCreds())
+
+  test("happy path: valid callback resolves with workspaceId + tenant", async () => {
+    const result = await runHandoffWithOpener(
+      {
+        identifier: { repoRemote: "git@github.com:acme/x.git", projectPath: "/x" },
+        projectName: "x",
+      },
+      async (url) => {
+        const { state, redirect } = parseHandoffUrl(url)
+        await fireCallback(redirect, { workspace_id: "42", state, tenant: "acme" })
+      },
+    )
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.workspaceId).toBe(42)
+      expect(result.tenant).toBe("acme")
+    }
+  })
+
+  test("tenant mismatch is refused", async () => {
+    const result = await runHandoffWithOpener(
+      { identifier: { projectPath: "/x" }, projectName: "x" },
+      async (url) => {
+        const { state, redirect } = parseHandoffUrl(url)
+        await fireCallback(redirect, { workspace_id: "42", state, tenant: "not-acme" })
+      },
+    )
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe("tenant_mismatch")
+  })
+
+  test("?error=cancelled callback resolves as {cancelled}", async () => {
+    const result = await runHandoffWithOpener(
+      { identifier: { projectPath: "/x" }, projectName: "x" },
+      async (url) => {
+        const { state, redirect } = parseHandoffUrl(url)
+        await fireCallback(redirect, { state, error: "cancelled", tenant: "acme" })
+      },
+    )
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe("cancelled")
+  })
+
+  test("missing workspace_id in callback resolves as {error}", async () => {
+    const result = await runHandoffWithOpener(
+      { identifier: { projectPath: "/x" }, projectName: "x" },
+      async (url) => {
+        const { state, redirect } = parseHandoffUrl(url)
+        await fireCallback(redirect, { state, tenant: "acme" })
+      },
+    )
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe("error")
+  })
+
+  test("invalid workspace_id (non-numeric) resolves as {error}", async () => {
+    const result = await runHandoffWithOpener(
+      { identifier: { projectPath: "/x" }, projectName: "x" },
+      async (url) => {
+        const { state, redirect } = parseHandoffUrl(url)
+        await fireCallback(redirect, { workspace_id: "not-a-number", state, tenant: "acme" })
+      },
+    )
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe("error")
+  })
+
+  test("browser open failure resolves as {browser_open_failed} with authorizeUrl", async () => {
+    const result = await runHandoffWithOpener(
+      { identifier: { projectPath: "/x" }, projectName: "x" },
+      async () => {
+        throw new Error("mock: no browser available")
+      },
+    )
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.reason).toBe("browser_open_failed")
+      expect(result.authorizeUrl).toContain("/create-and-link")
+      expect(result.authorizeUrl).toContain("client=altimate-code")
+      expect(result.authorizeUrl).toContain("project_name=x")
+    }
+  })
+
+  test("URL includes project_remote + project_path + project_name from input", async () => {
+    let observed = ""
+    await runHandoffWithOpener(
+      {
+        identifier: { repoRemote: "git@github.com:acme/foo.git", projectPath: "/w/foo" },
+        projectName: "foo",
+      },
+      async (url) => {
+        observed = url
+        // fire callback so the flow doesn't hang for 15 min
+        const { state, redirect } = parseHandoffUrl(url)
+        await fireCallback(redirect, { workspace_id: "1", state, tenant: "acme" })
+      },
+    )
+    const u = new URL(observed)
+    expect(u.searchParams.get("project_remote")).toBe("git@github.com:acme/foo.git")
+    expect(u.searchParams.get("project_path")).toBe("/w/foo")
+    expect(u.searchParams.get("project_name")).toBe("foo")
+    expect(u.pathname).toBe("/create-and-link")
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Port walk: a squatting listener on 7317 forces handoff to 7318+
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("port walk", () => {
+  beforeEach(() => stubCreds("acme", "https://api.myaltimate.com"))
+  afterEach(() => unstubCreds())
+
+  test("stale listener on 7317 forces handoff to 7318", async () => {
+    const squatter = createServer()
+    await new Promise<void>((resolve, reject) => {
+      squatter.once("error", reject)
+      squatter.listen(7317, "127.0.0.1", () => resolve())
+    })
+
+    try {
+      let observedPort = -1
+      const result = await runHandoffWithOpener(
+        { identifier: { projectPath: "/x" }, projectName: "x" },
+        async (url) => {
+          const { port, state, redirect } = parseHandoffUrl(url)
+          observedPort = port
+          await fireCallback(redirect, { workspace_id: "1", state, tenant: "acme" })
+        },
+      )
+      expect(result.ok).toBe(true)
+      expect(observedPort).toBeGreaterThan(7317)
+      expect(observedPort).toBeLessThanOrEqual(7325)
+    } finally {
+      await new Promise<void>((r) => squatter.close(() => r()))
+    }
+  })
+})

From ffc2b0f303b215b790891ff65619823dabb1c3a6 Mon Sep 17 00:00:00 2001
From: Haider <haider@altimate.ai>
Date: Mon, 17 Aug 2026 00:16:47 +0530
Subject: [PATCH 2/7] feat(workspace): top-level nav handoff + confirmation
 dialog + sidebar tile
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Deliver workspace handoff to CLI loopback via top-level navigation (matches
  OAuth sign-in pattern), bypassing HTTPS→loopback Private Network Access
  restrictions that would gate a subresource fetch in prod. Cancel uses the
  same mechanism; loopback bounces the browser back to the SaaS workspace
  page on success and workspace home on cancel.
- Replace transient success toasts with a persistent post-bind
  `WorkspaceLinkedDialog` (workspace name + manage URL + "Continue editing
  in browser" / "Done"). Wired into all five bind success paths (browser
  handoff, inline create, picker attach, picker rebind, on-demand palette).
- New right-pane sidebar tile showing the currently-linked workspace + manage
  URL, polling the local cache every 3s so a fresh bind surfaces without a
  TUI reload. Falls back to "Not linked — run /link" for unbound projects.
- Canonicalize local binding cache keys via `realpathSync` on both write and
  read paths, with a scan fallback for pre-existing entries. Fixes the macOS
  `/tmp` → `/private/tmp` symlink mismatch that caused the sidebar and
  by-path lookups to miss bindings the CLI itself had written.
- `altimate-code link` subcommand: show manage URL on success, cancel via
  top-level nav for reliability.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016H42Vt4pt5dcD7opRqckeM
---
 .../src/altimate/workspace/browser-handoff.ts |  49 ++++-
 .../opencode/src/altimate/workspace/state.ts  |  47 ++---
 packages/opencode/src/cli/cmd/link.ts         |   2 +
 .../opencode/src/plugin/tui/altimate/index.ts |  12 +-
 .../plugin/tui/altimate/workspace-sidebar.tsx |  93 ++++++++++
 .../src/plugin/tui/altimate/workspace.tsx     | 171 +++++++++++++-----
 6 files changed, 297 insertions(+), 77 deletions(-)
 create mode 100644 packages/opencode/src/plugin/tui/altimate/workspace-sidebar.tsx

diff --git a/packages/opencode/src/altimate/workspace/browser-handoff.ts b/packages/opencode/src/altimate/workspace/browser-handoff.ts
index 78a0bc7ab..7f04505d8 100644
--- a/packages/opencode/src/altimate/workspace/browser-handoff.ts
+++ b/packages/opencode/src/altimate/workspace/browser-handoff.ts
@@ -40,10 +40,23 @@ const CALLBACK_PORT_MIN = 7317
 const CALLBACK_PORT_MAX = 7325
 
 const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000
-const DELIVERY_HTML_SUCCESS = `<!doctype html><meta charset="utf-8"><title>Altimate Code</title>
+
+/** Loopback success page. We land the user back on the SaaS workspace page via
+ * top-level navigation — matches the OAuth sign-in pattern in altimate.ts,
+ * which is proven in prod. The rationale over a subresource fetch: HTTPS→HTTP
+ * loopback subresource fetches trigger Chrome/Safari Private Network Access
+ * checks (preflight OPTIONS with Access-Control-Request-Private-Network); a
+ * top-level navigation from an HTTP 302 or ``window.location.href`` bypasses
+ * PNA entirely. Meta refresh + JS assign for belt-and-suspenders. */
+function deliverySuccessHtml(manageUrl: string): string {
+  const safe = escapeHtml(manageUrl)
+  return `<!doctype html><meta charset="utf-8"><title>Altimate Code</title>
+<meta http-equiv="refresh" content="0;url=${safe}">
 <body style="font-family:system-ui;text-align:center;padding:64px">
-<h2>Workspace ready</h2><p>Return to your terminal to finish linking.</p>
-<script>setTimeout(()=>window.close(),1500)</script></body>`
+<h2>Workspace ready</h2><p>Returning you to the workspace page…</p>
+<p><a href="${safe}">Continue</a> if you're not redirected automatically.</p>
+<script>window.location.replace(${JSON.stringify(manageUrl)})</script></body>`
+}
 
 const log = Log.create({ service: "altimate-workspace-handoff" })
 
@@ -61,6 +74,20 @@ function htmlError(msg: string): string {
 <p>Please return to your terminal and try again.</p></body>`
 }
 
+/** Cancel-path response: bounce the browser back to the SaaS workspace home
+ * so the user doesn't get stranded on the plain loopback page. Same top-level
+ * navigation mechanism as ``deliverySuccessHtml``. */
+function cancelHtml(workspaceWebBase: URL): string {
+  const home = workspaceWebBase.toString().replace(/\/$/, "") + "/"
+  const safe = escapeHtml(home)
+  return `<!doctype html><meta charset="utf-8"><title>Altimate Code</title>
+<meta http-equiv="refresh" content="0;url=${safe}">
+<body style="font-family:system-ui;text-align:center;padding:64px">
+<h2>Cancelled</h2><p>Returning you to the workspace home…</p>
+<p><a href="${safe}">Continue</a> if you're not redirected automatically.</p>
+<script>window.location.replace(${JSON.stringify(home)})</script></body>`
+}
+
 export type HandoffFailureReason =
   | "unavailable" // resolveWorkspaceWebUrl returned null (not freemium)
   | "not_configured" // CLI credentials not present
@@ -111,6 +138,9 @@ export function resolveWorkspaceWebUrl(altimateUrl: string, tenant: string): URL
 interface HandoffPending {
   state: string
   expectedTenant: string
+  /** Base URL for the tenant's SaaS workspace stack, used to build the
+   * ``/w/:id`` bounce target that the loopback success HTML redirects to. */
+  workspaceWebBase: URL
   resolve: (v: HandoffSuccess) => void
   reject: (err: Error & { handoffReason?: HandoffFailureReason }) => void
 }
@@ -151,7 +181,11 @@ async function startListener(pending: HandoffPending): Promise<{ server: Server;
     const error = url.searchParams.get("error")
     if (error) {
       const reason: HandoffFailureReason = error === "cancelled" ? "cancelled" : "error"
-      respond(200, htmlError(error === "cancelled" ? "Cancelled by user" : error))
+      // Cancel bounces the browser back to the SaaS workspace home so the user
+      // isn't stranded on the plain loopback page; hard errors keep the plain
+      // error card (there's no useful place to bounce them to).
+      const body = error === "cancelled" ? cancelHtml(pending.workspaceWebBase) : htmlError(error)
+      respond(200, body)
       pending.reject(markReason(new Error(error), reason))
       return
     }
@@ -184,7 +218,11 @@ async function startListener(pending: HandoffPending): Promise<{ server: Server;
       return
     }
 
-    respond(200, DELIVERY_HTML_SUCCESS)
+    // Bounce the browser back to the SaaS workspace page. Loopback constructs
+    // the URL itself (no need to trust a `return` query param) — the base is
+    // deterministic from the tenant we already validated above.
+    const manageUrl = `${pending.workspaceWebBase.toString().replace(/\/$/, "")}/w/${workspaceId}`
+    respond(200, deliverySuccessHtml(manageUrl))
     pending.resolve({ ok: true, workspaceId, tenant })
   })
 
@@ -272,6 +310,7 @@ export async function runHandoffWithOpener(
     const pending: HandoffPending = {
       state,
       expectedTenant: creds.altimateInstanceName,
+      workspaceWebBase: webUrl,
       resolve: (v) => {
         closeListener()
         clearTimeout(timeoutHandle)
diff --git a/packages/opencode/src/altimate/workspace/state.ts b/packages/opencode/src/altimate/workspace/state.ts
index 5ada4971f..bcbf9cbe9 100644
--- a/packages/opencode/src/altimate/workspace/state.ts
+++ b/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
@@ -124,6 +106,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
@@ -153,7 +147,17 @@ export async function readLocalBinding(directory: string): Promise<CachedBinding
   const 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)
+  // First try the direct canonical + raw key lookups (cheap). If neither hits,
+  // scan every stored key and re-canonicalize it — catches entries written by
+  // earlier CLI builds under an unresolved key (e.g. ``/tmp/foo``) even though
+  // the caller looks them back up under the resolved key (``/private/tmp/foo``).
+  const direct = cache.bindings[canon] ?? cache.bindings[directory]
+  if (direct) return direct
+  for (const [k, v] of Object.entries(cache.bindings)) {
+    if (canonicalizeKey(k) === canon) return v
+  }
+  return null
 }
 
 export async function recordApprovedBinding(
@@ -166,14 +170,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", {
diff --git a/packages/opencode/src/cli/cmd/link.ts b/packages/opencode/src/cli/cmd/link.ts
index b251ec0c1..897a4426b 100644
--- a/packages/opencode/src/cli/cmd/link.ts
+++ b/packages/opencode/src/cli/cmd/link.ts
@@ -466,6 +466,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)
diff --git a/packages/opencode/src/plugin/tui/altimate/index.ts b/packages/opencode/src/plugin/tui/altimate/index.ts
index adb5662e6..8e90e364b 100644
--- a/packages/opencode/src/plugin/tui/altimate/index.ts
+++ b/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
diff --git a/packages/opencode/src/plugin/tui/altimate/workspace-sidebar.tsx b/packages/opencode/src/plugin/tui/altimate/workspace-sidebar.tsx
new file mode 100644
index 000000000..712b8d54d
--- /dev/null
+++ b/packages/opencode/src/plugin/tui/altimate/workspace-sidebar.tsx
@@ -0,0 +1,93 @@
+// altimate_change - new file
+// Right-pane sidebar tile that shows the workspace the current project
+// directory is bound to (or "Not linked" with a hint). Reads from the local
+// binding cache written by `../workspace.tsx` (post-scan dialog, on-demand
+// picker, browser handoff). Cache is polled every 3s so a fresh bind
+// surfaces without the user having to reload the TUI.
+//
+// Deliberately read-only. All bind mutations live in workspace.tsx / link.ts;
+// this tile just reflects state.
+import type { TuiPlugin, TuiPluginApi } from "@opencode-ai/plugin/tui"
+import type { BuiltinTuiPlugin } from "@opencode-ai/tui/builtins"
+import { createSignal, onCleanup, onMount, Show } from "solid-js"
+import { readLocalBinding, type CachedBinding } from "@/altimate/workspace/state"
+import { resolveWorkspaceWebUrl } from "@/altimate/workspace/browser-handoff"
+import { AltimateApi } from "@/altimate/api/client"
+
+const id = "altimate:sidebar-workspace"
+
+const POLL_MS = 3000
+
+function View(props: { api: TuiPluginApi }) {
+  const theme = () => props.api.theme.current
+  const [binding, setBinding] = createSignal<CachedBinding | null>(null)
+  const [manageUrl, setManageUrl] = createSignal<string | null>(null)
+
+  const refresh = async () => {
+    const dir = props.api.state.path.directory
+    const b = await readLocalBinding(dir).catch(() => null)
+    setBinding(b)
+    if (!b) {
+      setManageUrl(null)
+      return
+    }
+    try {
+      const creds = await AltimateApi.getCredentials()
+      const base = resolveWorkspaceWebUrl(creds.altimateUrl, creds.altimateInstanceName)
+      setManageUrl(base ? `${base.toString().replace(/\/$/, "")}/w/${b.datamateId}` : null)
+    } catch {
+      setManageUrl(null)
+    }
+  }
+
+  onMount(() => {
+    void refresh()
+    const timer = setInterval(() => void refresh(), POLL_MS)
+    onCleanup(() => clearInterval(timer))
+  })
+
+  return (
+    <box>
+      <text fg={theme().text}>
+        <b>Workspace</b>
+      </text>
+      <Show
+        when={binding()}
+        fallback={
+          <text fg={theme().textMuted}>
+            Not linked — run <b>/link</b>
+          </text>
+        }
+      >
+        {(b) => (
+          <>
+            <text fg={theme().textMuted}>{b().datamateName}</text>
+            <Show when={manageUrl()}>
+              {(u) => <text fg={theme().textMuted}>{u()}</text>}
+            </Show>
+          </>
+        )}
+      </Show>
+    </box>
+  )
+}
+
+const tui: TuiPlugin = async (api) => {
+  api.slots.register({
+    // Below MCP (200) and above LSP (300) — workspace identity is high-signal
+    // when present, but not more useful than the connection status above.
+    order: 250,
+    slots: {
+      sidebar_content() {
+        return <View api={api} />
+      },
+    },
+  })
+}
+
+const plugin: BuiltinTuiPlugin = {
+  id,
+  tui,
+}
+
+export default plugin
diff --git a/packages/opencode/src/plugin/tui/altimate/workspace.tsx b/packages/opencode/src/plugin/tui/altimate/workspace.tsx
index 0d039465a..2d980bd10 100644
--- a/packages/opencode/src/plugin/tui/altimate/workspace.tsx
+++ b/packages/opencode/src/plugin/tui/altimate/workspace.tsx
@@ -220,6 +220,100 @@ function OfferDialog(props: OfferProps) {
   )
 }
 
+/** Build the SaaS manage-workspace URL for a bound workspace. Deterministic
+ * from tenant + id, so any caller can construct it without an extra round-trip.
+ * Returns null when the current deployment isn't the freemium web (BYOK or
+ * unresolvable) — the confirmation dialog degrades to id-only in that case. */
+async function buildManageUrl(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
+  }
+}
+
+interface LinkedProps {
+  api: TuiPluginApi
+  workspaceName: string
+  manageUrl: string | null
+  /** Verb for the title — "Linked" / "Re-linked" / "Created". Keeps the
+   * three success paths visually consistent while still labelling what
+   * just happened. */
+  verb: "Linked" | "Re-linked" | "Created"
+}
+
+/** Persistent confirmation card shown after a successful bind. Replaces the
+ * transient success toast so the user has an unmissable "yes, it worked" and
+ * a stable CTA back to the browser. Dismissable via Done or Esc. */
+function WorkspaceLinkedDialog(props: LinkedProps) {
+  const title = () => {
+    const suffix = props.manageUrl ? ` — ${props.manageUrl}` : ""
+    return `${props.verb} workspace "${props.workspaceName}"${suffix}`
+  }
+  const options = () => {
+    if (props.manageUrl) {
+      return [
+        {
+          title: "Continue editing in browser",
+          value: "open",
+          description: "Open the workspace in your browser.",
+        },
+        { title: "Done", value: "done", description: "Close this dialog." },
+      ]
+    }
+    return [{ title: "Done", value: "done", description: "Close this dialog." }]
+  }
+  return (
+    <props.api.ui.DialogSelect
+      title={title()}
+      options={options()}
+      current={props.manageUrl ? "open" : "done"}
+      onSelect={(option) => {
+        if (option.value === "open" && props.manageUrl) {
+          const url = props.manageUrl
+          // Guard before delegating to open() — a rogue manage_url with a
+          // non-http protocol would otherwise dispatch to an unrelated OS
+          // scheme handler. buildManageUrl only ever emits http(s) URLs from
+          // resolveWorkspaceWebUrl, but the guard survives future changes.
+          if (!isSafeHttpUrl(url)) {
+            props.api.ui.toast({
+              variant: "warning",
+              message: `Refused to open a non-http URL: ${url}`,
+              duration: 15_000,
+            })
+          } else {
+            open(url).catch(() => {
+              props.api.ui.toast({
+                variant: "warning",
+                message: `Could not open browser. Copy this URL: ${url}`,
+                duration: 15_000,
+              })
+            })
+          }
+        }
+        props.api.ui.dialog.clear()
+      }}
+    />
+  )
+}
+
+/** Show the persistent linked-confirmation dialog. Builds the manage URL
+ * best-effort; degrades gracefully on BYOK/unresolvable. */
+async function showLinkedConfirmation(
+  api: TuiPluginApi,
+  verb: LinkedProps["verb"],
+  workspaceId: number,
+  workspaceName: string,
+): Promise<void> {
+  const manageUrl = await buildManageUrl(workspaceId)
+  api.ui.dialog.replace(() => (
+    <WorkspaceLinkedDialog api={api} workspaceName={workspaceName} manageUrl={manageUrl} verb={verb} />
+  ))
+}
+
 /** Post-scan / on-demand browser-handoff runner. Opens the SaaS approval
  * modal, waits for the callback, and binds the current project to the
  * returned workspace via the existing ``POST /bind`` endpoint. Every failure
@@ -233,7 +327,7 @@ async function runBrowserHandoff(
   api.ui.dialog.clear()
   api.ui.toast({
     variant: "info",
-    message: "Opening browser to set up your workspace — return here once you approve.",
+    message: "Opening browser to set up your workspace — approve there, then check back here for the confirmation.",
   })
   const result: HandoffResult = await openWorkspaceBrowserHandoff({ identifier, projectName })
   if (!result.ok) {
@@ -251,10 +345,7 @@ async function runBrowserHandoff(
       projectPath: res.binding.project_path,
       linkedAt: Date.now(),
     })
-    api.ui.toast({
-      variant: "success",
-      message: `Linked to workspace "${res.binding.datamate_name}".`,
-    })
+    await showLinkedConfirmation(api, "Linked", res.binding.datamate_id, res.binding.datamate_name)
   } catch (err) {
     if (err instanceof ConflictError) {
       api.ui.toast({
@@ -389,10 +480,11 @@ async function createAndBindInline(
   // Post-success tail — this function is invoked fire-and-forget
   // (``void createAndBindInline(...)``), so a bare rejection here would
   // surface as an unhandled promise and terminate the TUI. Contain the
-  // fallout inside the function itself: ``recordApprovedBinding`` already
-  // swallows its own errors (state.ts is best-effort), but ``open()`` and
-  // the toast APIs can reject unexpectedly. Fall back to a plain info
-  // toast so the user still sees the URL. (Kilo cycle 5.)
+  // fallout inside the function itself. ``recordApprovedBinding`` already
+  // swallows its own errors (state.ts is best-effort), but
+  // ``showLinkedConfirmation`` can reject on dialog-teardown races — the
+  // toast fallback keeps the user informed without taking the process down.
+  // (Kilo cycle 5.)
   try {
     await recordApprovedBinding(api.state.path.directory, {
       datamateId: res.datamate.id,
@@ -401,27 +493,7 @@ async function createAndBindInline(
       projectPath: res.binding.project_path,
       linkedAt: Date.now(),
     })
-    // Guard against a non-http(s) manage_url — ``open`` dispatches to whatever
-    // OS handler matches the protocol, so a rogue value could launch an
-    // unrelated app. Fall through to the info toast (with the URL for manual
-    // copy) if the URL isn't a safe http/https link.
-    if (isSafeHttpUrl(res.manage_url)) {
-      try {
-        await open(res.manage_url)
-        api.ui.toast({
-          variant: "success",
-          message: `Workspace "${res.datamate.name}" created. Opened ${res.manage_url} in your browser.`,
-        })
-        return
-      } catch {
-        /* fall through to the "open manually" toast below */
-      }
-    }
-    api.ui.toast({
-      variant: "info",
-      message: `Workspace "${res.datamate.name}" created. Open ${res.manage_url} to configure it.`,
-      duration: 10_000,
-    })
+    await showLinkedConfirmation(api, "Created", res.datamate.id, res.datamate.name)
   } catch (err) {
     api.ui.toast({
       variant: "info",
@@ -433,7 +505,9 @@ async function createAndBindInline(
 
 /** True when the URL parses and its protocol is exactly ``http:`` or ``https:``.
  * Used before handing a server-supplied URL to ``open()`` (which would otherwise
- * dispatch to whatever OS scheme handler matches the protocol). */
+ * dispatch to whatever OS scheme handler matches the protocol). Kept exported
+ * as a top-level helper because both ``showLinkedConfirmation`` (below) and
+ * the on-demand link paths need the same guard. */
 function isSafeHttpUrl(url: string): boolean {
   try {
     const u = new URL(url)
@@ -589,10 +663,13 @@ function PickerDialog(props: PickerProps) {
           projectPath: res.binding.project_path,
           linkedAt: Date.now(),
         })
-        props.api.ui.toast({
-          variant: "success",
-          message: `Linked to workspace "${res.binding.datamate_name}".`,
-        })
+        await showLinkedConfirmation(
+          props.api,
+          "Linked",
+          res.binding.datamate_id,
+          res.binding.datamate_name,
+        )
+        return
       } else {
         // Rebind: pick the endpoint that matches which identifier the
         // pre-check RESOLVED the binding on — not what the current identifier
@@ -615,12 +692,14 @@ function PickerDialog(props: PickerProps) {
           projectPath: res.binding.project_path,
           linkedAt: Date.now(),
         })
-        props.api.ui.toast({
-          variant: "success",
-          message: `Re-linked to workspace "${res.binding.datamate_name}".`,
-        })
+        await showLinkedConfirmation(
+          props.api,
+          "Re-linked",
+          res.binding.datamate_id,
+          res.binding.datamate_name,
+        )
+        return
       }
-      props.api.ui.dialog.clear()
     } catch (err) {
       // Surface as a toast so the user sees the specific failure. Dialog
       // closes either way — the palette command ``altimate.workspace.link``
@@ -817,12 +896,12 @@ async function bindOrRebindInline(
       projectPath: res.binding.project_path,
       linkedAt: Date.now(),
     })
-    api.ui.toast({
-      variant: "success",
-      message: isRebind
-        ? `Re-linked to workspace "${res.binding.datamate_name}".`
-        : `Linked to workspace "${res.binding.datamate_name}".`,
-    })
+    await showLinkedConfirmation(
+      api,
+      isRebind ? "Re-linked" : "Linked",
+      res.binding.datamate_id,
+      res.binding.datamate_name,
+    )
   } catch (err) {
     let msg: string
     if (err instanceof ConflictError) {

From 7af313d7abebcdc1554ce238dabbe79e2e5965eb Mon Sep 17 00:00:00 2001
From: Haider <haider@altimate.ai>
Date: Mon, 17 Aug 2026 04:01:50 +0530
Subject: [PATCH 3/7] =?UTF-8?q?fix(workspace):=20consensus=20review=20?=
 =?UTF-8?q?=E2=80=94=20handoff=20error=20contract,=20credential=20re-verif?=
 =?UTF-8?q?y,=20sidebar=20polish,=20cache=20canonicalization?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses the review findings introduced by this PR's commits (browser
handoff + top-level nav / sidebar tile). PR #1099 fixes landed
separately.

- `runHandoffWithOpener` now wraps preflight (`getCredentials`) AND the
  post-listener async IIFE in one try/catch that converts every error to
  a `HandoffResult`. Previously a malformed credentials file rejected the
  returned Promise with no toast, and a throw inside the lazy
  `import("../plugin/altimate")` left the caller waiting the full 15
  minutes with no reason surfaced. The port is captured into a local
  immediately after `startListener` resolves so a timeout-cleared handle
  can't be dereferenced later. (M4)
- `HandoffSuccess` now carries a `credentials` fingerprint (apiUrl +
  tenant) that the handoff was validated against. `runBrowserHandoff` in
  both entry points re-reads `AltimateApi.getCredentials()` immediately
  before `bindExisting` and refuses if either field drifted — workspace
  ids are tenant-schema-local so a mid-flow account switch would
  otherwise bind under the wrong tenant. (M6)
- `resolveWorkspaceWebUrl` guards the tenant with a DNS-label regex and
  reconstructs the origin from the parsed URL, so a credential row
  carrying `evil.example/path?x=` cannot open the handoff at
  `https://evil.example`. Override still available for local dev; both
  paths reject non-http(s) protocols. (m3)
- Optional `AbortSignal` on `OpenBrowserHandoffInput` — a caller-fired
  abort tears down the listener immediately with `reason: "aborted"`
  instead of holding the port for 15 minutes; timeout is `.unref()`'d so
  it doesn't keep the CLI process alive on its own. (m2)
- `port_exhausted` is now only returned when the errno is `EADDRINUSE`
  — other codes (EACCES, EBADF) map to `reason: "error"` so the user
  isn't told "ports all in use" for a permissions problem. (m5)
- `project_path` + `project_remote` moved to the URL fragment, matching
  the `cli_context` rationale — those two values carry usernames /
  customer names / internal paths that shouldn't land in SaaS access
  logs, WAF logs, or browser history. `project_name` stays in the query
  because the SaaS approval modal renders it. Test updated. (m6)
- `workspace_id` uses `Number.isInteger` instead of `Number.isFinite`,
  so `42.5` no longer reaches a backend expecting an integer. (m9)
- Inline `<script>` blocks now escape `</script` in JSON.stringify'd
  values via a `<\/script` replacement, closing the theoretical inline-
  script-break vector. (N5.b)
- Local binding cache: one-shot migration to canonical keys on the
  first `readLocalBinding` that finds a non-canonical key, followed by
  a plain property lookup for every subsequent read. Deletes the O(n)
  `realpathSync` rescan that ran on every cache miss under the 3s
  sidebar poll. (N1)
- Sidebar tile polls at 30s instead of 3s, memoizes the manage-URL
  base per (apiUrl, tenant), and guards against overlapping refreshes.
  Copy updated from "run /link" (the slash command doesn't exist —
  N2) to "run altimate-code link" (the actual CLI subcommand).
  Interval timer `.unref()`'d.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016H42Vt4pt5dcD7opRqckeM
---
 .../src/altimate/workspace/browser-handoff.ts | 218 +++++++++++++-----
 .../opencode/src/altimate/workspace/state.ts  |  48 +++-
 packages/opencode/src/cli/cmd/link.ts         |  22 ++
 .../plugin/tui/altimate/workspace-sidebar.tsx |  67 ++++--
 .../src/plugin/tui/altimate/workspace.tsx     |  32 ++-
 .../workspace/browser-handoff.test.ts         |  17 +-
 6 files changed, 320 insertions(+), 84 deletions(-)

diff --git a/packages/opencode/src/altimate/workspace/browser-handoff.ts b/packages/opencode/src/altimate/workspace/browser-handoff.ts
index 7f04505d8..a6cadfb0b 100644
--- a/packages/opencode/src/altimate/workspace/browser-handoff.ts
+++ b/packages/opencode/src/altimate/workspace/browser-handoff.ts
@@ -33,6 +33,15 @@ import type { ProjectIdentifier } from "./api-client"
 const FREEMIUM_API_HOST = "api.myaltimate.com"
 const FREEMIUM_WORKSPACE_HOST = "ws.myaltimate.com"
 
+/** DNS-label-shaped tenant guard for the freemium subdomain. Credentials
+ * only require ``altimateInstanceName`` to be a non-empty string, so a tenant
+ * like ``evil.example/path?x=`` would otherwise be interpolated straight into
+ * the origin, opening the handoff URL — carrying the project path, remote,
+ * callback address, CSRF state, and telemetry context — at
+ * ``https://evil.example`` (m3 in the consensus review). Reject anything that
+ * would not survive a round-trip through URL parsing back to the same host. */
+const TENANT_LABEL_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i
+
 // Loopback port range for the workspace-bound callback. Shared with the OAuth
 // sign-in listener in altimate.ts — each listener walks independently, so a
 // live OAuth server on 7317 forces us to 7318 (or later) transparently.
@@ -55,7 +64,7 @@ function deliverySuccessHtml(manageUrl: string): string {
 <body style="font-family:system-ui;text-align:center;padding:64px">
 <h2>Workspace ready</h2><p>Returning you to the workspace page…</p>
 <p><a href="${safe}">Continue</a> if you're not redirected automatically.</p>
-<script>window.location.replace(${JSON.stringify(manageUrl)})</script></body>`
+<script>window.location.replace(${escapeInlineScript(manageUrl)})</script></body>`
 }
 
 const log = Log.create({ service: "altimate-workspace-handoff" })
@@ -67,6 +76,15 @@ function escapeHtml(s: string): string {
   )
 }
 
+/** JSON-encode + escape any ``</`` so a value containing ``</script>`` cannot
+ * close the surrounding inline <script> block. Not reachable via any
+ * caller-supplied field today (tenant is DNS-label-guarded, workspace_id is
+ * a validated integer), but the belt-and-suspenders is trivial. (N5.b in
+ * the consensus review.) */
+function escapeInlineScript(value: string): string {
+  return JSON.stringify(value).replace(/<\/(script)/gi, "<\\/$1")
+}
+
 function htmlError(msg: string): string {
   return `<!doctype html><meta charset="utf-8"><title>Altimate Code</title>
 <body style="font-family:system-ui;text-align:center;padding:64px">
@@ -85,7 +103,7 @@ function cancelHtml(workspaceWebBase: URL): string {
 <body style="font-family:system-ui;text-align:center;padding:64px">
 <h2>Cancelled</h2><p>Returning you to the workspace home…</p>
 <p><a href="${safe}">Continue</a> if you're not redirected automatically.</p>
-<script>window.location.replace(${JSON.stringify(home)})</script></body>`
+<script>window.location.replace(${escapeInlineScript(home)})</script></body>`
 }
 
 export type HandoffFailureReason =
@@ -94,14 +112,29 @@ export type HandoffFailureReason =
   | "timeout" // 15-min window expired
   | "cancelled" // user hit Cancel in the browser
   | "tenant_mismatch" // callback tenant != credentials tenant
-  | "port_exhausted" // 7317..7325 all in use
+  | "port_exhausted" // 7317..7325 all EADDRINUSE
   | "browser_open_failed"
+  | "aborted" // caller-provided AbortSignal fired
   | "error"
 
+/** Snapshot of the credentials the handoff started against, returned to the
+ * caller so it can re-verify against fresh creds immediately before binding
+ * (M6 in the consensus review). Workspace ids are tenant-schema-local, so
+ * binding a callback validated for tenant A under tenant B (after an account
+ * switch mid-flow) would 404 or, worse, hit an unrelated workspace. */
+export interface CredentialFingerprint {
+  apiUrl: string
+  tenant: string
+}
+
 export interface HandoffSuccess {
   ok: true
   workspaceId: number
   tenant: string
+  /** Credentials the handoff resolved and validated the callback against.
+   * Callers must compare against ``AltimateApi.getCredentials()`` at bind
+   * time and refuse the bind if either field drifted. */
+  credentials: CredentialFingerprint
 }
 export interface HandoffFailure {
   ok: false
@@ -114,14 +147,19 @@ export type HandoffResult = HandoffSuccess | HandoffFailure
 /** Compute the workspace-stack URL for a given API host + tenant, or null if
  * this deployment isn't supported (localhost, enterprise, custom domain).
  *
- * Dev escape hatch: ``ALTIMATE_WORKSPACE_WEB_URL`` overrides the map lookup
- * when set (must be a well-formed URL). Used for local integration testing
- * against a non-freemium SaaS instance. Not something production users touch. */
+ * Dev escape hatch: ``ALTIMATE_WORKSPACE_WEB_URL`` overrides the tenant map
+ * lookup when set. The override is DEV-ONLY — it returns the URL as-is
+ * without tenant scoping (which is what a local ``altimate2.localhost:3003``
+ * dev server needs). Production callers must not set it; if it is somehow
+ * present and points off-tenant, the CSRF ``state`` still gates the callback
+ * so no cross-workspace bind is possible. */
 export function resolveWorkspaceWebUrl(altimateUrl: string, tenant: string): URL | null {
   const override = process.env["ALTIMATE_WORKSPACE_WEB_URL"]
   if (override) {
     try {
-      return new URL(override)
+      const u = new URL(override)
+      if (u.protocol !== "http:" && u.protocol !== "https:") return null
+      return u
     } catch {
       return null
     }
@@ -129,7 +167,15 @@ export function resolveWorkspaceWebUrl(altimateUrl: string, tenant: string): URL
   try {
     const apiHost = new URL(altimateUrl).host
     if (apiHost !== FREEMIUM_API_HOST) return null
-    return new URL(`https://${tenant}.${FREEMIUM_WORKSPACE_HOST}`)
+    // DNS-label guard — see TENANT_LABEL_RE for rationale. Double-check by
+    // reconstructing the origin from the parsed URL: if the parser resolved
+    // to a different host (embedded slashes, port, path in the "tenant"),
+    // refuse rather than emit a URL that points off-domain.
+    if (!TENANT_LABEL_RE.test(tenant)) return null
+    const lower = tenant.toLowerCase()
+    const u = new URL(`https://${lower}.${FREEMIUM_WORKSPACE_HOST}`)
+    if (u.hostname !== `${lower}.${FREEMIUM_WORKSPACE_HOST}`) return null
+    return u
   } catch {
     return null
   }
@@ -211,7 +257,9 @@ async function startListener(pending: HandoffPending): Promise<{ server: Server;
     }
 
     const workspaceId = Number(workspaceIdRaw)
-    if (!Number.isFinite(workspaceId) || workspaceId <= 0) {
+    // Integer-only: floats like ``42.5`` are rejected server-side but produce
+    // a confusing failure the caller can't recover from. (m9 in the review.)
+    if (!Number.isInteger(workspaceId) || workspaceId <= 0) {
       const msg = `Invalid workspace_id: ${workspaceIdRaw}`
       respond(400, htmlError(msg))
       pending.reject(markReason(new Error(msg), "error"))
@@ -223,7 +271,15 @@ async function startListener(pending: HandoffPending): Promise<{ server: Server;
     // deterministic from the tenant we already validated above.
     const manageUrl = `${pending.workspaceWebBase.toString().replace(/\/$/, "")}/w/${workspaceId}`
     respond(200, deliverySuccessHtml(manageUrl))
-    pending.resolve({ ok: true, workspaceId, tenant })
+    // Callback validated — but the SUCCESS payload carries the credentials
+    // snapshot the handoff was started against; the caller re-verifies
+    // against fresh creds before binding (M6). This module never binds.
+    pending.resolve({
+      ok: true,
+      workspaceId,
+      tenant,
+      credentials: { apiUrl: "", tenant: pending.expectedTenant }, // apiUrl filled in by caller
+    })
   })
 
   // Walk 7317..7325 — each server instance is independent, so a squatting
@@ -246,6 +302,9 @@ async function startListener(pending: HandoffPending): Promise<{ server: Server;
       lastErr = err as NodeJS.ErrnoException
       // Defensive cleanup in case any listeners linger after a rejected bind.
       server.removeAllListeners("error")
+      // Only keep walking on EADDRINUSE — any other errno (EACCES, EBADF, …)
+      // is a real problem, not port squatting, so break out and report it
+      // faithfully rather than falsely claiming "all ports in use". (m5)
       if (lastErr.code !== "EADDRINUSE") break
     }
   }
@@ -258,13 +317,18 @@ async function startListener(pending: HandoffPending): Promise<{ server: Server;
         ? `Every port in ${CALLBACK_PORT_MIN}-${CALLBACK_PORT_MAX} is in use (tried ${tried.join(", ")}). Close what's using them (e.g. \`lsof -i :${CALLBACK_PORT_MIN}\`) and try again.`
         : `Could not start the workspace-handoff server: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`,
     ),
-    "port_exhausted",
+    code === "EADDRINUSE" ? "port_exhausted" : "error",
   )
 }
 
 export interface OpenBrowserHandoffInput {
   identifier: ProjectIdentifier
   projectName: string
+  /** Optional AbortSignal — if it fires the flow settles with
+   * ``{ok: false, reason: "aborted"}`` and tears down the listener. Lets a
+   * TUI supersede a stale handoff without leaking a port for the full
+   * 15-minute window. (m2) */
+  signal?: AbortSignal
 }
 
 /** Full browser-handoff flow. Returns the created/picked workspace ID on
@@ -283,12 +347,28 @@ export async function runHandoffWithOpener(
   input: OpenBrowserHandoffInput,
   openBrowser: (url: string) => Promise<void>,
 ): Promise<HandoffResult> {
-  if (!(await AltimateApi.isConfigured().catch(() => false))) {
-    return { ok: false, reason: "not_configured" }
+  // Preflight is inside the same try/catch that owns the startup IIFE — a
+  // rejection from ``getCredentials()`` (malformed JSON, unresolved ${env:…}
+  // placeholder, schema mismatch) or from any other setup step converts to
+  // a HandoffResult instead of propagating as an unhandled rejection into
+  // the TUI's ``void runBrowserHandoff(...)`` call sites. (M4)
+  let creds: Awaited<ReturnType<typeof AltimateApi.getCredentials>>
+  let webUrl: URL
+  try {
+    if (!(await AltimateApi.isConfigured().catch(() => false))) {
+      return { ok: false, reason: "not_configured" }
+    }
+    creds = await AltimateApi.getCredentials()
+    const resolved = resolveWorkspaceWebUrl(creds.altimateUrl, creds.altimateInstanceName)
+    if (!resolved) return { ok: false, reason: "unavailable" }
+    webUrl = resolved
+  } catch (err) {
+    return {
+      ok: false,
+      reason: "error",
+      message: err instanceof Error ? err.message : String(err),
+    }
   }
-  const creds = await AltimateApi.getCredentials()
-  const webUrl = resolveWorkspaceWebUrl(creds.altimateUrl, creds.altimateInstanceName)
-  if (!webUrl) return { ok: false, reason: "unavailable" }
 
   const state = randomBytes(16).toString("hex")
 
@@ -306,7 +386,8 @@ export async function runHandoffWithOpener(
     }
   }
 
-  const settled = new Promise<HandoffResult>((resolve) => {
+  return new Promise<HandoffResult>((resolve) => {
+    let onAbort: (() => void) | null = null
     const pending: HandoffPending = {
       state,
       expectedTenant: creds.altimateInstanceName,
@@ -314,11 +395,16 @@ export async function runHandoffWithOpener(
       resolve: (v) => {
         closeListener()
         clearTimeout(timeoutHandle)
-        resolve(v)
+        if (onAbort && input.signal) input.signal.removeEventListener("abort", onAbort)
+        // Fill in the apiUrl snapshot the listener couldn't set (it doesn't
+        // hold ``creds``); the tenant already went through the expectedTenant
+        // check inside the listener.
+        resolve({ ...v, credentials: { apiUrl: creds.altimateUrl, tenant: v.tenant } })
       },
       reject: (err) => {
         closeListener()
         clearTimeout(timeoutHandle)
+        if (onAbort && input.signal) input.signal.removeEventListener("abort", onAbort)
         const reason = (err as { handoffReason?: HandoffFailureReason }).handoffReason ?? "error"
         const authorizeUrl = (err as { authorizeUrl?: string }).authorizeUrl
         resolve({
@@ -332,49 +418,75 @@ export async function runHandoffWithOpener(
     const timeoutHandle = setTimeout(() => {
       pending.reject(markReason(new Error("Timed out waiting for browser workspace handoff"), "timeout"))
     }, DEFAULT_TIMEOUT_MS)
+    // ``.unref()`` so the timer alone doesn't keep the CLI process alive
+    // once every other handle has exited. (m2)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ;(timeoutHandle as any)?.unref?.()
+
+    // Wire the AbortSignal — if it fires the flow settles with
+    // ``reason: "aborted"`` and the listener is torn down immediately.
+    if (input.signal) {
+      if (input.signal.aborted) {
+        pending.reject(markReason(new Error("Handoff aborted"), "aborted"))
+        return
+      }
+      onAbort = () => pending.reject(markReason(new Error("Handoff aborted"), "aborted"))
+      input.signal.addEventListener("abort", onAbort, { once: true })
+    }
 
     ;(async () => {
       try {
         listenerHandle = await startListener(pending)
+        // Capture the port to a local IMMEDIATELY — ``listenerHandle`` is
+        // cleared by ``closeListener`` on timeout, and a lazy ``import()``
+        // below can straddle that clear. (M4 sub-case)
+        const boundPort = listenerHandle.port
+
+        // Import buildCliContext lazily so this module doesn't pull altimate.ts
+        // into every consumer's import graph at load time.
+        const { buildCliContext } = await import("../plugin/altimate")
+        const cliContext = await buildCliContext().catch((err) => {
+          log.warn("buildCliContext failed; proceeding without", { err: String(err) })
+          return ""
+        })
+
+        const redirect = `http://127.0.0.1:${boundPort}/workspace-bound`
+        const target = new URL("/create-and-link", webUrl)
+        target.searchParams.set("client", "altimate-code")
+        target.searchParams.set("redirect", redirect)
+        target.searchParams.set("state", state)
+        target.searchParams.set("project_name", input.projectName)
+        // Project path + remote go in the URL FRAGMENT, not the query, so
+        // they don't land in SaaS access logs, WAF logs, or browser history
+        // as query params. Same rationale as ``cli_context`` in altimate.ts
+        // (see altimate.ts:135-137). (m6)
+        const fragment = new URLSearchParams()
+        if (input.identifier.repoRemote) fragment.set("project_remote", input.identifier.repoRemote)
+        if (input.identifier.projectPath) fragment.set("project_path", input.identifier.projectPath)
+        if (cliContext) fragment.set("cli_context", cliContext)
+        const authorizeUrl = fragment.toString()
+          ? `${target.toString()}#${fragment.toString()}`
+          : target.toString()
+
+        try {
+          await openBrowser(authorizeUrl)
+        } catch (err) {
+          // Browser open failed. Preserve the URL so the caller can copy-paste.
+          pending.reject(
+            Object.assign(
+              markReason(new Error(`Could not open browser: ${err instanceof Error ? err.message : String(err)}`), "browser_open_failed"),
+              { authorizeUrl },
+            ),
+          )
+        }
       } catch (err) {
+        // ANY throw in this async IIFE — startListener rejection, the lazy
+        // ``import()``, ``buildCliContext()`` panic — funnels through
+        // pending.reject so ``settled`` resolves and the caller sees a
+        // ``HandoffResult`` instead of a 15-minute silent hang. (M4)
         const reason = (err as { handoffReason?: HandoffFailureReason }).handoffReason ?? "error"
         pending.reject(markReason(err as Error, reason))
-        return
-      }
-
-      // Import buildCliContext lazily so this module doesn't pull altimate.ts
-      // into every consumer's import graph at load time.
-      const { buildCliContext } = await import("../plugin/altimate")
-      const cliContext = await buildCliContext().catch((err) => {
-        log.warn("buildCliContext failed; proceeding without", { err: String(err) })
-        return ""
-      })
-
-      const redirect = `http://127.0.0.1:${listenerHandle.port}/workspace-bound`
-      const target = new URL("/create-and-link", webUrl)
-      target.searchParams.set("client", "altimate-code")
-      target.searchParams.set("redirect", redirect)
-      target.searchParams.set("state", state)
-      if (input.identifier.repoRemote) target.searchParams.set("project_remote", input.identifier.repoRemote)
-      if (input.identifier.projectPath) target.searchParams.set("project_path", input.identifier.projectPath)
-      target.searchParams.set("project_name", input.projectName)
-      const authorizeUrl = cliContext
-        ? `${target.toString()}#cli_context=${encodeURIComponent(cliContext)}`
-        : target.toString()
-
-      try {
-        await openBrowser(authorizeUrl)
-      } catch (err) {
-        // Browser open failed. Preserve the URL so the caller can copy-paste.
-        pending.reject(
-          Object.assign(
-            markReason(new Error(`Could not open browser: ${err instanceof Error ? err.message : String(err)}`), "browser_open_failed"),
-            { authorizeUrl },
-          ),
-        )
       }
     })()
   })
-
-  return settled
 }
diff --git a/packages/opencode/src/altimate/workspace/state.ts b/packages/opencode/src/altimate/workspace/state.ts
index bcbf9cbe9..075f861c7 100644
--- a/packages/opencode/src/altimate/workspace/state.ts
+++ b/packages/opencode/src/altimate/workspace/state.ts
@@ -91,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)
@@ -139,23 +165,25 @@ 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
   const canon = canonicalizeKey(directory)
-  // First try the direct canonical + raw key lookups (cheap). If neither hits,
-  // scan every stored key and re-canonicalize it — catches entries written by
-  // earlier CLI builds under an unresolved key (e.g. ``/tmp/foo``) even though
-  // the caller looks them back up under the resolved key (``/private/tmp/foo``).
-  const direct = cache.bindings[canon] ?? cache.bindings[directory]
+  const direct = cache.bindings[canon]
   if (direct) return direct
-  for (const [k, v] of Object.entries(cache.bindings)) {
-    if (canonicalizeKey(k) === canon) return v
+  // 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
 }
diff --git a/packages/opencode/src/cli/cmd/link.ts b/packages/opencode/src/cli/cmd/link.ts
index 897a4426b..17b861dad 100644
--- a/packages/opencode/src/cli/cmd/link.ts
+++ b/packages/opencode/src/cli/cmd/link.ts
@@ -209,6 +209,28 @@ async function runBrowserHandoff(
     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...")
diff --git a/packages/opencode/src/plugin/tui/altimate/workspace-sidebar.tsx b/packages/opencode/src/plugin/tui/altimate/workspace-sidebar.tsx
index 712b8d54d..da6fdddb3 100644
--- a/packages/opencode/src/plugin/tui/altimate/workspace-sidebar.tsx
+++ b/packages/opencode/src/plugin/tui/altimate/workspace-sidebar.tsx
@@ -2,8 +2,7 @@
 // Right-pane sidebar tile that shows the workspace the current project
 // directory is bound to (or "Not linked" with a hint). Reads from the local
 // binding cache written by `../workspace.tsx` (post-scan dialog, on-demand
-// picker, browser handoff). Cache is polled every 3s so a fresh bind
-// surfaces without the user having to reload the TUI.
+// picker, browser handoff).
 //
 // Deliberately read-only. All bind mutations live in workspace.tsx / link.ts;
 // this tile just reflects state.
@@ -16,33 +15,69 @@ import { AltimateApi } from "@/altimate/api/client"
 
 const id = "altimate:sidebar-workspace"
 
-const POLL_MS = 3000
+/** Cache-file poll cadence. Longer than a "reactive" ideal but the cheapest
+ * option that does not require plumbing an event bus through the binding
+ * writers. Trade-off documented (m1 in the consensus review): a fresh bind
+ * surfaces within one interval instead of instantly; a mostly-idle CLI reads
+ * the small cache file twice per minute. In-flight guard below prevents
+ * overlap when the file grows / the disk is slow. */
+const POLL_MS = 30_000
+
+/** Cached credential lookup — the API is a network round-trip candidate in
+ * the general case, but the credentials source here (local file) rarely
+ * changes within a single CLI process. We memoize the resolved manage-URL
+ * base per (apiUrl, tenant) pair for the life of the process; if the file
+ * changes mid-session, the binding cache invalidation (in state.ts) still
+ * catches it via its own (tenant, apiUrl) top-level scoping. */
+let cachedManageBase: { apiUrl: string; tenant: string; base: string | null } | null = null
+async function resolveManageBase(): Promise<string | null> {
+  try {
+    const creds = await AltimateApi.getCredentials()
+    if (
+      cachedManageBase &&
+      cachedManageBase.apiUrl === creds.altimateUrl &&
+      cachedManageBase.tenant === creds.altimateInstanceName
+    ) {
+      return cachedManageBase.base
+    }
+    const url = resolveWorkspaceWebUrl(creds.altimateUrl, creds.altimateInstanceName)
+    const base = url ? url.toString().replace(/\/$/, "") : null
+    cachedManageBase = { apiUrl: creds.altimateUrl, tenant: creds.altimateInstanceName, base }
+    return base
+  } catch {
+    return null
+  }
+}
 
 function View(props: { api: TuiPluginApi }) {
   const theme = () => props.api.theme.current
   const [binding, setBinding] = createSignal<CachedBinding | null>(null)
   const [manageUrl, setManageUrl] = createSignal<string | null>(null)
 
+  let refreshInFlight = false
   const refresh = async () => {
-    const dir = props.api.state.path.directory
-    const b = await readLocalBinding(dir).catch(() => null)
-    setBinding(b)
-    if (!b) {
-      setManageUrl(null)
-      return
-    }
+    if (refreshInFlight) return
+    refreshInFlight = true
     try {
-      const creds = await AltimateApi.getCredentials()
-      const base = resolveWorkspaceWebUrl(creds.altimateUrl, creds.altimateInstanceName)
-      setManageUrl(base ? `${base.toString().replace(/\/$/, "")}/w/${b.datamateId}` : null)
-    } catch {
-      setManageUrl(null)
+      const dir = props.api.state.path.directory
+      const b = await readLocalBinding(dir).catch(() => null)
+      setBinding(b)
+      if (!b) {
+        setManageUrl(null)
+        return
+      }
+      const base = await resolveManageBase()
+      setManageUrl(base ? `${base}/w/${b.datamateId}` : null)
+    } finally {
+      refreshInFlight = false
     }
   }
 
   onMount(() => {
     void refresh()
     const timer = setInterval(() => void refresh(), POLL_MS)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ;(timer as any)?.unref?.()
     onCleanup(() => clearInterval(timer))
   })
 
@@ -55,7 +90,7 @@ function View(props: { api: TuiPluginApi }) {
         when={binding()}
         fallback={
           <text fg={theme().textMuted}>
-            Not linked — run <b>/link</b>
+            Not linked — run <b>altimate-code link</b>
           </text>
         }
       >
diff --git a/packages/opencode/src/plugin/tui/altimate/workspace.tsx b/packages/opencode/src/plugin/tui/altimate/workspace.tsx
index 2d980bd10..3766598ef 100644
--- a/packages/opencode/src/plugin/tui/altimate/workspace.tsx
+++ b/packages/opencode/src/plugin/tui/altimate/workspace.tsx
@@ -334,8 +334,36 @@ async function runBrowserHandoff(
     toastHandoffFailure(api, result)
     return
   }
-  // Handoff succeeded — bind the project to the returned workspace via the
-  // existing bind endpoint. Same code path as PickerDialog's attach mode.
+  // M6 in the consensus review: the browser window can stay open for up to
+  // 15 minutes. If the user signs out or switches tenant mid-flow, the
+  // WorkspaceApi client re-reads credentials on every call — so a callback
+  // validated for tenant A would then bind under tenant B, and workspace
+  // ids are tenant-schema-local (same integer, different workspace). Compare
+  // the credential fingerprint the handoff was validated against with the
+  // credentials we're about to bind under, and refuse if either drifted.
+  try {
+    const fresh = await AltimateApi.getCredentials()
+    if (
+      fresh.altimateInstanceName !== result.credentials.tenant ||
+      fresh.altimateUrl !== result.credentials.apiUrl
+    ) {
+      api.ui.toast({
+        variant: "error",
+        message: `Your Altimate credentials changed while the browser was open (was ${result.credentials.tenant}, now ${fresh.altimateInstanceName}). Re-run to link this project.`,
+        duration: 15_000,
+      })
+      return
+    }
+  } catch {
+    api.ui.toast({
+      variant: "error",
+      message: "Lost Altimate credentials while the browser was open — sign in and re-run.",
+    })
+    return
+  }
+  // Handoff succeeded and credentials are still consistent — bind the project
+  // to the returned workspace via the existing bind endpoint. Same code path
+  // as PickerDialog's attach mode.
   try {
     const res = await WorkspaceApi.bindExisting(result.workspaceId, identifier)
     await recordApprovedBinding(api.state.path.directory, {
diff --git a/packages/opencode/test/altimate/workspace/browser-handoff.test.ts b/packages/opencode/test/altimate/workspace/browser-handoff.test.ts
index 386e89b58..a889d5744 100644
--- a/packages/opencode/test/altimate/workspace/browser-handoff.test.ts
+++ b/packages/opencode/test/altimate/workspace/browser-handoff.test.ts
@@ -204,7 +204,11 @@ describe("runHandoffWithOpener end-to-end", () => {
     }
   })
 
-  test("URL includes project_remote + project_path + project_name from input", async () => {
+  test("URL includes project_name in query and project_remote/project_path in fragment", async () => {
+    // Per m6 in the consensus review: project_path + project_remote MUST NOT
+    // be sent as query params (they'd land in browser history, SaaS/CDN/WAF
+    // access logs, and REST-log aggregators). Move them to the URL fragment
+    // instead — same reason cli_context lives in the fragment.
     let observed = ""
     await runHandoffWithOpener(
       {
@@ -219,9 +223,16 @@ describe("runHandoffWithOpener end-to-end", () => {
       },
     )
     const u = new URL(observed)
-    expect(u.searchParams.get("project_remote")).toBe("git@github.com:acme/foo.git")
-    expect(u.searchParams.get("project_path")).toBe("/w/foo")
+    // project_name is a display-safe label — the SaaS approval screen
+    // renders it in the modal — so it stays in the query.
     expect(u.searchParams.get("project_name")).toBe("foo")
+    // project_remote + project_path MUST NOT be in the query.
+    expect(u.searchParams.get("project_remote")).toBeNull()
+    expect(u.searchParams.get("project_path")).toBeNull()
+    // They live in the fragment instead.
+    const frag = new URLSearchParams(u.hash.replace(/^#/, ""))
+    expect(frag.get("project_remote")).toBe("git@github.com:acme/foo.git")
+    expect(frag.get("project_path")).toBe("/w/foo")
     expect(u.pathname).toBe("/create-and-link")
   })
 })

From b05f707897f66d1121e6d6b4ab9888e19941b9f5 Mon Sep 17 00:00:00 2001
From: Haider <haider@altimate.ai>
Date: Mon, 17 Aug 2026 10:45:23 +0530
Subject: [PATCH 4/7] =?UTF-8?q?fix(workspace):=20bot-review=20round=205=20?=
 =?UTF-8?q?=E2=80=94=20no=20browser-handoff=20for=20already-linked=20proje?=
 =?UTF-8?q?ct,=20tighter=20workspace=5Fid=20spelling?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two #1100-only cycle-5 findings:

- **link.ts SET_UP_IN_BROWSER_SENTINEL** (CodeRabbit Major) — the browser
  handoff option was offered even when the project was already linked;
  ``runBrowserHandoff`` then created a fresh workspace and 409'd on
  ``bindExisting``, stranding the workspace. Gate the option on ``!existing``
  alongside ``browserAvailable``.
- **browser-handoff.ts workspace_id** (cubic P3) — ``Number()`` coerces
  ``"1e2"``, ``"0x2a"``, and ``"  42 "`` into finite integers, slipping past
  the ``isInteger`` guard. Require a plain decimal-digit spelling first.

Test suite green (4072 pass across the altimate suite).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016H42Vt4pt5dcD7opRqckeM
---
 .../src/altimate/workspace/browser-handoff.ts       | 13 ++++++++++++-
 packages/opencode/src/cli/cmd/link.ts               |  8 +++++++-
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/packages/opencode/src/altimate/workspace/browser-handoff.ts b/packages/opencode/src/altimate/workspace/browser-handoff.ts
index a6cadfb0b..b87ef133b 100644
--- a/packages/opencode/src/altimate/workspace/browser-handoff.ts
+++ b/packages/opencode/src/altimate/workspace/browser-handoff.ts
@@ -256,9 +256,20 @@ async function startListener(pending: HandoffPending): Promise<{ server: Server;
       return
     }
 
-    const workspaceId = Number(workspaceIdRaw)
     // Integer-only: floats like ``42.5`` are rejected server-side but produce
     // a confusing failure the caller can't recover from. (m9 in the review.)
+    // Also reject non-canonical spellings — ``Number()`` happily coerces
+    // ``"1e2"``, ``"0x2a"``, and ``"  42 "`` into finite integers, so a
+    // callback URL carrying those forms would slip past ``isInteger`` and
+    // reach the bind payload. Requiring a plain decimal-digit string first
+    // is the tight gate. (cubic cycle 4/5.)
+    if (!/^[1-9][0-9]*$/.test(workspaceIdRaw)) {
+      const msg = `Invalid workspace_id: ${workspaceIdRaw}`
+      respond(400, htmlError(msg))
+      pending.reject(markReason(new Error(msg), "error"))
+      return
+    }
+    const workspaceId = Number(workspaceIdRaw)
     if (!Number.isInteger(workspaceId) || workspaceId <= 0) {
       const msg = `Invalid workspace_id: ${workspaceIdRaw}`
       respond(400, htmlError(msg))
diff --git a/packages/opencode/src/cli/cmd/link.ts b/packages/opencode/src/cli/cmd/link.ts
index 17b861dad..5579ba7ed 100644
--- a/packages/opencode/src/cli/cmd/link.ts
+++ b/packages/opencode/src/cli/cmd/link.ts
@@ -132,7 +132,13 @@ export const LinkCommand = cmd({
       resolveWorkspaceWebUrl(creds.altimateUrl, creds.altimateInstanceName) !== null
 
     const options: Array<{ value: string; label: string; hint?: string }> = [
-      ...(browserAvailable
+      // 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.
+      ...(browserAvailable && !existing
         ? [
             {
               value: SET_UP_IN_BROWSER_SENTINEL,

From cea9c3c3c6fe4a6699b2dd434505a1c0e43cedc1 Mon Sep 17 00:00:00 2001
From: Haider <haider@altimate.ai>
Date: Mon, 17 Aug 2026 12:08:29 +0530
Subject: [PATCH 5/7] =?UTF-8?q?fix(workspace):=20bot-review=20round=206=20?=
 =?UTF-8?q?=E2=80=94=20isBrowserHandoffAvailable=20guard,=20gate=20on=20pr?=
 =?UTF-8?q?eCheckOk,=20keep=20err=20diagnostic?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three #1100-only cycle-6 findings:

- **``isBrowserHandoffAvailable`` guarded** (CR Major) — line 63 wrapped
  ``isConfigured()`` with ``.catch(() => false)`` but ``getCredentials()``
  on line 64 was unguarded. That call can throw on corrupt credentials JSON,
  Zod schema drift, or an unresolved ``${env:...}`` reference; an unhandled
  rejection there would take the TUI down. Wrap the whole body in try/catch
  and fail closed (treat as "handoff unavailable").
- **``link.ts`` browser option also gated on ``preCheckOk``** (Kilo suggestion)
  — was ``browserAvailable && !existing``. When the pre-check itself failed
  (network / 5xx), ``existing`` stays null while the project MAY be linked
  server-side. Offering the browser flow then reproduces the "workspace
  created + 409 on bindExisting" strand. Add ``&& preCheckOk``.
- **``void err`` no-op replaced with log** (Kilo suggestion) — the previous
  ``catch (err) { ... void err }`` discarded the diagnostic. Log-warn so a
  regression in ``showLinkedConfirmation`` doesn't vanish silently.

Test suite: green (4072 pass, 0 fail).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016H42Vt4pt5dcD7opRqckeM
---
 packages/opencode/src/cli/cmd/link.ts         |  8 +++++++-
 .../src/plugin/tui/altimate/workspace.tsx     | 19 +++++++++++++++----
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/packages/opencode/src/cli/cmd/link.ts b/packages/opencode/src/cli/cmd/link.ts
index 5579ba7ed..0da0543de 100644
--- a/packages/opencode/src/cli/cmd/link.ts
+++ b/packages/opencode/src/cli/cmd/link.ts
@@ -138,7 +138,13 @@ export const LinkCommand = cmd({
       // 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.
-      ...(browserAvailable && !existing
+      //
+      // 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,
diff --git a/packages/opencode/src/plugin/tui/altimate/workspace.tsx b/packages/opencode/src/plugin/tui/altimate/workspace.tsx
index 3766598ef..a59293bcf 100644
--- a/packages/opencode/src/plugin/tui/altimate/workspace.tsx
+++ b/packages/opencode/src/plugin/tui/altimate/workspace.tsx
@@ -60,9 +60,17 @@ const log = Log.create({ service: "altimate-workspace" })
  * flow and the on-demand `altimate-code link` picker can hide the option
  * consistently when the deployment isn't supported. */
 async function isBrowserHandoffAvailable(): Promise<boolean> {
-  if (!(await AltimateApi.isConfigured().catch(() => false))) return false
-  const creds = await AltimateApi.getCredentials()
-  return resolveWorkspaceWebUrl(creds.altimateUrl, creds.altimateInstanceName) !== null
+  // Both credential calls can throw (corrupt JSON, schema drift, unresolved
+  // ``${env:...}`` reference). Callers use this in the sync arm of dialog
+  // rendering, so an unhandled rejection would take the TUI down. Fail
+  // closed — treat any credential error as "handoff unavailable". (CR cycle 6.)
+  try {
+    if (!(await AltimateApi.isConfigured().catch(() => false))) return false
+    const creds = await AltimateApi.getCredentials()
+    return resolveWorkspaceWebUrl(creds.altimateUrl, creds.altimateInstanceName) !== null
+  } catch {
+    return false
+  }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -523,11 +531,14 @@ async function createAndBindInline(
     })
     await showLinkedConfirmation(api, "Created", res.datamate.id, res.datamate.name)
   } catch (err) {
+    // Log the failure so a regression in ``showLinkedConfirmation`` doesn't
+    // vanish silently, then fall back to a plain toast. Previously ``void err``
+    // discarded the diagnostic — Kilo cycle 6 called it out.
+    log.warn("workspace post-create confirmation failed", { err: String(err) })
     api.ui.toast({
       variant: "info",
       message: `Workspace "${res.datamate.name}" created and linked.`,
     })
-    void err
   }
 }
 

From 115bc174c62bfd2f578257df0ff063dbc99f1087 Mon Sep 17 00:00:00 2001
From: Haider <haider@altimate.ai>
Date: Tue, 18 Aug 2026 21:01:34 +0530
Subject: [PATCH 6/7] =?UTF-8?q?fix(workspace):=20bot-review=20round=207=20?=
 =?UTF-8?q?=E2=80=94=20post-listen=20error=20handler=20+=20pending-abort?=
 =?UTF-8?q?=20race?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two focused fixes on browser-handoff.ts. Both verified against the
current tip after rebase onto the updated #1099 branch. Full altimate
suite (4072 tests) passes.

- **Persistent post-listen server error handler.** ``startListener``
  attached an ``onErr`` handler only for the ``server.listen()``
  port-walk (via ``once("error", …)``, removed on the ``listen``
  callback). After a successful bind the server had NO error handler
  for the ~15-minute wait window, so any post-listen socket-level
  ``error`` event (spurious ECONNRESET, client-abort mid-request,
  transient EMFILE) reached the process as an unhandled exception and
  terminated the CLI. Attach a persistent log-and-continue handler
  right before returning ``{server, port}`` — the listener is per-flow
  and there is nothing useful to do with a transient socket error but
  keep serving until the caller resolves or the timeout fires.
  (CodeRabbit cycle 6.)

- **Listener leak when the flow settles during ``await
  startListener(pending)``.** ``closeListener`` closes
  ``listenerHandle.server`` only when the handle is non-nullish, and
  ``listenerHandle`` is assigned AFTER ``await startListener(...)``
  returns. If the flow rejects during that window (timeout raced with
  the port walk, ``AbortSignal`` fired, or the lazy ``buildCliContext
  import()`` threw), ``closeListener`` ran with a still-undefined
  handle — a no-op — and the awaited startListener eventually returned
  a bound server that stayed open for the full 15-minute timeout.
  Introduce a ``settled`` flag flipped by ``pending.resolve`` /
  ``pending.reject``; check it immediately after
  ``listenerHandle = await startListener(pending)`` and close the
  server if the flow already settled. (cubic cycle 5.)

Other #1100-tagged findings verified as fixed at tip in earlier rounds
(preCheckOk gate, isBrowserHandoffAvailable cred guard, Number()
coercion tightening, .git/ trailing strip, SSH ``git@host:path``
credential no-op, writeCache best-effort try/catch) and are not
re-touched here.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016H42Vt4pt5dcD7opRqckeM
---
 .../src/altimate/workspace/browser-handoff.ts | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/packages/opencode/src/altimate/workspace/browser-handoff.ts b/packages/opencode/src/altimate/workspace/browser-handoff.ts
index b87ef133b..b58b45ead 100644
--- a/packages/opencode/src/altimate/workspace/browser-handoff.ts
+++ b/packages/opencode/src/altimate/workspace/browser-handoff.ts
@@ -308,6 +308,18 @@ async function startListener(pending: HandoffPending): Promise<{ server: Server;
           resolve()
         })
       })
+      // Post-listen persistent error handler. Without this, any socket-level
+      // ``error`` event during the ~15-minute wait (spurious ECONNRESET,
+      // client abort mid-request, an OS EMFILE spike) is unhandled and takes
+      // the process down. We can't do anything useful with the error — the
+      // listener is per-flow and short-lived — so log-and-continue is the
+      // right call. (CodeRabbit cycle 6.)
+      server.on("error", (err: NodeJS.ErrnoException) => {
+        log.warn("handoff loopback listener emitted a post-listen error", {
+          code: err.code,
+          err: err.message,
+        })
+      })
       return { server, port }
     } catch (err) {
       lastErr = err as NodeJS.ErrnoException
@@ -386,6 +398,13 @@ export async function runHandoffWithOpener(
   // Register pending, then bind the listener. Timeout owns rejection with
   // reason "timeout"; the listener's own reject paths mark their own reasons.
   let listenerHandle: { server: Server; port: number } | undefined
+  // ``settled`` reflects whether ``pending.resolve``/``pending.reject`` has
+  // fired. Needed to close the server if the flow rejects (timeout / abort /
+  // browser-open failure) DURING the ``await startListener(pending)`` window
+  // — otherwise ``closeListener`` runs while ``listenerHandle`` is still
+  // undefined, then the awaited startListener returns a server that never
+  // gets closed and stays bound for the full 15-min timeout. (cubic cycle 5.)
+  let settled = false
   const closeListener = () => {
     if (listenerHandle) {
       try {
@@ -404,6 +423,7 @@ export async function runHandoffWithOpener(
       expectedTenant: creds.altimateInstanceName,
       workspaceWebBase: webUrl,
       resolve: (v) => {
+        settled = true
         closeListener()
         clearTimeout(timeoutHandle)
         if (onAbort && input.signal) input.signal.removeEventListener("abort", onAbort)
@@ -413,6 +433,7 @@ export async function runHandoffWithOpener(
         resolve({ ...v, credentials: { apiUrl: creds.altimateUrl, tenant: v.tenant } })
       },
       reject: (err) => {
+        settled = true
         closeListener()
         clearTimeout(timeoutHandle)
         if (onAbort && input.signal) input.signal.removeEventListener("abort", onAbort)
@@ -448,6 +469,15 @@ export async function runHandoffWithOpener(
     ;(async () => {
       try {
         listenerHandle = await startListener(pending)
+        // If the flow already settled during the ``await`` above (timeout
+        // fired, abort fired, browser-open failed), ``closeListener`` ran
+        // with ``listenerHandle`` still undefined — nothing was closed. Now
+        // that we own a real handle, close it and bail so it doesn't sit
+        // bound for the full timeout. (cubic cycle 5.)
+        if (settled) {
+          closeListener()
+          return
+        }
         // Capture the port to a local IMMEDIATELY — ``listenerHandle`` is
         // cleared by ``closeListener`` on timeout, and a lazy ``import()``
         // below can straddle that clear. (M4 sub-case)

From 7af007c16827ef1eb6b437c84441c094ac1ceb42 Mon Sep 17 00:00:00 2001
From: Haider <haider@altimate.ai>
Date: Thu, 20 Aug 2026 00:52:00 +0530
Subject: [PATCH 7/7] feat(workspace-sidebar): show "(pinned via --workspace)"
 when session was launched with the flag
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The `--workspace <name>` launch flag (AI-8504 item 1, landed on #1099
as b193a5c6b9) sets `ALTIMATE_RESOLVED_WORKSPACE_ID` for the worker
subprocess to read. The sidebar tile already shows the correct
workspace name because launch-time resolution is same-directory-only
and always matches the on-disk binding — so the ID from
`getResolvedWorkspaceId()` == `binding.datamateId` whenever the flag
took effect. Surface that as a small visual confirmation so the user
knows the flag was recognized rather than silently ignored.

Renders as `<workspace-name> (pinned via --workspace)` when the ID
matches, else just `<workspace-name>` (behaviour unchanged for
default launches).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016H42Vt4pt5dcD7opRqckeM
---
 .../src/plugin/tui/altimate/workspace-sidebar.tsx         | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/opencode/src/plugin/tui/altimate/workspace-sidebar.tsx b/packages/opencode/src/plugin/tui/altimate/workspace-sidebar.tsx
index da6fdddb3..ace3e089a 100644
--- a/packages/opencode/src/plugin/tui/altimate/workspace-sidebar.tsx
+++ b/packages/opencode/src/plugin/tui/altimate/workspace-sidebar.tsx
@@ -11,6 +11,7 @@ import type { BuiltinTuiPlugin } from "@opencode-ai/tui/builtins"
 import { createSignal, onCleanup, onMount, Show } from "solid-js"
 import { readLocalBinding, type CachedBinding } from "@/altimate/workspace/state"
 import { resolveWorkspaceWebUrl } from "@/altimate/workspace/browser-handoff"
+import { getResolvedWorkspaceId } from "@/altimate/workspace/session-context"
 import { AltimateApi } from "@/altimate/api/client"
 
 const id = "altimate:sidebar-workspace"
@@ -96,7 +97,12 @@ function View(props: { api: TuiPluginApi }) {
       >
         {(b) => (
           <>
-            <text fg={theme().textMuted}>{b().datamateName}</text>
+            <text fg={theme().textMuted}>
+              {b().datamateName}
+              <Show when={getResolvedWorkspaceId() === b().datamateId}>
+                {" (pinned via --workspace)"}
+              </Show>
+            </text>
             <Show when={manageUrl()}>
               {(u) => <text fg={theme().textMuted}>{u()}</text>}
             </Show>