@linxin666/dsh-remote-web-ui 0.4.1 → 0.4.3

package/lib/types/index.js

@@ -7,15 +7,14 @@
  * `./client` entry) renders the sidebar entry, the pairing panel, and the
  * phone-side pair/accept + deep-link flow.
  */
-import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { setInterval as nodeSetInterval, setTimeout as nodeSetTimeout } from 'node:timers';
-import z from 'schemastery';
+import z from '@deepseek-ai/schemastery';
 import { DEFAULT_IDLE_EXPIRE_MS, PairingService } from "./pairing.js";
 import { dshHome } from "./dsh-home.js";
 import { isPairedDeviceRequest, makeGateListener } from "./gate.js";
 import { RemoteWebUiPairing } from "./pairing-access.js";
-import { isTrustedApiRequest, makeRoutes } from "./routes.js";
+import { makeRoutes } from "./routes.js";
 import { makeRemoteApiRoutes, makeRemoteApiUpgradeRoutes } from "./remote-api.js";
 import { startRemotePresencePet } from "./remote-presence-pet.js";
 import { claimPostureKey, postureTargets, probePosture, releasePostureKey } from "./posture.js";
@@ -24,13 +23,11 @@ import { ensureFirewallRule, firewallSummary, removeFirewallRule } from "./firew
 import { lanBindState, writeLanBind } from "./lan-bind.js";
 import { isHttpUrl, tunnelPlanOf } from "./tunnel-plan.js";
 import { loadRelayIdentity, RelayRegistrar } from "./relay-registry.js";
-import { desiredBindHost, desiredBindPort, firewallActionNeeded, pendingRestartOf } from "./lan-bind-plan.js";
+import { desiredBindHost, desiredBindPort, firewallActionNeeded, pendingRestartOf, resolveManagedProfile } from "./lan-bind-plan.js";
 import { createInnerAuth } from "./inner-auth.js";
 import { withIdentityEncoding } from "./http.js";
 import { TunnelManager } from "./tunnel.js";
 import { PublicBaseKeeper } from "./public-base.js";
-import { checkUpdates, fetchGitHubReleaseNotes, fetchLatestVersion, RELEASE_NOTES_CACHE_TTL_MS, resolveAnchorManifest, resolveUpdateTarget, runUpdateVerified, } from "./update.js";
-import { makeUpdateRoutes } from "./update-routes.js";
 import { mountOnce } from "./mount-once.js";
 import { REMOTE_CHANNEL_BOOT_SCRIPT } from "./remote-channel-boot.js";
 import { UUID_POLYFILL_SCRIPT } from "./uuid-polyfill.js";
@@ -47,31 +44,68 @@ export const inject = ['webServer', 'typertGateway', 'connection'];
  * Host package.
  */
 export const REMOTE_WEB_UI_SETTINGS_NAMESPACE = 'remote-web-ui';
+/**
+ * Plugin config schema. Under the 0.1.7 settings model this schema IS the
+ * entry's settings page: the Host derives one form per profile entry from it
+ * and serves that form only when at least one field is `volatile()`. The marker
+ * is also what admits a write and what keeps the edit on the live path — the
+ * Loader commits the new value into the field's reference and announces
+ * `loader/volatile-update` on this fiber instead of remounting the row, so the
+ * pairing service, its device sessions, the tunnel and the route registrations
+ * survive a settings save (see {@link applyImpl}'s sync).
+ *
+ * The schema is left to inference rather than annotated with `z<Config>`: a
+ * volatile field's parsed output is a live reference while its accepted input
+ * stays the plain value, so the two sides no longer share one shape and the
+ * annotation would reject the schema the Host must be given.
+ *
+ * The deployment-level fields (`trustedHosts`, `devicesFile`, `profile`) are
+ * deliberately NOT volatile: they belong in the profile patch, so the form
+ * leaves them to the operator instead of offering a card control that a
+ * document write could not honor.
+ */
 export const Config = z.object({
-    tokenTtlMs: z.number().step(1).min(60_000).default(10 * 60_000),
-    offlineAfterMs: z.number().step(1).min(5_000).default(25_000),
-    maxDevices: z.number().step(1).min(1).max(64).default(4),
-    idleExpireMs: z.number().step(1).min(60_000).default(DEFAULT_IDLE_EXPIRE_MS),
-    cookieName: z.string().min(1).default('dsh_pair'),
-    requirePairingForLan: z.boolean().default(true),
-    publicBaseUrl: z.string(),
+    tokenTtlMs: z.number().step(1).min(60_000).default(10 * 60_000).volatile(),
+    offlineAfterMs: z.number().step(1).min(5_000).default(25_000).volatile(),
+    maxDevices: z.number().step(1).min(1).max(64).default(4).volatile(),
+    idleExpireMs: z.number().step(1).min(60_000).default(DEFAULT_IDLE_EXPIRE_MS).volatile(),
+    cookieName: z.string().min(1).default('dsh_pair').volatile(),
+    requirePairingForLan: z.boolean().default(true).volatile(),
+    publicBaseUrl: z.string().volatile(),
     trustedHosts: z.array(z.string()),
     devicesFile: z.string(),
-    autoTunnel: z.boolean().default(false),
-    tunnelToken: z.string().role('secret'),
-    relay: z.boolean().default(true),
-    lanBind: z.boolean(),
+    autoTunnel: z.boolean().default(false).volatile(),
+    tunnelToken: z.string().role('secret').volatile(),
+    relay: z.boolean().default(true).volatile(),
+    lanBind: z.boolean().volatile(),
     profile: z.string().pattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
-    enabled: z.boolean().default(true),
+    enabled: z.boolean().default(true).volatile(),
 });
 /** Presence sweep cadence (a stale device flips to disconnected within two sweeps). */
 const SWEEP_INTERVAL_MS = 10_000;
+/** Read one resolved config field, following the live reference the schema produces. */
+function readConfigField(field, fallback) {
+    if (field === undefined)
+        return fallback;
+    if (typeof field === 'object' && field !== null && typeof field.get === 'function') {
+        const value = field.get();
+        return value === undefined ? fallback : value;
+    }
+    return field;
+}
 /**
- * How long one update-status probe answer is reused. The probe fans out one
- * registry GET per family package plus a GitHub call, and the sidebar update
- * entry asks for the status on every GUI page load.
+ * Read one optional resolved config field. A volatile reference is read at
+ * call time, so an unset field stays `undefined` rather than falling back to a
+ * schema default (the distinction the LAN toggle and the tunnel plan depend on).
  */
-const UPDATE_STATUS_TTL_MS = 60_000;
+function readOptionalConfigField(field) {
+    if (field === undefined)
+        return undefined;
+    if (typeof field === 'object' && field !== null && typeof field.get === 'function') {
+        return field.get();
+    }
+    return field;
+}
 /**
  * The single mapping from resolved plugin config to the pairing service
  * config. Both the constructed service and every later apply of this row
@@ -106,9 +140,22 @@ const DEFAULTS = {
     tunnelToken: undefined,
     relay: true,
     lanBind: undefined,
-    profile: process.env.DSH_PROFILE ?? 'web',
+    profile: resolveManagedProfile(undefined, undefined, process.env.DSH_PROFILE),
     enabled: true,
 };
+/**
+ * The launched profile the Host publishes on its `profileContext` service
+ * (`{ name, dir, patchPath, … }`). The Desktop client boots the "desktop"
+ * profile without exporting DSH_PROFILE, so the environment alone resolves
+ * the wrong profile there and the LAN bind toggle would edit a profile that
+ * is not running.
+ * @param ctx - host plugin context.
+ * @returns the profile name when the Host publishes one; undefined otherwise.
+ */
+function launchedProfileName(ctx) {
+    const fact = ctx.get('profileContext');
+    return typeof fact?.name === 'string' && fact.name.length > 0 ? fact.name : undefined;
+}
 /**
  * Mount the pairing service, routes, gate listener, and presence sweep.
  * @param ctx - host plugin context carrying webServer.
@@ -117,30 +164,29 @@ const DEFAULTS = {
 export const apply = mountOnce('@linxin666/dsh-remote-web-ui', applyImpl);
 function applyImpl(ctx, config) {
     const envPublicBase = process.env.DSH_REMOTE_PUBLIC_BASE_URL?.trim() || undefined;
-    const resolved = {
-        tokenTtlMs: config?.tokenTtlMs ?? DEFAULTS.tokenTtlMs,
-        offlineAfterMs: config?.offlineAfterMs ?? DEFAULTS.offlineAfterMs,
-        maxDevices: config?.maxDevices ?? DEFAULTS.maxDevices,
-        idleExpireMs: config?.idleExpireMs ?? DEFAULTS.idleExpireMs,
-        cookieName: config?.cookieName ?? DEFAULTS.cookieName,
-        requirePairingForLan: config?.requirePairingForLan ?? DEFAULTS.requirePairingForLan,
-        publicBaseUrl: config?.publicBaseUrl ?? envPublicBase,
-        trustedHosts: config?.trustedHosts,
-        devicesFile: config?.devicesFile ?? DEFAULTS.devicesFile,
-        autoTunnel: config?.autoTunnel ?? DEFAULTS.autoTunnel,
-        tunnelToken: config?.tunnelToken,
-        relay: config?.relay ?? DEFAULTS.relay,
-        lanBind: config?.lanBind,
-        profile: config?.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
-        enabled: config?.enabled ?? DEFAULTS.enabled,
-    };
-    // The effective configuration this activation runs on: under the 0.1.7
-    // settings model the plugin's own Config IS its settings document, so the
-    // Host serves the settings page from this schema and reloads the row after a
-    // save — a live edit re-enters apply() with the new value instead of being
-    // pushed into a running instance.
-    const resolve = () => resolved;
-    const service = new PairingService(pairingConfigOf(resolved));
+    // The settings are read through the volatile references at every call rather
+    // than captured once: a settings save commits into those references and
+    // announces `loader/volatile-update` (see the listener below), so resolving
+    // them here is what makes a live edit reach the running instance without a
+    // remount — and keeps the device sessions, the tunnel and the routes alive.
+    const resolve = () => ({
+        tokenTtlMs: readConfigField(config?.tokenTtlMs, DEFAULTS.tokenTtlMs),
+        offlineAfterMs: readConfigField(config?.offlineAfterMs, DEFAULTS.offlineAfterMs),
+        maxDevices: readConfigField(config?.maxDevices, DEFAULTS.maxDevices),
+        idleExpireMs: readConfigField(config?.idleExpireMs, DEFAULTS.idleExpireMs),
+        cookieName: readConfigField(config?.cookieName, DEFAULTS.cookieName),
+        requirePairingForLan: readConfigField(config?.requirePairingForLan, DEFAULTS.requirePairingForLan),
+        publicBaseUrl: readOptionalConfigField(config?.publicBaseUrl) ?? envPublicBase,
+        trustedHosts: readOptionalConfigField(config?.trustedHosts),
+        devicesFile: readConfigField(config?.devicesFile, DEFAULTS.devicesFile),
+        autoTunnel: readConfigField(config?.autoTunnel, DEFAULTS.autoTunnel),
+        tunnelToken: readOptionalConfigField(config?.tunnelToken),
+        relay: readConfigField(config?.relay, DEFAULTS.relay),
+        lanBind: readOptionalConfigField(config?.lanBind),
+        profile: resolveManagedProfile(readOptionalConfigField(config?.profile), launchedProfileName(ctx), process.env.DSH_PROFILE),
+        enabled: readConfigField(config?.enabled, DEFAULTS.enabled),
+    });
+    const service = new PairingService(pairingConfigOf(resolve()));
     // ── auto tunnel ─────────────────────────────────────────────────────────
     // The minted public URL becomes the QR base (and the pairing fence's
     // trusted host). Phone /api traffic rides the plugin's own /remote channel,
@@ -213,7 +259,7 @@ function applyImpl(ctx, config) {
     };
     // 'off' until a sync pass turns a mode on; the phase listener only feeds
     // the public base while a plugin-managed tunnel (quick or named) runs.
-    let tunnelMode = resolved.autoTunnel ? 'quick' : 'off';
+    let tunnelMode = resolve().autoTunnel ? 'quick' : 'off';
     tunnel.onPhase((info) => {
         if (tunnelMode === 'off')
             return;
@@ -272,92 +318,6 @@ function applyImpl(ctx, config) {
     // request) instead of opening the fence.
     let disposeRoutes;
     let disposeSweep;
-    // ── remote update ────────────────────────────────────────────────────────
-    // The dsh-web self-update surface: probe the npm registry for family
-    // releases and run `pnpm update --latest` in the owning profile. Resolutions
-    // anchor on the host process's own module graph, so the update always
-    // targets the profile the running web GUI was booted from. The anchor path
-    // is re-resolved per operation: pnpm removes the old version's .pnpm
-    // directory on update, so a boot-time captured path would fail to read
-    // after a successful update; versions are re-read from disk per check.
-    const requireFromHost = createRequire(import.meta.url);
-    /** Host-process resolve that degrades to "not installed" (undefined) instead of throwing. */
-    const hostResolve = (specifier) => {
-        try {
-            return requireFromHost.resolve(specifier);
-        }
-        catch {
-            return undefined;
-        }
-    };
-    const resolveAnchorPath = () => resolveAnchorManifest(hostResolve);
-    const releaseNotesCache = new Map();
-    const fetchReleaseNotesCached = async (version) => {
-        const cached = releaseNotesCache.get(version);
-        if (cached !== undefined && Date.now() - cached.at < RELEASE_NOTES_CACHE_TTL_MS)
-            return cached.notes;
-        const notes = await fetchGitHubReleaseNotes(version, fetch);
-        releaseNotesCache.set(version, { at: Date.now(), notes });
-        return notes;
-    };
-    // The status probe fans out one registry GET per family package (plus a
-    // GitHub release-notes call), and the sidebar update entry asks for it on
-    // every GUI page load — so the answer is memoized briefly and concurrent
-    // callers share one probe. A completed update invalidates it.
-    let updateStatusCache;
-    let updateStatusInFlight;
-    const checkStatusCached = () => {
-        const cached = updateStatusCache;
-        if (cached !== undefined && Date.now() - cached.at < UPDATE_STATUS_TTL_MS)
-            return Promise.resolve(cached.value);
-        if (updateStatusInFlight !== undefined)
-            return updateStatusInFlight;
-        updateStatusInFlight = checkUpdates({
-            anchorManifestPath: resolveAnchorPath(),
-            resolve: hostResolve,
-            fetchLatest: name => fetchLatestVersion(name, fetch),
-            fetchReleaseNotes: fetchReleaseNotesCached,
-        }).then((value) => {
-            updateStatusCache = { at: Date.now(), value };
-            return value;
-        }).finally(() => { updateStatusInFlight = undefined; });
-        return updateStatusInFlight;
-    };
-    const updateRoutes = makeUpdateRoutes({
-        // Control endpoints are host-surface only: a LAN/phone origin must never
-        // trigger a real install on this machine.
-        fence: request => isTrustedApiRequest(request, []),
-        check: () => checkStatusCached(),
-        run: async () => {
-            const target = resolveUpdateTarget({ anchorManifestPath: resolveAnchorPath() });
-            if ('error' in target) {
-                const code = target.error;
-                return {
-                    ok: false,
-                    exitCode: null,
-                    output: '',
-                    error: code === 'not-found' ? 'dsh-web aggregate not installed' : 'local link install — update unavailable',
-                    errorCode: code,
-                };
-            }
-            // Verify the versions actually moved after a green pnpm exit: the pnpm
-            // 11 minimumReleaseAge gate can silently keep the installed versions
-            // (same-day releases), which a plain exit-0 check would report as
-            // success — the user then restarts and nothing changed.
-            const result = await runUpdateVerified({
-                run: { profileDir: target.profileDir, packages: target.packages },
-                check: {
-                    anchorManifestPath: resolveAnchorPath(),
-                    resolve: hostResolve,
-                    fetchLatest: name => fetchLatestVersion(name, fetch),
-                    fetchReleaseNotes: fetchReleaseNotesCached,
-                },
-            });
-            // The install moved (or failed) the versions the cached status reported.
-            updateStatusCache = undefined;
-            return result;
-        },
-    });
     // LAN-bind facts for the settings card, re-read per request so a hot
     // rebind (the patch watcher recomposes the process) and a fresh toggle
     // round are both reflected without a restart.
@@ -488,7 +448,6 @@ function applyImpl(ctx, config) {
             port: ctx.webServer.port,
             auth: innerAuth,
         }),
-        ...updateRoutes,
     ];
     const upgrades = makeRemoteApiUpgradeRoutes({
         service,
@@ -760,8 +719,16 @@ function applyImpl(ctx, config) {
             return;
         table.push({ kind: 'script', placement: 'head', text: REMOTE_CHANNEL_BOOT_SCRIPT });
     }), 'remote-web-ui: remote channel boot patch');
+    // The settings write path. The Host commits the new values into this row's
+    // volatile references and announces it here instead of remounting the row, so
+    // `sync` is what re-applies them: it re-reads every field through those
+    // references (see `resolve`) and is idempotent, so a save that changes
+    // nothing observable is a no-op while a disable, a bind flip or a tunnel
+    // change lands on the live instance without dropping the pairing service,
+    // its device sessions or the route registrations.
+    ctx.on('loader/volatile-update', () => { sync(); });
     // No settings registration: the Host derives this plugin's settings page
-    // from the exported `Config` schema and reloads the row after a save, so
-    // every write re-enters apply() with the new config (see `resolve`).
+    // from the exported `Config` schema, whose volatile fields are what make the
+    // page writable and what route a save through the live path above.
     sync();
 }

package/lib/types/lan-bind-plan.d.ts

@@ -44,6 +44,20 @@ export interface AppliedFirewallState {
     enabled: boolean;
     port: number;
 }
+/** The managed profile when neither the config nor the runtime names one. */
+export declare const DEFAULT_MANAGED_PROFILE = "web";
+/**
+ * The profile whose `cordis.patch.yml` the LAN bind toggle manages. An
+ * explicit `profile` config wins; otherwise the launched profile the Host
+ * publishes is authoritative, because the DSH Desktop client boots the
+ * `desktop` profile without exporting `DSH_PROFILE` — an environment-only
+ * fallback edited `profiles/web` there, so the toggle looked applied while
+ * the running host never followed the block.
+ * @param configured - the explicit `profile` plugin config, when set.
+ * @param launched - the launched profile name the Host published, when available.
+ * @param env - the DSH_PROFILE environment value, when set.
+ */
+export declare function resolveManagedProfile(configured: string | undefined, launched: string | undefined, env: string | undefined): string;
 /**
  * Whether the firewall rule must be (re)applied: only when the toggle or the
  * bound port moved since the last application. Keeps unrelated settings

package/lib/types/lan-bind-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lan-bind-plan.d.ts","sourceRoot":"","sources":["../../src/lan-bind-plan.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iDAAiD;AACjD,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,WAAW,CAAA;AAErD,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAGlG;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGjH;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,WAAW,EAAE,eAAe,GAAG,SAAS,EACxC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAGT;AAED,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,IAAI,EAAE,oBAAoB,GAAG,SAAS,GACrC,OAAO,CAIT"}
+{"version":3,"file":"lan-bind-plan.d.ts","sourceRoot":"","sources":["../../src/lan-bind-plan.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iDAAiD;AACjD,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,WAAW,CAAA;AAErD,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAGlG;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGjH;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,WAAW,EAAE,eAAe,GAAG,SAAS,EACxC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAGT;AAED,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,QAAQ,CAAA;AAE5C;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,IAAI,EAAE,oBAAoB,GAAG,SAAS,GACrC,OAAO,CAIT"}

package/lib/types/lan-bind-plan.js

@@ -44,6 +44,22 @@ export function pendingRestartOf(lanBind, desiredHost, liveHost) {
         return false;
     return liveHost !== desiredHost;
 }
+/** The managed profile when neither the config nor the runtime names one. */
+export const DEFAULT_MANAGED_PROFILE = 'web';
+/**
+ * The profile whose `cordis.patch.yml` the LAN bind toggle manages. An
+ * explicit `profile` config wins; otherwise the launched profile the Host
+ * publishes is authoritative, because the DSH Desktop client boots the
+ * `desktop` profile without exporting `DSH_PROFILE` — an environment-only
+ * fallback edited `profiles/web` there, so the toggle looked applied while
+ * the running host never followed the block.
+ * @param configured - the explicit `profile` plugin config, when set.
+ * @param launched - the launched profile name the Host published, when available.
+ * @param env - the DSH_PROFILE environment value, when set.
+ */
+export function resolveManagedProfile(configured, launched, env) {
+    return configured ?? launched ?? env ?? DEFAULT_MANAGED_PROFILE;
+}
 /**
  * Whether the firewall rule must be (re)applied: only when the toggle or the
  * bound port moved since the last application. Keeps unrelated settings

package/lib/types/lan-bind.d.ts

@@ -24,7 +24,7 @@ export declare const LAN_BIND_BLOCK_END = "# --- end remote-web-ui lan-bind bloc
 export type LanBindHost = '0.0.0.0' | '127.0.0.1';
 /**
  * The absolute path of the profile patch file this toggle manages. The value
- * is config-controlled (and the DSH_PROFILE env fallback bypasses schema
+ * is config-controlled (and the runtime/environment fallbacks bypass schema
  * validation entirely), so the path is guarded twice: the profile must be a
  * single safe path segment, and the resolved file must stay under the
  * profiles directory.
@@ -64,6 +64,10 @@ export declare function lanBindState(profile: string, home?: string): {
  * 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 declare function writeLanBind(host: LanBindHost, port: number, profile: string, home?: string): void;
 //# sourceMappingURL=lan-bind.d.ts.map

package/lib/types/lan-bind.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lan-bind.d.ts","sourceRoot":"","sources":["../../src/lan-bind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,eAAO,MAAM,oBAAoB,mEAAmE,CAAA;AACpG,eAAO,MAAM,kBAAkB,+CAA+C,CAAA;AAE9E,iDAAiD;AACjD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,WAAW,CAAA;AAEjD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAUlF;AAYD,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAcpE;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;IACjC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CACzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAW3E;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG;IAAE,YAAY,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAI/H;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,IAAI,CAa7G"}
+{"version":3,"file":"lan-bind.d.ts","sourceRoot":"","sources":["../../src/lan-bind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAUH,eAAO,MAAM,oBAAoB,mEAAmE,CAAA;AACpG,eAAO,MAAM,kBAAkB,+CAA+C,CAAA;AAE9E,iDAAiD;AACjD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,WAAW,CAAA;AAEjD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAUlF;AAYD,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKzD;AA0DD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAcpE;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;IACjC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CACzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAW3E;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG;IAAE,YAAY,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAI/H;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,IAAI,CAa7G"}

package/lib/types/lan-bind.js

@@ -20,6 +20,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.js";
 /** Profile names safe to interpolate into the patch path: one path segment, no traversal. */
 const PROFILE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
@@ -27,7 +28,7 @@ export const LAN_BIND_BLOCK_BEGIN = '# --- remote-web-ui lan-bind block (managed
 export const LAN_BIND_BLOCK_END = '# --- end remote-web-ui lan-bind block ---';
 /**
  * The absolute path of the profile patch file this toggle manages. The value
- * is config-controlled (and the DSH_PROFILE env fallback bypasses schema
+ * is config-controlled (and the runtime/environment fallbacks bypass schema
  * validation entirely), so the path is guarded twice: the profile must be a
  * single safe path segment, and the resolved file must stay under the
  * profiles directory.
@@ -59,6 +60,64 @@ export function stripManagedBlock(content) {
     const pattern = new RegExp(`\\r?\\n?${begin}[\\s\\S]*?${end}\\r?\\n?`, 'g');
     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) {
+    return base.trimStart().startsWith('[');
+}
+/** Force one parsed collection (and its item collections) into block style. */
+function toBlockStyle(node) {
+    if (typeof node !== 'object' || node === null)
+        return;
+    const collection = node;
+    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) {
+    if (typeof node !== 'object' || node === null)
+        return node;
+    const json = node.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, block, file) {
+    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)) {
+        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
@@ -113,6 +172,10 @@ export function lanBindState(profile, home = dshHome()) {
  * 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, port, profile, home = dshHome()) {
     const file = profilePatchFile(profile, home);
@@ -121,7 +184,7 @@ export function writeLanBind(host, port, profile, home = dshHome()) {
     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/lib/types/mount-once.d.ts

@@ -4,19 +4,50 @@
  * the loader accepts a standalone install of the same package side by side;
  * without this guard the second instance would still re-register the same
  * webserver routes, tools, settings namespaces, and system-prompt sections
- * and fail the boot. mountOnce makes the second host apply a no-op for the
- * lifetime of the first instance (the browser half is already deduped by
- * package name in the client module host).
+ * and fail the boot. mountOnce makes a mount of an already-mounted package a
+ * no-op for as long as the first instance lives (the browser half is already
+ * deduped by package name in the client module host).
+ *
+ * A no-op is only safe while the holder is ALIVE. The holder can be disposed
+ * long after the refused mount ran its course: the Host reloads a profile by
+ * creating the new loader entries before the old ones are torn down (a
+ * plugin-manager enable/disable/install write, a settings-driven row reload,
+ * HMR), so the new aggregate shell entry mounts its family plugin while the
+ * previous entry still owns the name. Dropping that refused mount lost the
+ * plugin for good - the previous entry then disposed its own mount, releasing
+ * the name with nobody left to take it, and the family row stayed listed as
+ * active while its host routes 404ed (the task-board panel showed
+ * "board.hostError.notMounted", no degraded record appeared, and only a Host
+ * restart recovered it).
+ *
+ * The refused mount is therefore QUEUED, not dropped, and replayed the moment
+ * the holder releases the name - if the waiting fiber is still alive then. The
+ * single-instance guarantee is unchanged: exactly one mount is live per
+ * package name, and the replay re-enters the guard so a later mount still
+ * dedupes against it.
  *
  * The registry rides a global symbol so two module instances of the same
- * package (npm copy vs repository link) still share one verdict. cordis
- * `ctx.effect` runs its callback immediately and treats the callback's
+ * package (npm copy vs repository link) still share one verdict. That symbol
+ * is a CROSS-REPOSITORY contract, not this file's private state: the four
+ * satellite packages (dsh-skins / dsh-pet / dsh-presets /
+ * dsh-community-plugins) are separate repositories carrying their own copy of
+ * this guard, rebuilt on their own schedule, so the value under `MOUNTED`
+ * must keep the shape every published copy reads (a `Set` of package names
+ * with `has`/`add`/`delete`). The wait queues this guard added therefore live
+ * under their own additive key, and the registry reads back a `Set` even when
+ * some other build left a different value there. Changing `MOUNTED`'s shape
+ * in place broke that contract once: a satellite's legacy copy created a
+ * `Set`, the family's new copy read it as a `Map`, and every family row
+ * mounted after it failed with "claims.get is not a function".
+ *
+ * cordis `ctx.effect` runs its callback immediately and treats the callback's
  * return value as the fiber disposer, so the unmarker is returned, not run.
  */
 /**
  * Wrap a cordis plugin apply so the package runs at most once per process.
- * The first mount registers normally and unmarks when its fiber disposes;
- * any later mount of the same package name is a no-op.
+ * The first mount registers normally and releases the name when its fiber
+ * disposes; a mount refused while that name is held waits for the release and
+ * then runs, unless its own fiber disposes first.
  * @param packageName - npm package identity shared by every install source.
  * @param fn - the original plugin apply.
  * @returns an apply of the same shape.

package/lib/types/mount-once.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mount-once.d.ts","sourceRoot":"","sources":["../../src/mount-once.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;GAcG;AAaH;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAW9F"}
+{"version":3,"file":"mount-once.d.ts","sourceRoot":"","sources":["../../src/mount-once.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AA6CH;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CA0C9F"}