@openchambery/web 1.17.1 → 1.18.1

package/server/lib/desktop-hosts/routes.test.js

@@ -0,0 +1,227 @@
+import { describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+
+import { registerDesktopHostRoutes } from './routes.js';
+
+const baseSettings = {
+  desktopSshInstances: [{ id: 'ssh-1' }, { id: 'ssh-2' }],
+  desktopHosts: [
+    { id: 'ssh-1', clientToken: 'ssh-token-1' },
+    { id: 'ssh-2', clientToken: 'ssh-token-2' },
+    { id: 'lan-other', clientToken: 'other-token' },
+  ],
+};
+
+const createApp = ({
+  settings = baseSettings,
+  getSshRoutingTable = () => [],
+  getPairingSession,
+  mintSshHostToken,
+  logger = { warn: vi.fn(), error: vi.fn() },
+} = {}) => {
+  const app = express();
+  registerDesktopHostRoutes(app, {
+    express,
+    readSettingsFromDiskMigrated: async () => settings,
+    getSshRoutingTable,
+    getPairingSession,
+    mintSshHostToken,
+    logger,
+  });
+  return { app, logger };
+};
+
+describe('desktop host routes', () => {
+  it('lists SSH hosts with reachable from the routing table and never returns clientToken', async () => {
+    const { app } = createApp({
+      settings: {
+        desktopSshInstances: [
+          { id: 'ssh-1', nickname: 'Remote A', localForward: { preferredLocalPort: 41001 } },
+          { id: 'ssh-2', nickname: 'Remote B', localForward: { preferredLocalPort: 41002 } },
+        ],
+        desktopHosts: [
+          { id: 'ssh-1', label: 'Remote A', clientToken: 'secret-a' },
+          { id: 'ssh-2', label: 'Remote B', clientToken: 'secret-b' },
+          { id: 'lan-other', label: 'Other', clientToken: 'secret-other' },
+        ],
+      },
+      getSshRoutingTable: () => [{ id: 'ssh-1', localPort: 41234 }],
+    });
+
+    const res = await request(app).get('/api/openchamber/desktop-hosts');
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({
+      hosts: [
+        { id: 'ssh-1', label: 'Remote A', localPort: 41234, reachable: true },
+        { id: 'ssh-2', label: 'Remote B', localPort: 41002, reachable: false },
+      ],
+    });
+    expect(JSON.stringify(res.body)).not.toContain('secret');
+    expect(JSON.stringify(res.body)).not.toContain('clientToken');
+  });
+
+  it('issues token with localPort/reachable when pairingId matches a redeemed session', async () => {
+    const getPairingSession = vi.fn(async (id) => {
+      if (id !== 'pair_ok') return null;
+      return { id: 'pair_ok', sshHostId: 'ssh-1', usedAt: '2026-01-01T00:00:00.000Z' };
+    });
+    const { app, logger } = createApp({
+      getSshRoutingTable: () => [{ id: 'ssh-1', localPort: 41234 }],
+      getPairingSession,
+    });
+
+    const ok = await request(app)
+      .post('/api/openchamber/ssh-host-token')
+      .send({ hostId: 'ssh-1', pairingId: 'pair_ok' });
+    expect(ok.status).toBe(200);
+    expect(ok.headers['cache-control']).toBe('no-store');
+    expect(ok.body).toEqual({
+      token: 'ssh-token-1',
+      localPort: 41234,
+      reachable: true,
+    });
+    expect(getPairingSession).toHaveBeenCalledWith('pair_ok');
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it('returns 403 when pairingId sshHostId does not match hostId', async () => {
+    const { app } = createApp({
+      getPairingSession: async () => ({
+        id: 'pair_x',
+        sshHostId: 'ssh-2',
+        usedAt: '2026-01-01T00:00:00.000Z',
+      }),
+    });
+
+    const res = await request(app)
+      .post('/api/openchamber/ssh-host-token')
+      .send({ hostId: 'ssh-1', pairingId: 'pair_x' });
+    expect(res.status).toBe(403);
+    expect(res.body).toEqual({ error: 'pairing-mismatch' });
+  });
+
+  it('returns 403 when pairing session is not redeemed', async () => {
+    const { app } = createApp({
+      getPairingSession: async () => ({
+        id: 'pair_pending',
+        sshHostId: 'ssh-1',
+        usedAt: null,
+      }),
+    });
+
+    const res = await request(app)
+      .post('/api/openchamber/ssh-host-token')
+      .send({ hostId: 'ssh-1', pairingId: 'pair_pending' });
+    expect(res.status).toBe(403);
+    expect(res.body).toEqual({ error: 'pairing-mismatch' });
+  });
+
+  it('returns 403 when pairingId is unknown', async () => {
+    const { app } = createApp({
+      getPairingSession: async () => null,
+    });
+
+    const res = await request(app)
+      .post('/api/openchamber/ssh-host-token')
+      .send({ hostId: 'ssh-1', pairingId: 'pair_missing' });
+    expect(res.status).toBe(403);
+    expect(res.body).toEqual({ error: 'pairing-mismatch' });
+  });
+
+  it('allows legacy mint without pairingId and logs a deprecation warning', async () => {
+    const { app, logger } = createApp({
+      getSshRoutingTable: () => [{ id: 'ssh-1', localPort: 41234 }],
+    });
+
+    const ok = await request(app)
+      .post('/api/openchamber/ssh-host-token')
+      .send({ hostId: 'ssh-1' });
+    expect(ok.status).toBe(200);
+    expect(ok.headers['cache-control']).toBe('no-store');
+    expect(ok.body).toEqual({
+      token: 'ssh-token-1',
+      localPort: 41234,
+      reachable: true,
+    });
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+    expect(String(logger.warn.mock.calls[0][0])).toMatch(/deprecated/i);
+  });
+
+  it('returns reachable false and localPort null when routing table misses', async () => {
+    const { app } = createApp({
+      getSshRoutingTable: () => [],
+      getPairingSession: async () => ({
+        id: 'pair_ok',
+        sshHostId: 'ssh-1',
+        usedAt: '2026-01-01T00:00:00.000Z',
+      }),
+    });
+
+    const res = await request(app)
+      .post('/api/openchamber/ssh-host-token')
+      .send({ hostId: 'ssh-1', pairingId: 'pair_ok' });
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({
+      token: 'ssh-token-1',
+      localPort: null,
+      reachable: false,
+    });
+  });
+
+  it('returns 404 for missing / non-SSH / tokenless hosts', async () => {
+    const { app } = createApp();
+
+    const missing = await request(app)
+      .post('/api/openchamber/ssh-host-token')
+      .send({ hostId: 'missing' });
+    expect(missing.status).toBe(404);
+
+    const nonSsh = await request(app)
+      .post('/api/openchamber/ssh-host-token')
+      .send({ hostId: 'lan-other' });
+    expect(nonSsh.status).toBe(404);
+
+    const { app: noTokenApp } = createApp({
+      settings: {
+        desktopSshInstances: [{ id: 'ssh-empty' }],
+        desktopHosts: [{ id: 'ssh-empty' }],
+      },
+    });
+    const noToken = await request(noTokenApp)
+      .post('/api/openchamber/ssh-host-token')
+      .send({ hostId: 'ssh-empty' });
+    expect(noToken.status).toBe(404);
+  });
+
+  it('mints a token on demand when the stored SSH host is tokenless', async () => {
+    const mintSshHostToken = vi.fn(async (hostId) => {
+      expect(hostId).toBe('ssh-empty');
+      return 'minted-on-demand';
+    });
+    const { app } = createApp({
+      settings: {
+        desktopSshInstances: [{ id: 'ssh-empty' }],
+        desktopHosts: [{ id: 'ssh-empty' }],
+      },
+      getSshRoutingTable: () => [{ id: 'ssh-empty', localPort: 41234 }],
+      getPairingSession: async () => ({
+        id: 'pair_ok',
+        sshHostId: 'ssh-empty',
+        usedAt: '2026-01-01T00:00:00.000Z',
+      }),
+      mintSshHostToken,
+    });
+
+    const res = await request(app)
+      .post('/api/openchamber/ssh-host-token')
+      .send({ hostId: 'ssh-empty', pairingId: 'pair_ok' });
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({
+      token: 'minted-on-demand',
+      localPort: 41234,
+      reachable: true,
+    });
+    expect(mintSshHostToken).toHaveBeenCalledWith('ssh-empty');
+  });
+});

package/server/lib/message-queue/DOCUMENTATION.md

@@ -20,7 +20,7 @@ Import staging accepts canonical payloads with scope/item ordinals, payload hash
 
 There is no long-lived "dormant module" state in production: cutover is explicit `shadow` → `active` (with optional `paused`). Documentation that previously described the production v3 queue as authoritative while this module stayed dormant is obsolete once authority is `active`.
 
-Scopes key records by the server-derived runtime key, normalized directory, and session ID. Stateless Assistant clients use the stable synthetic session ID `assistant:<assistantID>` for this existing scope contract; execution still uses a fresh captured-workspace OpenCode Session per item. Client transport identity stays outside durable keys. Each scope exposes a stable `scopeID`, revision, and worktree lifecycle state. Edit reservations fence ordinary edit, removal, and manual-send mutations for their exact queue item only; they never fence reorder or unrelated rows in the scope. Reservation renewal binds queue item ID, token, and current authority generation; it accepts a bounded TTL until its durable expiry timestamp, commits only the expiry field in an immediate transaction, and leaves scope and global revisions unchanged. Reserved removal presents its token and authority generation in the same SQLite delete CAS. Releasing a reservation wakes the worker.
+Scopes key records by the server-derived runtime key, normalized directory, and session ID. Stateless Assistant clients use the stable synthetic session ID `assistant:<assistantID>` for this existing scope contract; execution still uses a fresh captured-workspace OpenCode Session per item. Client transport identity stays outside durable keys. Each scope exposes a stable `scopeID`, revision, and worktree lifecycle state. A runtime holds at most 128 scopes; creating a new scope at the cap first evicts the oldest empty scopes (LRU by `updated_at`, scope ID tiebreak — safe because `queue_item` is the only foreign key into `queue_scope`), and admission fails with `scope_limit` (HTTP 409) only when every scope still holds items. Edit reservations fence ordinary edit, removal, and manual-send mutations for their exact queue item only; they never fence reorder or unrelated rows in the scope. Reservation renewal binds queue item ID, token, and current authority generation; it accepts a bounded TTL until its durable expiry timestamp, commits only the expiry field in an immediate transaction, and leaves scope and global revisions unchanged. Reserved removal presents its token and authority generation in the same SQLite delete CAS. Releasing a reservation wakes the worker.
 
 ## Per-item sendConfig
 

package/server/lib/message-queue/routes.js

@@ -1,5 +1,5 @@
 const prefix = '/api/openchamber/message-queue';
-const statusFor = (error) => ({ validation_error: 400, not_found: 404, revision_conflict: 409, row_version_conflict: 409, idempotency_conflict: 409, generation_conflict: 409, authority_conflict: 409, scope_locked: 409, reserved: 409, reservation_expired: 409, reservation_generation_conflict: 409, reservation_token_mismatch: 409, attachment_unavailable: 404, attachment_total_limit: 413, admission_payload_limit: 413, attachment_store_not_found: 404, attachment_store_max_bytes: 413, attachment_store_size_mismatch: 400, attachment_store_hash_mismatch: 400, attachment_store_aborted: 499 })[error?.code] ?? 500;
+const statusFor = (error) => ({ validation_error: 400, not_found: 404, revision_conflict: 409, row_version_conflict: 409, idempotency_conflict: 409, generation_conflict: 409, authority_conflict: 409, scope_locked: 409, scope_limit: 409, reserved: 409, reservation_expired: 409, reservation_generation_conflict: 409, reservation_token_mismatch: 409, attachment_unavailable: 404, attachment_total_limit: 413, admission_payload_limit: 413, attachment_store_not_found: 404, attachment_store_max_bytes: 413, attachment_store_size_mismatch: 400, attachment_store_hash_mismatch: 400, attachment_store_aborted: 499 })[error?.code] ?? 500;
 const publicCode = (error) => statusFor(error) === 500 ? 'internal_error' : error.code;
 const unsupported = (res) => res.status(501).json({ code: 'unavailable' });
 const send = (res, action) => { try { res.json(action()); } catch (error) { const status = statusFor(error); if (status === 500) console.error('[message-queue] route failed', error); res.status(status).json({ code: publicCode(error) }); } };

package/server/lib/message-queue/routes.test.js

@@ -20,6 +20,7 @@ describe('message queue routes', () => {
   });
   it('maps stable errors to code-only responses', () => { const { app, route } = registry(); registerMessageQueueRoutes(app, { messageQueueService: { admit: () => { const error = new Error('private detail'); error.code = 'attachment_total_limit'; throw error; } } }); const res = response(); route('POST', `${prefix}/items`)({ body: {} }, res); expect(res).toMatchObject({ statusCode: 413, body: { code: 'attachment_total_limit' } }); });
   it('maps admission payload limits to 413', () => { const { app, route } = registry(); registerMessageQueueRoutes(app, { messageQueueService: { admit: () => { const error = new Error('private detail'); error.code = 'admission_payload_limit'; throw error; } } }); const res = response(); route('POST', `${prefix}/items`)({ body: {} }, res); expect(res).toMatchObject({ statusCode: 413, body: { code: 'admission_payload_limit' } }); });
+  it('maps scope capacity exhaustion to 409 scope_limit', () => { const { app, route } = registry(); registerMessageQueueRoutes(app, { messageQueueService: { admit: () => { const error = new Error('private detail'); error.code = 'scope_limit'; throw error; } } }); const res = response(); route('POST', `${prefix}/items`)({ body: {} }, res); expect(res).toMatchObject({ statusCode: 409, body: { code: 'scope_limit' } }); });
   it('wakes the runtime after a successful admit', () => {
     const { app, route } = registry();
     const admit = vi.fn(() => ({ revision: 1, queueItemID: 'item' }));

package/server/lib/message-queue/service.js

@@ -371,11 +371,22 @@ export const createMessageQueueService = ({ dbPath, getRuntimeConfig = () => nul
     if (excess) db.prepare('DELETE FROM operation_receipt WHERE rowid IN (SELECT rowid FROM operation_receipt WHERE runtime_key = ? ORDER BY created_at, rowid LIMIT ?)').run(key, excess);
     db.prepare('INSERT INTO operation_receipt(runtime_key,request_id,operation_type,payload_hash,response_json,committed_revision,created_at) VALUES (?,?,?,?,?,?,?)').run(key, requestID, operationType, payloadHash, JSON.stringify(response), revision, now());
   };
+  // Empty scopes carry no durable queue rows (queue_item is the sole FK into
+  // queue_scope), so LRU eviction cannot strand items, attempts, receipts, or
+  // completions; worktree lifecycle state lives in its own table and scopes
+  // re-create from it on demand.
+  const evictEmptyScopes = (key, slots) => db.prepare(`DELETE FROM queue_scope WHERE runtime_key = ? AND scope_id IN (
+    SELECT s.scope_id FROM queue_scope s WHERE s.runtime_key = ? AND NOT EXISTS (SELECT 1 FROM queue_item i WHERE i.scope_id = s.scope_id)
+    ORDER BY s.updated_at, s.scope_id LIMIT ?
+  )`).run(key, key, slots);
   const ensureScope = (scope, key) => {
     const directory = normalizeDirectory(scope.directory); const scopeID = scopeIDFor(key, directory, scope.sessionID);
     const state = lifecycle(key, directory)?.state ?? 'active';
     db.prepare('INSERT OR IGNORE INTO worktree_lifecycle(runtime_key,directory,state,deletion_token,updated_at) VALUES (?,?,?,NULL,?)').run(key, directory, state, now());
-    if (!scopeRow(scopeID) && Number(db.prepare('SELECT COUNT(*) AS count FROM queue_scope WHERE runtime_key = ?').get(key).count) >= MAX_SCOPES) fail('validation_error');
+    if (!scopeRow(scopeID)) {
+      const count = db.prepare('SELECT COUNT(*) AS count FROM queue_scope WHERE runtime_key = ?').get(key).count;
+      if (count >= MAX_SCOPES) { evictEmptyScopes(key, count - MAX_SCOPES + 1); if (Number(db.prepare('SELECT COUNT(*) AS count FROM queue_scope WHERE runtime_key = ?').get(key).count) >= MAX_SCOPES) fail('scope_limit'); }
+    }
     db.prepare('INSERT OR IGNORE INTO queue_scope(scope_id,runtime_key,directory,session_id,revision,worktree_state,created_at,updated_at) VALUES (?,?,?,?,0,?,?,?)').run(scopeID, key, directory, scope.sessionID, state, now(), now());
     return scopeRow(scopeID);
   };

package/server/lib/message-queue/service.test.js

@@ -969,4 +969,34 @@ describe('message queue service', () => {
     const overflow = stage('late-overflow', [addition('three')]); expect(() => service.commitLateImport({ requestID: 'late-overflow-commit', importID: overflow.created.importID, expectedGeneration: 1, manifestHash: overflow.sealed.manifestHash, protocol: 4 })).toThrow(expect.objectContaining({ code: 'validation_error' }));
     service.close();
   });
+
+  it('evicts oldest empty scopes when admission reaches the scope cap', () => {
+    const service = createService(dbPath());
+    const admissionFor = (suffix) => ({ requestID: `request-${suffix}`, scope: { directory: '/repo', sessionID: `session-${suffix}` }, item: { queueItemID: `item-${suffix}`, operationID: `operation-${suffix}`, messageID: `message-${suffix}`, content: 'hello', attachments: [], attachmentIssues: [], createdAt: 100 } });
+    let retained; const emptied = [];
+    for (let index = 0; index < 128; index += 1) {
+      const result = service.admit(admissionFor(index));
+      if (index === 0) { retained = result; continue; }
+      service.remove({ requestID: `remove-${index}`, queueItemID: result.queueItemID, expectedRevision: result.revision, expectedRowVersion: 1 });
+      emptied.push(result.scopeID);
+    }
+    expect(service.snapshot().scopes).toHaveLength(128);
+    const fresh = service.admit(admissionFor('fresh'));
+    expect(service.getScope(fresh.scopeID).items).toHaveLength(1);
+    expect(service.snapshot().scopes).toHaveLength(128);
+    const remaining = new Set(service.snapshot().scopes.map((scope) => scope.scopeID));
+    expect(remaining.has(fresh.scopeID)).toBe(true);
+    expect(remaining.has(retained.scopeID)).toBe(true);
+    expect(emptied.filter((scopeID) => remaining.has(scopeID))).toHaveLength(emptied.length - 1);
+    expect(service.getScope(retained.scopeID).items[0]).toMatchObject({ queueItemID: retained.queueItemID });
+    service.close();
+  });
+
+  it('fails admission with scope_limit when every scope at the cap still holds items', () => {
+    const service = createService(dbPath());
+    const admissionFor = (suffix) => ({ requestID: `request-${suffix}`, scope: { directory: '/repo', sessionID: `session-${suffix}` }, item: { queueItemID: `item-${suffix}`, operationID: `operation-${suffix}`, messageID: `message-${suffix}`, content: 'hello', attachments: [], attachmentIssues: [], createdAt: 100 } });
+    for (let index = 0; index < 128; index += 1) service.admit(admissionFor(index));
+    expect(() => service.admit(admissionFor('overflow'))).toThrow(expect.objectContaining({ code: 'scope_limit' }));
+    service.close();
+  });
 });

package/server/lib/opencode/DOCUMENTATION.md

@@ -8,7 +8,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/auth.js`: provider authentication file operations.
 - `packages/web/server/lib/opencode/auth-state-runtime.js`: managed OpenCode server auth password/header runtime.
 - `packages/web/server/lib/opencode/cli-options.js`: CLI/environment option parsing for server startup arguments.
-- `packages/web/server/lib/opencode/cli-entry-runtime.js`: CLI entrypoint runtime that detects direct execution, parses CLI options, and starts server bootstrap.
+- `packages/web/server/lib/opencode/cli-entry-runtime.js`: CLI entrypoint runtime that detects direct execution, forces `OPENCHAMBER_RUNTIME=web` (so `dev:server` cannot inherit a leftover desktop env and host a relay), parses CLI options, and starts server bootstrap.
 - `packages/web/server/lib/opencode/routes.js`: OpenCode/provider settings and auth-related route registration.
 - `packages/web/server/lib/opencode/lifecycle.js`: OpenCode process lifecycle runtime (startup, restart, readiness, health monitoring). Managed child env inherits the user shell environment unchanged; experimental flags such as `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS` follow the user's own environment and are never injected by OpenChamber.
 - `packages/web/server/lib/opencode/managed-capabilities-runtime.js`: managed-child scheduled-task resources, config injection, rotating bridge identity, and bridge authorization.
@@ -33,7 +33,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/tunnel-wiring-runtime.js`: active loopback-port wiring shared by pairing/LAN URLs and the private relay host.
 - `packages/web/server/lib/opencode/startup-pipeline-runtime.js`: server startup tail orchestration runtime for terminal/proxy/static/start-listen flow.
 - `packages/web/server/lib/opencode/server-utils-runtime.js`: shared server runtime utilities for OpenCode proxy wiring, OpenCode port/readiness helpers, and snapshot fetchers.
-- `packages/web/server/lib/opencode/openchamber-routes.js`: OpenChamber update, models metadata, session-index, and transcript-cache route registration.
+- `packages/web/server/lib/opencode/openchamber-routes.js`: OpenChamber update, models metadata, session-index, transcript-cache, and desktop SSH host-token route registration. Tokenless ready SSH hosts may mint a client token on demand via Electron `mintSshHostToken`, which authenticates to the forwarded remote with the in-memory tunnel UI password.
 - `packages/web/server/lib/transcript-cache/`: opt-in Electron/local SQLite transcript cache (`/api/openchamber/transcript-cache`); default path is null so remote Web servers do not persist conversation bodies. See `transcript-cache/DOCUMENTATION.md`.
 - `packages/web/server/lib/opencode/pwa-manifest-routes.js`: PWA manifest route registration with recent-session shortcut resolution and short-lived caching.
 - `packages/web/server/lib/opencode/project-icon-routes.js`: project icon upload/read/discovery route registration and icon storage orchestration.
@@ -273,7 +273,7 @@ When adding or changing Host HTTP APIs that mobile/desktop clients reach over Pr
    - `DELETE /api/passkeys/:id`
    - `POST /api/auth/reset`
     - `POST /api/client-auth/pairing/sessions`: accepts an optional `relayUrl` when Relay is included. An owner UI session or the local `desktop-local` shell client may set a custom endpoint (other client bearers receive HTTP 403). Canonical form is `ws://`/`wss://` scheme/host/path: userinfo is rejected (HTTP 400); query and fragment are stripped and are not part of endpoint identity. The Host persists the switch and reconnects its control connection before returning the pairing-v2 Relay candidate; an `OPENCHAMBER_RELAY_URL` override stays authoritative.
-   - `GET /api/client-auth/pairing/transports`: returns direct transport availability plus the effective Relay URL and whether the environment pins it.
+    - `GET /api/client-auth/pairing/transports`: returns direct transport availability. `relayAvailable` is true only for the Electron desktop host; local `dev` / `web` / CLI servers report false and omit Relay URL fields so the create-device dialog never defaults to Anywhere or probes the relay.
    - `GET /connect`
    - `POST /api/system/probe-url`
    - `app.use('/api', ...)` auth/tunnel guard
@@ -294,7 +294,7 @@ When adding or changing Host HTTP APIs that mobile/desktop clients reach over Pr
   - Legacy `--tunnel` shorthand normalization
 
 ## Public exports (cli-entry-runtime.js)
-- `runCliEntryIfMain(dependencies)`: detects direct CLI execution and runs server startup with parsed CLI options.
+- `runCliEntryIfMain(dependencies)`: detects direct CLI execution, forces `OPENCHAMBER_RUNTIME=web` so a leftover desktop env cannot host or probe a relay, and runs server startup with parsed CLI options.
 
 ## Public exports (server-utils-runtime.js)
 - `createServerUtilsRuntime(dependencies)`: creates server utility runtime for OpenCode orchestration helpers.

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

@@ -61,6 +61,9 @@ export const createBootstrapRuntime = (dependencies) => {
       sessionIndexService,
       sessionIndexSyncRuntime,
       transcriptCacheService,
+      getSshRoutingTable,
+      mintSshHostToken,
+      getPairingSession,
     } = options;
 
     const uiAuthController = createUiAuth({
@@ -149,6 +152,10 @@ export const createBootstrapRuntime = (dependencies) => {
       sessionIndexService,
       sessionIndexSyncRuntime,
       transcriptCacheService,
+      getSshRoutingTable,
+      mintSshHostToken,
+      getPairingSession,
+      express,
     });
 
     return {

package/server/lib/opencode/cli-entry-runtime.js

@@ -13,6 +13,12 @@ export const runCliEntryIfMain = (dependencies) => {
     return;
   }
 
+  // Direct `node server/index.js` is the standalone web/dev server. Never inherit
+  // OPENCHAMBER_RUNTIME=desktop from the parent shell — that would open a relay
+  // host-control socket from `bun run dev` / `dev:server`. Electron sets desktop
+  // before importing this module and never takes this CLI path.
+  process.env.OPENCHAMBER_RUNTIME = 'web';
+
   const cliOptions = parseServeCliOptions({
     argv: process.argv.slice(2),
     env: process.env,

package/server/lib/opencode/cli-entry-runtime.test.js

@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { runCliEntryIfMain } from './cli-entry-runtime.js';
+
+describe('cli-entry-runtime', () => {
+  const previousRuntime = process.env.OPENCHAMBER_RUNTIME;
+
+  afterEach(() => {
+    if (previousRuntime === undefined) delete process.env.OPENCHAMBER_RUNTIME;
+    else process.env.OPENCHAMBER_RUNTIME = previousRuntime;
+  });
+
+  it('forces OPENCHAMBER_RUNTIME=web on the direct node server path even if the parent shell leaked desktop', () => {
+    process.env.OPENCHAMBER_RUNTIME = 'desktop';
+    const startServer = vi.fn(async () => {});
+
+    runCliEntryIfMain({
+      process: { argv: ['node', '/tmp/server/index.js', '--port', '3001'], env: process.env, exit: vi.fn() },
+      currentFilename: '/tmp/server/index.js',
+      parseServeCliOptions: () => ({ port: 3001, host: undefined, uiPassword: null, apiOnly: false }),
+      defaultPort: 3001,
+      setExitOnShutdown: vi.fn(),
+      startServer,
+    });
+
+    expect(process.env.OPENCHAMBER_RUNTIME).toBe('web');
+    expect(startServer).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not rewrite OPENCHAMBER_RUNTIME when imported as a library (Electron in-process)', () => {
+    process.env.OPENCHAMBER_RUNTIME = 'desktop';
+
+    runCliEntryIfMain({
+      process: { argv: ['electron', '/tmp/electron/main.mjs'], env: process.env, exit: vi.fn() },
+      currentFilename: '/tmp/server/index.js',
+      parseServeCliOptions: vi.fn(),
+      defaultPort: 3001,
+      setExitOnShutdown: vi.fn(),
+      startServer: vi.fn(),
+    });
+
+    expect(process.env.OPENCHAMBER_RUNTIME).toBe('desktop');
+  });
+});

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

@@ -395,7 +395,7 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
     // Returns { local, lan, relayAvailable } — the direct transport URLs the
     // server can actually be reached on (LAN derived from the server bind, not
     // the UI origin), for the create-device dialog.
-    getPairingTransports = () => ({ local: null, lan: null, relayAvailable: true }),
+    getPairingTransports = () => ({ local: null, lan: null, relayAvailable: false }),
     // Returns ALL direct LAN URLs the server is currently reachable on (client-
     // reached address first, then interface scan) for the candidates-refresh
     // endpoint. Empty when the server is loopback-only.
@@ -871,6 +871,9 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
         allowedClientKinds: req.body?.allowedClientKinds,
         createdByClientId: clientIdFromAuthContext(authContext),
         usesRelay,
+        // Optional SSH instance id: binds mobile ssh-host-token mint to this
+        // pairing after redeem. Does not affect redeem itself.
+        sshHostId: req.body?.sshHostId,
       });
       void reconcileRelay();
       res.setHeader('Cache-Control', 'no-store');

package/server/lib/opencode/core-routes.test.js

@@ -774,9 +774,24 @@ describe('core-routes', () => {
       allowedClientKinds: ['mobile'],
       createdByClientId: null,
       usesRelay: false,
+      sshHostId: undefined,
     });
   });
 
+  it('forwards optional sshHostId into createPairingSession', async () => {
+    const { app, dependencies } = createPairingRouteApp();
+
+    await request(app)
+      .post('/api/client-auth/pairing/sessions')
+      .set('Host', 'runtime.example')
+      .send({ label: 'SSH phone', allowedClientKinds: ['mobile'], sshHostId: 'ssh-1', includeRelay: true })
+      .expect(201);
+
+    expect(dependencies.clientPairingRuntime.createPairingSession).toHaveBeenCalledWith(
+      expect.objectContaining({ sshHostId: 'ssh-1' }),
+    );
+  });
+
   it('advertises the caller-supplied serverUrl as the direct candidate over the request origin', async () => {
     const { app } = createPairingRouteApp();
 
@@ -988,6 +1003,20 @@ describe('core-routes', () => {
     expect(dependencies.clientPairingRuntime.createPairingSession).toHaveBeenCalled();
   });
 
+  it('defaults pairing transports to relay unavailable so web/dev never advertise Anywhere', async () => {
+    const { app } = createPairingRouteApp();
+
+    const response = await request(app)
+      .get('/api/client-auth/pairing/transports')
+      .expect(200);
+
+    expect(response.body).toEqual({
+      local: null,
+      lan: null,
+      relayAvailable: false,
+    });
+  });
+
   it('reports the effective Relay endpoint and environment lock to the pairing dialog', async () => {
     const { app } = createPairingRouteApp({
       getPairingTransports: vi.fn(async () => ({

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

@@ -1,5 +1,6 @@
 import { registerSessionIndexRoutes } from '../session-index/routes.js';
 import { registerTranscriptCacheRoutes } from '../transcript-cache/routes.js';
+import { registerDesktopHostRoutes } from '../desktop-hosts/routes.js';
 
 export const registerOpenChamberRoutes = (app, dependencies) => {
   const {
@@ -15,10 +16,21 @@ export const registerOpenChamberRoutes = (app, dependencies) => {
     sessionIndexService,
     sessionIndexSyncRuntime,
     transcriptCacheService,
+    getSshRoutingTable,
+    mintSshHostToken,
+    getPairingSession,
+    express,
   } = dependencies;
 
   registerSessionIndexRoutes(app, { sessionIndexService, sessionIndexSyncRuntime });
   registerTranscriptCacheRoutes(app, { transcriptCacheService });
+  registerDesktopHostRoutes(app, {
+    readSettingsFromDiskMigrated,
+    getSshRoutingTable,
+    mintSshHostToken,
+    getPairingSession,
+    express,
+  });
 
   app.get('/api/openchamber/update-check', async (req, res) => {
     try {

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

@@ -695,7 +695,7 @@ export const createSettingsRuntime = (deps) => {
     const next = { ...settings };
 
     if (typeof settings.notifyOnSubtasks !== 'boolean') {
-      next.notifyOnSubtasks = true;
+      next.notifyOnSubtasks = false;
       changed = true;
     }
     if (typeof settings.notifyOnCompletion !== 'boolean') {

package/server/lib/package-manager.js

@@ -669,7 +669,9 @@ export function getUpdateCommand(pm = detectPackageManager()) {
     case 'bun':
       return `${pmCommand} add -g ${PACKAGE_NAME}@latest`;
     default:
-      return `${pmCommand} install -g ${PACKAGE_NAME}@latest`;
+      // --force: npm refuses to overwrite an existing global bin (EEXIST) when
+      // a previous install left the bin file behind.
+      return `${pmCommand} install -g ${PACKAGE_NAME}@latest --force`;
   }
 }
 

package/server/lib/relay/DOCUMENTATION.md

@@ -19,7 +19,7 @@ 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 to Electron: non-desktop runtimes report `state: 'unavailable'`, refuse `/relay/enable` and relay pairing with 403, and never call `startRelayHost`. On desktop, started from `packages/web/server/index.js` only when demand/opt-in enables the relay. 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 to Electron: non-desktop runtimes (`bun run dev`, `dev:web:hmr`, 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` so a leftover desktop env cannot open the host-control socket. On desktop, started from `packages/web/server/index.js` only when demand/opt-in enables the relay. 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.
 - `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.
 - `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.
@@ -104,6 +104,48 @@ Relay mode plugs into the existing client transport layer rather than a parallel
 
 Catalog loaders (`loadProviders` / `loadAgents`) and assistant Query keys gate writes/caches on the **transport fingerprint**, not `runtimeKey`. On endpoint reset and same-device transport switch, `runtimeEndpointReset.ts` must set `useConfigStore.catalogTransportIdentity` to `getRuntimeTransportIdentity()`. Writing `detail.runtimeKey` there silently discards provider/agent catalog refreshes under Relay, which then hides capability-gated surfaces such as Assistants.
 
+## SSH host routing
+
+Mobile (and other relay clients) can reach a desktop's **SSH-forwarded remote OpenChamber instances** through the same private-relay tunnel that already reaches the desktop's local loopback origin. Routing is host-side only: the client selects a target local-forward port; the tunnel dispatcher dials that port on `127.0.0.1` when — and only when — it is present in the live SSH routing table.
+
+### Header contract
+
+- Header name: `x-openchamber-target-port`
+- Value: decimal port number string (e.g. `"41234"`)
+- HTTP: carried on the tunneled request headers
+- WebSocket: optional `headers` field on the `WsOpen` payload (same header name/value)
+- The dispatcher **strips** this header before forwarding to loopback (it is routing metadata, not an upstream header)
+
+### Resolution rules (`resolveTargetPort` in `tunnel-host.js`)
+
+| Condition | Result |
+|---|---|
+| Header absent | Dial `getLocalPort()` (desktop local origin) — unchanged default behavior |
+| Header present and `localPort` is in `getSshRoutingTable()` | Dial that port |
+| Header present but port missing/invalid/not in table | **Do not** fall back to the default port |
+
+HTTP miss → synthetic **503** with body `{ error: 'ssh-host-unreachable', …, source: 'relay-tunnel-host' }`.  
+WS miss → stream abort with reason `ssh-host-unreachable`.
+
+### Routing table (authoritative in memory)
+
+- Electron injects `getSshRoutingTable: () => sshManager.getRoutingTable()` into `startWebUiServer`.
+- Table entries are `{ id, localPort }` for SSH sessions whose status phase is **`ready`** and whose `localPort` is finite.
+- Degraded / connecting / disconnected sessions are absent. Settings.json is **not** the allowlist for dialing — only the live table is.
+- Non-desktop runtimes default to `() => []`.
+
+### Companion HTTP APIs (authenticated `/api` gate)
+
+- `GET /api/openchamber/desktop-hosts` → `{ hosts: [{ id, label, localPort, reachable }] }` for configured SSH instances. `reachable` is true iff the host id is in the routing table. **Never returns `clientToken`.**
+- `POST /api/openchamber/ssh-host-token` body `{ hostId }` → `{ token }` from `settings.json` `desktopHosts[].clientToken` for SSH instance hosts only. Missing / non-SSH / no token → **404**. Response includes `Cache-Control: no-store`.
+
+### Security invariants (do not regress)
+
+- Path allowlists (`isAllowedHttpPath` / `ALLOWED_WS_PATHS`) are **not** relaxed for SSH targets.
+- The dispatcher **never injects credentials**; the client still authenticates with its own bearer / `oc_url_token` against the target instance.
+- Port legitimacy is solely the in-memory routing table, not client-supplied trust and not settings alone.
+- List endpoints must not leak `clientToken`; token mint is a separate authenticated POST.
+
 ## Design invariants (do not regress)
 
 - The relay never sees plaintext application traffic; it sees only routing metadata (routing id, connection identifiers, timestamps, coarse counts).
@@ -112,5 +154,6 @@ Catalog loaders (`loadProviders` / `loadAgents`) and assistant Query keys gate w
 - The host dispatcher never injects credentials; the server authenticates each tunneled request.
 - The tunnel is transparent to the app: adding relay support to a feature should not require the feature to know the relay exists — it goes through the shared runtime transport helpers.
 - The two implementations stay byte-compatible and the wire format is versioned/negotiated so mixed client/host app versions degrade gracefully rather than break.
+- SSH target-port routing never falls back to the default local port on a routing-table miss (see "SSH host routing").
 
 For the operational rules that keep future changes (new WebSocket endpoints, transport refactors, terminal/voice porting) from breaking this, load the `relay-transport` skill.