@@ -16,11 +16,53 @@ import * as OnboardingTelemetry from "../telemetry/onboarding"
 // EventV2 bridge the server/routes/tui.ts uses to publish TuiEvent.CommandExecute
 // so the workspace TuiPlugin (packages/opencode/src/plugin/tui/altimate/workspace.tsx)
 // runs its post-scan flow. Feature-flagged via Flag.ALTIMATE_WORKSPACE.
+import { Effect } from "effect"
 import { Flag } from "@opencode-ai/core/flag/flag"
 import { AltimateApi } from "@/altimate/api/client"
 import { AppRuntime } from "@/effect/app-runtime"
 import { EventV2Bridge } from "@/event-v2-bridge"
 import { TuiEvent } from "@/server/tui-event"
+import { Event as SessionEvent } from "@/session/status"
+
+/**
+ * Publish the workspace-postScan command AFTER the session goes idle, not on
+ * `project_scan`'s tool.execute.after. Rationale: project_scan tool RETURNS while
+ * the LLM is still generating the activation-menu text; the dialog paints in
+ * that window but user interactions queue behind the streaming. Waiting for
+ * session.idle costs a few seconds of latency but sidesteps the race entirely —
+ * the dialog appears once things are quiet.
+ *
+ * One-shot per sessionID: the listener unregisters as soon as the target
+ * session emits idle. A pending arm is dropped if a second project_scan fires
+ * in the same session (unlikely but handled).
+ */
+const pendingWorkspacePromptSessions = new Set<string>()
+let workspacePromptListenerArmed = false
+
+async function armWorkspacePromptOnSessionIdle(sessionID: string): Promise<void> {
+  pendingWorkspacePromptSessions.add(sessionID)
+  if (workspacePromptListenerArmed) return
+  workspacePromptListenerArmed = true
+  await AppRuntime.runPromise(
+    EventV2Bridge.Service.use((events) =>
+      events.listen((event) =>
+        Effect.gen(function* () {
+          if (event.type !== SessionEvent.Idle.type) return
+          const sid = (event.data as { sessionID?: string } | undefined)?.sessionID
+          if (!sid || !pendingWorkspacePromptSessions.has(sid)) return
+          pendingWorkspacePromptSessions.delete(sid)
+          yield* events.publish(TuiEvent.CommandExecute, {
+            command: "altimate.workspace.postScan",
+          })
+        }),
+      ),
+    ),
+  ).catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error("[altimate-workspace] session-idle listener install failed:", err)
+    workspacePromptListenerArmed = false
+  })
+}
 // altimate_change end
 
 const ONBOARD_CONNECT = "onboard-connect"
@@ -145,25 +187,11 @@ export async function OnboardingTelemetryPlugin(_input: PluginInput): Promise<Ho
           input.sessionID,
         )
         // altimate_change start — AI-8398 workspaces post-scan prompt trigger.
-        // Fires the TUI plugin's altimate.workspace.postScan command once the scan
-        // completes AND the CLI has real Altimate credentials (BYOK users skip this
-        // path entirely — no place to send them). All the state (Skip latch, cache,
-        // server pre-check) is plugin-side so the trigger stays a fire-and-forget
-        // signal here; a retry would just re-enter the plugin's idempotent runFlow.
+        // ARM (don't publish yet) — the dialog fires when the session goes idle,
+        // not the moment project_scan returns. See armWorkspacePromptOnSessionIdle
+        // above for why the immediate publish raced the LLM's ongoing streaming.
         if (Flag.ALTIMATE_WORKSPACE && (await AltimateApi.isConfigured().catch(() => false))) {
-          void AppRuntime.runPromise(
-            EventV2Bridge.Service.use((events) =>
-              events.publish(TuiEvent.CommandExecute, {
-                command: "altimate.workspace.postScan",
-              }),
-            ),
-          ).catch((err) => {
-            // Never block onboarding on a publish failure — worst case the
-            // user picks up the workspace on their next launch or via the
-            // /altimate.workspace.link palette command.
-            // eslint-disable-next-line no-console
-            console.error("[altimate-workspace] postScan trigger failed:", err)
-          })
+          void armWorkspacePromptOnSessionIdle(input.sessionID)
         }
         // altimate_change end
         return
 
@@ -23,10 +23,20 @@ export interface Binding {
   id: number
   datamate_id: number
   datamate_name: string
-  repo_remote: string
+  /** Either ``repo_remote`` OR ``project_path`` is populated (at least one). */
+  repo_remote: string | null
+  project_path: string | null
   created_at?: string
 }
 
+/** Project identifier passed to create/bind endpoints. At least one field is
+ * required by the backend's CHECK constraint; the CLI's resolveProjectIdentifier
+ * always populates ``projectPath`` and populates ``repoRemote`` when available. */
+export interface ProjectIdentifier {
+  repoRemote?: string
+  projectPath?: string
+}
+
 export interface CreateAndBindResponse {
   datamate: DatamateRef
   binding: Binding
@@ -47,6 +57,7 @@ export interface ConflictDetail {
   existing_datamate_id?: number
   existing_datamate_name?: string | null
   repo_remote?: string
+  project_path?: string
 }
 
 export interface PreconditionDetail {
@@ -170,7 +181,7 @@ async function req<T>(
 }
 
 export namespace WorkspaceApi {
-  /** Server-authoritative pre-check: is this remote already bound in this tenant? */
+  /** Server-authoritative pre-check by git remote. Returns null on 404. */
   export async function getBindingForRemote(remote: string): Promise<GetBindingResponse | null> {
     try {
       return await req<GetBindingResponse>("GET", "/by-remote", { query: { repo_remote: remote } })
@@ -180,23 +191,56 @@ export namespace WorkspaceApi {
     }
   }
 
+  /** Symmetric pre-check by absolute project directory path (for projects
+   * without a git remote). Returns null on 404. */
+  export async function getBindingForPath(projectPath: string): Promise<GetBindingResponse | null> {
+    try {
+      return await req<GetBindingResponse>("GET", "/by-path", { query: { project_path: projectPath } })
+    } catch (err) {
+      if (err instanceof NotFoundError) return null
+      throw err
+    }
+  }
+
+  /** Tries remote first (stronger identity), then path. Returns the first hit
+   * or null. Both fields on the identifier are optional but at least one must
+   * be present. */
+  export async function getBindingForProject(id: ProjectIdentifier): Promise<GetBindingResponse | null> {
+    if (id.repoRemote) {
+      const hit = await getBindingForRemote(id.repoRemote)
+      if (hit) return hit
+    }
+    if (id.projectPath) {
+      return await getBindingForPath(id.projectPath)
+    }
+    return null
+  }
+
   export async function createAndBind(input: {
     name: string
-    repoRemote: string
+    identifier: ProjectIdentifier
     description?: string
   }): Promise<CreateAndBindResponse> {
     return req<CreateAndBindResponse>("POST", "/", {
       body: {
         name: input.name,
-        repo_remote: input.repoRemote,
+        repo_remote: input.identifier.repoRemote ?? null,
+        project_path: input.identifier.projectPath ?? null,
         description: input.description ?? null,
       },
     })
   }
 
-  export async function bindExisting(datamateId: number, remote: string): Promise<BindingResponse> {
+  export async function bindExisting(
+    datamateId: number,
+    identifier: ProjectIdentifier,
+  ): Promise<BindingResponse> {
     return req<BindingResponse>("POST", "/bind", {
-      body: { datamate_id: datamateId, repo_remote: remote },
+      body: {
+        datamate_id: datamateId,
+        repo_remote: identifier.repoRemote ?? null,
+        project_path: identifier.projectPath ?? null,
+      },
     })
   }
 
@@ -216,6 +260,24 @@ export namespace WorkspaceApi {
     })
   }
 
+  /** Path-identified rebind — symmetric to ``rebindByRemote`` for projects
+   * without a git remote. */
+  export async function rebindByPath(input: {
+    projectPath: string
+    targetDatamateId: number
+    expectedCurrentDatamateId?: number
+  }): Promise<BindingResponse> {
+    return req<BindingResponse>("PUT", "/by-path", {
+      body: {
+        project_path: input.projectPath,
+        target_datamate_id: input.targetDatamateId,
+        ...(input.expectedCurrentDatamateId !== undefined
+          ? { expected_current_datamate_id: input.expectedCurrentDatamateId }
+          : {}),
+      },
+    })
+  }
+
   /** Populates the "link to existing workspace" picker. Reuses the existing
    * /datamates/ list endpoint on the datamates_router. */
   export async function listDatamates(): Promise<DatamateRef[]> {
 
@@ -8,6 +8,8 @@
 // basic-auth (e.g. `https://x-access-token:ghp_xxx@github.com/...`) never
 // reaches the server or the local cache in clear.
 import { spawnSync } from "node:child_process"
+import { realpathSync } from "node:fs"
+import path from "node:path"
 import { stripGitRemoteCredentials } from "../tools/project-scan"
 
 export function detectProjectRemote(directory: string): string | undefined {
@@ -24,6 +26,30 @@ export function detectProjectRemote(directory: string): string | undefined {
   }
 }
 
+/** Project identity for the binding system. Prefers ``repo_remote`` when the
+ * project has a git remote (stronger identity — survives directory moves); falls
+ * back to ``project_path`` (absolute, symlink-resolved directory path) for
+ * projects without one (materialized sample scaffolds, fresh scratch dirs).
+ *
+ * Both fields can be populated simultaneously; callers pick which to use for
+ * lookup or send both to create/bind (server uses whichever it needs for its
+ * partial unique index). At least one field is always populated — falling back
+ * to the raw ``directory`` argument keeps the "no remote AND unresolvable path"
+ * degenerate case from returning empty. */
+export function resolveProjectIdentifier(directory: string): {
+  repoRemote?: string
+  projectPath: string
+} {
+  const repoRemote = detectProjectRemote(directory)
+  let projectPath: string
+  try {
+    projectPath = realpathSync(path.resolve(directory))
+  } catch {
+    projectPath = path.resolve(directory)
+  }
+  return repoRemote ? { repoRemote, projectPath } : { projectPath }
+}
+
 /** Sensible default workspace name from a remote URL — best-effort. Used to
  * prefill the workspace-name prompt in the CreateDialog and `altimate link`.
  * ``github.com/foo/bar.git`` → ``bar`` ; ``git@github.com:foo/bar.git`` → ``bar``. */
@@ -32,3 +58,10 @@ export function projectNameFromRemote(remote: string): string {
   const parts = trimmed.split(/[/:]/)
   return parts[parts.length - 1] || "workspace"
 }
+
+/** Fallback name source when the project has no git remote — uses the directory's
+ * basename (e.g. ``/Users/x/sample-dbt-project`` → ``sample-dbt-project``). */
+export function projectNameFromPath(projectPath: string): string {
+  const base = path.basename(projectPath.replace(/\/$/, ""))
+  return base || "workspace"
+}
@@ -24,7 +24,11 @@ const log = Log.create({ service: "altimate-workspace-state" })
 export interface CachedBinding {
   datamateId: number
   datamateName: string
-  repoRemote: string
+  /** Either ``repoRemote`` or ``projectPath`` is populated (at least one).
+   * Mirrors the server-side binding row, which is identified by whichever
+   * fields it has. */
+  repoRemote: string | null
+  projectPath: string | null
   linkedAt: number
 }