@linxin666/dsh-usage 0.4.1 → 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,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.1_@deepseek-ai+cordis@4.0.4/node_modules/@deepseek-ai/dsh-brand/lib/index.js
+//#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
 /**
 * 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.1_@deepseek-ai+cordis@4.0.4_@deepseek-ai+dsh-inva_9b80248df36b741e5eb76c73b242287a/node_modules/@deepseek-ai/dsh-credentials/lib/index.js
+//#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
 /**
 * Service Definition for the credential-reference capability seam (`ctx.credentials`). Settings and composition files carry
 * *references* to secrets — environment-variable names — while providers own
@@ -235,16 +308,11 @@ function usedPercent(used, limit) {
 function bearer(apiKey) {
 	return { authorization: `Bearer ${apiKey}` };
 }
-/**
-* The official pay-as-you-go balance. `deepseek` is the configurable-catalog
-* route key; `deepseek-official` is the live provider route the llm-deepseek
-* adapter registers (sessions and agent-default-model carry it), so both ids
-* must resolve here or the current provider would never be probed.
-*/
 const DEEPSEEK = {
 	ids: ["deepseek", "deepseek-official"],
 	displayName: "DeepSeek",
 	balance: {
+		origin: "https://api.deepseek.com",
 		build: ({ apiKey }) => ({
 			url: "https://api.deepseek.com/user/balance",
 			headers: bearer(apiKey)
@@ -624,6 +692,40 @@ const PROVIDER_ADAPTERS = [
 function adapterFor(provider) {
 	return PROVIDER_ADAPTERS.find((adapter) => adapter.ids.includes(provider));
 }
+/** Origin of a configured base URL, or undefined when it cannot be parsed. */
+function originOf(baseURL) {
+	if (baseURL === void 0 || baseURL.trim() === "") return void 0;
+	try {
+		return new URL(baseURL).origin;
+	} catch {
+		return;
+	}
+}
+/**
+* Whether an adapter's balance endpoint reports THIS route's account.
+*
+* Some adapter families share one route key across providers that merely
+* speak the same API: `deepseek` is both the official DeepSeek catalog entry
+* and a common id for an OpenAI-compatible reseller (Alibaba Bailian, ...)
+* pointed at another host by the profile's `baseURL`. The balance endpoint is
+* per ORIGIN, not per route key, so probing the official endpoint for a
+* reseller profile reports the official account's money under the reseller's
+* name (issue #1688). An adapter published with a fixed `origin` therefore
+* only applies to a route whose configured base URL is that origin, or to a
+* route that pins no base URL at all (the catalog alias of the official
+* route, which resolves the family's own credential).
+*
+* @param adapter - the matched adapter.
+* @param baseURL - the route's configured base URL (pi-ai profile), if any.
+* @returns true when the adapter may probe its balance endpoint for the route.
+*/
+function balanceAppliesToRoute(adapter, baseURL) {
+	const expected = adapter.balance?.origin;
+	if (expected === void 0) return true;
+	const configured = originOf(baseURL);
+	if (configured === void 0) return true;
+	return configured === expected;
+}
 /**
 * Whether a provider route belongs to the official DeepSeek family: the only
 * family with a spend price book and a settings-section-owned env credential
@@ -1086,7 +1188,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 ? { balanceSupported: true } : {},
+				...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?.plan !== void 0 ? { planSupported: true } : {},
 				...snapshot?.balance !== void 0 ? { balance: snapshot.balance } : {},
 				...snapshot?.plan !== void 0 ? { plan: snapshot.plan } : {},
@@ -1415,6 +1518,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);
 		if (credential.key === void 0) {
 			this.snapshots.set(route.id, {
 				provider: route.id,
@@ -1430,11 +1534,13 @@ var UsageService = class {
 			displayName: route.displayName || adapter.displayName,
 			credential: credential.kind,
 			supported: true,
+			...adapter.balance !== void 0 && !balanceApplies ? { balanceSupported: false } : {},
 			updatedAt: Date.now()
 		};
 		const runProbe = async (kind) => {
 			const half = adapter[kind];
 			if (half === void 0) return void 0;
+			if (kind === "balance" && !balanceApplies) return void 0;
 			try {
 				const spec = half.build({
 					apiKey: credential.key,
@@ -1678,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)
 	};
 }
 /**
@@ -1701,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/core/adapters.d.ts

@@ -19,6 +19,14 @@ export interface AdapterProbeContext {
     apiKey: string;
     /** Provider account id riding a dedicated header, when the credential carries one (Codex). */
     accountId?: string;
+    /**
+     * The route's configured base URL (the pi-ai profile's baseURL), when it
+     * declares one. An adapter whose endpoint belongs to one provider origin
+     * uses it to refuse an account that merely shares the route key, so a
+     * differently-hosted model of the same family is never reported with the
+     * other account's number.
+     */
+    baseURL?: string;
 }
 /** A parsed balance fact. */
 export interface BalanceParse {
@@ -37,6 +45,14 @@ export interface ProviderAdapter {
     /** Fallback display name when the LLM runtime has none. */
     displayName: string;
     balance?: {
+        /**
+         * Origin (scheme + host) whose account this balance endpoint reports.
+         * Omitted when the endpoint is per-route by construction (a profile
+         * supplies the host) or when the provider has only one origin. When set,
+         * a route whose configured baseURL resolves elsewhere is not this
+         * origin's account and must not be probed with this adapter.
+         */
+        origin?: string;
         build(context: AdapterProbeContext): ProbeSpec;
         parse(status: number, body: unknown): BalanceParse | undefined;
     };
@@ -45,6 +61,14 @@ export interface ProviderAdapter {
         parse(status: number, body: unknown): PlanParse | undefined;
     };
 }
+/**
+ * The official pay-as-you-go balance. `deepseek` is the configurable-catalog
+ * route key; `deepseek-official` is the live provider route the llm-deepseek
+ * adapter registers (sessions and agent-default-model carry it), so both ids
+ * must resolve here or the current provider would never be probed.
+ */
+/** The official DeepSeek API origin: the only account its balance endpoint reports. */
+export declare const DEEPSEEK_API_ORIGIN = "https://api.deepseek.com";
 /**
  * The adapter registry, in no particular order. Route keys come from the
  * pi-ai provider catalog plus the routes this deployment observed in user
@@ -53,6 +77,27 @@ export interface ProviderAdapter {
 export declare const PROVIDER_ADAPTERS: readonly ProviderAdapter[];
 /** Find the adapter serving a provider route key, if any. */
 export declare function adapterFor(provider: string): ProviderAdapter | undefined;
+/** Origin of a configured base URL, or undefined when it cannot be parsed. */
+export declare function originOf(baseURL: string | undefined): string | undefined;
+/**
+ * Whether an adapter's balance endpoint reports THIS route's account.
+ *
+ * Some adapter families share one route key across providers that merely
+ * speak the same API: `deepseek` is both the official DeepSeek catalog entry
+ * and a common id for an OpenAI-compatible reseller (Alibaba Bailian, ...)
+ * pointed at another host by the profile's `baseURL`. The balance endpoint is
+ * per ORIGIN, not per route key, so probing the official endpoint for a
+ * reseller profile reports the official account's money under the reseller's
+ * name (issue #1688). An adapter published with a fixed `origin` therefore
+ * only applies to a route whose configured base URL is that origin, or to a
+ * route that pins no base URL at all (the catalog alias of the official
+ * route, which resolves the family's own credential).
+ *
+ * @param adapter - the matched adapter.
+ * @param baseURL - the route's configured base URL (pi-ai profile), if any.
+ * @returns true when the adapter may probe its balance endpoint for the route.
+ */
+export declare function balanceAppliesToRoute(adapter: ProviderAdapter, baseURL: string | undefined): boolean;
 /**
  * Whether a provider route belongs to the official DeepSeek family: the only
  * family with a spend price book and a settings-section-owned env credential

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 {};