@linxin666/dsh-remote-web-ui 0.4.0 → 0.4.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-remote-web-ui",
   "description": "Scan-to-pair remote access for the dsh web GUI that shares one official interface: a QR beside the settings button pairs phones and PCs into the same Web GUI (a portrait-touch adaptation layer for phones, full desktop on PCs) through one-time tokens and revocable device sessions, with a LAN bind toggle, optional Cloudflare tunnel, and one-click family self-update",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "icon": "icon.svg",
   "type": "module",
   "engines": {
@@ -38,7 +38,7 @@
   "license": "Apache-2.0",
   "dsh": {
     "engines": {
-      "dsh": ">=0.1.7-rc.1"
+      "dsh": ">=0.1.7-rc.2"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -57,31 +57,32 @@
     "clsx": "^2.1.1",
     "qrcode.react": "^4.2.0",
     "schemastery": "^3.18.0",
+    "yaml": "^2.8.2",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh": ">=0.1.7-rc.1",
+    "@deepseek-ai/dsh": ">=0.1.7-rc.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
-    "@deepseek-ai/dsh-agent": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-api-session-controller": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-api-workspace-controller": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-connection": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-store": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-commands": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-api-session-controller": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-api-workspace-controller": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-connection": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-store": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-commands": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.1.7-rc.2",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^22.20.0",

package/src/client/RemoteEntry.tsx

@@ -128,7 +128,7 @@ export function RemoteEntry({ wide, t }: RemoteEntryProps) {
     // unreachable origins are fenced out of the events endpoint, so opening
     // it there would just start a doomed reconnect loop.
     if (next.kind !== 'ready' && next.kind !== 'lan-required') return
-    const source = new EventSource('/api/pair/events')
+    const source = new EventSource('api/pair/events')
     eventSource.current = source
     source.onmessage = (event) => {
       try {

package/src/client/index.ts

@@ -31,11 +31,12 @@ import { readPairGatePolicy, sendHeartbeat, shouldStopHeartbeat } from './pair-a
 import {
   channelTransition,
   installRemoteChannel,
-  isLoopbackHostname,
+  pageOriginFacts,
   remoteChannelRequired,
   REMOTE_CHANNEL_BOOT_GLOBAL,
   type RemoteChannelBootSeat,
 } from './remote-channel.ts'
+import { isLocalPage } from '../remote-channel-rules.ts'
 import { FenceNotice } from './FenceNotice.tsx'
 import { reportDailyHeartbeat } from './telemetry.ts'
 import { startMobileAdapt, type RemoteAdaptGlobal } from './mobile-adapt.ts'
@@ -333,7 +334,7 @@ export function apply(ctx: ClientContext): void {
     showFenceNotice()
   }
   const channelActive = (): boolean => remoteChannelRequired(
-    window.location.hostname,
+    pageOriginFacts(window),
     settingsForm.getSnapshot(),
     hostPairingPolicy,
   )
@@ -387,7 +388,8 @@ export function apply(ctx: ClientContext): void {
   }
   settingsForm.subscribe(syncChannel)
   syncChannel()
-  if (!isLoopbackHostname(window.location.hostname) && settingsForm.getSnapshot().status !== 'ready') {
+  const pageOrigin = pageOriginFacts(window)
+  if (!isLocalPage(pageOrigin.hostname, pageOrigin.protocol, pageOrigin.transportOwnsHost) && settingsForm.getSnapshot().status !== 'ready') {
     void readPairGatePolicy().then((policy) => {
       hostPairingPolicy = policy.requirePairingForLan
       syncChannel()

package/src/client/locales.ts

@@ -15,7 +15,7 @@ export const zh = {
   'status.disconnected': '已配对设备离线',
   'status.stopped': '已停止远程访问',
   'status.lanRequired': '此功能需要局域网绑定或公网地址才能使用',
-  'status.lanRequiredHint': '当前服务仅绑定在 127.0.0.1 且未配置公网地址，手机无法访问。请在「设置 → Web 插件 → 远程访问设置」卡片中打开“局域网访问”，或用 dsh web --host 0.0.0.0 重新启动，或填写内网穿透的公网地址。',
+  'status.lanRequiredHint': '当前服务仅绑定在 127.0.0.1 且未配置公网地址，手机无法访问。请在本插件的设置卡片中打开“局域网访问”（装在全家桶里时在「设置 → Web 插件 → 远程访问设置」，单独安装时在设置 → 插件 → 本插件行），或用 dsh web --host 0.0.0.0 重新启动，或填写内网穿透的公网地址。',
   'status.loopbackRequired': '配对面板仅限本机使用',
   'status.loopbackRequiredHint': '请通过 http://127.0.0.1 打开此页面后重试；手机请使用配对链接访问。',
   'status.unreachable': '无法连接配对服务',
@@ -188,7 +188,7 @@ export const en = {
   'status.disconnected': 'Paired devices offline',
   'status.stopped': 'Remote access stopped',
   'status.lanRequired': 'This feature needs a LAN bind or a public address',
-  'status.lanRequiredHint': 'The server is bound to 127.0.0.1 and no public address is configured, so a phone cannot reach it. Turn on LAN access in the settings card under Settings → Web Plugins → Remote access, or restart with dsh web --host 0.0.0.0, or set the tunneled public address.',
+  'status.lanRequiredHint': 'The server is bound to 127.0.0.1 and no public address is configured, so a phone cannot reach it. Turn on LAN access in this plugin settings card (under Settings → Web Plugins → Remote access when the full family is installed, or on this plugin row under Settings → Plugins for a standalone install), or restart with dsh web --host 0.0.0.0, or set the tunneled public address.',
   'status.loopbackRequired': 'The pairing panel works on this machine only',
   'status.loopbackRequiredHint': 'Open this page at http://127.0.0.1 to mint a QR code; phones use the paired link.',
   'status.unreachable': 'Cannot reach the pairing service',

package/src/client/pair-api.ts

@@ -2,6 +2,10 @@
  * Browser-side wire helpers for the /api/pair surface. Plain fetch over
  * same-origin /api (like the connection client); JSON bodies, string
  * responses for the error codes.
+ *
+ * The paths are DOCUMENT-RELATIVE (issue #1707): the GUI is served with
+ * `<base href="./">`, so a sub-path deployment resolves them against its entry
+ * directory instead of escaping to the origin root.
  */
 
 /** issue() response. */
@@ -43,7 +47,7 @@ export interface PairGatePolicy {
 
 /** Read the host-authoritative desktop pairing policy. */
 export async function readPairGatePolicy(): Promise<PairGatePolicy> {
-  const response = await fetch('/api/pair/status')
+  const response = await fetch('api/pair/status')
   if (!response.ok) throw new Error(`remote-web-ui: status failed with ${String(response.status)}`)
   const value = await response.json() as { requirePairingForLan?: unknown }
   if (typeof value.requirePairingForLan !== 'boolean') {
@@ -116,7 +120,7 @@ export interface DeviceFrame {
  * origin — the panel is a desktop control endpoint).
  */
 export async function issuePair(address?: string): Promise<IssueResponse> {
-  const response = await fetch('/api/pair/issue', {
+  const response = await fetch('api/pair/issue', {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify({
@@ -139,7 +143,7 @@ export async function issuePair(address?: string): Promise<IssueResponse> {
  * @returns the wire result.
  */
 export async function acceptPair(token: string): Promise<{ ok: true } | AcceptFailure> {
-  const response = await fetch('/api/pair/accept', {
+  const response = await fetch('api/pair/accept', {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify({ token }),
@@ -153,7 +157,7 @@ export async function acceptPair(token: string): Promise<{ ok: true } | AcceptFa
 
 /** Revoke mobile access (paired devices + the current token). */
 export async function stopPair(): Promise<void> {
-  const response = await fetch('/api/pair/stop', { method: 'POST' })
+  const response = await fetch('api/pair/stop', { method: 'POST' })
   if (!response.ok) throw new Error(`remote-web-ui: stop failed with ${String(response.status)}`)
 }
 
@@ -162,7 +166,7 @@ export async function stopPair(): Promise<void> {
  * @param deviceId - the session id of the row to drop.
  */
 export async function revokePair(deviceId: string): Promise<void> {
-  const response = await fetch('/api/pair/revoke', {
+  const response = await fetch('api/pair/revoke', {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify({ deviceId }),
@@ -177,7 +181,7 @@ export async function revokePair(deviceId: string): Promise<void> {
  *   proves this page is not paired (see {@link shouldStopHeartbeat}).
  */
 export async function sendHeartbeat(): Promise<number> {
-  const response = await fetch('/api/pair/heartbeat', { method: 'POST' })
+  const response = await fetch('api/pair/heartbeat', { method: 'POST' })
   return response.status
 }
 
@@ -242,7 +246,7 @@ export class LanBindStatusError extends Error {
 
 /** Read the LAN-bind facts (loopback-only endpoint). */
 export async function readLanBindStatus(): Promise<LanBindFrame> {
-  const response = await fetch('/api/pair/lan-bind')
+  const response = await fetch('api/pair/lan-bind')
   if (!response.ok) throw new LanBindStatusError(response.status, `remote-web-ui: lan-bind status failed with ${String(response.status)}`)
   return await response.json() as LanBindFrame
 }

package/src/client/remote-channel.ts

@@ -23,6 +23,8 @@
  */
 
 import {
+  isLoopbackHostname as isLoopbackName,
+  isLocalPage,
   REMOTE_API_PREFIX,
   REMOTE_CHANNEL_RULES,
   REMOTE_PREFIX,
@@ -40,13 +42,41 @@ export interface RemoteChannelSettingsSnapshot {
   value?: { enabled?: boolean; requirePairingForLan?: boolean }
 }
 
+/**
+ * Facts about the live page that decide whether it is local. Defaults come
+ * from `window` so ordinary call sites stay argument-free; tests pass them
+ * explicitly.
+ */
+export interface PageOriginFacts {
+  hostname: string
+  protocol?: string
+  transportOwnsHost?: boolean
+}
+
+/**
+ * Read the page-origin facts from a window-like object: the hostname and
+ * protocol of the page itself plus the official transport's host-owner flag
+ * (`__DSH_TRANSPORT__.ownsHost`, set by the desktop shell before any boot
+ * entry, and by this plugin's own paired landing).
+ * @param win - the window to read (defaults to the real one).
+ * @returns the facts `isLocalPage`/`remoteChannelRequired` decide from.
+ */
+export function pageOriginFacts(win: Pick<Window, 'location'> & Partial<Pick<Window, 'navigator'>> = window): PageOriginFacts {
+  const transport = (win as unknown as { __DSH_TRANSPORT__?: { ownsHost?: unknown } }).__DSH_TRANSPORT__
+  return {
+    hostname: win.location.hostname,
+    protocol: win.location.protocol,
+    ...(transport?.ownsHost === true ? { transportOwnsHost: true } : {}),
+  }
+}
+
 /** Decide whether a remote desktop channel is required from local or host policy. */
 export function remoteChannelRequired(
-  hostname: string,
+  origin: PageOriginFacts,
   snapshot: RemoteChannelSettingsSnapshot,
   hostPairingPolicy: boolean | undefined,
 ): boolean {
-  if (isLoopbackHostname(hostname)) return false
+  if (isLocalPage(origin.hostname, origin.protocol, origin.transportOwnsHost)) return false
   if (snapshot.status === 'ready') {
     return (snapshot.value?.enabled ?? true) && (snapshot.value?.requirePairingForLan ?? true)
   }
@@ -56,20 +86,13 @@ export function remoteChannelRequired(
 }
 
 /**
- * Browser-safe loopback classification for the page origin (the SDK client
- * exports its own; this copy keeps the module dependency-free).
- * @param hostname - a location hostname (IPv6 without brackets).
- * @returns true for localhost, IPv6 loopback, or any 127/8 literal.
+ * Browser-safe loopback classification for the page origin. The definition
+ * lives once in the rules module, which the inlined boot script mirrors
+ * verbatim, so the browser half and the parse-time patch can never disagree
+ * (an IPv6-loopback origin judged remote would rewrite every call onto a
+ * channel it can never pair on).
  */
-export function isLoopbackHostname(hostname: string): boolean {
-  // WHATWG location.hostname keeps IPv6 literals bracketed ("[::1]"); the
-  // host-side shared predicate accepts that spelling, so this browser copy must
-  // too, or an IPv6-loopback origin is judged remote and rewrites every call
-  // onto the gated channel where it can never pair.
-  if (hostname === 'localhost' || hostname === '::1' || hostname === '[::1]') return true
-  const parts = hostname.split('.')
-  return parts.length === 4 && parts[0] === '127' && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
-}
+export const isLoopbackHostname = isLoopbackName
 
 /**
  * Whether one same-origin path must ride the gated channel (fetch, EventSource,

package/src/client/remote.module.css

@@ -822,6 +822,24 @@
   align-items: center;
 }
 
+/* ── Collapsed rail foot seat ────────────────────────────────────────────
+
+   The shell renders `sidebar.footer.action` as a centered horizontal row
+   in both column states. In the 56px rail that row is only as wide as its
+   occupants, so a second registrar overflows the icon column on both sides:
+   with two 36px circles the seat measures 78px against a 35px column, and
+   the outer buttons land at x=-11 and x=31 while every other rail row sits
+   at x=10 (issue #1678). Stack the seat vertically whenever a rail-marked
+   occupant is inside it, so each circle keeps the 36px rail column the
+   shell uses elsewhere; the wide column never matches this rule. The anchor
+   is this plugin's own `data-rail` marker, so the rule is an equal-value
+   no-op for a shell that already stacks its foot. */
+:global([data-dsh-frame][data-sidebar-collapsed]) [class*='footerActions']:has([data-rail='rail']) {
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+
 /* ── update panel extras ─────────────────────────────────────────────── */
 
 .updateStatus {

package/src/client/update-api.ts

@@ -28,7 +28,7 @@ export class UpdateStatusError extends Error {
 export async function fetchUpdateStatus(): Promise<UpdateStatus> {
   let response: Response
   try {
-    response = await fetch('/api/update/status')
+    response = await fetch('api/update/status')
   } catch {
     // Network-level failure: nothing came back at all.
     throw new UpdateStatusError(0)
@@ -43,7 +43,7 @@ export async function fetchUpdateStatus(): Promise<UpdateStatus> {
  * @returns the run outcome.
  */
 export async function runUpdate(): Promise<UpdateRunResult> {
-  const response = await fetch('/api/update/run', { method: 'POST' })
+  const response = await fetch('api/update/run', { method: 'POST' })
   if (!response.ok) throw new Error('update run unavailable')
   return await response.json() as UpdateRunResult
 }

package/src/lan-bind.ts

@@ -21,6 +21,7 @@
 
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve, sep } from 'node:path'
+import { parseDocument } from 'yaml'
 import { dshHome } from './dsh-home.ts'
 
 /** Profile names safe to interpolate into the patch path: one path segment, no traversal. */
@@ -69,6 +70,62 @@ export function stripManagedBlock(content: string): string {
   return content.replace(pattern, '\n')
 }
 
+/**
+ * Render the managed block for one bind state. The values are static: the
+ * user patch layer has no reliable lazy service evaluation, and the plugin
+ * re-asserts the block at every boot so CLI flags (--port, --host) win by
+ * rewriting it before the next start.
+ */
+/**
+ * Whether the base opens a flow collection at the root. That is the shape the
+ * plugin manager's YAML document round-trip leaves behind when it appends rows
+ * to the profile's placeholder `[]`: `[ { id: … }, … ]`. Every other base
+ * (empty, block sequence, comment-only prefix) keeps the historical string
+ * concatenation, so the common paths stay byte-identical.
+ */
+function isFlowRoot(base: string): boolean {
+  return base.trimStart().startsWith('[')
+}
+
+/** Force one parsed collection (and its item collections) into block style. */
+function toBlockStyle(node: unknown): void {
+  if (typeof node !== 'object' || node === null) return
+  const collection = node as { flow?: boolean; items?: unknown[] }
+  if (!Array.isArray(collection.items) && typeof collection.flow !== 'boolean') return
+  collection.flow = false
+  for (const item of collection.items ?? []) toBlockStyle(item)
+}
+
+/** Plain-value view of one parsed node (YAML nodes keep their own accessors). */
+function plainOf(node: unknown): unknown {
+  if (typeof node !== 'object' || node === null) return node
+  const json = (node as { toJSON?: () => unknown }).toJSON
+  return typeof json === 'function' ? json.call(node) : node
+}
+
+/**
+ * Produce the file text for one bind state. A flow-style base is re-emitted as
+ * a block sequence before the managed block is appended, so the file stays
+ * exactly one valid YAML document; concatenating the block onto a non-empty
+ * flow array produced two root documents and the profile failed to parse at
+ * `dsh web` startup (#1675). A base that cannot be parsed is refused with the
+ * file path rather than written half-valid.
+ */
+function mergePatchContent(base: string, block: string, file: string): string {
+  if (base.length === 0) return block
+  if (!isFlowRoot(base)) return `${base}\n\n${block}`
+  const doc = parseDocument(base, { uniqueKeys: false })
+  if (doc.errors.length > 0 || doc.contents === null) {
+    throw new Error(`remote-web-ui: cannot update the lan-bind block in ${file}: ${doc.errors[0]?.message ?? 'the patch file is not a YAML document'}`)
+  }
+  if (!('items' in (doc.contents as { items?: unknown[] }))) {
+    throw new Error(`remote-web-ui: cannot update the lan-bind block in ${file}: the patch file is not a top-level patch list`)
+  }
+  toBlockStyle(doc.contents)
+  const rendered = doc.toString({ lineWidth: 0 }).trimEnd()
+  return `${rendered}\n\n${block}`
+}
+
 /**
  * Render the managed block for one bind state. The values are static: the
  * user patch layer has no reliable lazy service evaluation, and the plugin
@@ -130,6 +187,10 @@ export function lanBindState(profile: string, home: string = dshHome()): { block
  * unterminated block (BEGIN marker without END, which stripManagedBlock
  * cannot match) is truncated at its BEGIN marker first so the rewrite can
  * never stack a second webserver row onto the orphan.
+ *
+ * The written file is always exactly one valid YAML document: a base the
+ * plugin manager left in flow style is re-emitted as a block sequence before
+ * the managed block is appended (see mergePatchContent).
  */
 export function writeLanBind(host: LanBindHost, port: number, profile: string, home: string = dshHome()): void {
   const file = profilePatchFile(profile, home)
@@ -138,7 +199,7 @@ export function writeLanBind(host: LanBindHost, port: number, profile: string, h
   const rawBase = (orphanBegin === -1 ? stripped : stripped.slice(0, orphanBegin)).trimEnd()
   const base = rawBase.replace(/\[\s*\]\s*$/, '').trimEnd()
   const block = managedBlock(host, port)
-  const content = base.length > 0 ? `${base}\n\n${block}` : block
+  const content = mergePatchContent(base, block, file)
   const mode = existsSync(file) ? statSync(file).mode & 0o777 : 0o600
   mkdirSync(dirname(file), { recursive: true })
   const temp = `${file}.remote-web-ui-tmp-${process.pid.toString(36)}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`

package/src/pairing.persist.test.ts

@@ -96,17 +96,61 @@ describe('PairingService device persistence', () => {
     expect(restarted.hasDevice(deviceId)).toBe(true)
   })
 
-  it('clamps a persisted table to maxDevices when the file holds more sessions', () => {
+  // #1696: the constructor runs before the saved settings row is applied, so
+  // its cap can still be the schema default. Restoring must not enforce it —
+  // trimming there silently revokes authorizations the user never revoked,
+  // and the trimmed table reaches disk on the next heartbeat/sweep write.
+  it('operator: every valid persisted session survives a restart under the startup cap', () => {
     const file = join(dir, 'devices.json')
+    // Given a store holding three devices while the startup cap reads 4
+    // (the schema default) and the saved settings value is 12.
     writeFileSync(file, JSON.stringify({
       dev1: { createdAt: 1_000, lastSeenAt: 1_000 },
       dev2: { createdAt: 2_000, lastSeenAt: 2_000 },
       dev3: { createdAt: 3_000, lastSeenAt: 3_000 },
     }))
-    const service = new PairingService({ ...BASE_CONFIG, maxDevices: 2, devicesFile: file }, makeClock())
-    expect(service.hasDevice('dev3')).toBe(true)
+    // When a new process restores the store.
+    const service = new PairingService({ ...BASE_CONFIG, maxDevices: 4, devicesFile: file }, makeClock())
+    // Then no paired device lost its authorization to the transient cap.
+    expect(service.hasDevice('dev1')).toBe(true)
     expect(service.hasDevice('dev2')).toBe(true)
+    expect(service.hasDevice('dev3')).toBe(true)
+  })
+
+  it('operator: a restored over-cap table is not trimmed by a heartbeat and sweep', () => {
+    const file = join(dir, 'devices.json')
+    // Given twelve persisted devices restored under the default cap of 4.
+    const rows = Object.fromEntries(
+      Array.from({ length: 12 }, (_, i) => [`dev${i}`, { createdAt: 1_000 + i, lastSeenAt: 1_000 + i }]),
+    )
+    writeFileSync(file, JSON.stringify(rows))
+    const service = new PairingService({ ...BASE_CONFIG, maxDevices: 4, devicesFile: file }, makeClock())
+    // When the saved cap of 12 arrives and normal traffic writes the store.
+    service.config = { ...service.config, maxDevices: 12 }
+    service.heartbeat('dev0')
+    service.sweep()
+    // Then the file still names all twelve devices.
+    const persisted = JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown>
+    expect(Object.keys(persisted)).toHaveLength(12)
+    expect(service.deviceCount()).toBe(12)
+  })
+
+  it('operator: the cap is enforced when a device is admitted, not before', () => {
+    const file = join(dir, 'devices.json')
+    // Given three persisted devices restored under a cap of 2.
+    writeFileSync(file, JSON.stringify({
+      dev1: { createdAt: 1_000, lastSeenAt: 1_000 },
+      dev2: { createdAt: 2_000, lastSeenAt: 2_000 },
+      dev3: { createdAt: 3_000, lastSeenAt: 3_000 },
+    }))
+    const service = new PairingService({ ...BASE_CONFIG, maxDevices: 2, devicesFile: file }, makeClock())
+    expect(service.deviceCount()).toBe(3)
+    // When one more device pairs.
+    const paired = pairDevice(service)
+    // Then the table is trimmed to the cap, oldest first, keeping the newcomer.
+    expect(service.deviceCount()).toBe(2)
     expect(service.hasDevice('dev1')).toBe(false)
+    expect(service.hasDevice(paired)).toBe(true)
   })
 
   it('keeps sessions memory-only when devicesFile is unset', () => {

package/src/pairing.ts

@@ -248,6 +248,14 @@ export class PairingService {
    * Restore device sessions persisted by a previous process run. A corrupt
    * or missing file is tolerated (an empty device table, never a throw) —
    * persistence is an availability convenience, not a security boundary.
+   *
+   * Every still-valid session is restored, deliberately without applying
+   * `maxDevices`: the constructor runs with whatever cap the configuration
+   * layer has delivered so far (the schema default until the saved settings
+   * row is applied), and trimming here would permanently drop authorizations
+   * the user never revoked — the trimmed table reaches disk on the next
+   * heartbeat/sweep write. The cap is enforced where a device is admitted
+   * (see `accept`), against the configuration in force at that moment.
    */
   private loadPersisted(): void {
     const file = this.config.devicesFile
@@ -271,21 +279,12 @@ export class PairingService {
           ...(label !== undefined ? { userAgent: label } : {}),
         })
       }
-      this.clampToMaxDevices()
       if (this.evictIdle()) this.persistRevocation()
     } catch {
       // Unreadable/corrupt: start empty rather than refusing to boot.
     }
   }
 
-  /** FIFO-cap the device table (a persisted file may outlive a lowered cap). */
-  private clampToMaxDevices(): void {
-    if (this.devices.size <= this.config.maxDevices) return
-    const overflow = this.devices.size - this.config.maxDevices
-    const ordered = [...this.devices.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt)
-    for (const [id] of ordered.slice(0, overflow)) this.devices.delete(id)
-  }
-
   /** Drop sessions whose lastSeenAt is older than idleExpireMs. */
   private evictIdle(): boolean {
     const now = this.clock.now()
@@ -457,13 +456,18 @@ export class PairingService {
     }
     const deviceId = this.clock.randomToken()
     const now = this.clock.now()
-    if (this.devices.size >= this.config.maxDevices) {
-      // Evict the oldest session (FIFO) before binding a new device.
+    // FIFO-evict until a slot is free. The loop (not a single delete) covers a
+    // table that is already over the cap: restore keeps every persisted session
+    // (see loadPersisted), so the excess is collected here, once the store is
+    // actually asked to admit a new device, rather than at startup on a cap the
+    // configuration may not have delivered yet.
+    while (this.devices.size >= this.config.maxDevices) {
       let oldest: { id: string; createdAt: number } | undefined
       for (const [id, session] of this.devices) {
         if (oldest === undefined || session.createdAt < oldest.createdAt) oldest = { id, createdAt: session.createdAt }
       }
-      if (oldest !== undefined) this.devices.delete(oldest.id)
+      if (oldest === undefined) break
+      this.devices.delete(oldest.id)
     }
     const label = sanitizeUserAgent(userAgent)
     this.devices.set(deviceId, {
@@ -570,6 +574,16 @@ export class PairingService {
     return this.liveSession(deviceId) !== undefined
   }
 
+  /**
+   * Number of device sessions in the table, including idle ones whose idle
+   * window has not been swept yet. Restore keeps every persisted session
+   * (see `loadPersisted`), so this can exceed the configured cap until the
+   * next `accept` trims the excess.
+   */
+  deviceCount(): number {
+    return this.devices.size
+  }
+
   /** Subscribe to snapshot changes (each emit passes a fresh snapshot). */
   onState(listener: (snapshot: PairingSnapshot) => void): () => void {
     this.listeners.add(listener)

package/src/remote-channel-boot.ts

@@ -45,10 +45,20 @@ export function buildRemoteChannelBootScript(rules: RemoteChannelRules = REMOTE_
   return '(function(){' +
     'try{' +
     'var w=window,loc=w.location,h=loc.hostname;' +
-    // Loopback origins (including the bracketed IPv6 literal WHATWG returns)
-    // keep the original paths (mirrors isLoopbackHostname).
-    "if(h==='localhost'||h==='::1'||h==='[::1]'||/^127(\\.\\d{1,3}){3}$/.test(h))return;" +
     'var R=' + json + ';' +
+    // A page the machine itself serves keeps the original paths and no
+    // channel: loopback names (including the bracketed IPv6 literal WHATWG
+    // returns), any scheme no web transport carries (an application on this
+    // machine delivered it - the desktop shell's own scheme, a file page, a
+    // scheme a newer shell introduces), or a shell the official transport
+    // already declared the host owner. This mirrors isLocalPage in
+    // remote-channel-rules.ts, which owns the decision.
+    "if(h==='localhost'||h==='::1'||h==='[::1]'||/^127(\\.\\d{1,3}){3}$/.test(h))return;" +
+    'var pr=loc.protocol;' +
+    'if(typeof pr==="string"&&pr!==""&&R.webProtocols.indexOf(pr)===-1)return;' +
+    // ownsHost alone does not lift the fence: the plugin's own device-gated
+    // landing grants it to a paired LAN/tunnel page, which must stay gated.
+    'try{if(w.__DSH_TRANSPORT__&&w.__DSH_TRANSPORT__.ownsHost===true&&h.indexOf(".")===-1&&h.indexOf(":")===-1)return}catch(e){}' +
     // Host mode is server-granted: only the device-gated app landing
     // publishes the grant marker (in a capture script that runs ahead of
     // this one), so a shell that merely sits on a non-loopback origin - an