@mars-sea/dsh-commandcode-provider 0.11.8 → 0.11.9

package/CHANGELOG.md

@@ -6,6 +6,45 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.11.9] - 2026-09-22
+
+### Changed
+
+- **dsh 0.1.7-alpha.1 is a declared-compatible engine, and the release that rewrote settings needs no user action to keep working.** The engine replaced its settings.yaml document with schema-derived Config forms (`SettingsProvider` → `SettingsForms`, and `installSection` plus the browser's `settingsScope` service are both gone), so this release carries the two-generation adaptation: every Config field except the top-level `apiKey` secret is marked volatile through a feature-detected bridge (`src/config-volatile.ts`) — an unmarked field would be invisible to and unwritable from 0.1.7's settings page — while the ≤0.1.6 registration keeps an unmarked schema and an unwrapped config, exactly as that generation validates and clones it; volatile writes commit in place and re-run the two facts not re-derived per use (the web-search selection and the dsh-TUI section re-registration); and the browser side speaks the `remote.settings` describe/mutate wire directly through the plugin's own scope, so one implementation serves 0.1.2-rc.1 through 0.1.7-alpha.1. The one-time settings.yaml import needs no cooperation from the plugin: the engine looks the section up by profile entry id, which is the same string as the section id (`llm-commandcode`) and must stay that way. `npm run test:engine` passes against 0.1.7-alpha.1 (the bundle links and evaluates there — the request-image policy is the durable one — and the adapter is driven with each engine's own message constructors), so a release installed beside the newest engine is proven to load before it ships.
+
+- **The plugin manager now shows a real identity for this plugin on dsh 0.1.7+.** The package declares `icon` (`icon.svg`) and ships `locale/en.json` + `locale/zh.json` under the `locale/*.json` export, so the plugin-management page renders "Command Code" / "Command Code 提供方" with a description instead of a bare package name and a placeholder icon. Both are pure metadata: older engines ignore them, and every other install path is unaffected.
+
+### Fixed
+
+- **The account card's "无法连接 Command Code 服务 / 请检查网络连接或 API 地址设置" is no longer a guess, and three of its false causes are gone.** `classifyTotalFailure()` answers `network` whenever all four account endpoints throw without a status, so one verdict covered a real outage, a per-request timeout, a key no HTTP header can carry and an unparseable `apiBase` — while the card hid the only evidence, the four per-endpoint messages. Now: (a) the account path validates the key through the harness's own `assertUsableApiKey`, as chat already did, and answers `blocked: 'invalid-key'` with the credential message instead of four phantom transport failures (a key pasted with an embedded newline or a full-width character makes `fetch` throw a `TypeError` **before any I/O**, once per endpoint — the connection was fine); (b) the four endpoints use the connection's own `requestTimeoutMs` (the SAME 60 s budget as a chat call) instead of the catalog's hidden 10 s cap, which on a slow link made every account query time out while chat kept working; (c) both surfaces now render `report.failures`, so the next occurrence names its actual cause. Refresh keeps working in every case — it was the diagnosis, not the fetch lifecycle, that was wrong.
+
+- **Turning the web-search toggle off no longer destroys the user's own `commandcode` pin.** `applyCommandCodeSearchSelection()` remembered "the field already read `commandcode` before we touched it" as `displaced: undefined`, and its disable branch wrote that value back — which is not the no-op its contract promises. The field was cleared, dsh-web reads a cleared `searchProviderId` as auto-select, and with a second usable provider registered (the shipped `deepseek-official` is usable whenever a DeepSeek key resolves) EVERY later search threw `WEB_PROVIDER_AMBIGUOUS`; the same write ran on plugin unload. The tracked selection now carries `preexisting`, so a field we did not take over is left alone, while a field that was genuinely unset at takeover is still cleared (or the toggle would leave Command Code serving). `tests/web-search.test.ts` pins both directions, including an end-to-end boot with `searchProvider: commandcode`.
+
+- **A 5xx that proxies a credits/plan rejection rotates the account instead of being retried as a transient outage.** `classifyAccountRejection()` hoisted only `RATE_LIMITED` above its `status >= 500` guard, so `503 {"code":"INSUFFICIENT_CREDITS"}`, `502 MODEL_NOT_IN_PLAN`, `USAGE_EXCEEDED` and `PREMIUM_CREDITS_EXHAUSTED` were classified as "the provider is unavailable": no rotation, and `SERVER` put the byte-identical request on dsh-llm-retry's 1000-attempt cadence while the configured sibling accounts were never consulted. All four structured codes (`ACCOUNT_UNAVAILABLE_CODES`) are now status-independent, exactly like `RATE_LIMITED`; only the prose scan stays confined to 4xx.
+
+- **A provider-published rate-limit reset of an implausible magnitude no longer breaks the failure it belongs to.** `error.rateLimit.reset` is seconds multiplied by 1000 and was trusted verbatim: `1e300` reached `new Date(1e303).toISOString()` and threw `RangeError: Invalid time value` out of `stream()` in place of the intended retryable `RATE_LIMIT`, and a mark pinned to it became a `cooldown` that no probe ever revisits (the account left rotation for the life of the process). Resets are now accepted only within `MAX_TRUSTED_RESET_MS` (30 days — the longest window this provider meters, so the bound rejects nonsense rather than second-guessing a schedule) at BOTH seams: the rejection body and the `/alpha/billing/credits` probe. A dropped reset degrades the mark to `unknown`, which the probe pass re-checks.
+
+- **An in-band stream error's `statusCode` no longer outvotes a terminal marker or `isRetryable: false`.** `{statusCode: 500, message: 'insufficient credits'}` was reported as retryable `SERVER`, so a permanent quota/plan refusal was replayed on the 1000-attempt cadence. The terminal markers now also match the spaced spelling (the separator is normalized, as the pre-stream classifier already did), and an explicit refusal or a terminal marker outranks a retryable status; an explicit `isRetryable: true` still wins.
+
+- **The first usage report no longer sticks as a false "remote is not mounted" error.** The plugin's `remote.commandcode` namespace lands one wire round-trip after the plugin asks for it, and a surface that asked first (the sidebar quota card does, on every boot) stored the synthetic not-mounted failure as `status: 'error'` — and the card's `shouldRefresh` only fires from `idle`, so nothing retried it until the panel's two-minute tick. The mount callback now re-reads the usage report through a seam declared before the effect (a `const` read in its temporal dead zone would throw). `tests/client-boot.test.ts` boots with the namespace deferred by a macrotask and asserts that re-read.
+
+- **A settings directory whose FIRST read fails retries instead of leaving the page permanently disabled.** With nothing ever held, the mirror keeps its initial `status: 'loading'`/`writable: false` snapshot, which the settings page renders as a fully disabled form behind a "read-only" banner — and the forwarded invalidations need a live Host to fire, so a Host that was still starting up left the page dead until a reload. `SettingsDescribeMirror` now retries a first-read failure on a bounded 1/2/4 s ladder (`SETTINGS_DESCRIBE_RETRY_MS`, injectable timer, cancelled on disposal); a failure with a HELD view schedules nothing, because the page is already showing the last good document.
+
+- **A concurrent `loginBegin` no longer leaks a loopback login server.** `begin()` rejoin read a status that only becomes `waiting` after two awaits, so two GUI tabs (or a Sign-in following a cancel that arrived too early to retire anything) each bound their own server — and only the last one was reachable by `teardown()`, so the orphan kept listening and answering `/callback` for the process's lifetime; ten of those exhausted the login port window. `begin()` is now single-flight across the bind, a `cancel()` in that window sets `cancelPending` (observed after the bind, which closes the fresh server and publishes `failed/cancelled`), and `bindServer` closes a server it does not track.
+
+- **`DSH_COMMANDCODE_TRACE=false` (or `0`/`no`/`off`) now disables the trace instead of enabling it.** Only `1`/`true`/`yes`/`on` were recognized as flags and everything else was taken for a path, so an explicit disable switched the trace ON and wrote the conversation to a file named `false` in the process's working directory.
+
+- **DSH 0.1.7 tool results survive into the next model request.** That engine uses `role: 'tool'` with message-level `toolCallId` and raw content blocks; the adapter only recognized the older user-role `tool-result` wrapper and silently discarded both results and their paired calls on both transports. The model consequently lost completed work, could repeat tools, and could end with only a statement of intent. Both envelopes now share pairing and serialization, including errors, images and long call ids. Engine smoke tests capture both request bodies using each engine's actual message constructors.
+
+- **Reasoning-only replies no longer silently complete a turn.** Both transports now validate that a terminal response contains answer text or a tool call before emitting a success finish. Empty completions use the existing `EMPTY_RESPONSE` retry policy; output-limit completions without an answer report non-retryable `OUTPUT_TOKEN_LIMIT` with the actual budget and available usage, without assuming all tokens went to reasoning. Received usage is retained on failure, and trace terminal diagnostics survive the payload cap.
+
+- **A reply cut off mid-generation is a reported failure again, not a turn that quietly finished** (report: 《调用会莫名其妙的自动停止，并没有任何报错信息》). The mechanism was in the stream tail: when the response body ended without its transport's terminal event — the gateway or an intermediary closing the socket mid-generation — the adapter closed the open blocks and yielded a clean `finish: { kind: 'stop' }`. Both transports DO terminate explicitly (the CLI transport with a `finish` event, the Provider API with a final `finish_reason` chunk), so an EOF there is not a normal ending, and reporting it as one is exactly why a truncated answer arrived with no error in the UI and nothing in the session log: the harness saw a completed turn. The tail now classifies. `!sawContent` (no visible text AND no tool call) keeps the pre-existing retryable `EMPTY_RESPONSE`, because such a request is free to repeat and the retry policy's whitelist absorbs it — a cut during a long thinking phase lands there, unchanged. A cut that HAD produced content throws `STREAM_CLOSED`, the code `dsh-llm-deepseek`'s own `translate()` raises for the same condition ("… stream ended before message_stop"); a tool call still in flight when the socket closed is dropped rather than executed with truncated JSON arguments. The code is deliberately OUTSIDE `providerRetryPolicy()`'s whitelist for now: every retry of a content-bearing cut re-generates the whole answer, so auto-retrying is a cost decision rather than an obvious win (adding it to `retryableCodes`, ideally bounded by `src/transport-retry.ts`'s per-agent budget, is the one-line opt-in). `tests/adapter.test.ts` pins both endings on both transports, the in-flight-tool-call refusal, and the untouched `EMPTY_RESPONSE` path.
+- **The Command Code settings page is interactive again on dsh 0.1.7** (report: 《Command Code 设置页面所有的按钮和开关都无法点击，下拉选择模型也无法使用》). The page rendered — with its read-only banner, empty text fields and every switch, button and select disabled — because the plugin's own settings scope read `ctx.remote.settings` directly, and `remote.settings` is a Cordis service NESTED under the `remote` service (api-gateway registers one `Service` per contribution namespace as `remote.<ns>`): a read from a fiber that does not declare that name in its inject list is answered with `Error: cannot get property "remote.settings" without inject`. The throw landed inside the scope's own `try`/`catch`, so nothing was logged and no `settings/describe` ever left the browser; the mirror stayed `idle`, the scope kept its INITIAL snapshot (`status: 'loading'`, `writable: false`, `value: undefined`), and since the page disables its controls on `!state.writable`, everything was inert. The boolean toggles were the confusing part of the report: they fall back to their hardcoded `defaultChecked` while the scope has no value, so they looked "set" over empty text inputs. `createSettingsScope()` now takes the namespace as a resolver, and the client entry fills it from the object `ctx.inject(['remote.settings'], …)` resolves — the same shape the `remote.credentials` and `remote.commandcode` reads have always used. `$host` / `$on` / `$mount` are plain members of the declared `remote` service, so those stay direct reads, and no namespace was added to the exported client `inject` list: gating the whole client half on a service a profile may not serve would silence every surface, which is the failure this scope is built to avoid. Verified end to end against a real dsh 0.1.7-alpha.1 web app (the page converges on the stored row, a toggle marks it dirty, the model multi-select opens its 76-model list, and a save lands in the profile document and survives a reload); `tests/settings-scope.test.ts` now builds its fake context with a `settings` getter that throws the engine's exact error and covers the unmounted → mount + `refresh()` handshake, and `tests/client-boot.test.ts` mounts its namespaces as real `remote.<ns>` Cordis services — with the old direct read restored, the boot suite fails.
+
+### Added
+
+- **`DSH_COMMANDCODE_TRACE=<path>`: an opt-in raw-stream trace, so the next "it stopped in the middle" report arrives with evidence** (`src/stream-trace.ts`). A cut stream is diagnosed from the wire or not at all — which events actually arrived, how long the socket then sat silent, and how it ended are the facts that separate "the provider closed it" from "our parser missed the terminal event", and until now the adapter kept none of them. With the variable set (a bare `1`/`true`/`yes`/`on` writes to `$TMPDIR/dsh-commandcode-stream.jsonl`), every request appends JSONL: one record per raw chunk carrying the provider's own payload verbatim, plus `response` / `eof` / `idle-timeout` / `read-error` / `end` / `stream-close`, each stamped with milliseconds since that request's first byte. Records never include the request body, an API key, or a request header; one request is capped at 4 MiB (`trace-capped` names the cap); a path that cannot be written turns the trace off rather than failing the request it is observing; and unset, the whole facility is one environment read and some inert calls. `scripts/probe-stream.mjs` is the companion isolation test — it drives the adapter alone, with no harness and no session, so a cut seen there is the provider's while a clean `finished` puts the cut above the adapter (`PROBE_MODEL` / `PROBE_MAX_TOKENS` / `PROBE_PROMPT` / `PROBE_TRACE` override its defaults). `tests/stream-trace.test.ts` pins switch resolution, the JSONL shape, the cap, the degradation paths, and the adapter wiring on both a finished and a cut stream. Both live probes so far (`deepseek/deepseek-v4.1-flash`, 13 and 244 chunks) reached `finished` on `/provider/v1/chat/completions`, so the gateway does not cut unconditionally.
+
 ## [0.11.8] - 2026-09-22
 
 ### Changed

package/icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Command Code">
+  <rect width="64" height="64" rx="14" fill="#0F172A"/>
+  <path d="M18 20 L30 32 L18 44" fill="none" stroke="#4ADE80" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M34 44 L48 44" fill="none" stroke="#94A3B8" stroke-width="6" stroke-linecap="round"/>
+</svg>

package/lib/client.js

@@ -36,6 +36,424 @@ window.__ModuleLoader__.load({
 			};
 		}
 		//#endregion
+		//#region src/client/settings-scope.ts
+		const MEMORY_STATUS = "unavailable";
+		/**
+		* Backoff before re-reading a directory whose FIRST read failed, in millis.
+		*
+		* A first read can lose to a Host that is still coming up (the gateway's WS
+		* handshake, a settings service mid-start): the failure is transient, but the
+		* scope has nothing held, so it keeps its initial `{ status: 'loading',
+		* writable: false }` snapshot — and every control on the settings page renders
+		* disabled behind a "read-only" banner. Nothing else would ever re-read it:
+		* the forwarded `settings/document-updated` and `connection/reset` signals need
+		* a live Host to fire, and the namespace only re-mounts on a page reload. So a
+		* failure with NOTHING held retries on this bounded ladder; a failure with a
+		* held view keeps it (no retry — the page is already showing the last good
+		* document, and `tests/settings-scope.test.ts` pins that).
+		*/
+		const SETTINGS_DESCRIBE_RETRY_MS = [
+			1e3,
+			2e3,
+			4e3
+		];
+		/** The production timer: a browser/node timeout, no polling. */
+		const REAL_SETTINGS_TIMER = {
+			set(callback, ms) {
+				const handle = setTimeout(callback, ms);
+				handle.unref?.();
+				return handle;
+			},
+			clear(handle) {
+				clearTimeout(handle);
+			}
+		};
+		/** Shallow equality over the snapshot fields, so an unchanged derive never churns subscribers. */
+		function sameSnapshot(a, b) {
+			return a.status === b.status && Object.is(a.value, b.value) && Object.is(a.base, b.base) && Object.is(a.user, b.user) && Object.is(a.revision, b.revision) && a.writable === b.writable && a.mode === b.mode;
+		}
+		/** Accept a decoded row value only when it is the object a settings section is. */
+		function decodeRow(value) {
+			if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+			return value;
+		}
+		/**
+		* One shared mirror of the Host `settings.describe()` view.
+		*
+		* The run loop is the harness's own: serialize behind `inFlight`, fold a
+		* concurrent invalidation into exactly one rerun, and hold the previous view
+		* across a failed read (status stays `ready` with an `error`, or returns to
+		* `idle` when nothing was ever held).
+		*/
+		var SettingsDescribeMirror = class {
+			resolveRemote;
+			timer;
+			store;
+			persistence;
+			inFlight;
+			rerun = false;
+			generation = 0;
+			/** Pending retry handle and how many of {@link SETTINGS_DESCRIBE_RETRY_MS} are spent. */
+			retryHandle;
+			retries = 0;
+			disposed = false;
+			/**
+			* @param resolveRemote - Reads the inject-captured `remote.settings` namespace.
+			* @param persistence - Client-selected Host persistence; non-loopback pages may stay process-local.
+			* @param timer - Retry timer seam (see {@link SETTINGS_DESCRIBE_RETRY_MS}).
+			*/
+			constructor(resolveRemote, persistence, timer = REAL_SETTINGS_TIMER) {
+				this.resolveRemote = resolveRemote;
+				this.timer = timer;
+				this.persistence = persistence;
+				this.store = createSnapshotStore({
+					status: persistence === "host" ? "idle" : MEMORY_STATUS,
+					view: null,
+					error: null
+				});
+			}
+			getSnapshot() {
+				return this.store.getSnapshot();
+			}
+			subscribe(listener) {
+				return this.store.subscribe(listener);
+			}
+			/** The cheap idempotent entry: kick a first read (a no-op on memory persistence). */
+			ensure() {
+				this.load();
+			}
+			/**
+			* Refresh from the Host. A call during an in-flight read marks one rerun
+			* after it settles instead of racing a second wire read.
+			* @returns settlement after this call's freshness is reflected.
+			*/
+			load() {
+				if (this.disposed || this.persistence === "memory") return Promise.resolve();
+				this.clearRetry();
+				if (this.inFlight !== void 0) {
+					this.rerun = true;
+					return this.inFlight;
+				}
+				const run = Promise.resolve().then(() => this.run());
+				this.inFlight = run;
+				return run;
+			}
+			/**
+			* Fold one write answer's namespace ROW into the held view without a wire
+			* read, and invalidate any read still in flight: a read begun before the
+			* write committed must not publish the pre-write document over it. With no
+			* held document the answer is not published as a partial document — the
+			* next read (or the failed-write recovery) picks it up.
+			* @param row - The namespace view a settings write answered with.
+			*/
+			acceptView(row) {
+				const before = this.store.getSnapshot();
+				this.generation += 1;
+				if (this.inFlight !== void 0) this.rerun = true;
+				if (before.view === null) return;
+				const held = before.view;
+				const namespaces = held.namespaces?.some((candidate) => candidate.ns === row.ns) ? held.namespaces.map((candidate) => candidate.ns === row.ns ? row : candidate) : [...held.namespaces ?? [], row];
+				this.store.set({
+					...before,
+					view: {
+						...held,
+						namespaces
+					}
+				});
+			}
+			async run() {
+				try {
+					for (;;) {
+						const before = this.store.getSnapshot();
+						if (before.status === "idle") this.store.set({
+							...before,
+							status: "loading"
+						});
+						this.rerun = false;
+						const generation = ++this.generation;
+						let outcome;
+						try {
+							const namespace = this.resolveRemote();
+							if (namespace === void 0) throw new Error("the settings remote namespace is not mounted");
+							const response = await namespace.describe();
+							if (response.ok) {
+								const value = response.value;
+								outcome = typeof value === "object" && value !== null ? { view: value } : { failure: "settings describe answered no view" };
+							} else outcome = { failure: response.error?.message ?? "settings describe failed" };
+						} catch (error) {
+							outcome = { failure: error instanceof Error ? error.message : String(error) };
+						}
+						if (generation !== this.generation) continue;
+						if ("view" in outcome) {
+							this.retries = 0;
+							this.store.set({
+								status: "ready",
+								view: outcome.view,
+								error: null
+							});
+						} else {
+							const held = this.store.getSnapshot();
+							this.store.set({
+								status: held.view === null ? "idle" : "ready",
+								view: held.view,
+								error: outcome.failure
+							});
+							if (held.view === null) this.scheduleRetry();
+						}
+						if (!this.rerun) break;
+					}
+				} finally {
+					this.inFlight = void 0;
+				}
+			}
+			/**
+			* Schedule the next retry of a failed FIRST read ({@link SETTINGS_DESCRIBE_RETRY_MS}).
+			* Bounded: once the ladder is spent the scope keeps its degraded snapshot,
+			* exactly as before, until an invalidation or a namespace re-mount arrives.
+			*/
+			scheduleRetry() {
+				if (this.disposed || this.retries >= SETTINGS_DESCRIBE_RETRY_MS.length) return;
+				const delay = SETTINGS_DESCRIBE_RETRY_MS[this.retries];
+				this.retries += 1;
+				this.retryHandle = this.timer.set(() => {
+					this.retryHandle = void 0;
+					this.load();
+				}, delay);
+			}
+			/** Cancel a pending retry (a live read is starting, or the scope is going away). */
+			clearRetry() {
+				if (this.retryHandle !== void 0) this.timer.clear(this.retryHandle);
+				this.retryHandle = void 0;
+			}
+			/** Stop the mirror: no further reads, and no retry may fire after disposal. */
+			dispose() {
+				this.disposed = true;
+				this.clearRetry();
+			}
+		};
+		/**
+		* One namespace's derived scope over the shared mirror, plus its serialized
+		* Host writes. This is the face `CommandCodeSettingsController` consumes
+		* (`getSnapshot` / `subscribe` / `set` / `unset`), so the controller itself
+		* needs no changes for either generation.
+		*/
+		var RemoteSettingsScope = class {
+			resolveRemote;
+			store;
+			mirror;
+			namespace;
+			persistence;
+			tail = Promise.resolve();
+			writeGeneration = 0;
+			disposed = false;
+			unsubscribe;
+			/** Revision answered by a superseded write still ahead of the mirror. */
+			pendingRevision;
+			constructor(resolveRemote, mirror, namespace, persistence) {
+				this.resolveRemote = resolveRemote;
+				this.mirror = mirror;
+				this.namespace = namespace;
+				this.persistence = persistence;
+				this.store = createSnapshotStore({
+					status: persistence === "host" ? "loading" : "unavailable",
+					value: void 0,
+					base: void 0,
+					user: void 0,
+					revision: void 0,
+					writable: false,
+					mode: persistence
+				});
+				if (persistence === "host") {
+					this.unsubscribe = mirror.subscribe(() => {
+						this.derive();
+					});
+					this.derive();
+				}
+			}
+			getSnapshot() {
+				return this.store.getSnapshot();
+			}
+			subscribe(listener) {
+				return this.store.subscribe(listener);
+			}
+			/** Queue one field write (the single-path `set` op form). */
+			set(field, value) {
+				return this.mutate([{
+					op: "set",
+					path: [field],
+					value
+				}]);
+			}
+			/** Queue one field clear (the single-path `unset` op form). */
+			unset(field) {
+				return this.mutate([{
+					op: "unset",
+					path: [field]
+				}]);
+			}
+			/**
+			* Queue one atomic namespace mutation behind the single-flight fence.
+			* A rejected write (e.g. `SETTINGS_CONFLICT`) re-reads the Host so the
+			* snapshot reports what actually landed; an accepted one folds its answer
+			* in directly — unless a newer write already superseded it, in which case
+			* that answer's revision becomes the next write's fence.
+			*/
+			mutate(ops, expectedRevision) {
+				const ownedOps = structuredClone(ops);
+				const generation = ++this.writeGeneration;
+				return this.enqueue(async () => {
+					const revision = expectedRevision ?? this.pendingRevision ?? this.getSnapshot().revision;
+					const response = await this.mutateRemote(ownedOps, revision);
+					if (!response.ok) {
+						await this.recover(generation);
+						return;
+					}
+					if (this.disposed) return;
+					const row = response.value;
+					if (generation === this.writeGeneration) {
+						this.pendingRevision = void 0;
+						this.mirror.acceptView(row);
+					} else this.pendingRevision = typeof row.revision === "number" ? row.revision : void 0;
+				});
+			}
+			async mutateRemote(ops, revision) {
+				try {
+					const namespace = this.resolveRemote();
+					if (namespace === void 0) return {
+						ok: false,
+						error: { message: "the settings remote namespace is not mounted" }
+					};
+					return await namespace.mutate(this.namespace, ops, revision);
+				} catch (error) {
+					return {
+						ok: false,
+						error: { message: error instanceof Error ? error.message : String(error) }
+					};
+				}
+			}
+			/** Reload Host state for the latest failed write; superseded failures leave recovery to it. */
+			async recover(generation) {
+				if (this.disposed || generation !== this.writeGeneration) return;
+				this.pendingRevision = void 0;
+				await this.mirror.load();
+			}
+			/** Derive this namespace's snapshot from the mirror's held view. */
+			derive() {
+				if (this.disposed) return;
+				const mirrored = this.mirror.getSnapshot();
+				if (mirrored.view === null || mirrored.view === void 0) return;
+				const writable = mirrored.view.writable === true;
+				const row = mirrored.view.namespaces?.find((candidate) => candidate.ns === this.namespace);
+				if (row === void 0) {
+					this.publish({
+						status: "unavailable",
+						writable
+					});
+					return;
+				}
+				const decoded = decodeRow(row.value);
+				if (decoded === void 0) return;
+				this.publish({
+					status: "ready",
+					writable,
+					value: decoded,
+					base: row.base,
+					user: row.user,
+					revision: typeof row.revision === "number" ? row.revision : void 0
+				});
+			}
+			/** Publish `next` over the current snapshot, skipping the write when nothing changed. */
+			publish(next) {
+				const current = this.store.getSnapshot();
+				const candidate = {
+					status: next.status,
+					value: "value" in next ? next.value : current.value,
+					base: "base" in next ? next.base : current.base,
+					user: "user" in next ? next.user : current.user,
+					revision: "revision" in next ? next.revision : current.revision,
+					writable: next.writable,
+					mode: current.mode
+				};
+				if (sameSnapshot(candidate, current)) return;
+				this.store.set(candidate);
+			}
+			/** Queue operations one at a time; memory persistence and disposal are no-ops. */
+			enqueue(operation) {
+				if (this.persistence === "memory" || this.disposed) return Promise.resolve();
+				const task = this.tail.then(async () => {
+					if (this.disposed) return;
+					await operation();
+				});
+				this.tail = task.catch(() => {});
+				return task;
+			}
+			/** Stop queued operations, stop deriving, and wait for the current wire call to settle. */
+			async dispose() {
+				this.disposed = true;
+				this.writeGeneration += 1;
+				this.unsubscribe?.();
+				await this.tail;
+			}
+		};
+		/**
+		* Build the plugin's settings scope for one namespace.
+		*
+		* Subscribes the two signals that can move the Host view — the forwarded
+		* `settings/document-updated` invalidation and (when the client exposes it)
+		* `connection/reset` — kicks the first describe read, and derives the
+		* namespace row on every mirror change.
+		*
+		* `resolveRemote` is the INJECT-CAPTURED namespace (see
+		* {@link SettingsRemoteResolver}): `remote.settings` is a Cordis service nested
+		* under `remote`, so a read through our own context throws and has to be
+		* replaced by an object captured inside `ctx.inject(['remote.settings'], …)`.
+		* The caller that owns that inject calls {@link ManagedSettingsScope.refresh}
+		* once the namespace lands, which is what turns the first, namespace-less read
+		* into a served one; a profile that never mounts the namespace leaves the page
+		* in its degraded (`unavailable`, read-only) state instead of throwing.
+		*
+		* @param context - The client context slice (only the declared `remote` service is read).
+		* @param namespace - Settings namespace (profile entry id) this scope binds.
+		* @param resolveRemote - Reads the inject-captured `remote.settings` namespace.
+		* @returns The scope plus the refresh/dispose handles the entry wires into its fiber.
+		*/
+		function createSettingsScope(context, namespace, resolveRemote, timer = REAL_SETTINGS_TIMER) {
+			const loopback = context.remote.$host?.isLoopback === true;
+			const persistence = loopback ? "host" : "memory";
+			const mirror = new SettingsDescribeMirror(resolveRemote, persistence, timer);
+			const scope = new RemoteSettingsScope(resolveRemote, mirror, namespace, persistence);
+			const disposers = [];
+			if (loopback) {
+				if (typeof context.remote.$on === "function") {
+					const off = context.remote.$on("settings/document-updated", () => {
+						mirror.ensure();
+					});
+					if (typeof off === "function") disposers.push(off);
+				}
+				if (typeof context.on === "function") {
+					const off = context.on("connection/reset", () => {
+						mirror.load();
+					});
+					if (typeof off === "function") disposers.push(off);
+				}
+				mirror.ensure();
+			}
+			return {
+				getSnapshot: () => scope.getSnapshot(),
+				subscribe: (listener) => scope.subscribe(listener),
+				set: (field, value) => scope.set(field, value),
+				unset: (field) => scope.unset(field),
+				refresh: () => {
+					mirror.load();
+				},
+				dispose: async () => {
+					for (const dispose of disposers.splice(0)) dispose();
+					mirror.dispose();
+					await scope.dispose();
+				}
+			};
+		}
+		//#endregion
 		//#region src/client/settings.ts
 		/**
 		* Browser controller for the "Command Code" settings page.
@@ -56,10 +474,14 @@ window.__ModuleLoader__.load({
 		*   - Working dir, request/stream timeouts -> the same namespace.
 		*
 		* The controller mirrors the plugin-card pattern from the harness's own
-		* settings UI: it binds the `llm-commandcode` namespace through the
-		* `settingsScope` service, keeps a staged draft of edits, and writes them on
-		* save through `scope.set` / the credentials domain. The Host stays the
-		* single fact source; the snapshot is republished after each accepted write.
+		* settings UI: it binds the `llm-commandcode` namespace through a
+		* `SettingsScope` — this plugin's own binding of `remote.settings` (see
+		* `./settings-scope.ts`; the harness's `settingsScope` wrapper existed only
+		* through 0.1.6 and was removed with the 0.1.7 settings rewrite, while the
+		* wire underneath spans every supported release) — keeps a staged draft of
+		* edits, and writes them on save through `scope.set` / the credentials
+		* domain. The Host stays the single fact source; the snapshot is republished
+		* after each accepted write.
 		*
 		* This module is deliberately free of JSX — it only produces the state face
 		* the React component renders.
@@ -2157,7 +2579,7 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region package.json
-		var version = "0.11.8";
+		var version = "0.11.9";
 		var repository = {
 			"type": "git",
 			"url": "git+https://github.com/Mars-Sea/dsh-commandcode-provider.git"
@@ -2812,13 +3234,21 @@ window.__ModuleLoader__.load({
 					report.blocked !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						className: "cc-usageBlocked",
 						role: "alert",
-						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-							className: "cc-usageBlockedTitle",
-							children: blockedTitle(report.blocked, t)
-						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-							className: "cc-usageBlockedHint",
-							children: blockedHint(report.blocked, t)
-						})]
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "cc-usageBlockedTitle",
+								children: blockedTitle(report.blocked, t)
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "cc-usageBlockedHint",
+								children: blockedHint(report.blocked, t)
+							}),
+							report.failures.length > 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "cc-usageBlockedDetail",
+								title: report.failures.join("; "),
+								children: report.failures.join(" · ")
+							}) : null
+						]
 					}) : null,
 					report.usage !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						className: "cc-usageStats",
@@ -4122,21 +4552,23 @@ window.__ModuleLoader__.load({
 		}
 		/** The report-level failure box, or undefined when the report is usable. */
 		function failureView(state) {
-			const blocked = state.report?.accounts.find((entry) => entry.report.blocked !== void 0)?.report.blocked;
+			const blockedEntry = state.report?.accounts.find((entry) => entry.report.blocked !== void 0);
+			const blocked = blockedEntry?.report.blocked;
+			const detail = (blockedEntry?.report.failures ?? []).join(" · ");
 			if (blocked === "invalid-key") return {
 				title: "errorInvalidKey",
 				hint: "errorInvalidKeyHint",
-				detail: ""
+				detail
 			};
 			if (blocked === "service-unavailable") return {
 				title: "errorServiceUnavailable",
 				hint: "errorServiceUnavailableHint",
-				detail: ""
+				detail
 			};
 			if (blocked === "network") return {
 				title: "errorNetwork",
 				hint: "errorNetworkHint",
-				detail: ""
+				detail
 			};
 			if (state.status === "error" && state.report === void 0) return {
 				title: "errorGeneric",
@@ -5791,6 +6223,7 @@ select.cc-input{appearance:none;-webkit-appearance:none;-moz-appearance:none;box
 .cc-usageBlocked{border:1px solid var(--dsw-alias-label-error);border-radius:10px;padding:10px 12px;display:flex;flex-direction:column;gap:4px}
 .cc-usageBlockedTitle{color:var(--dsw-alias-label-error);margin:0;font-size:13px;font-weight:600;line-height:1.5}
 .cc-usageBlockedHint{color:var(--dsw-alias-label-secondary);margin:0;font-size:12px;line-height:1.5}
+.cc-usageBlockedDetail{color:var(--dsw-alias-label-secondary);margin:0;font-size:11px;line-height:1.5;word-break:break-word;opacity:.85}
 .cc-version{margin:4px 0 0;text-align:center;color:var(--dsw-alias-label-tertiary);font-size:12px;line-height:1.5}
 /* The Models-page provider panel root: unstyled by design — the row card the
  * Models page owns supplies the surface, the panel only stacks its controls. */
@@ -6314,9 +6747,11 @@ select.cc-input{appearance:none;-webkit-appearance:none;-moz-appearance:none;box
 		const SESSION_COST_ID = "commandcode-session-cost";
 		/**
 		* Client plugin body. Gates on the services shared by both client generations
-		* (`slots`, `locale`, `connection`, `remote`, `settingsScope`). Current clients
-		* mount the page after `remote.credentials` appears; legacy clients mount it
-		* from the connection ApiProxy credential face.
+		* (`slots`, `locale`, `connection`, `remote`) — never on `settingsScope`,
+		* which 0.1.7 removed and which the settings scope here replaces for every
+		* generation. Current clients mount the page after `remote.credentials`
+		* appears; legacy clients mount it from the connection ApiProxy credential
+		* face.
 		*/
 		function apply(ctx) {
 			injectPageCss();
@@ -6341,7 +6776,18 @@ select.cc-input{appearance:none;-webkit-appearance:none;-moz-appearance:none;box
 		}
 		/** Mount the one shared UI implementation over either credential transport. */
 		function applyClientSurfaces(ctx, api, hostDescription) {
-			const scope = ctx.settingsScope.bind({ namespace: COMMANDCODE_NS });
+			let settingsNamespace;
+			const scope = createSettingsScope(ctx, COMMANDCODE_NS, () => settingsNamespace);
+			ctx.effect(() => () => {
+				scope.dispose();
+			}, "dsh-commandcode-provider: settings scope");
+			ctx.inject(["remote.settings"], (settingsCtx) => {
+				settingsNamespace = settingsCtx.remote.settings;
+				scope.refresh();
+				settingsCtx.effect(() => () => {
+					settingsNamespace = void 0;
+				}, "dsh-commandcode-provider: settings namespace");
+			});
 			let modelsRemote;
 			const controller = new CommandCodeSettingsController(scope, {
 				...api,
@@ -6359,6 +6805,7 @@ select.cc-input{appearance:none;-webkit-appearance:none;-moz-appearance:none;box
 			let usageNamespace;
 			let usageMountError;
 			let pricesController;
+			let refreshUsage;
 			const contribution = {
 				package: USAGE_REMOTE_CONTRIBUTION.package,
 				descriptors: [
@@ -6381,6 +6828,7 @@ select.cc-input{appearance:none;-webkit-appearance:none;-moz-appearance:none;box
 						usageNamespace = namespaceCtx.remote.commandcode;
 						controller.refreshCatalog();
 						pricesController?.reload();
+						refreshUsage?.();
 						namespaceCtx.effect(() => () => {
 							usageNamespace = void 0;
 						}, "dsh-commandcode-provider: usage namespace");
@@ -6430,6 +6878,7 @@ select.cc-input{appearance:none;-webkit-appearance:none;-moz-appearance:none;box
 			};
 			modelsRemote = () => usageRemote.models();
 			const usageController = new CommandCodeUsageController(usageRemote);
+			refreshUsage = () => void usageController.refresh();
 			ctx.effect(() => () => usageController.dispose(), "dsh-commandcode-provider: usage controller");
 			const usageStore = createSnapshotStore(usageController.state());
 			usageController.subscribe(() => usageStore.set(usageController.state()));
@@ -6596,8 +7045,7 @@ select.cc-input{appearance:none;-webkit-appearance:none;-moz-appearance:none;box
 			"slots",
 			"locale",
 			"connection",
-			"remote",
-			"settingsScope"
+			"remote"
 		];
 		//#endregion
 		exports.apply = apply;