@openchambery/web 1.19.0-beta.9 → 1.19.0

package/server/lib/notifications/apns-titles.js

@@ -0,0 +1,212 @@
+// Localized scenario titles for native push (APNs / FCM). Keys match UI locales.
+// Titles stay content-free (scenario only); session name is the body separately.
+
+export const APNS_DEFAULT_LOCALE = 'en';
+
+export const APNS_LOCALES = Object.freeze([
+  'en',
+  'fr',
+  'zh-CN',
+  'zh-TW',
+  'uk',
+  'es',
+  'pt-BR',
+  'ko',
+  'pl',
+  'ja',
+]);
+
+/** @typedef {'ready'|'error'|'question'|'permission'|'goal_complete'|'goal_blocked'|'goal_budget'|'update'} ApnsTitleType */
+
+const TITLES = Object.freeze({
+  en: Object.freeze({
+    ready: 'Agent response is ready',
+    error: 'Agent hit an error',
+    question: 'Agent needs your input',
+    permission: 'Agent needs permission',
+    goal_complete: 'Goal complete',
+    goal_blocked: 'Goal blocked',
+    goal_budget: 'Goal reached its token budget',
+    update: 'Agent update',
+    session: 'Session',
+  }),
+  fr: Object.freeze({
+    ready: "La réponse de l'agent est prête",
+    error: "L'agent a rencontré une erreur",
+    question: "L'agent a besoin de votre saisie",
+    permission: "L'agent a besoin d'une autorisation",
+    goal_complete: 'Objectif terminé',
+    goal_blocked: 'Objectif bloqué',
+    goal_budget: "L'objectif a atteint son budget de tokens",
+    update: "Mise à jour de l'agent",
+    session: 'Session',
+  }),
+  'zh-CN': Object.freeze({
+    ready: '智能体回复已就绪',
+    error: '智能体遇到错误',
+    question: '智能体需要你的输入',
+    permission: '智能体需要权限',
+    goal_complete: '目标已完成',
+    goal_blocked: '目标受阻',
+    goal_budget: '目标已达 token 预算',
+    update: '智能体更新',
+    session: '会话',
+  }),
+  'zh-TW': Object.freeze({
+    ready: '智能體回覆已就緒',
+    error: '智能體遇到錯誤',
+    question: '智能體需要你的輸入',
+    permission: '智能體需要權限',
+    goal_complete: '目標已完成',
+    goal_blocked: '目標受阻',
+    goal_budget: '目標已達 token 預算',
+    update: '智能體更新',
+    session: '工作階段',
+  }),
+  uk: Object.freeze({
+    ready: 'Відповідь агента готова',
+    error: 'Агент зіткнувся з помилкою',
+    question: 'Агенту потрібне ваше введення',
+    permission: 'Агенту потрібен дозвіл',
+    goal_complete: 'Цілі досягнуто',
+    goal_blocked: 'Цілі заблоковано',
+    goal_budget: 'Ціль досягла ліміту токенів',
+    update: 'Оновлення агента',
+    session: 'Сесія',
+  }),
+  es: Object.freeze({
+    ready: 'La respuesta del agente está lista',
+    error: 'El agente encontró un error',
+    question: 'El agente necesita tu entrada',
+    permission: 'El agente necesita permiso',
+    goal_complete: 'Objetivo completado',
+    goal_blocked: 'Objetivo bloqueado',
+    goal_budget: 'El objetivo alcanzó su presupuesto de tokens',
+    update: 'Actualización del agente',
+    session: 'Sesión',
+  }),
+  'pt-BR': Object.freeze({
+    ready: 'A resposta do agente está pronta',
+    error: 'O agente encontrou um erro',
+    question: 'O agente precisa da sua entrada',
+    permission: 'O agente precisa de permissão',
+    goal_complete: 'Objetivo concluído',
+    goal_blocked: 'Objetivo bloqueado',
+    goal_budget: 'O objetivo atingiu o orçamento de tokens',
+    update: 'Atualização do agente',
+    session: 'Sessão',
+  }),
+  ko: Object.freeze({
+    ready: '에이전트 응답이 준비되었습니다',
+    error: '에이전트에서 오류가 발생했습니다',
+    question: '에이전트가 입력을 요청합니다',
+    permission: '에이전트가 권한이 필요합니다',
+    goal_complete: '목표 완료',
+    goal_blocked: '목표 차단됨',
+    goal_budget: '목표가 토큰 예산에 도달했습니다',
+    update: '에이전트 업데이트',
+    session: '세션',
+  }),
+  pl: Object.freeze({
+    ready: 'Odpowiedź agenta jest gotowa',
+    error: 'Agent napotkał błąd',
+    question: 'Agent potrzebuje Twojego wejścia',
+    permission: 'Agent potrzebuje uprawnienia',
+    goal_complete: 'Cel ukończony',
+    goal_blocked: 'Cel zablokowany',
+    goal_budget: 'Cel osiągnął budżet tokenów',
+    update: 'Aktualizacja agenta',
+    session: 'Sesja',
+  }),
+  ja: Object.freeze({
+    ready: 'エージェントの応答が準備できました',
+    error: 'エージェントでエラーが発生しました',
+    question: 'エージェントが入力を求めています',
+    permission: 'エージェントが許可を求めています',
+    goal_complete: '目標完了',
+    goal_blocked: '目標がブロックされました',
+    goal_budget: '目標がトークン予算に達しました',
+    update: 'エージェントの更新',
+    session: 'セッション',
+  }),
+});
+
+const matchSupportedLocale = (value) => {
+  if (!value || typeof value !== 'string') return undefined;
+  const normalized = value.toLowerCase().replace(/_/g, '-');
+  if (
+    normalized === 'zh-tw'
+    || normalized.startsWith('zh-tw-')
+    || normalized === 'zh-hk'
+    || normalized.startsWith('zh-hk-')
+    || normalized === 'zh-mo'
+    || normalized.startsWith('zh-mo-')
+    || normalized === 'zh-hant'
+    || normalized.startsWith('zh-hant-')
+  ) {
+    return 'zh-TW';
+  }
+  if (normalized.startsWith('zh')) return 'zh-CN';
+  if (normalized.startsWith('en')) return 'en';
+  if (normalized === 'fr' || normalized.startsWith('fr-')) return 'fr';
+  if (normalized === 'uk' || normalized.startsWith('uk-') || normalized === 'ua' || normalized.startsWith('ua-')) {
+    return 'uk';
+  }
+  if (normalized === 'es' || normalized.startsWith('es-')) return 'es';
+  if (normalized === 'pt' || normalized.startsWith('pt-')) return 'pt-BR';
+  if (normalized === 'ko' || normalized.startsWith('ko-')) return 'ko';
+  if (normalized === 'ja' || normalized.startsWith('ja-')) return 'ja';
+  if (normalized === 'pl' || normalized.startsWith('pl-')) return 'pl';
+  return undefined;
+};
+
+export const normalizeApnsLocale = (value) => matchSupportedLocale(value) ?? APNS_DEFAULT_LOCALE;
+
+const titlesFor = (locale) => TITLES[normalizeApnsLocale(locale)] || TITLES[APNS_DEFAULT_LOCALE];
+
+/**
+ * @param {string|undefined|null} type
+ * @param {string|undefined|null} locale
+ */
+export const resolveApnsTitle = (type, locale) => {
+  const dict = titlesFor(locale);
+  if (typeof type === 'string' && Object.prototype.hasOwnProperty.call(dict, type) && type !== 'session') {
+    return dict[type];
+  }
+  return dict.update;
+};
+
+/**
+ * @param {string|undefined|null} locale
+ */
+export const resolveApnsSessionFallback = (locale) => titlesFor(locale).session;
+
+/**
+ * Localize a generic native-push payload for one device locale.
+ * `payload.type` selects the scenario title; `payload.sessionName` (or non-empty body) is the body.
+ * Callers that already pass a fixed `title`/`body` (tests / legacy) keep that text when `type` is absent.
+ *
+ * @param {{ type?: string, title?: string, body?: string, sessionName?: string, badge?: number, tag?: string, data?: object }} payload
+ * @param {string|undefined|null} locale
+ */
+export const localizeApnsPayload = (payload, locale) => {
+  const type = typeof payload?.type === 'string' ? payload.type : undefined;
+  const sessionName = typeof payload?.sessionName === 'string' && payload.sessionName.trim().length > 0
+    ? payload.sessionName.trim()
+    : '';
+  const legacyBody = typeof payload?.body === 'string' && payload.body.trim().length > 0
+    ? payload.body.trim()
+    : '';
+  const title = type
+    ? resolveApnsTitle(type, locale)
+    : (typeof payload?.title === 'string' && payload.title.length > 0
+      ? payload.title
+      : resolveApnsTitle('update', locale));
+  return {
+    title,
+    body: sessionName || legacyBody || resolveApnsSessionFallback(locale),
+    badge: payload?.badge,
+    tag: payload?.tag,
+    data: payload?.data,
+  };
+};

package/server/lib/notifications/apns-titles.test.js

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  APNS_DEFAULT_LOCALE,
+  APNS_LOCALES,
+  localizeApnsPayload,
+  normalizeApnsLocale,
+  resolveApnsSessionFallback,
+  resolveApnsTitle,
+} from './apns-titles.js';
+
+describe('apns-titles', () => {
+  it('normalizes BCP-47 tags onto supported app locales', () => {
+    expect(normalizeApnsLocale('zh-Hans-CN')).toBe('zh-CN');
+    expect(normalizeApnsLocale('zh_TW')).toBe('zh-TW');
+    expect(normalizeApnsLocale('pt-PT')).toBe('pt-BR');
+    expect(normalizeApnsLocale('ja-JP')).toBe('ja');
+    expect(normalizeApnsLocale('nope')).toBe(APNS_DEFAULT_LOCALE);
+    expect(normalizeApnsLocale(undefined)).toBe(APNS_DEFAULT_LOCALE);
+  });
+
+  it('resolves every scenario type for every supported locale', () => {
+    const types = ['ready', 'error', 'question', 'permission', 'goal_complete', 'goal_blocked', 'goal_budget', 'update'];
+    for (const locale of APNS_LOCALES) {
+      for (const type of types) {
+        const title = resolveApnsTitle(type, locale);
+        expect(typeof title).toBe('string');
+        expect(title.length).toBeGreaterThan(0);
+      }
+      expect(resolveApnsSessionFallback(locale).length).toBeGreaterThan(0);
+    }
+  });
+
+  it('localizes payload title by type and keeps session name as body', () => {
+    expect(localizeApnsPayload({ type: 'question', sessionName: 'Build fix' }, 'zh-CN')).toEqual({
+      title: '智能体需要你的输入',
+      body: 'Build fix',
+      badge: undefined,
+      tag: undefined,
+      data: undefined,
+    });
+    expect(localizeApnsPayload({ type: 'ready' }, 'fr').body).toBe('Session');
+    expect(localizeApnsPayload({ type: 'ready' }, 'zh-CN').body).toBe('会话');
+  });
+
+  it('keeps explicit legacy title/body when type is absent', () => {
+    expect(localizeApnsPayload({ title: 'Custom', body: 'Body' }, 'ja')).toEqual({
+      title: 'Custom',
+      body: 'Body',
+      badge: undefined,
+      tag: undefined,
+      data: undefined,
+    });
+  });
+});

package/server/lib/notifications/routes.js

@@ -162,8 +162,9 @@ export const registerNotificationRoutes = (app, dependencies) => {
     }
 
     const platform = req.body?.platform === 'android' ? 'android' : 'ios';
+    const locale = typeof req.body?.locale === 'string' ? req.body.locale.trim() : undefined;
     if (typeof addOrUpdateApnsToken === 'function') {
-      await addOrUpdateApnsToken(uiToken, deviceToken, req.headers['user-agent'], platform);
+      await addOrUpdateApnsToken(uiToken, deviceToken, req.headers['user-agent'], platform, locale);
     }
     return res.json({ ok: true });
   });

package/server/lib/notifications/runtime.js

@@ -49,24 +49,16 @@ export const createNotificationTriggerRuntime = (deps) => {
 
   // Generic notification for native push (per the mobile design): a fixed, scenario-based
   // title + the session name as the body. No model/project/message content crosses the relay.
-  const APNS_TITLE_BY_TYPE = {
-    ready: 'Agent response is ready',
-    error: 'Agent hit an error',
-    question: 'Agent needs your input',
-    permission: 'Agent needs permission',
-    goal_complete: 'Goal complete',
-    goal_blocked: 'Goal blocked',
-    goal_budget: 'Goal reached its token budget',
-  };
-
+  // Title strings are localized per device token locale inside sendApnsToAllUiSessions.
   const toApnsGenericPayload = (payload) => {
     const data = payload?.data && typeof payload.data === 'object' ? payload.data : {};
     const sessionName = typeof data.sessionName === 'string' && data.sessionName.trim().length > 0
       ? data.sessionName.trim()
-      : 'Session';
+      : '';
+    const type = typeof data.type === 'string' ? data.type : undefined;
     return {
-      title: APNS_TITLE_BY_TYPE[data.type] || 'Agent update',
-      body: sessionName,
+      type,
+      sessionName,
       badge: trackPushAndCountBadge(typeof payload?.tag === 'string' ? payload.tag : undefined),
       tag: payload?.tag,
       // sessionId is forwarded so a tapped push can deep-link; it is an opaque id, not content.

package/server/lib/opencode/openchamber-routes.js

@@ -10,8 +10,6 @@ export const registerOpenChamberRoutes = (app, dependencies) => {
     server,
     __dirname,
     openchamberDataDir,
-    readSettingsFromDiskMigrated,
-    persistSettings,
     fetchFreeZenModels,
     getCachedZenModels,
     sessionIndexService,
@@ -22,11 +20,7 @@ export const registerOpenChamberRoutes = (app, dependencies) => {
 
   registerSessionIndexRoutes(app, { sessionIndexService, sessionIndexSyncRuntime });
   registerTranscriptCacheRoutes(app, { transcriptCacheService });
-  registerConfigSyncRoutes(app, {
-    readSettingsFromDiskMigrated,
-    persistSettings,
-    express,
-  });
+  registerConfigSyncRoutes(app, { express });
 
   app.get('/api/openchamber/update-check', async (req, res) => {
     try {

package/server/lib/opencode/settings-helpers.js

@@ -318,9 +318,6 @@ export const createSettingsHelpers = (dependencies) => {
     if (typeof candidate.showReasoningTraces === 'boolean') {
       result.showReasoningTraces = candidate.showReasoningTraces;
     }
-    if (typeof candidate.sessionRecapEnabled === 'boolean') {
-      result.sessionRecapEnabled = candidate.sessionRecapEnabled;
-    }
     if (typeof candidate.sessionTitleRefreshEnabled === 'boolean') {
       result.sessionTitleRefreshEnabled = candidate.sessionTitleRefreshEnabled;
     }

package/server/lib/opencode/shutdown-runtime.js

@@ -8,7 +8,6 @@ export const createGracefulShutdownRuntime = (dependencies) => {
     syncToHmrState,
     openCodeWatcherRuntime,
     sessionRuntime,
-    sessionAssistRuntime,
     sessionTitleRuntime,
     sessionGoalRuntime,
     scheduledTasksRuntime,
@@ -43,7 +42,6 @@ export const createGracefulShutdownRuntime = (dependencies) => {
 
     openCodeWatcherRuntime.stop();
     sessionRuntime.dispose();
-    sessionAssistRuntime?.stop?.();
     sessionTitleRuntime?.stop?.();
     sessionGoalRuntime?.stop?.();
     // Stop timers/queue only. Keep the process-lifetime run history store open so

package/server/lib/relay/DOCUMENTATION.md

@@ -19,9 +19,9 @@ Traffic is modeled as three stacked layers. The relay understands only Layer 1;
 ## Entrypoints and structure
 
 Host side (`packages/web/server/lib/relay/`):
-- `service.js` — thin entrypoint: relay config (enabled flag + relay URL), the management routes (`GET/POST /api/openchamber/relay/{status,enable,disable}`), a `getPairingCandidate()` accessor (the relay transport candidate folded into pairing-v2 links when enabled, consumed by the pairing-session route in `core-routes.js`), and lifecycle wiring. Host lifecycle is gated by `isRelayHostRuntime()` (`desktop` or `ssh-remote`): other runtimes (`bun run dev`, `dev:web:hmr`, ordinary CLI `serve`, VS Code, plain `node server`) report `state: 'unavailable'`, refuse `/relay/enable`, `/relay/disable`, and relay pairing with 403, never mint a relay identity, never advertise `relayAvailable`, and never call `startRelayHost`. Direct `node server/index.js` forces `OPENCHAMBER_RUNTIME=web` unless it is already `ssh-remote`, so a leftover desktop env cannot open the host-control socket. On host runtimes, started from `packages/web/server/index.js` when demand/opt-in enables the relay. Desktop auto-clears `privateRelay.enabled` when demand drops; `ssh-remote` keeps an explicit opt-in (e.g. `openchamber serve --relay-host`) sticky until disabled. The relay endpoint defaults to the OpenChamber-hosted relay but can be pinned to a self-hosted relay via the `OPENCHAMBER_RELAY_URL` env var; when set it overrides the stored setting for the host connection, the pairing candidate, and status, so paired clients inherit the endpoint automatically. Endpoint identity is scheme/host/path only: accepted schemes are `ws://` and `wss://`; URLs with userinfo are rejected (no silent default fallback); query and fragment are stripped before persistence and pairing candidates. Custom endpoint persistence and Host control-connection switching are explicit authenticated management actions. Pairing creation with `relayUrl` requires an owner UI session or the local `desktop-local` shell client; `/relay/enable` follows its API auth gate.
+- `service.js` — thin entrypoint: relay config (enabled flag + relay URL), the management routes (`GET/POST /api/openchamber/relay/{status,enable,disable}`), a `getPairingCandidate()` accessor (the relay transport candidate folded into pairing-v2 links when enabled, consumed by the pairing-session route in `core-routes.js`), and lifecycle wiring. Host lifecycle is gated by `isRelayHostRuntime()` (`desktop` or `ssh-remote`): other runtimes (`bun run dev`, `dev:web:hmr`, ordinary CLI `serve`, VS Code, plain `node server`) report `state: 'unavailable'`, refuse `/relay/enable`, `/relay/disable`, and relay pairing with 403, never mint a relay identity, never advertise `relayAvailable`, and never call `startRelayHost`. Direct `node server/index.js` forces `OPENCHAMBER_RUNTIME=web` unless it is already `ssh-remote`, so a leftover desktop env cannot open the host-control socket. On host runtimes, started from `packages/web/server/index.js` when demand/opt-in enables the relay. Desktop auto-clears `privateRelay.enabled` when demand drops; `ssh-remote` keeps an explicit opt-in (e.g. `openchamber serve --relay-host`) sticky until disabled. The relay endpoint defaults to the OpenChamber-hosted relay but can be pinned to a self-hosted relay via the `OPENCHAMBER_RELAY_URL` env var; when set it overrides the stored setting for the host connection, the pairing candidate, and status, so paired clients inherit the endpoint automatically. Endpoint identity is scheme/host/path only: accepted schemes are `ws://` and `wss://`; URLs with userinfo are rejected (no silent default fallback); query and fragment are stripped before persistence and pairing candidates. Custom endpoint persistence and Host control-connection switching are explicit authenticated management actions. Pairing creation with `relayUrl` requires an owner UI session or the local `desktop-local` shell client; `/relay/enable` follows its API auth gate. `derivePushSendUrlFromRelayUrl` maps a canonical Relay `wss://`/`ws://` URL to the same host's `https://`/`http://` `/v1/push/send` path (register is `/v1/push/register-token`); `OPENCHAMBER_PUSH_RELAY_URL` on the Host overrides that derivation. The isolated Push process lives in `packages/relay-server/src/push/` and does not share Layer 1 credentials or tunnel state.
 - `identity.js` — the host's stable identity: the long-lived signing keypair (shared with the push relay, defines the routing id) plus a long-lived encryption keypair (the E2EE trust anchor). Reused across restarts; never rotated implicitly.
-- `signing-key.js` — storage/derivation of the signing keypair and the routing id, shared with the notifications runtime.
+- `signing-key.js` — storage/derivation of the signing keypair and the routing id, shared with the notifications runtime. Canonical public JWK hashing matches `packages/relay-server/src/push/crypto.js`.
 - `host-client.js` — the long-lived connection manager: one outbound control connection to the relay, a per-client data connection for each connected device, reconnect/backoff, and the E2EE responder handshake per connection.
 - `host-lock.js` — the per-machine host claim. Every local instance sharing the data dir shares the relay identity (same serverId), so concurrent relay hosts evict each other at the relay worker (`4001: Control replaced`) and paired devices land on whichever local process won last. The claim file (`<data-dir>/relay-host.lock`, `{ pid }`) makes this deterministic: `service.js` only starts the host when no LIVE process holds the claim (stale claims from dead pids are ignored), goes to `standby` otherwise, and a 30s watcher both takes over when the claimant dies and stands down when another process claims. Explicit user intent — creating a pairing link or hitting `/relay/enable` — force-claims; the previous holder's watcher sees the takeover and backs off instead of fighting. The claim is cooperative (the relay worker still enforces the single host slot); it only decides which process keeps retrying.
 - `tunnel-host.js` — the per-connection dispatcher: decrypts tunnel frames and forwards HTTP/SSE/WS to the local server over loopback, then streams responses back. Enforces a path allowlist and never injects credentials.

package/server/lib/relay/service.js

@@ -54,6 +54,25 @@ export const canonicalizeRelayUrl = (value) => {
   }
 };
 
+// Canonical ws(s) relay URL → Push send endpoint on the same host/port.
+// Always `/v1/push/send`; never derived from window/location.
+export const derivePushSendUrlFromRelayUrl = (value) => {
+  const canonical = canonicalizeRelayUrl(value);
+  if (!canonical) return null;
+  try {
+    const url = new URL(canonical);
+    url.protocol = url.protocol === 'wss:' ? 'https:' : 'http:';
+    url.pathname = '/v1/push/send';
+    url.username = '';
+    url.password = '';
+    url.hash = '';
+    url.search = '';
+    return url.toString();
+  } catch {
+    return null;
+  }
+};
+
 const normalizeRelayUrl = (value) => {
   if (typeof value !== 'string') return DEFAULT_RELAY_URL;
   return canonicalizeRelayUrl(value) ?? DEFAULT_RELAY_URL;
@@ -63,12 +82,16 @@ const normalizeRelayUrl = (value) => {
 // your own Cloudflare account/domain). When set and valid it overrides the
 // stored setting entirely, so the host connection, the pairing offer, and the
 // status all point at it — clients then inherit it from the offer automatically.
-const envRelayUrlOverride = () => {
-  const raw = process.env.OPENCHAMBER_RELAY_URL;
+const envRelayUrlOverride = (env = process.env) => {
+  const raw = env?.OPENCHAMBER_RELAY_URL;
   if (typeof raw !== 'string' || !raw.trim()) return null;
   return canonicalizeRelayUrl(raw);
 };
 
+// Env (`OPENCHAMBER_RELAY_URL`) → settings.privateRelay.relayUrl → DEFAULT_RELAY_URL.
+export const resolveEffectiveRelayUrl = ({ settings = null, env = process.env } = {}) =>
+  envRelayUrlOverride(env) ?? normalizeRelayUrl(settings?.privateRelay?.relayUrl);
+
 /**
  * @param {{
  *   crypto: typeof import('node:crypto'),
@@ -77,6 +100,7 @@ const envRelayUrlOverride = () => {
  *   getLocalPort: () => number,
  *   logger?: Pick<Console, 'warn'>,
  *   canHostRelay?: () => boolean,
+ *   onRelayUrlChanged?: () => Promise<void> | void,
  * }} deps
  */
 export const createRelayService = ({
@@ -98,6 +122,7 @@ export const createRelayService = ({
   // Host gate: false for non-host runtimes (dev server, ordinary CLI, VS Code, …).
   canHostRelay = () => isRelayHostRuntime(),
   logger = console,
+  onRelayUrlChanged = null,
 }) => {
   const identityRuntime = createRelayIdentityRuntime({ crypto, readSettingsFromDiskMigrated, writeSettingsToDisk, readSettingsStrict });
 
@@ -131,13 +156,22 @@ export const createRelayService = ({
     const override = envRelayUrlOverride();
     return {
       enabled: stored?.enabled === true,
-      relayUrl: override ?? normalizeRelayUrl(stored?.relayUrl),
+      relayUrl: resolveEffectiveRelayUrl({ settings }),
       // True when the endpoint is pinned by OPENCHAMBER_RELAY_URL (a self-hosted
       // relay); the stored setting is ignored while it is set.
       relayUrlLocked: override !== null,
     };
   };
 
+  const notifyRelayUrlChanged = async () => {
+    if (typeof onRelayUrlChanged !== 'function') return;
+    try {
+      await onRelayUrlChanged();
+    } catch (error) {
+      logger.warn(`[Relay] push token re-register failed: ${error?.message ?? error}`);
+    }
+  };
+
   const writeConfig = async (config) => {
     const settings = await readSettingsFromDiskMigrated();
     await writeSettingsToDisk({
@@ -365,6 +399,10 @@ export const createRelayService = ({
     if (!config.enabled || endpointChanged) {
       await writeConfig({ enabled: true, relayUrl });
     }
+    const next = await readConfig();
+    if (next.relayUrl !== config.relayUrl) {
+      await notifyRelayUrlChanged();
+    }
     if (endpointChanged) {
       // One Host identity can have only one live Relay control connection. A
       // custom endpoint therefore becomes the authoritative transport before
@@ -409,6 +447,10 @@ export const createRelayService = ({
           relayUrl = canonical;
         }
         await writeConfig({ enabled: true, relayUrl });
+        const next = await readConfig();
+        if (next.relayUrl !== current.relayUrl) {
+          await notifyRelayUrlChanged();
+        }
         if (hostClient) stop();
         // Explicit user action: take the machine's host claim like pairing does.
         await start(relayUrl, { claim: 'force' });

package/server/lib/relay/service.test.js

@@ -34,8 +34,10 @@ vi.mock('./host-client.js', () => ({
 import {
   createRelayService,
   DEFAULT_RELAY_URL,
+  derivePushSendUrlFromRelayUrl,
   isRelayHostRuntime,
   RELAY_HOST_DESKTOP_ONLY_MESSAGE,
+  resolveEffectiveRelayUrl,
 } from './service.js';
 
 const createSettingsHarness = () => {
@@ -60,6 +62,59 @@ const createTestRelayService = ({ canHostRelay = true, ...overrides } = {}) => {
   return { service, settings };
 };
 
+describe('derivePushSendUrlFromRelayUrl', () => {
+  it('converts wss and ws canonical relay URLs to the fixed push send path', () => {
+    expect(derivePushSendUrlFromRelayUrl('wss://relay.openchamber.dev/ws')).toBe(
+      'https://relay.openchamber.dev/v1/push/send',
+    );
+    expect(derivePushSendUrlFromRelayUrl('ws://127.0.0.1:8787/custom')).toBe(
+      'http://127.0.0.1:8787/v1/push/send',
+    );
+    expect(derivePushSendUrlFromRelayUrl('wss://relay.example:8443/any/path?token=secret#frag')).toBe(
+      'https://relay.example:8443/v1/push/send',
+    );
+  });
+
+  it('rejects userinfo and non-ws(s) URLs', () => {
+    expect(derivePushSendUrlFromRelayUrl('wss://user:pass@relay.example/ws')).toBeNull();
+    expect(derivePushSendUrlFromRelayUrl('https://relay.openchamber.dev/ws')).toBeNull();
+    expect(derivePushSendUrlFromRelayUrl('http://relay.example/v1/push/send')).toBeNull();
+    expect(derivePushSendUrlFromRelayUrl('')).toBeNull();
+    expect(derivePushSendUrlFromRelayUrl(null)).toBeNull();
+  });
+});
+
+describe('resolveEffectiveRelayUrl', () => {
+  afterEach(() => {
+    delete process.env.OPENCHAMBER_RELAY_URL;
+  });
+
+  it('prefers a valid env URL, then settings, then the default', () => {
+    expect(resolveEffectiveRelayUrl()).toBe(DEFAULT_RELAY_URL);
+    expect(
+      resolveEffectiveRelayUrl({
+        settings: { privateRelay: { relayUrl: 'wss://settings.example/ws' } },
+      }),
+    ).toBe('wss://settings.example/ws');
+
+    process.env.OPENCHAMBER_RELAY_URL = 'wss://env.example/ws?x=1#frag';
+    expect(
+      resolveEffectiveRelayUrl({
+        settings: { privateRelay: { relayUrl: 'wss://settings.example/ws' } },
+      }),
+    ).toBe('wss://env.example/ws');
+  });
+
+  it('ignores an invalid env URL and falls through to settings', () => {
+    process.env.OPENCHAMBER_RELAY_URL = 'https://not-a-relay.example/ws';
+    expect(
+      resolveEffectiveRelayUrl({
+        settings: { privateRelay: { relayUrl: 'wss://settings.example/ws' } },
+      }),
+    ).toBe('wss://settings.example/ws');
+  });
+});
+
 describe('relay service pairing endpoint', () => {
   afterEach(() => {
     relayMocks.starts.length = 0;
@@ -142,6 +197,68 @@ describe('relay service pairing endpoint', () => {
     });
     expect(relayMocks.starts).toEqual(['wss://relay.example/custom']);
   });
+
+  it('invokes onRelayUrlChanged only when the canonical URL actually changes', async () => {
+    const onRelayUrlChanged = vi.fn(async () => {});
+    const { service } = createTestRelayService({ onRelayUrlChanged });
+
+    await service.ensureEnabledForPairing();
+    expect(onRelayUrlChanged).not.toHaveBeenCalled();
+
+    await service.ensureEnabledForPairing('wss://relay.example/custom');
+    expect(onRelayUrlChanged).toHaveBeenCalledTimes(1);
+
+    await service.ensureEnabledForPairing('wss://relay.example/custom?x=1#frag');
+    expect(onRelayUrlChanged).toHaveBeenCalledTimes(1);
+
+    const app = express();
+    service.registerRoutes(app);
+    await request(app)
+      .post('/api/openchamber/relay/enable')
+      .send({ relayUrl: 'wss://relay.example/other' })
+      .expect(200);
+    expect(onRelayUrlChanged).toHaveBeenCalledTimes(2);
+
+    await request(app)
+      .post('/api/openchamber/relay/enable')
+      .send({ relayUrl: 'wss://relay.example/other' })
+      .expect(200);
+    expect(onRelayUrlChanged).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not invoke onRelayUrlChanged for an env-pinned relay and still uses the pin', async () => {
+    process.env.OPENCHAMBER_RELAY_URL = 'wss://pinned.example/ws';
+    const onRelayUrlChanged = vi.fn(async () => {});
+    const { service } = createTestRelayService({ onRelayUrlChanged });
+    const app = express();
+    service.registerRoutes(app);
+
+    const candidate = await service.ensureEnabledForPairing('wss://ignored.example/ws');
+    expect(candidate.relayUrl).toBe('wss://pinned.example/ws');
+    expect(onRelayUrlChanged).not.toHaveBeenCalled();
+
+    await request(app)
+      .post('/api/openchamber/relay/enable')
+      .send({ relayUrl: 'wss://ignored.example/ws' })
+      .expect(200);
+    expect(onRelayUrlChanged).not.toHaveBeenCalled();
+    expect((await service.getStatus()).relayUrl).toBe('wss://pinned.example/ws');
+  });
+
+  it('continues the relay switch when onRelayUrlChanged fails', async () => {
+    const onRelayUrlChanged = vi.fn(async () => {
+      throw new Error('push relay unavailable');
+    });
+    const logger = { warn: vi.fn() };
+    const { service } = createTestRelayService({ onRelayUrlChanged, logger });
+
+    await expect(service.ensureEnabledForPairing('wss://relay.example/custom')).resolves.toMatchObject({
+      relayUrl: 'wss://relay.example/custom',
+    });
+    expect(onRelayUrlChanged).toHaveBeenCalledTimes(1);
+    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('push token re-register failed'));
+    expect(relayMocks.starts).toEqual(['wss://relay.example/custom']);
+  });
 });
 
 describe('relay host runtime gate', () => {

package/server/lib/relay/signing-key.js

@@ -49,7 +49,7 @@ export const getOrCreateRelaySigningKeypair = async ({ crypto, readSettingsFromD
 };
 
 // Fixed key order so the hash is stable regardless of stored JSON field order.
-// Byte-for-byte mirror of canonicalJwk in openchamber-website apps/api relay-auth.ts.
+// Byte-for-byte mirror of canonicalPublicJwkString in packages/relay-server/src/push/crypto.js.
 /** @param {JsonWebKey} jwk */
 export const canonicalPublicJwkString = (jwk) =>
   JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y });

package/server/lib/session-goal/DOCUMENTATION.md

@@ -3,7 +3,7 @@
 Server-side control loop that keeps a session working toward a user-defined
 objective stored under `metadata.openchamber.goal`, with the small model as
 an independent progress auditor. Built on OpenChamber's backend-driven
-architecture (session-assist is the structural template): the loop lives in
+architecture: the loop lives in
 the web server and survives UI disconnects.
 
 ## Goal payload (`metadata.openchamber.goal`)
@@ -69,8 +69,8 @@ before touching the filesystem). Rationale: metadata rides every
 
 ## Flow
 
-1. `createSessionGoalRuntime` subscribes to the global SSE hub (same pattern
-   as session-assist — it needs the envelope's `directory`).
+1. `createSessionGoalRuntime` subscribes to the global SSE hub (it needs
+   the envelope's `directory`).
 2. `session.status: idle` arms a 15s per-session timer; `busy`/`retry` clears
    it. A `session.updated` carrying a fresh active goal (`turnsUsed === 0` or
    `statusReason === 'resumed'`) arms a kickoff timer — 3s for fresh goals,