@linxin666/dsh-usage 0.4.2 → 0.4.4

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,41 +11,114 @@ 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
+//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-brand@0.2.0-rc.1_@deepseek-ai+cordis@4.0.4/node_modules/@deepseek-ai/dsh-brand/lib/index.js
 /**
 * Duplicate-install-safe nominal primitive helpers.
 *
@@ -68,7 +141,7 @@ function brandString(value) {
 	return value;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-credentials@0.1.7-rc.2_@deepseek-ai+cordis@4.0.4_@deepseek-ai+dsh-inva_98fa173416f048996704a605a96a2b0e/node_modules/@deepseek-ai/dsh-credentials/lib/index.js
+//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-credentials@0.2.0-rc.1_@deepseek-ai+cordis@4.0.4_@deepseek-ai+dsh-inva_1a647ad178a224e363f109a5f72e2237/node_modules/@deepseek-ai/dsh-credentials/lib/index.js
 /**
 * Service Definition for the credential-reference capability seam (`ctx.credentials`). Settings and composition files carry
 * *references* to secrets — environment-variable names — while providers own
@@ -1025,16 +1098,71 @@ async function writeJsonAtomic(path, value) {
 		throw error;
 	}
 }
+function unwrapVolatiles(value) {
+	if (value === null || value === void 0) return value;
+	if (typeof value === "object") {
+		if (typeof value.get === "function") return unwrapVolatiles(value.get());
+		if (Array.isArray(value)) return value.map(unwrapVolatiles);
+		const result = {};
+		for (const [k, v] of Object.entries(value)) result[k] = unwrapVolatiles(v);
+		return result;
+	}
+	return value;
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepMerge(base, patch) {
+	if (!isPlainObject(base) || !isPlainObject(patch)) return patch !== void 0 ? patch : base;
+	const result = { ...base };
+	for (const [key, value] of Object.entries(patch)) {
+		if (value === void 0) continue;
+		result[key] = isPlainObject(value) && isPlainObject(result[key]) ? deepMerge(result[key], value) : value;
+	}
+	return result;
+}
 /**
 * Read a foreign settings namespace's resolved value (the llm adapter
-* profiles, the agent default model). Unregistered namespaces read as
-* undefined; nothing here throws into the poll loop.
+* profiles, the agent default model). Resolves across pre-0.1.7 settings.get(),
+* 0.1.7 SettingsForms.describe(), live loader entries, and configEditor.
+* Unregistered namespaces read as undefined; nothing here throws into the poll loop.
 */
 function readNamespace(ctx, ns) {
 	try {
 		const settings = service(ctx, "settings");
-		if (settings === void 0) return void 0;
-		return settings.get(ns);
+		if (settings !== void 0) {
+			if (typeof settings.get === "function") {
+				const value = settings.get(ns);
+				if (value !== void 0) return unwrapVolatiles(value);
+			}
+			if (typeof settings.describe === "function") {
+				const descriptors = settings.describe({ redactSecrets: false });
+				if (Array.isArray(descriptors)) {
+					const match = descriptors.find((d) => d.ns === ns || ns === "llm-pi-ai" && (d.ns === "llm" || isPlainObject(d.value?.providers)) || ns === "llm-deepseek" && (d.ns === "llm-deepseek" || d.ns === "llm-deepseek-api-key"));
+					if (match !== void 0 && match.value !== void 0) return unwrapVolatiles(match.value);
+				}
+			}
+		}
+		const loader = ctx.root?.loader ?? ctx.loader;
+		if (loader !== void 0 && typeof loader.entries === "function") for (const entry of loader.entries()) {
+			const id = entry.options?.id;
+			const name = entry.options?.name;
+			if (id === ns || name === `@deepseek-ai/dsh-${ns}` || name?.endsWith(`/${ns}`) || ns === "llm-pi-ai" && (id === "llm" || name === "@deepseek-ai/dsh-llm-pi-ai") || ns === "llm-deepseek" && (id === "llm-deepseek-api-key" || name === "@deepseek-ai/dsh-llm-deepseek-api-key")) {
+				if (entry.fiber?.config !== void 0) return unwrapVolatiles(entry.fiber.config);
+			}
+		}
+		const editor = service(ctx, "configEditor");
+		if (editor !== void 0 && typeof editor.configuration === "function") {
+			const match = editor.configuration().find((r) => {
+				const id = r.entry.options.id;
+				const name = r.entry.options.name;
+				return id === ns || name === `@deepseek-ai/dsh-${ns}` || name?.endsWith(`/${ns}`) || ns === "llm-pi-ai" && (id === "llm" || name === "@deepseek-ai/dsh-llm-pi-ai") || ns === "llm-deepseek" && (id === "llm-deepseek-api-key" || name === "@deepseek-ai/dsh-llm-deepseek-api-key");
+			});
+			if (match !== void 0) {
+				if (match.entry.fiber?.config !== void 0) return unwrapVolatiles(match.entry.fiber.config);
+				return unwrapVolatiles(deepMerge(match.inherited, match.override));
+			}
+		}
 	} catch {
 		return;
 	}
@@ -1115,8 +1243,8 @@ var UsageService = class {
 				displayName: route.displayName || adapter?.displayName || route.id,
 				credential: snapshot?.credential ?? "none",
 				supported: adapter !== void 0 && (adapter.balance !== void 0 || adapter.plan !== void 0),
-				...adapter?.balance !== void 0 && balanceAppliesToRoute(adapter, this.piAiProfile(route.id)?.baseURL) ? { balanceSupported: true } : {},
-				...adapter?.balance !== void 0 && !balanceAppliesToRoute(adapter, this.piAiProfile(route.id)?.baseURL) ? { balanceSupported: false } : {},
+				...adapter?.balance !== void 0 && balanceAppliesToRoute(adapter, this.routeBaseUrl(route.id)) ? { balanceSupported: true } : {},
+				...adapter?.balance !== void 0 && !balanceAppliesToRoute(adapter, this.routeBaseUrl(route.id)) ? { balanceSupported: false } : {},
 				...adapter?.plan !== void 0 ? { planSupported: true } : {},
 				...snapshot?.balance !== void 0 ? { balance: snapshot.balance } : {},
 				...snapshot?.plan !== void 0 ? { plan: snapshot.plan } : {},
@@ -1445,7 +1573,7 @@ var UsageService = class {
 	async probeRoute(route, adapter) {
 		const credential = await this.resolveCredential(route.id);
 		const previous = this.snapshots.get(route.id);
-		const balanceApplies = balanceAppliesToRoute(adapter, this.piAiProfile(route.id)?.baseURL);
+		const balanceApplies = balanceAppliesToRoute(adapter, this.routeBaseUrl(route.id));
 		if (credential.key === void 0) {
 			this.snapshots.set(route.id, {
 				provider: route.id,
@@ -1560,6 +1688,14 @@ var UsageService = class {
 	deepseekApiKeyEnv() {
 		return readNamespace(this.ctx, "llm-deepseek")?.apiKeyEnv ?? "DEEPSEEK_API_KEY";
 	}
+	/** The DeepSeek official adapter's configured baseURL. */
+	deepseekBaseUrl() {
+		return readNamespace(this.ctx, "llm-deepseek")?.baseURL;
+	}
+	/** The effective base URL for a provider route (pi-ai or deepseek). */
+	routeBaseUrl(provider) {
+		return this.piAiProfile(provider)?.baseURL ?? (isDeepSeekProviderRoute(provider) ? this.deepseekBaseUrl() : void 0);
+	}
 };
 //#endregion
 //#region src/host/loopback.ts
@@ -1711,16 +1847,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 +1902,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/host/usage-service.d.ts

@@ -153,4 +153,8 @@ export declare class UsageService {
     private piAiProfile;
     /** The DeepSeek official adapter's credential reference name. */
     private deepseekApiKeyEnv;
+    /** The DeepSeek official adapter's configured baseURL. */
+    private deepseekBaseUrl;
+    /** The effective base URL for a provider route (pi-ai or deepseek). */
+    private routeBaseUrl;
 }

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.