diff --git a/apps/affiliation-rating-resolver/src/App.svelte b/apps/affiliation-rating-resolver/src/App.svelte
index 10d0c6c..299c94f 100644
--- a/apps/affiliation-rating-resolver/src/App.svelte
+++ b/apps/affiliation-rating-resolver/src/App.svelte
@@ -8,7 +8,7 @@
   // context-v/specs/Augment-From-Affiliations.md.
 
   import { onMount } from 'svelte';
-  import { workspace, type RecordSet, type Row } from '@augment-it/workspace';
+  import { workspace, type RecordSet, type Row, resolveWsUrl } from '@augment-it/workspace';
   import ColumnMapper from './components/ColumnMapper.svelte';
   import { normalizeRatingRecord, guessMapping, MAPPING_NONE } from './lib/normalize';
   import {
@@ -23,7 +23,7 @@
   import type { RatingFieldMapping, RatingNormRecord, AffiliationDetail, Link, CorpusEntry } from './lib/types';
 
   const TOKEN_KEY = 'augment-it:session-token';
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
   const ACTIVE_RECORD_SET_KEY = 'augment-it:active-record-set';
   const MAPPING_KEY_PREFIX = 'augment-it:affiliation-rating-resolver:mapping:';
 
diff --git a/apps/chat/src/App.svelte b/apps/chat/src/App.svelte
index c5dbcd7..8e2bf1a 100644
--- a/apps/chat/src/App.svelte
+++ b/apps/chat/src/App.svelte
@@ -6,7 +6,7 @@
   // is established independently (no shared workspace singleton).
 
   import { onMount } from 'svelte';
-  import { workspace } from '@augment-it/workspace';
+  import { workspace, resolveWsUrl } from '@augment-it/workspace';
   import CharacterCastRow from './CharacterCastRow.svelte';
   import ChatSurface from './ChatSurface.svelte';
 
@@ -15,9 +15,7 @@
   // even when mounted inside the shell, so it needs the same env-configured
   // WS_URL the shell and corpora-curator each read (rsbuild inlines
   // PUBLIC_-prefixed vars into import.meta.env at build time).
-  const WS_URL =
-    ((import.meta as { env?: Record<string, string> }).env?.PUBLIC_WS_URL as string | undefined) ||
-    'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
 
   let connectionStatus = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
 
diff --git a/apps/corpora-curator/src/App.svelte b/apps/corpora-curator/src/App.svelte
index 70a5bee..f8afe8f 100644
--- a/apps/corpora-curator/src/App.svelte
+++ b/apps/corpora-curator/src/App.svelte
@@ -1,12 +1,12 @@
 <script lang="ts">
   import { onMount } from 'svelte';
-  import { workspace } from '@augment-it/workspace';
+  import { workspace, resolveWsUrl } from '@augment-it/workspace';
   import { curation } from './curation.svelte';
   import CorpusPicker from './CorpusPicker.svelte';
   import SourceList from './SourceList.svelte';
   import SourceDetail from './SourceDetail.svelte';
 
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
 
   onMount(() => {
     curation.init();
diff --git a/apps/corpora-curator/src/curation.svelte.ts b/apps/corpora-curator/src/curation.svelte.ts
index 2b85fc0..ba36be6 100644
--- a/apps/corpora-curator/src/curation.svelte.ts
+++ b/apps/corpora-curator/src/curation.svelte.ts
@@ -8,7 +8,7 @@
 // $state is assigned in the constructor (not as a class-field initializer) to
 // match the workspace package's placement-invariant note about field lowering.
 
-import { workspace, WORKSPACE_CHANGED_EVENT, type WorkspaceSummary } from '@augment-it/workspace';
+import { workspace, WORKSPACE_CHANGED_EVENT, type WorkspaceSummary, resolveWsUrl } from '@augment-it/workspace';
 import type { ExtractKind, Source, Strategy } from './types';
 
 const TOKEN_KEY = 'augment-it:session-token';
@@ -18,9 +18,7 @@ const TOKEN_KEY = 'augment-it:session-token';
 // shell and chat each read (rsbuild inlines PUBLIC_-prefixed vars into
 // import.meta.env at build time — applies to plain .ts modules too, not
 // just .svelte files).
-const WS_URL =
-  ((import.meta as { env?: Record<string, string> }).env?.PUBLIC_WS_URL as string | undefined) ||
-  'ws://localhost:3001/ws';
+const WS_URL = resolveWsUrl();
 // Stores "<type>:<slug>" since gh #88 — uniqueness is (type, slug), so a bare
 // slug can restore the wrong corpus once a workspace holds both. Bare slugs
 // from before #88 still resolve; see loadStrategies().
diff --git a/apps/enhanced-records-list/src/App.svelte b/apps/enhanced-records-list/src/App.svelte
index 0c9a85e..150739d 100644
--- a/apps/enhanced-records-list/src/App.svelte
+++ b/apps/enhanced-records-list/src/App.svelte
@@ -28,7 +28,6 @@
   onMount(() => {
     const TOKEN_KEY = 'augment_it_session_token';
     workspace.connect({
-      url: 'ws://localhost:3001/ws',
       getToken: () => localStorage.getItem(TOKEN_KEY),
       saveToken: (t) => localStorage.setItem(TOKEN_KEY, t),
       onStatus: (s) => {
diff --git a/apps/org-workbench/src/App.svelte b/apps/org-workbench/src/App.svelte
index 03f0389..b5d31ec 100644
--- a/apps/org-workbench/src/App.svelte
+++ b/apps/org-workbench/src/App.svelte
@@ -7,7 +7,7 @@
   // from person-db-resolver. See context-v/specs/Augment-From-DB-Flow.md.
 
   import { onMount } from 'svelte';
-  import { workspace } from '@augment-it/workspace';
+  import { workspace, resolveWsUrl } from '@augment-it/workspace';
   import OrgSearch from './OrgSearch.svelte';
   import OrgCard from './OrgCard.svelte';
   import OrgCreateInline from './OrgCreateInline.svelte';
@@ -17,7 +17,7 @@
   import type { OrgDetail, OrgSuggestion } from './lib/types';
 
   const TOKEN_KEY = 'augment-it:session-token';
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
   // Restore the last-worked org on remount (HMR, flow switch, tab reopen).
   const ACTIVE_ORG_KEY = 'augment-it:org-workbench:active-org';
   // Cross-remote focused-entity broadcast — the chat rail includes it in
diff --git a/apps/pack-runner/src/App.svelte b/apps/pack-runner/src/App.svelte
index 3a0afbd..e971b26 100644
--- a/apps/pack-runner/src/App.svelte
+++ b/apps/pack-runner/src/App.svelte
@@ -1,6 +1,6 @@
 <script lang="ts">
   import { onMount } from 'svelte';
-  import { workspace, type RecordSet, type Row } from '@augment-it/workspace';
+  import { workspace, type RecordSet, type Row, resolveWsUrl } from '@augment-it/workspace';
   import {
     BUNDLES, getBundle, packDisplayName, inferEntityNameField,
     PACK_PALETTE_META,
@@ -23,7 +23,7 @@
   let rowPackFired = $state<Record<string, Set<string>>>({});
 
   const TOKEN_KEY = 'augment-it:session-token';
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
 
   // Remember the user's last record-set + column picks so re-entry doesn't
   // require re-selecting everything. Keys keep the augment-it prefix per
diff --git a/apps/person-db-resolver/src/App.svelte b/apps/person-db-resolver/src/App.svelte
index 0693177..82eaa7c 100644
--- a/apps/person-db-resolver/src/App.svelte
+++ b/apps/person-db-resolver/src/App.svelte
@@ -7,7 +7,7 @@
   // context-v/plans/Person-Aware-Canonical-Resolver-Extension.md.
 
   import { onMount } from 'svelte';
-  import { workspace, type RecordSet, type Row } from '@augment-it/workspace';
+  import { workspace, type RecordSet, type Row, resolveWsUrl } from '@augment-it/workspace';
   import RecordCard from './components/RecordCard.svelte';
   import ColumnMapper from './components/ColumnMapper.svelte';
   import PersonCandidateList from './components/PersonCandidateList.svelte';
@@ -35,7 +35,7 @@
   } from './lib/types';
 
   const TOKEN_KEY = 'augment-it:session-token';
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
   const ACTIVE_RECORD_SET_KEY = 'augment-it:active-record-set';
   const MAPPING_KEY_PREFIX = 'augment-it:person-db-resolver:mapping:';
   // Per-record-set "where I left off" — restored on every selectRecordSet()
diff --git a/apps/prompt-template-manager/src/App.svelte b/apps/prompt-template-manager/src/App.svelte
index 01e3b50..31c15ee 100644
--- a/apps/prompt-template-manager/src/App.svelte
+++ b/apps/prompt-template-manager/src/App.svelte
@@ -1,9 +1,9 @@
 <script lang="ts">
   import { onMount } from 'svelte';
-  import { workspace, type PromptTemplate, type PromptTool } from '@augment-it/workspace';
+  import { workspace, type PromptTemplate, type PromptTool, resolveWsUrl } from '@augment-it/workspace';
 
   const TOKEN_KEY = 'augment-it:session-token';
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
   const TOKEN_RE = /\{\{\s*([^{}]+?)\s*\}\}/g;
 
   let status = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
diff --git a/apps/record-collector/src/App.svelte b/apps/record-collector/src/App.svelte
index 602b81c..36d25be 100644
--- a/apps/record-collector/src/App.svelte
+++ b/apps/record-collector/src/App.svelte
@@ -1,11 +1,11 @@
 <script lang="ts">
   import { onMount } from 'svelte';
-  import { workspace, type RecordSet, type Row } from '@augment-it/workspace';
+  import { workspace, type RecordSet, type Row, resolveWsUrl } from '@augment-it/workspace';
   import RecordSetsList from './components/RecordSetsList.svelte';
   import { formatFieldValue } from './logic/format';
 
   const TOKEN_KEY = 'augment-it:session-token';
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
 
   let status = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
   let selectedId = $state<string | null>(null);
diff --git a/apps/record-db-resolver/src/App.svelte b/apps/record-db-resolver/src/App.svelte
index d7497a8..bb1190d 100644
--- a/apps/record-db-resolver/src/App.svelte
+++ b/apps/record-db-resolver/src/App.svelte
@@ -10,7 +10,7 @@
   // context-v/specs/Record-DB-Resolver.md.
 
   import { onMount } from 'svelte';
-  import { workspace, type RecordSet, type Row } from '@augment-it/workspace';
+  import { workspace, type RecordSet, type Row, resolveWsUrl } from '@augment-it/workspace';
   import RecordCard from './components/RecordCard.svelte';
   import CandidateList from './components/CandidateList.svelte';
   import { normalizeRecord, buildCrm } from './lib/normalize';
@@ -18,7 +18,7 @@
   import type { Candidate, OrgSuggestion, ApplyResult } from './lib/types';
 
   const TOKEN_KEY = 'augment-it:session-token';
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
   const ACTIVE_RECORD_SET_KEY = 'augment-it:active-record-set';
 
   let status = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
diff --git a/apps/records-surface/src/App.svelte b/apps/records-surface/src/App.svelte
index 8cb3122..57c2348 100644
--- a/apps/records-surface/src/App.svelte
+++ b/apps/records-surface/src/App.svelte
@@ -1,11 +1,11 @@
 <script lang="ts">
   import { onMount } from 'svelte';
-  import { workspace } from '@augment-it/workspace';
+  import { workspace, resolveWsUrl } from '@augment-it/workspace';
   import RecordsList from './components/RecordsList.svelte';
   import { records } from './state/records.svelte';
 
   const TOKEN_KEY = 'augment-it:session-token';
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
 
   let status = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
 
diff --git a/apps/request-reviewer/src/App.svelte b/apps/request-reviewer/src/App.svelte
index e9ed90e..06735d8 100644
--- a/apps/request-reviewer/src/App.svelte
+++ b/apps/request-reviewer/src/App.svelte
@@ -9,13 +9,12 @@
     type RecordSet,
     type Row,
     type PreviewResult,
-    type Coverage,
-  } from '@augment-it/workspace';
+    type Coverage, resolveWsUrl } from '@augment-it/workspace';
 
   // Each remote owns its own workspace singleton + WebSocket — no `shared`
   // federation block (see the 2026-05-21_03 changelog).
   const TOKEN_KEY = 'augment-it:session-token';
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
 
   let status = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
 
diff --git a/apps/response-reviewer/src/App.svelte b/apps/response-reviewer/src/App.svelte
index 0aea807..697c5c8 100644
--- a/apps/response-reviewer/src/App.svelte
+++ b/apps/response-reviewer/src/App.svelte
@@ -8,8 +8,7 @@
     type ResponseFlag,
     type Row,
     type HelpfulLink,
-    type SocialProfile,
-  } from '@augment-it/workspace';
+    type SocialProfile, resolveWsUrl } from '@augment-it/workspace';
   import ConfidencePill from '@augment-it/shared-ui/ConfidencePill.svelte';
   import { MOCK_PACKS_FIXTURE } from './fixtures/mock-packs';
   import ConnectorPalette from './ConnectorPalette.svelte';
@@ -18,7 +17,7 @@
   // Each remote owns its own workspace singleton + WebSocket — no `shared`
   // federation block (see the 2026-05-21_03 changelog).
   const TOKEN_KEY = 'augment-it:session-token';
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
 
   const FLAGS: ResponseFlag[] = ['good', 'partial', 'wrong', 'needs-rerun', 'needs-human'];
 
diff --git a/apps/search-and-add/src/App.svelte b/apps/search-and-add/src/App.svelte
index 47e48ef..ac680f8 100644
--- a/apps/search-and-add/src/App.svelte
+++ b/apps/search-and-add/src/App.svelte
@@ -10,7 +10,7 @@
   // See context-v/specs/Augment-From-DB-Flow.md §Phase 3.
 
   import { onMount } from 'svelte';
-  import { workspace } from '@augment-it/workspace';
+  import { workspace, resolveWsUrl } from '@augment-it/workspace';
   import TermBar from './TermBar.svelte';
   import ProviderPalette from './ProviderPalette.svelte';
   import ResultsList from './ResultsList.svelte';
@@ -19,7 +19,7 @@
   import type { ConnectorInfo, ConnectorResult } from './lib/types';
 
   const TOKEN_KEY = 'augment-it:session-token';
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
 
   let status = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
   let client = $state<string>('reach-edu');
diff --git a/apps/search-results/src/App.svelte b/apps/search-results/src/App.svelte
index cf3d611..6ff6abd 100644
--- a/apps/search-results/src/App.svelte
+++ b/apps/search-results/src/App.svelte
@@ -7,13 +7,13 @@
   // See context-v/specs/Search-Results-Queue-Remote.md.
 
   import { onMount } from 'svelte';
-  import { workspace } from '@augment-it/workspace';
+  import { workspace, resolveWsUrl } from '@augment-it/workspace';
   import SearchCard from './SearchCard.svelte';
   import { dismissSearch, listSearches } from './lib/search-client';
   import type { SearchCard as SearchCardT } from './lib/types';
 
   const TOKEN_KEY = 'augment-it:session-token';
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
 
   let status = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
   let client = $state<string>('reach-edu');
diff --git a/apps/sort-filter-lens/src/App.svelte b/apps/sort-filter-lens/src/App.svelte
index 336d330..b333a98 100644
--- a/apps/sort-filter-lens/src/App.svelte
+++ b/apps/sort-filter-lens/src/App.svelte
@@ -10,7 +10,7 @@
   // Spec: ../../../context-v/specs/Records-Surface-Sort-Step-and-UI.md
 
   import { onMount } from 'svelte';
-  import { workspace, type RecordSet, type Row } from '@augment-it/workspace';
+  import { workspace, type RecordSet, type Row, resolveWsUrl } from '@augment-it/workspace';
   import {
     type SortSpec,
     type SortKey,
@@ -21,7 +21,7 @@
   } from './sort-spec';
 
   const TOKEN_KEY = 'augment-it:session-token';
-  const WS_URL = 'ws://localhost:3001/ws';
+  const WS_URL = resolveWsUrl();
   const ACTIVE_RECORD_SET_KEY = 'augment-it:active-record-set';
   const CLIENT_ID = 'reach-edu';
 
diff --git a/packages/workspace/src/index.ts b/packages/workspace/src/index.ts
index 6d85984..c906df9 100644
--- a/packages/workspace/src/index.ts
+++ b/packages/workspace/src/index.ts
@@ -2,6 +2,7 @@ export { workspace, WORKSPACE_CHANGED_EVENT } from './state.svelte';
 export { bootMark, bootSummary } from './boot-timing';
 export { createAdapter } from './adapter';
 export { createTransport } from './transport';
+export { resolveWsUrl, resolveHttpBase, DEFAULT_WS_URL } from './ws-url';
 export { suggest } from './anticipation';
 export type { Suggestion } from './anticipation';
 export { MODELS, DEFAULT_MODEL, DEFAULT_MAX_TOKENS } from './models';
diff --git a/packages/workspace/src/state.svelte.ts b/packages/workspace/src/state.svelte.ts
index 2d69e5c..6681670 100644
--- a/packages/workspace/src/state.svelte.ts
+++ b/packages/workspace/src/state.svelte.ts
@@ -15,6 +15,7 @@
 // rule in https://svelte.dev/e/state_invalid_placement.
 
 import { createTransport, type ChatTurnReply, type ChatTurnRequest, type Transport, type TransportConfig } from './transport';
+import { resolveWsUrl } from './ws-url';
 import { bootMark, bootSummary } from './boot-timing';
 import type { ActiveView, JobEvent, PromptTemplate, RecordSet, Row, ServerFrame, UserContext, WorkspaceSummary } from './types';
 
@@ -264,7 +265,7 @@ class AugmentItWorkspace {
    */
   connect(config: Omit<TransportConfig, 'onFrame'>): void {
     if (this.transport) return;
-    console.info('[workspace] connect →', config.url);
+    console.info('[workspace] connect →', config.url ?? resolveWsUrl());
     const userOnStatus = config.onStatus;
     this.transport = createTransport({
       ...config,
diff --git a/packages/workspace/src/transport.ts b/packages/workspace/src/transport.ts
index de4e079..ed495a2 100644
--- a/packages/workspace/src/transport.ts
+++ b/packages/workspace/src/transport.ts
@@ -27,9 +27,15 @@ import type {
   ServerFrame,
 } from './types';
 import { bootMark } from './boot-timing';
+import { resolveWsUrl } from './ws-url';
 
 export type TransportConfig = {
-  url: string;                              // e.g. 'ws://localhost:3001/ws'
+  /**
+   * Workspace-service WS endpoint. OPTIONAL — omit it and the endpoint is
+   * resolved from PUBLIC_WS_URL via resolveWsUrl(). Callers should omit it;
+   * passing a literal is how every remote ended up hardcoded to localhost.
+   */
+  url?: string;
   getToken: () => string | null;
   saveToken: (token: string) => void;
   onFrame: (frame: ServerFrame) => void;    // called for event/session/result frames
@@ -118,9 +124,13 @@ export function createTransport(config: TransportConfig): Transport {
 
   function connect(): void {
     const token = config.getToken();
+    // Resolved per attempt, not captured once: a caller that omits `url`
+    // gets the build's PUBLIC_WS_URL, which is the path every remote
+    // should take.
+    const base = config.url ?? resolveWsUrl();
     const url = token
-      ? `${config.url}?token=${encodeURIComponent(token)}`
-      : config.url;
+      ? `${base}?token=${encodeURIComponent(token)}`
+      : base;
 
     bootMark('ws:connect-start');
     config.onStatus?.('connecting');
diff --git a/packages/workspace/src/ws-url.ts b/packages/workspace/src/ws-url.ts
new file mode 100644
index 0000000..9768ead
--- /dev/null
+++ b/packages/workspace/src/ws-url.ts
@@ -0,0 +1,39 @@
+// Where workspace-service's WebSocket lives.
+//
+// This is the ONE place the endpoint is decided. It exists because it used
+// to be decided in sixteen places: every remote declared its own
+// `const WS_URL = 'ws://localhost:3001/ws'` and never read the environment,
+// so on augment.didi.sh they each dialled the *visitor's* laptop and showed
+// an empty surface behind a `closed` badge. Local dev hid it perfectly —
+// the operator's machine really is running workspace-service on :3001.
+// See [[Every-Remote-Hardcodes-The-Workspace-WS-To-Localhost-So-Prod-Loads-No-Data]].
+//
+// rsbuild inlines PUBLIC_-prefixed vars into import.meta.env at BUILD time,
+// and it does so for plain .ts modules too — not just .svelte files. This
+// module is consumed as source (packages/workspace has `main: ./src/index.ts`),
+// so each app's own build substitutes its own PUBLIC_WS_URL here. Changing
+// the value therefore requires a rebuild, never just a restart.
+
+/** Dev fallback: the local docker-compose workspace-service. */
+export const DEFAULT_WS_URL = 'ws://localhost:3001/ws';
+
+/**
+ * The workspace WebSocket endpoint for this build.
+ *
+ * Prod must set `PUBLIC_WS_URL=wss://ws.augment.didi.sh/ws`. Note the `wss`:
+ * an insecure `ws://` socket opened from an `https://` page is blocked as
+ * mixed content, so a plain `ws://` value cannot work in production even
+ * when the host is right.
+ */
+export function resolveWsUrl(): string {
+  const fromEnv = (import.meta as { env?: Record<string, string> }).env?.PUBLIC_WS_URL;
+  return (typeof fromEnv === 'string' && fromEnv.length > 0 ? fromEnv : DEFAULT_WS_URL);
+}
+
+/**
+ * The matching HTTP origin for the same service — `ws(s)://host/ws` →
+ * `http(s)://host`. Used for plain fetches like `/config`.
+ */
+export function resolveHttpBase(wsUrl: string = resolveWsUrl()): string {
+  return wsUrl.replace(/^ws/, 'http').replace(/\/ws$/, '');
+}
diff --git a/packages/workspace/test/ws-url.test.ts b/packages/workspace/test/ws-url.test.ts
new file mode 100644
index 0000000..e5bafab
--- /dev/null
+++ b/packages/workspace/test/ws-url.test.ts
@@ -0,0 +1,72 @@
+// Guard — the workspace WS endpoint is decided in exactly one place.
+//
+// Regression test for the defect where sixteen remotes each declared
+// `const WS_URL = 'ws://localhost:3001/ws'` and never read the environment,
+// so augment.didi.sh opened data sockets against the *visitor's* laptop and
+// every Augment-from-DB surface rendered empty behind a `closed` badge.
+// Local dev hid it completely, because the operator's machine really does
+// run workspace-service on :3001.
+//
+// The unit assertions cover the resolver; the source sweep is what actually
+// stops the regression, because the original bug was never a logic error —
+// it was copy-paste into a new remote.
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { describe, expect, test } from 'vitest';
+import { DEFAULT_WS_URL, resolveHttpBase, resolveWsUrl } from '../src/ws-url';
+
+const REPO_ROOT = join(import.meta.dirname, '../../..');
+/** The one file allowed to name the dev endpoint: the fallback itself. */
+const ALLOWED = ['packages/workspace/src/ws-url.ts'];
+
+function sourceFiles(dir: string, out: string[] = []): string[] {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    // Tests legitimately name endpoints (fixtures, assertions, this file).
+    if (e === 'node_modules' || e === 'dist' || e === '.git' || e === 'test') continue;
+    const p = join(dir, e);
+    if (statSync(p).isDirectory()) sourceFiles(p, out);
+    else if (/\.(ts|svelte)$/.test(e) && !/\.(test|spec)\.ts$/.test(e)) out.push(p);
+  }
+  return out;
+}
+
+describe('resolveWsUrl', () => {
+  test('falls back to the local dev endpoint when PUBLIC_WS_URL is unset', () => {
+    // rsbuild inlines the var at build time; under vitest it is simply absent.
+    expect(resolveWsUrl()).toBe(DEFAULT_WS_URL);
+  });
+
+  test('derives the plain-HTTP origin from a ws endpoint', () => {
+    expect(resolveHttpBase('ws://localhost:3001/ws')).toBe('http://localhost:3001');
+    expect(resolveHttpBase('wss://ws.augment.didi.sh/ws')).toBe('https://ws.augment.didi.sh');
+  });
+});
+
+describe('no surface hardcodes the workspace endpoint', () => {
+  test('ws://localhost:3001 appears only in the shared fallback', () => {
+    const roots = ['apps', 'shell', 'packages'].map((d) => join(REPO_ROOT, d));
+    const offenders: string[] = [];
+
+    for (const root of roots) {
+      for (const file of sourceFiles(root)) {
+        const rel = relative(REPO_ROOT, file);
+        if (ALLOWED.includes(rel)) continue;
+        if (readFileSync(file, 'utf8').includes('ws://localhost:3001')) offenders.push(rel);
+      }
+    }
+
+    expect(
+      offenders,
+      `These files name the dev WS endpoint directly. Import resolveWsUrl() from ` +
+        `@augment-it/workspace instead — a literal here is invisible on localhost ` +
+        `and breaks every deployed surface.\n  ${offenders.join('\n  ')}`,
+    ).toEqual([]);
+  });
+});
diff --git a/shell/src/App.svelte b/shell/src/App.svelte
index e6bc78e..316a55b 100644
--- a/shell/src/App.svelte
+++ b/shell/src/App.svelte
@@ -9,7 +9,7 @@
   import SignInWall from './SignInWall.svelte';
   import JumboPopdown, { type PopdownItem } from './JumboPopdown.svelte';
   import ToggleHeader from '@augment-it/shared-ui/ToggleHeader__PromptOrPackage--Icons.svelte';
-  import { workspace, bootMark } from '@augment-it/workspace';
+  import { workspace, bootMark, resolveWsUrl, resolveHttpBase } from '@augment-it/workspace';
   import {
     PAIRINGS,
     CHAT_REMOTE,
@@ -38,10 +38,8 @@
   // Deriving the plain-HTTP base from it (ws→http, wss→https) rather than a
   // second env var — Step 7's /config check needs the same origin, not the
   // WS scheme.
-  const WS_URL =
-    ((import.meta as { env?: Record<string, string> }).env?.PUBLIC_WS_URL as string | undefined) ||
-    'ws://localhost:3001/ws';
-  const WS_HTTP_BASE = WS_URL.replace(/^ws/, 'http').replace(/\/ws$/, '');
+  const WS_URL = resolveWsUrl();
+  const WS_HTTP_BASE = resolveHttpBase(WS_URL);
 
   // Chat rail visibility — persistent left-side companion to the focused
   // Window. Toggleable from the header; persisted to localStorage so a
diff --git a/shell/src/WorkspaceSwitcher.svelte b/shell/src/WorkspaceSwitcher.svelte
index a0e42da..06ebca6 100644
--- a/shell/src/WorkspaceSwitcher.svelte
+++ b/shell/src/WorkspaceSwitcher.svelte
@@ -11,7 +11,7 @@
   // (operator does `mkdir clients/<slug>/` on disk, picks up on next
   // refresh).
 
-  import { workspace } from '@augment-it/workspace';
+  import { workspace, resolveWsUrl } from '@augment-it/workspace';
 
   let open = $state<boolean>(false);
   let switching = $state<boolean>(false);
@@ -34,7 +34,7 @@
   });
   const tooltip = $derived.by(() => {
     if (workspace.connection_status === 'closed' || workspace.connection_status === 'error') {
-      return `WebSocket ${workspace.connection_status} — workspace-service at ws://localhost:3001/ws unreachable`;
+      return `WebSocket ${workspace.connection_status} — workspace-service at ${resolveWsUrl()} unreachable`;
     }
     if (workspace.workspaces_status === 'error' && workspace.workspaces_error) {
       return `workspace.list failed: ${workspace.workspaces_error}`;