@linxin666/dsh-usage 0.4.2 → 0.4.3

package/lib/index.js

@@ -1,4 +1,4 @@
-import z from "schemastery";
+import z from "@deepseek-ai/schemastery";
 import { mkdir, open, readFile, rename, unlink } from "node:fs/promises";
 import { dirname, isAbsolute, join } from "node:path";
 import "@deepseek-ai/cordis";
@@ -11,38 +11,111 @@ import { isAbsolute as isAbsolute$1, join as join$1 } from "node:path/posix";
 * 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.
 */
+/** Published cross-repository contract: package names currently mounted. */
 const MOUNTED = Symbol.for("dsh-web.mounted-plugins");
+/** Additive key this guard owns: refused mounts waiting for the name. */
+const WAITERS = Symbol.for("dsh-web.mounted-plugins.waiters");
+/**
+* The shared name registry, always a `Set` whatever another build stored here:
+* a foreign value (an interim shape, a hand-written global) must not take every
+* family plugin down with it.
+* @returns the process-wide set of mounted package names.
+*/
 function mountedSet() {
 	const registry = globalThis;
-	return registry[MOUNTED] ??= /* @__PURE__ */ new Set();
+	const existing = registry[MOUNTED];
+	if (existing instanceof Set) return existing;
+	const created = /* @__PURE__ */ new Set();
+	registry[MOUNTED] = created;
+	return created;
+}
+/** Queue per package name for mounts refused while a holder was alive. */
+function mountWaiters() {
+	const registry = globalThis;
+	return registry[WAITERS] ??= /* @__PURE__ */ new Map();
 }
 /**
 * 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.
 */
 function mountOnce(packageName, fn) {
-	return ((...args) => {
+	const mount = (...args) => {
 		const mounted = mountedSet();
-		if (mounted.has(packageName)) return;
+		const ctx = args[0];
+		if (mounted.has(packageName)) {
+			const waiters = mountWaiters();
+			const queue = waiters.get(packageName) ?? [];
+			let alive = true;
+			const pending = { run: () => {
+				if (alive) mount(...args);
+			} };
+			ctx?.effect?.(() => () => {
+				alive = false;
+				const index = queue.indexOf(pending);
+				if (index >= 0) queue.splice(index, 1);
+			});
+			queue.push(pending);
+			waiters.set(packageName, queue);
+			return;
+		}
 		mounted.add(packageName);
-		args[0]?.effect?.(() => () => {
+		ctx?.effect?.(() => () => {
 			mounted.delete(packageName);
+			const waiters = mountWaiters();
+			const queue = waiters.get(packageName);
+			if (queue === void 0) return;
+			waiters.delete(packageName);
+			for (const waiter of queue.splice(0)) queueMicrotask(() => {
+				waiter.run();
+			});
 		});
 		return fn(...args);
-	});
+	};
+	return mount;
 }
 //#endregion
 //#region ../../node_modules/.pnpm/@deepseek-ai+dsh-brand@0.1.7-rc.2_@deepseek-ai+cordis@4.0.4/node_modules/@deepseek-ai/dsh-brand/lib/index.js
@@ -1711,16 +1784,48 @@ const inject = ["webServer"];
 * family settings bridge (dsh-web-settings) resolves onto this row's entry id.
 */
 const USAGE_SETTINGS_NAMESPACE = "dsh-usage";
+/**
+* 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 it 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
+* probe cycle, its ledger and its route registrations survive a settings save.
+*
+* The schema is left to inference rather than annotated with
+* `z<UsageConfigFields>`: a volatile field's parsed output is a 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.
+*/
 const Config = z.object({
-	enabled: z.boolean().default(true),
-	pollIntervalSec: z.number().min(30).max(3600).default(60),
-	retainDays: z.number().min(7).max(730).default(180)
+	enabled: z.boolean().default(true).volatile(),
+	pollIntervalSec: z.number().min(30).max(3600).default(60).volatile(),
+	retainDays: z.number().min(7).max(730).default(180).volatile()
 });
+/** Read one config field, following the live reference the schema produces. */
+function readConfigField(field) {
+	if (field === void 0) return void 0;
+	if (typeof field === "object" && field !== null && typeof field.get === "function") return field.get();
+	return field;
+}
+/** Read one numeric field, falling back when the value is absent or not a usable number. */
+function readNumber(field, fallback) {
+	const value = readConfigField(field);
+	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+/**
+* Resolve the effective settings of one activation. Volatile references are
+* read here, so every re-arm observes the latest committed values rather than
+* whatever the row was activated with.
+* @param config - the config the Host passed to the activation.
+* @returns the resolved settings.
+*/
 function resolveConfig(config) {
 	return {
-		enabled: config?.enabled ?? true,
-		pollIntervalSec: typeof config?.pollIntervalSec === "number" ? config.pollIntervalSec : 60,
-		retainDays: typeof config?.retainDays === "number" ? config.retainDays : 180
+		enabled: readConfigField(config?.enabled) ?? true,
+		pollIntervalSec: readNumber(config?.pollIntervalSec, 60),
+		retainDays: readNumber(config?.retainDays, 180)
 	};
 }
 /**
@@ -1734,39 +1839,78 @@ let pendingStop;
 /**
 * Host body. The plugin's own Config schema above is the settings document the
 * 0.1.7 Host serves for this row; the effective config arrives here as the
-* `config` argument the Loader resolved and the Host reloads the row when the
-* user saves a change, so nothing in this body observes or writes settings.
+* `config` argument, and a settings save re-enters this body through the
+* volatile path rather than a row reload (see {@link Config}).
 * @param ctx - host root context.
 * @param config - the row's resolved configuration.
 */
 const apply = mountOnce("@linxin666/dsh-usage", (ctx, config) => {
-	const value = resolveConfig(config);
-	if (!value.enabled) return;
 	let live = true;
 	let service;
 	let disposeRoutes;
-	const begin = () => {
-		if (!live) return;
-		const next = new UsageService(ctx, value);
-		service = next;
-		next.start();
+	/** True while this activation has a start queued behind a predecessor's flush. */
+	let queued = false;
+	/** Register the service's two routes; the returned disposer unregisters them. */
+	const mountRoutes = (next) => {
 		const disposers = [makeUsageOverviewRoute(ctx, next), makeUsageRefreshRoute(ctx, next)].map((route) => ctx.webServer.register(route));
-		disposeRoutes = () => {
+		return () => {
 			for (const dispose of disposers) try {
 				dispose();
 			} catch {}
 		};
 	};
+	/** Start a fresh activation, unless this fiber is down or one already runs. */
+	const launch = () => {
+		queued = false;
+		if (!live || service !== void 0) return;
+		const value = resolveConfig(config);
+		if (!value.enabled) return;
+		const next = new UsageService(ctx, value);
+		service = next;
+		next.start();
+		disposeRoutes = mountRoutes(next);
+	};
+	/** Tear the running activation down, chaining its final flush for any successor. */
+	const stop = () => {
+		disposeRoutes?.();
+		disposeRoutes = void 0;
+		const stopping = service?.stop();
+		service = void 0;
+		if (stopping !== void 0) pendingStop = (pendingStop ?? Promise.resolve()).then(() => stopping);
+	};
+	/**
+	* Apply the activation's current settings: a disabled row mounts nothing (no
+	* probe cycle, no ledger, no routes), an enabled one starts on first use and
+	* otherwise re-applies its options in place.
+	*/
+	const rearm = () => {
+		const value = resolveConfig(config);
+		if (!value.enabled) {
+			queued = false;
+			stop();
+			return;
+		}
+		if (service !== void 0) {
+			service.applyOptions(value);
+			return;
+		}
+		if (queued) return;
+		if (pendingStop === void 0) {
+			launch();
+			return;
+		}
+		queued = true;
+		pendingStop = pendingStop.then(launch, launch).then(() => void 0);
+	};
+	ctx.on("loader/volatile-update", () => {
+		rearm();
+	});
 	ctx.effect(() => {
-		if (pendingStop === void 0) begin();
-		else pendingStop = pendingStop.then(begin, begin).then(() => void 0);
+		rearm();
 		return () => {
 			live = false;
-			disposeRoutes?.();
-			disposeRoutes = void 0;
-			const stopping = service?.stop();
-			service = void 0;
-			if (stopping !== void 0) pendingStop = (pendingStop ?? Promise.resolve()).then(() => stopping);
+			queued = false;
+			stop();
 		};
 	}, "dsh-usage: runtime");
 });

package/lib/types/client/body-mutations.d.ts

@@ -3,10 +3,10 @@
  * plugin bundle.
  *
  * Family plugins that inject at the DOM level must notice when the shell
- * re-renders around their injected node: the sidebar entry rows
- * (sidebar-entry-core), the center-column panel containers
- * (panel-mount-core), and the aggregate shell's column shims. Each consumer
- * used to install its OWN `MutationObserver` on `document.body` with
+ * re-renders around their injected node: the aggregate shell's column shims
+ * and any plugin surface still extending the shell from outside the official
+ * slot seats. Each consumer used to install its OWN `MutationObserver` on
+ * `document.body` with
  * `{ childList: true, subtree: true }`, so a page carrying N family plugins
  * paid N native observers and N callback invocations for EVERY mutation batch
  * the app produced — chat token streaming alone produces many per second, and

package/lib/types/client/settings-entry-form.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Family settings form bound to the profile entry id a Host actually serves.
+ *
+ * Under the 0.1.7 settings model a form is addressed by PROFILE ENTRY ID, while
+ * a family card knows only its own settings namespace. The family binder
+ * (`ctx.get('webUiSettings')`, published by dsh-web-settings) resolves one onto
+ * the other and is the preferred transport; this module is the fallback for a
+ * page that serves no binder — the group plugin is not installed, or its client
+ * half has not applied yet (the aggregate mounts its children in order, and a
+ * child still waiting on its own injects publishes nothing).
+ *
+ * The shared describe mirror is the only local evidence of which row id this
+ * profile serves, but it answers asynchronously: at plugin activation it usually
+ * holds nothing yet. A one-shot guess therefore cannot be right for every
+ * deployment, and the form is bound once per session:
+ *
+ * - binding the bare namespace made every save answer `No configurable plugin
+ *   entry "<namespace>"` on an aggregate install (the namespace is not an entry
+ *   id there), which the card reported as "the deployment did not accept these
+ *   values";
+ * - binding the aggregate row id would break a standalone install, whose row id
+ *   is the namespace or the package's own `ui-*` row.
+ *
+ * So the fallback starts on the most likely row and REBINDS the moment the
+ * mirror names one of this package's rows. Until the mirror answers, the form
+ * reports the binding it holds (usually `loading`), which the card renders as an
+ * unavailable form rather than a doomed one.
+ */
+import type { ConfigForm, ConfigForms } from '@deepseek-ai/dsh-client-ui-settings/client';
+/** Options of {@link createServedEntryForm}. */
+export interface ServedEntryFormOptions<T> {
+    /** The shared configuration forms service (`ctx.configForms`). */
+    forms: ConfigForms;
+    /**
+     * Profile entry ids this package's rows carry, most likely first: the
+     * aggregate's generated row, the package's own standalone row, then the bare
+     * namespace. The first is the fallback while the mirror has no answer; the
+     * last is the answer when the mirror serves none of them.
+     */
+    entryIds: readonly string[];
+}
+/**
+ * Create a settings form bound to the profile entry id this Host serves, and
+ * rebound whenever the shared describe mirror names a different one of this
+ * package's rows.
+ * @param options - the shared forms service and this package's candidate row ids.
+ * @returns a form delegating to the currently resolved entry's own form.
+ */
+export declare function createServedEntryForm<T>(options: ServedEntryFormOptions<T>): ConfigForm<T>;

package/lib/types/index.d.ts

@@ -1,7 +1,20 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
-import z from 'schemastery';
+import z from '@deepseek-ai/schemastery';
 import { type UsageServiceOptions } from './host/usage-service.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /**
+         * Volatile config values were committed into the running fiber without a
+         * remount; dispatched to the owning fiber only. Spelled here because the
+         * Loader package is not a dependency of this plugin, with the Loader's own
+         * shape so the two declarations merge when a Host program carries both.
+         * @param paths - changed config paths as key arrays; every value is committed before dispatch.
+         * @mode emit
+         */
+        'loader/volatile-update'(paths: readonly (readonly string[])[]): void;
+    }
+}
 export declare const name = "dsh-usage";
 export declare const inject: string[];
 /**
@@ -11,24 +24,62 @@ export declare const inject: string[];
  * family settings bridge (dsh-web-settings) resolves onto this row's entry id.
  */
 export declare const USAGE_SETTINGS_NAMESPACE: SettingsNamespace;
-export interface Config {
-    enabled?: boolean;
+/** The stable reference a `volatile()` config field resolves to; its owner updates it in place. */
+interface ConfigRef<T> {
+    /** @returns the value currently committed for the running instance. */
+    get(): T | undefined;
+}
+/** One config field as the Host hands it over: a live reference, or a plain value (profile patches, tests). */
+type ConfigField<T> = ConfigRef<T> | T | undefined;
+/** The config the Host hands this activation — the runtime face of {@link Config}. */
+export interface UsageConfigFields {
+    enabled?: ConfigField<boolean>;
     /** Provider probe cycle in seconds; 30-3600. */
-    pollIntervalSec?: number;
+    pollIntervalSec?: ConfigField<number>;
     /** Ledger retention in local days. */
-    retainDays?: number;
+    retainDays?: ConfigField<number>;
 }
-export declare const Config: z<Config>;
+/**
+ * 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 it 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
+ * probe cycle, its ledger and its route registrations survive a settings save.
+ *
+ * The schema is left to inference rather than annotated with
+ * `z<UsageConfigFields>`: a volatile field's parsed output is a 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.
+ */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    enabled: z<boolean, boolean, "volatile-defined">;
+    pollIntervalSec: z<number, number, "volatile-defined">;
+    retainDays: z<number, number, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    enabled: z<boolean, boolean, "volatile-defined">;
+    pollIntervalSec: z<number, number, "volatile-defined">;
+    retainDays: z<number, number, "volatile-defined">;
+}>>, "plain">;
 export interface ResolvedConfig extends UsageServiceOptions {
     enabled: boolean;
 }
-export declare function resolveConfig(config?: Config): ResolvedConfig;
+/**
+ * Resolve the effective settings of one activation. Volatile references are
+ * read here, so every re-arm observes the latest committed values rather than
+ * whatever the row was activated with.
+ * @param config - the config the Host passed to the activation.
+ * @returns the resolved settings.
+ */
+export declare function resolveConfig(config?: UsageConfigFields): ResolvedConfig;
 /**
  * Host body. The plugin's own Config schema above is the settings document the
  * 0.1.7 Host serves for this row; the effective config arrives here as the
- * `config` argument the Loader resolved and the Host reloads the row when the
- * user saves a change, so nothing in this body observes or writes settings.
+ * `config` argument, and a settings save re-enters this body through the
+ * volatile path rather than a row reload (see {@link Config}).
  * @param ctx - host root context.
  * @param config - the row's resolved configuration.
  */
-export declare const apply: (ctx: Context, config?: Config) => void;
+export declare const apply: (ctx: Context, config?: UsageConfigFields) => void;
+export {};

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-usage",
   "description": "Usage statistics plugin for the dsh web GUI: per-provider balance and coding-plan quota detection plus a live token usage ledger, with a compact price glance card above the sidebar's Settings row",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "icon": "icon.svg",
   "type": "module",
   "engines": {
@@ -50,7 +50,7 @@
     }
   },
   "dependencies": {
-    "schemastery": "^3.18.0"
+    "@deepseek-ai/schemastery": "^3.18.4"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh": ">=0.1.7-rc.2",

package/src/client/body-mutations.ts

@@ -4,10 +4,10 @@
  * plugin bundle.
  *
  * Family plugins that inject at the DOM level must notice when the shell
- * re-renders around their injected node: the sidebar entry rows
- * (sidebar-entry-core), the center-column panel containers
- * (panel-mount-core), and the aggregate shell's column shims. Each consumer
- * used to install its OWN `MutationObserver` on `document.body` with
+ * re-renders around their injected node: the aggregate shell's column shims
+ * and any plugin surface still extending the shell from outside the official
+ * slot seats. Each consumer used to install its OWN `MutationObserver` on
+ * `document.body` with
  * `{ childList: true, subtree: true }`, so a page carrying N family plugins
  * paid N native observers and N callback invocations for EVERY mutation batch
  * the app produced — chat token streaming alone produces many per second, and

package/src/client/index.ts

@@ -21,6 +21,7 @@ import { createUsageStore, type UsageStoreInstance } from './usage-store.ts'
 import { UsageSectionCard, type UsageSectionFace, type UsageSettings } from './UsageSectionCard.tsx'
 import { mountUsageFootCard, openUsageSettings } from './foot-card-mount.tsx'
 import { NS, en, zh, t } from './locales.ts'
+import { createServedEntryForm } from './settings-entry-form.ts'
 import type { UsageOverviewView } from '../core/types.ts'
 
 /** The host usage API as the browser sees it (same-origin JSON endpoints). */
@@ -49,9 +50,18 @@ const usageApi: UsageHttpApi = {
   refresh: () => usageFetch('api/dsh-usage/refresh', 'POST'),
 }
 
-/** Settings namespace the section edits (dsh-web-settings maps it onto this row's profile entry id). */
+/**
+ * Settings namespace the section edits: the family identity of this plugin's
+ * own settings form, and the row id a standalone bundle install carries.
+ */
 const USAGE_SETTINGS_NS = 'dsh-usage'
 
+/** Profile entry id the family aggregate's generated row carries. */
+const AGGREGATE_ENTRY_ID = 'web-ui-usage'
+
+/** Profile entry ids this package's patch rows carry, most likely first. */
+const USAGE_ENTRY_IDS: readonly string[] = [AGGREGATE_ENTRY_ID, 'usage', USAGE_SETTINGS_NS]
+
 /** First-level nav position: directly below the Workshop section (order 150). */
 const SECTION_ORDER = 151
 
@@ -101,15 +111,15 @@ export function apply(ctx: ClientContext): void {
   }, 'dsh-usage: dictionaries')
 
   // The family binder is what maps this namespace onto the row's profile entry
-  // id and hands back the native form. Without the group plugin the client can
-  // only address an entry id it already knows: the namespace itself is one when
-  // the profile keeps the family spelling. Any other entry id leaves the form
-  // unavailable, which renders the row's controls disabled — the Host's own
-  // generated page for the row still edits the same Config.
+  // id and hands back the native form. Without the group plugin the shared forms
+  // service is addressed on the entry id the describe mirror justifies, rebound
+  // as soon as the mirror answers: the namespace itself is only an entry id on a
+  // standalone install, so binding it on the aggregate left the form unavailable
+  // and the row's controls disabled.
   const binder = ctx.get('webUiSettings')
   const settingsForm = binder !== undefined
     ? binder.bind<UsageSettings>({ namespace: USAGE_SETTINGS_NS })
-    : ctx.configForms.get<UsageSettings>(USAGE_SETTINGS_NS)
+    : createServedEntryForm<UsageSettings>({ forms: ctx.configForms, entryIds: USAGE_ENTRY_IDS })
 
   // One store instance per apply body; the section mounts and unmounts with
   // the settings page, and the store survives between visits so the last