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

package/lib/index.js

@@ -1,4 +1,4 @@
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
@@ -6,7 +6,7 @@ import * as dshLlm from "@deepseek-ai/dsh-llm";
 import { CONTEXT_WINDOW_EXCEEDED_CODE, LlmAdapter, LlmError, ReasoningEffortId, ToolCallId, assertUsableApiKey, attributionHeaders, errorChain, isContextWindowExceededError, offloadedImageText, resolveRetryPolicy, textOnlyImageText } from "@deepseek-ai/dsh-llm";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
-import { existsSync, readFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { randomBytes, randomUUID } from "node:crypto";
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
@@ -2652,6 +2652,181 @@ function scaleBy(size, factor) {
 	};
 }
 //#endregion
+//#region src/stream-trace.ts
+/**
+* Opt-in raw-stream trace for the Command Code transports.
+*
+* Why this exists: this route's failure mode of record is a response that ENDS
+* EARLY. The gateway, an intermediary proxy, or the network closes the socket
+* mid-generation, so the adapter's read loop sees `done` without ever seeing
+* the transport's terminal event. From inside the adapter those two endings are
+* indistinguishable — the provider cut the stream, a proxy timed out, or the
+* socket was dropped — and the only artifact that separates them is the raw
+* wire: which events actually arrived, when the last one landed, how long the
+* socket then sat silent, and how it ended. Without that, a truncated answer is
+* a report with no evidence attached.
+*
+* Enable it per process:
+*
+* ```sh
+* DSH_COMMANDCODE_TRACE=/tmp/cc-stream.jsonl dsh web
+* DSH_COMMANDCODE_TRACE=1 dsh web     # -> $TMPDIR/dsh-commandcode-stream.jsonl
+* ```
+*
+* Any value that is not a flag is a path, and the explicit off-spellings
+* (`0`, `false`, `no`, `off`) are recognized as "off" rather than being taken
+* for a file name.
+*
+* Every model request appends one JSONL record per raw chunk plus lifecycle
+* records (`response`, `eof`, `idle-timeout`, `read-error`, `end`,
+* `stream-close`), each stamped with `at` — milliseconds since that request's
+* first byte. The chunk records carry the provider's own payload verbatim
+* (bounded per chunk), because a truncated answer is exactly what is being
+* diagnosed: treat the file as conversation content, not as a log safe to
+* share. It never carries the request body, an API key, or any request header.
+*
+* Deliberate trade-offs:
+*  - OFF costs one `process.env` read per request.
+*  - ON appends synchronously, one file open per chunk. The trace must survive
+*    a host killed mid-diagnosis, and the microseconds it costs are irrelevant
+*    beside the seconds-scale silences it is there to measure.
+*  - A trace that cannot be written turns itself off instead of failing the
+*    request it is observing: a diagnostic must never become the outage.
+*
+* @module
+*/
+/** Environment variable that turns the trace on. */
+const STREAM_TRACE_ENV = "DSH_COMMANDCODE_TRACE";
+/** File used when the variable is set to a bare flag instead of a path. */
+const STREAM_TRACE_DEFAULT_FILE = "dsh-commandcode-stream.jsonl";
+/** One raw chunk is recorded verbatim up to this many characters. */
+const STREAM_TRACE_MAX_TEXT = 16384;
+/** Values of {@link STREAM_TRACE_ENV} that mean "trace to the default file". */
+const FLAG_VALUES = /* @__PURE__ */ new Set([
+	"1",
+	"true",
+	"yes",
+	"on"
+]);
+/**
+* Values that explicitly mean OFF.
+*
+* A user turning the trace off writes `false` as readily as they write `1` to
+* turn it on, and without this set every one of these spellings fell through to
+* "…so it must be a path" — the trace switched ON and wrote the conversation to
+* a file NAMED `false` (or `0`, or `off`) in the process's working directory.
+*/
+const OFF_VALUES = /* @__PURE__ */ new Set([
+	"0",
+	"false",
+	"no",
+	"off"
+]);
+/** The inert trace used whenever the switch is off. */
+const OFF = {
+	enabled: false,
+	record: () => void 0,
+	close: () => void 0
+};
+/**
+* Resolve the trace file for this process.
+*
+* @param raw - the variable's raw value; defaults to the live environment.
+* @returns the file to append to, or undefined when the trace is off.
+*/
+function resolveStreamTracePath(raw = process.env[STREAM_TRACE_ENV]) {
+	const value = raw?.trim();
+	if (value === void 0 || value === "") return void 0;
+	const lower = value.toLowerCase();
+	if (OFF_VALUES.has(lower)) return void 0;
+	if (FLAG_VALUES.has(lower)) return join(tmpdir(), STREAM_TRACE_DEFAULT_FILE);
+	return value;
+}
+/**
+* Clamp one recorded payload so a single chunk cannot consume the whole cap.
+*
+* @param text - the text to record.
+* @param max - characters to keep, defaulting to {@link STREAM_TRACE_MAX_TEXT}.
+* @returns `text` unchanged, or its head plus a marker naming what was dropped.
+*/
+function boundTraceText(text, max = STREAM_TRACE_MAX_TEXT) {
+	if (text.length <= max) return text;
+	return `${text.slice(0, max)}…[+${text.length - max} chars]`;
+}
+/**
+* Open one request's trace.
+*
+* @param scope - what the records describe (the `provider/model` route).
+* @param options - `path` overrides the environment (tests pass a temp file);
+*   `now` overrides the clock the `at` stamps are measured with.
+* @returns a writer that never throws and never fails the request.
+*/
+function openStreamTrace(scope, options = {}) {
+	const path = options.path ?? resolveStreamTracePath();
+	if (path === void 0) return OFF;
+	const now = options.now ?? Date.now;
+	const startedAt = now();
+	let written = 0;
+	let stopped = false;
+	let capped = false;
+	const terminals = /* @__PURE__ */ new Set();
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+	} catch {
+		return OFF;
+	}
+	const write = (record) => {
+		if (stopped) return;
+		const terminal = record.event === "end" || record.event === "stream-close";
+		if (capped && !terminal) return;
+		if (terminal && terminals.has(String(record.event))) return;
+		let line;
+		try {
+			line = `${JSON.stringify({
+				at: now() - startedAt,
+				scope,
+				...record
+			})}\n`;
+		} catch {
+			return;
+		}
+		if (terminal) {
+			if (Buffer.byteLength(line) > 16384) return;
+			terminals.add(String(record.event));
+		} else if (written + Buffer.byteLength(line) > 4194304) {
+			capped = true;
+			line = `${JSON.stringify({
+				at: now() - startedAt,
+				scope,
+				event: "trace-capped",
+				bytes: written
+			})}\n`;
+		}
+		try {
+			appendFileSync(path, line);
+			written += Buffer.byteLength(line);
+		} catch {
+			stopped = true;
+		}
+	};
+	write({ event: "stream-open" });
+	return {
+		enabled: true,
+		record(event, fields) {
+			write(fields === void 0 ? { event } : {
+				event,
+				...fields
+			});
+		},
+		close() {
+			write({
+				event: "stream-close",
+				bytes: written
+			});
+		}
+	};
+}
+//#endregion
 //#region src/adapter.ts
 /**
 * DeepSeek Harness LLM adapter for the Command Code Provider API.
@@ -2767,15 +2942,21 @@ function periodEndValue(value) {
 * Terminal stream-error markers from the official CLI (`Xw` in command-code's
 * cli.mjs): these always mean "retrying cannot succeed", so the adapter must
 * not classify them as transient server errors.
+*
+* Written with spaces rather than the CLI's underscores, because
+* {@link hasTerminalStreamMarker} normalizes the separator before matching:
+* a JSON body usually carries `premium credits exhausted` while the CLI's own
+* list is written `premium_credits_exhausted`, and both are the same refusal
+* (the pre-stream classifier normalizes identically).
 */
 const TERMINAL_STREAM_ERROR_MARKERS = [
-	"premium_credits_exhausted",
-	"model_not_in_plan",
+	"premium credits exhausted",
+	"model not in plan",
 	"insufficient credits"
 ];
 function hasTerminalStreamMarker(message) {
-	const lower = message.toLowerCase();
-	return TERMINAL_STREAM_ERROR_MARKERS.some((marker) => lower.includes(marker));
+	const normalized = message.toLowerCase().replaceAll("_", " ");
+	return TERMINAL_STREAM_ERROR_MARKERS.some((marker) => normalized.includes(marker));
 }
 /**
 * Context-window wording the provider uses to reject a request that outgrew
@@ -2814,7 +2995,10 @@ function isContextOverflowDetail(detail) {
 *   (issue #39).
 * - Credits/plan wording is terminal, so an exhausted balance or a model
 *   outside the plan is not retried as if it were a transient rate limit.
-* - Only then does the status/`isRetryable` pair decide, as before.
+* - Only then does the status/`isRetryable` pair decide — and an explicit
+*   refusal (`isRetryable: false`) or a terminal marker OUTRANKS a status, so a
+*   5xx carrying "insufficient credits" stays terminal instead of entering the
+*   retry cadence as `SERVER`.
 */
 function streamErrorToLlmError(value, fallbackMessage) {
 	const record = isRecord(value) ? value : void 0;
@@ -2829,7 +3013,7 @@ function streamErrorToLlmError(value, fallbackMessage) {
 	const statusOption = statusCode !== void 0 ? { status: statusCode } : void 0;
 	if (isContextOverflowDetail(detail)) return new LlmError(`Command Code stream error: ${message}；Command Code API 拒绝了这次请求：内容超出模型上下文窗口。正在压缩上下文后重试；如仍失败，请新建会话或减少上下文`, CONTEXT_WINDOW_EXCEEDED_CODE, statusOption);
 	const terminal = hasTerminalStreamMarker(detail);
-	if (!(isRetryable === true || (statusCode !== void 0 ? statusCode !== void 0 && (statusCode === 429 || statusCode >= 500) : isRetryable !== false && !terminal))) return new LlmError(`Command Code stream error: ${message}`, "PROVIDER_STREAM_ERROR", statusOption);
+	if (!(isRetryable === true || (isRetryable === false || terminal ? false : statusCode !== void 0 ? statusCode !== void 0 && (statusCode === 429 || statusCode >= 500) : true))) return new LlmError(`Command Code stream error: ${message}`, "PROVIDER_STREAM_ERROR", statusOption);
 	return new LlmError(`Command Code stream error: ${message}`, "SERVER", statusOption);
 }
 function recordOrEmpty(value) {
@@ -3033,42 +3217,32 @@ async function writeModelsCache(cachePath, models) {
 	}
 }
 /**
-* Whether an inbound message is a tool RESULT — a `user`-role message the
-* producer tagged with `source: { kind: 'tool' }`.
-*
-* The tag is read defensively because it is PRODUCER-supplied and nothing
-* validates it: dsh-llm's `Message` type declares `source` required, but the
-* runtime never checks it and every adapter shipped before this one ignored the
-* field outright (`dsh-llm-deepseek` never reads it). A third-party plugin that
-* assembles its own history can therefore omit it and run correctly everywhere
-* else — dsh-mneme's memory pipeline did — which made this adapter, the first
-* to actually read the field, the first to crash on such a message with
-* `TypeError: Cannot read properties of undefined (reading 'kind')` in the
-* serialization phase, 0–8 ms in, before any request left the machine and with
-* nothing in the error naming the message or the producer (issue #47).
+* >=0.1.7 puts toolCallId/isError on a role:'tool' message and carries raw
+* content blocks. Older engines wrap those fields in the first tool-result
+* block of a role:'user' message. Read structurally so the bundle still builds
+* and loads against older peers. Pairing and emission MUST use this same view:
+* otherwise a dropped result either drops its call too (making the model
+* forget completed work), or leaves an unanswered call on the wire.
 *
-* Two rules keep an untagged message from costing the turn:
-*
-*  - A PRESENT tag is authoritative. `kind: 'user'`, `'model'`, `'plugin'` or
-*    any producer-added kind means "not a tool result", whatever the content
-*    looks like — the tag answers *who produced this*.
-*  - An ABSENT tag falls back to the content shape. A `user` message whose
-*    first block is a `tool-result` is a tool result by the harness's own
-*    definition (`ToolResultMessage` is exactly that shape with a
-*    `ToolMessageSource`), and the fallback is not cosmetic: `pairedToolCalls()`
-*    counts a `tool-result` block from ANY message, so classifying such a
-*    message as a plain user message would drop it at emission while its call
-*    still counted as paired — leaving the assistant's tool call unanswered on
-*    the wire, which the gateway rejects outright. FIRST block, not "any block":
-*    the tool-result branch reads `content[0]` and skips anything else, so
-*    claiming a mixed message as a tool result would discard its other blocks
-*    instead of sending them.
-*/
-function isToolResultMessage(message) {
-	if (message.role !== "user") return false;
+* For the legacy envelope a present source tag remains authoritative; an
+* absent tag falls back to the first block (issue #47). The modern role is
+* itself the discriminator, as it is for the Harness's own serializers.
+*/
+function toolResultOf(message) {
+	const current = message;
+	if (current.role === "tool") {
+		if (typeof current.toolCallId !== "string" || current.toolCallId === "") return void 0;
+		return {
+			toolCallId: current.toolCallId,
+			isError: current.isError ?? false,
+			content: current.content
+		};
+	}
+	if (message.role !== "user") return void 0;
 	const kind = message.source?.kind;
-	if (kind !== void 0) return kind === "tool";
-	return message.content?.[0]?.type === "tool-result";
+	if (kind !== void 0 && kind !== "tool") return void 0;
+	const block = message.content[0];
+	return block?.type === "tool-result" ? block : void 0;
 }
 /**
 * Collect the tool calls that have a paired tool result, plus each call's
@@ -3081,12 +3255,13 @@ function pairedToolCalls(messages) {
 	const callIds = /* @__PURE__ */ new Set();
 	const names = /* @__PURE__ */ new Map();
 	const resultIds = /* @__PURE__ */ new Set();
-	for (const message of messages) for (const block of message.content) {
-		if (message.role === "assistant" && block.type === "tool-call") {
+	for (const message of messages) {
+		const result = toolResultOf(message);
+		if (result) resultIds.add(result.toolCallId);
+		for (const block of message.content) if (message.role === "assistant" && block.type === "tool-call") {
 			callIds.add(block.id);
 			names.set(block.id, block.name);
 		}
-		if (block.type === "tool-result") resultIds.add(block.toolCallId);
 	}
 	return {
 		ids: new Set([...callIds].filter((id) => resultIds.has(id))),
@@ -3394,7 +3569,8 @@ async function messagesToCC(messages, readImage) {
 	};
 	for (const message of messages) {
 		if (message.role === "system") continue;
-		if (message.role === "user" && !isToolResultMessage(message)) {
+		const result = toolResultOf(message);
+		if (message.role === "user" && !result) {
 			flushPendingImages();
 			const parts = [];
 			for (const block of message.content) {
@@ -3437,18 +3613,17 @@ async function messagesToCC(messages, readImage) {
 			});
 			continue;
 		}
-		if (isToolResultMessage(message)) {
-			const block = message.content[0];
-			if (!block || block.type !== "tool-result" || !paired.has(block.toolCallId)) continue;
-			const media = toolResultMedia(block);
-			const wireToolCallId = wireIds.get(block.toolCallId) ?? block.toolCallId;
+		if (result) {
+			if (!paired.has(result.toolCallId)) continue;
+			const media = toolResultMedia(result);
+			const wireToolCallId = wireIds.get(result.toolCallId) ?? result.toolCallId;
 			out.push({
 				role: "tool",
 				content: [{
 					type: "tool-result",
 					toolCallId: wireToolCallId,
-					toolName: toolNames.get(block.toolCallId) || "unknown",
-					output: block.isError ? {
+					toolName: toolNames.get(result.toolCallId) || "unknown",
+					output: result.isError ? {
 						type: "error-text",
 						value: toolResultTextForWire(media)
 					} : {
@@ -3506,7 +3681,8 @@ async function messagesToOpenAI(messages, readImage) {
 	};
 	for (const message of messages) {
 		if (message.role === "system") continue;
-		if (message.role === "user" && !isToolResultMessage(message)) {
+		const result = toolResultOf(message);
+		if (message.role === "user" && !result) {
 			flushPendingImages();
 			const parts = [];
 			for (const block of message.content) {
@@ -3552,11 +3728,10 @@ async function messagesToOpenAI(messages, readImage) {
 			out.push(assistant);
 			continue;
 		}
-		if (isToolResultMessage(message)) {
-			const block = message.content[0];
-			if (!block || block.type !== "tool-result" || !paired.has(block.toolCallId)) continue;
-			const media = toolResultMedia(block);
-			const wireToolCallId = wireIds.get(block.toolCallId) ?? block.toolCallId;
+		if (result) {
+			if (!paired.has(result.toolCallId)) continue;
+			const media = toolResultMedia(result);
+			const wireToolCallId = wireIds.get(result.toolCallId) ?? result.toolCallId;
 			out.push({
 				role: "tool",
 				tool_call_id: wireToolCallId,
@@ -3817,6 +3992,7 @@ function createBlockAssembler() {
 		reasoningIndex: -1,
 		reasoningContent: "",
 		sawContent: false,
+		finishReason: void 0,
 		openAiToolCalls: []
 	};
 }
@@ -4036,8 +4212,10 @@ var CommandCodeAdapter = class extends LlmAdapter {
 	/** The headers every authenticated account endpoint shares. */
 	async accountHeaders(apiKey) {
 		const connection = this.deps.options();
+		const raw = apiKey ?? await this.deps.resolveApiKey(connection);
+		const named = connection.apiKeyEnv;
 		return {
-			Authorization: `Bearer ${apiKey ?? await this.deps.resolveApiKey(connection)}`,
+			Authorization: `Bearer ${assertUsableApiKey(raw, "llm-commandcode", typeof named === "string" && named !== "" ? named : "the stored credential")}`,
 			"x-command-code-version": COMMAND_CODE_CLI_VERSION,
 			"x-cli-environment": "production",
 			...attributionHeaders()
@@ -4049,11 +4227,16 @@ var CommandCodeAdapter = class extends LlmAdapter {
 	* failure accounting: the billing probe fails open silently, the usage
 	* report books failures per endpoint. Non-2xx and non-record bodies come
 	* back without a record; only a transport throw propagates to the caller.
+	*
+	* `timeoutMs` is the caller's budget for this one request. The default is the
+	* CATALOG probe's short cap, which fits the picker's fail-open reads; the
+	* usage report deliberately passes the connection's own request budget so an
+	* account query is not held to a stricter (and invisible) limit than chat.
 	*/
-	async fetchEndpointJson(url, headers) {
+	async fetchEndpointJson(url, headers, timeoutMs = MODELS_TIMEOUT_MS) {
 		const response = await this.fetchImpl(url, {
 			headers,
-			signal: AbortSignal.timeout(MODELS_TIMEOUT_MS)
+			signal: AbortSignal.timeout(timeoutMs)
 		});
 		if (!response.ok) return { status: response.status };
 		const parsed = await response.json();
@@ -4211,15 +4394,39 @@ var CommandCodeAdapter = class extends LlmAdapter {
 	* view. Requires a usable API key (throws `MISSING_CREDENTIAL` otherwise).
 	* Pass `apiKey` to report on a specific account of a multi-account pool;
 	* the default resolves the currently active account.
+	*
+	* Two failure modes are NOT "the network is down", and the report must say
+	* so rather than let {@link classifyTotalFailure} blame the connection:
+	*
+	*  - A key that no HTTP header can carry (a stray newline from a paste, a
+	*    full-width character) makes `fetch` throw a `TypeError` **before any
+	*    I/O**, for every endpoint at once. The chat path refuses such a key
+	*    through `assertUsableApiKey`; this path must too, and it answers
+	*    `blocked: 'invalid-key'` instead of four phantom transport failures.
+	*  - The four endpoints get the SAME per-request budget as a chat call
+	*    (`connection.requestTimeoutMs`, default 60 s), not the catalog's 10 s
+	*    probe budget: on a slow link a 10 s cap made every account query time
+	*    out while chat kept working, which is exactly a "check your network"
+	*    banner that never clears.
 	*/
 	async getUsage(apiKey) {
-		const base = this.deps.options().apiBase;
-		const headers = await this.accountHeaders(apiKey);
+		const connection = this.deps.options();
+		const base = connection.apiBase;
+		let headers;
+		try {
+			headers = await this.accountHeaders(apiKey);
+		} catch (error) {
+			if (error instanceof LlmError && error.code === "INVALID_CREDENTIAL") return {
+				failures: [error.message],
+				blocked: "invalid-key"
+			};
+			throw error;
+		}
 		const failures = [];
 		const failedStatuses = [];
 		const getJson = async (path) => {
 			try {
-				const { status, record } = await this.fetchEndpointJson(`${base}${path}`, headers);
+				const { status, record } = await this.fetchEndpointJson(`${base}${path}`, headers, connection.requestTimeoutMs);
 				if (record === void 0) {
 					failures.push(`${path}: HTTP ${status}`);
 					failedStatuses.push(status);
@@ -4305,7 +4512,7 @@ var CommandCodeAdapter = class extends LlmAdapter {
 				reported = true;
 				if (!window.exceeded) continue;
 				exceeded = true;
-				resetAt = Math.max(resetAt, window.resetAt);
+				if (window.resetAt > 0 && window.resetAt - Date.now() <= MAX_TRUSTED_RESET_MS) resetAt = Math.max(resetAt, window.resetAt);
 			}
 			if (!reported) return void 0;
 			return {
@@ -4413,6 +4620,19 @@ var CommandCodeAdapter = class extends LlmAdapter {
 		const reader = response.body.getReader();
 		const decoder = new TextDecoder();
 		let buffer = "";
+		const trace = openStreamTrace(`${options.provider}/${options.model}`);
+		const streamStartedAt = Date.now();
+		let chunkCount = 0;
+		let totalBytes = 0;
+		let lastChunkAt = streamStartedAt;
+		trace.record("response", {
+			protocol,
+			endpoint: protocol === "cli" ? `${connection.apiBase}/alpha/generate` : `${connection.apiBase}/provider/v1/chat/completions`,
+			status: response.status,
+			attempts: tried.size,
+			maxTokens,
+			...reasoningEffort === void 0 ? {} : { reasoningEffort }
+		});
 		let idleTimer;
 		let idleFired = false;
 		const armIdle = () => {
@@ -4429,9 +4649,16 @@ var CommandCodeAdapter = class extends LlmAdapter {
 			}
 		};
 		const asm = createBlockAssembler();
-		const handle = (event) => handleEvent(asm, protocol, event);
+		let finish;
+		let usage;
+		let usageEmitted = false;
+		let endRecorded = false;
+		function* handle(event) {
+			for (const chunk of handleEvent(asm, protocol, event)) if (chunk.type === "finish") finish = chunk;
+			else if (chunk.type === "usage") usage = chunk.usage;
+			else yield chunk;
+		}
 		try {
-			let finished = false;
 			for (;;) {
 				let read;
 				armIdle();
@@ -4439,44 +4666,104 @@ var CommandCodeAdapter = class extends LlmAdapter {
 					read = await reader.read();
 				} catch (error) {
 					if (options.signal?.aborted) throw error;
+					trace.record("read-error", {
+						chunks: chunkCount,
+						bytes: totalBytes,
+						silentMs: Date.now() - lastChunkAt,
+						message: errorChain(error)
+					});
 					throw new LlmError(`Command Code API stream from ${connection.apiBase} failed while reading: ${errorChain(error)}；Command Code API 流式响应中途断开——网络波动所致，重试通常可恢复`, "TRANSPORT", { cause: error });
 				} finally {
 					clearIdle();
 				}
 				const { done, value } = read;
 				if (done) {
+					trace.record("eof", {
+						chunks: chunkCount,
+						bytes: totalBytes,
+						silentMs: Date.now() - lastChunkAt,
+						totalMs: Date.now() - streamStartedAt,
+						finishSeen: finish !== void 0,
+						idleFired,
+						buffered: buffer.length
+					});
 					if (idleFired) throw new LlmError(`Command Code API stream from ${connection.apiBase} was idle for ${connection.streamIdleTimeoutMs}ms (no events) and was treated as a dead connection；Command Code API 流式响应已 ${connection.streamIdleTimeoutMs} 毫秒无任何事件，被判定为死连接——长思考模型可在设置中调大流空闲超时`, "TIMEOUT");
-					if (buffer.trim()) for (const chunk of handle(parseStreamEventLine(buffer))) {
-						yield chunk;
-						if (chunk.type === "finish") finished = true;
-					}
+					if (buffer.trim()) yield* handle(parseStreamEventLine(buffer));
 					break;
 				}
-				buffer += decoder.decode(value, { stream: true });
+				const text = decoder.decode(value, { stream: true });
+				buffer += text;
+				chunkCount += 1;
+				totalBytes += value.byteLength;
+				lastChunkAt = Date.now();
+				trace.record("chunk", {
+					n: chunkCount,
+					bytes: value.byteLength,
+					text: boundTraceText(text)
+				});
 				const lines = buffer.split("\n");
 				buffer = lines.pop() ?? "";
-				for (const line of lines) {
-					const chunks = handle(parseStreamEventLine(line));
-					for (const chunk of chunks) {
-						yield chunk;
-						if (chunk.type === "finish") finished = true;
-					}
-				}
-				if (finished) break;
+				for (const line of lines) yield* handle(parseStreamEventLine(line));
+				if (finish !== void 0) break;
 			}
-			if (!finished) {
-				yield* closeText(asm);
-				yield* closeReasoning(asm);
-				if (protocol === "openai") yield* emitOpenAiToolCalls(asm);
-				if (!asm.sawContent) throw new LlmError("Command Code returned an empty response；Command Code 返回了空响应，重试通常可恢复", "EMPTY_RESPONSE");
+			if (usage !== void 0) {
+				usageEmitted = true;
 				yield {
-					type: "finish",
-					reason: { kind: "stop" }
+					type: "usage",
+					usage
 				};
 			}
+			if (finish !== void 0) {
+				const failure = asm.sawContent ? void 0 : emptyCompletionError(asm.finishReason, maxTokens, usage);
+				trace.record("end", {
+					outcome: failure === void 0 ? "finished" : failure.code === "OUTPUT_TOKEN_LIMIT" ? "output-token-limit" : "empty",
+					finishReason: asm.finishReason,
+					...failure === void 0 ? {} : { code: failure.code },
+					maxTokens,
+					...usage === void 0 ? {} : { usage },
+					chunks: chunkCount,
+					bytes: totalBytes,
+					totalMs: Date.now() - streamStartedAt,
+					sawContent: asm.sawContent
+				});
+				endRecorded = true;
+				if (failure !== void 0) throw failure;
+				yield finish;
+			} else {
+				const elapsed = Date.now() - streamStartedAt;
+				const detail = `${chunkCount} chunk(s), ${totalBytes} bytes, ${elapsed}ms`;
+				trace.record("end", {
+					outcome: asm.sawContent ? "stream-closed" : "empty",
+					chunks: chunkCount,
+					bytes: totalBytes,
+					totalMs: elapsed,
+					sawContent: asm.sawContent
+				});
+				endRecorded = true;
+				if (!asm.sawContent) throw new LlmError("Command Code returned an empty response；Command Code 返回了空响应，重试通常可恢复", "EMPTY_RESPONSE");
+				throw new LlmError(`Command Code API stream from ${connection.apiBase} ended before its finish event (${detail}) — the response was closed mid-generation, so this is not the model stopping by itself；Command Code API 流式响应在结束事件之前被关闭（生成中途断流），并非模型主动结束——请重试；若频繁出现，可用 ${STREAM_TRACE_ENV}=<文件路径> 抓取原始流以定位断流原因`, "STREAM_CLOSED");
+			}
+		} catch (error) {
+			if (!usageEmitted && usage !== void 0) yield {
+				type: "usage",
+				usage
+			};
+			if (!endRecorded) trace.record("end", {
+				outcome: options.signal?.aborted ? "aborted" : "error",
+				code: error instanceof LlmError ? error.code : "unknown",
+				finishReason: asm.finishReason,
+				maxTokens,
+				...usage === void 0 ? {} : { usage },
+				sawContent: asm.sawContent,
+				chunks: chunkCount,
+				bytes: totalBytes,
+				totalMs: Date.now() - streamStartedAt
+			});
+			throw error;
 		} finally {
 			clearIdle();
 			cleanup();
+			trace.close();
 			await reader.cancel().catch(() => void 0);
 			reader.releaseLock();
 		}
@@ -4567,7 +4854,7 @@ function handleCliEvent(asm, event) {
 			}
 			const delta = stringValue(event.text) ?? "";
 			asm.textContent += delta;
-			asm.sawContent = true;
+			if (delta.trim() !== "") asm.sawContent = true;
 			chunks.push({
 				type: "text-delta",
 				index: asm.textIndex,
@@ -4630,6 +4917,7 @@ function handleCliEvent(asm, event) {
 			break;
 		}
 		case "finish": {
+			asm.finishReason = stringValue(event.finishReason);
 			chunks.push(...closeText(asm), ...closeReasoning(asm));
 			const usage = isRecord(event.totalUsage) ? event.totalUsage : void 0;
 			if (usage) {
@@ -4643,6 +4931,8 @@ function handleCliEvent(asm, event) {
 					cacheReadTokens: cacheRead,
 					cacheWriteTokens: cacheWrite
 				};
+				const reasoningTokens = numberValue((isRecord(usage.outputTokenDetails) ? usage.outputTokenDetails : void 0)?.reasoningTokens) ?? numberValue(usage.reasoningTokens);
+				if (reasoningTokens !== void 0) tokenUsage.reasoningTokens = reasoningTokens;
 				chunks.push({
 					type: "usage",
 					usage: tokenUsage
@@ -4707,39 +4997,38 @@ function handleOpenAIEvent(asm, event) {
 			});
 		}
 		asm.textContent += contentDelta;
-		asm.sawContent = true;
+		if (contentDelta.trim() !== "") asm.sawContent = true;
 		chunks.push({
 			type: "text-delta",
 			index: asm.textIndex,
 			text: contentDelta
 		});
 	}
-	if (Array.isArray(delta.tool_calls)) {
+	if (Array.isArray(delta.tool_calls)) for (const rawCall of delta.tool_calls) {
+		if (!isRecord(rawCall)) continue;
 		asm.sawContent = true;
-		for (const rawCall of delta.tool_calls) {
-			if (!isRecord(rawCall)) continue;
-			const callIndex = numberValue(rawCall.index) ?? 0;
-			let existing = asm.openAiToolCalls.find((call) => call.index === callIndex);
-			const fn = isRecord(rawCall.function) ? rawCall.function : void 0;
-			const id = stringValue(rawCall.id);
-			const name = fn === void 0 ? void 0 : stringValue(fn.name);
-			const argDelta = fn === void 0 ? void 0 : stringValue(fn.arguments) ?? (fn.arguments === void 0 ? "" : JSON.stringify(fn.arguments));
-			if (!existing) {
-				existing = {
-					index: callIndex,
-					name: name ?? "",
-					arguments: argDelta ?? ""
-				};
-				if (id !== void 0) existing.id = id;
-				asm.openAiToolCalls.push(existing);
-			} else {
-				if (id !== void 0 && existing.id === void 0) existing.id = id;
-				if (name !== void 0 && existing.name === "") existing.name = name;
-				if (argDelta !== void 0) existing.arguments += argDelta;
-			}
+		const callIndex = numberValue(rawCall.index) ?? 0;
+		let existing = asm.openAiToolCalls.find((call) => call.index === callIndex);
+		const fn = isRecord(rawCall.function) ? rawCall.function : void 0;
+		const id = stringValue(rawCall.id);
+		const name = fn === void 0 ? void 0 : stringValue(fn.name);
+		const argDelta = fn === void 0 ? void 0 : stringValue(fn.arguments) ?? (fn.arguments === void 0 ? "" : JSON.stringify(fn.arguments));
+		if (!existing) {
+			existing = {
+				index: callIndex,
+				name: name ?? "",
+				arguments: argDelta ?? ""
+			};
+			if (id !== void 0) existing.id = id;
+			asm.openAiToolCalls.push(existing);
+		} else {
+			if (id !== void 0 && existing.id === void 0) existing.id = id;
+			if (name !== void 0 && existing.name === "") existing.name = name;
+			if (argDelta !== void 0) existing.arguments += argDelta;
 		}
 	}
 	if (choice.finish_reason !== void 0 && choice.finish_reason !== null) {
+		asm.finishReason = stringValue(choice.finish_reason);
 		chunks.push(...closeText(asm), ...closeReasoning(asm), ...emitOpenAiToolCalls(asm));
 		if (event.usage !== void 0) chunks.push({
 			type: "usage",
@@ -4787,6 +5076,13 @@ function mapFinishReason(reason) {
 	if (reason === "length" || reason === "max_tokens" || reason === "max-tokens" || reason === "max_output_tokens") return { kind: "max-tokens" };
 	return { kind: "stop" };
 }
+/** A terminal marker without text or tools is a failed attempt, not a completed turn. */
+function emptyCompletionError(reason, maxTokens, usage) {
+	const detail = `finish_reason=${reason ?? "unknown"}, max_tokens=${maxTokens}, outputTokens=${usage?.outputTokens ?? "unknown"}, reasoningTokens=${usage?.reasoningTokens ?? "unknown"}`;
+	if (mapFinishReason(reason).kind === "max-tokens") return new LlmError(`Command Code reached the output token limit without producing answer text or a tool call (${detail})；Command Code 已达到输出 token 上限，但没有生成正文或工具调用；请调整思考强度，或在模型和接口上限内增加输出预算`, "OUTPUT_TOKEN_LIMIT");
+	if (reason === "content_filter" || reason === "content-filter") return new LlmError(`Command Code filtered the response (${detail})；Command Code 拦截了响应，未生成正文或工具调用`, "CONTENT_FILTER");
+	return new LlmError(`Command Code finished without producing answer text or a tool call (${detail})；Command Code 返回了空响应（可能只有思考内容），重试通常可恢复`, "EMPTY_RESPONSE");
+}
 /**
 * True when a Provider API pre-stream rejection is Command Code's Go-plan
 * gate (`upgrade_required`). Only this exact class of rejection should fall
@@ -4831,8 +5127,25 @@ function mapFinishReason(reason) {
 *     or a model outside its plan (`MODEL_NOT_IN_PLAN`). Rotating must NOT mark
 *     the account: the fact is about the model or the balance, it can change
 *     without the key changing, and a `:free` model can still be served by an
-*     account with an empty balance.
+*     account with an empty balance. These codes are recognized on EVERY
+*     status — a 5xx that proxies the provider's own credits/plan body is
+*     still an account fact, and only the prose scan is confined to 4xx.
 */
+/**
+* The provider's structured "this account cannot serve this request" codes.
+*
+* Status-independent on purpose, mirroring the CLI's classifier, which reads
+* the code before any status guard. A 5xx that carries one of these must not
+* be retried as a transient provider failure: the same request against the
+* same account cannot succeed, so the caller rotates past it (without marking
+* the key) instead of replaying it on the harness's retry cadence.
+*/
+const ACCOUNT_UNAVAILABLE_CODES = /* @__PURE__ */ new Set([
+	"USAGE_EXCEEDED",
+	"INSUFFICIENT_CREDITS",
+	"PREMIUM_CREDITS_EXHAUSTED",
+	"MODEL_NOT_IN_PLAN"
+]);
 function classifyAccountRejection(status, errText) {
 	if (status === 429 || readProviderErrorCode(errText)?.toUpperCase() === "RATE_LIMITED") {
 		const evidence = readWindowLimitEvidence(errText);
@@ -4843,10 +5156,11 @@ function classifyAccountRejection(status, errText) {
 		};
 	}
 	if (status === 401) return { reason: "invalid-credential" };
+	const code = readProviderErrorCode(errText)?.toUpperCase();
+	if (code !== void 0 && ACCOUNT_UNAVAILABLE_CODES.has(code)) return { reason: "unavailable" };
 	if (status < 400 || status >= 500) return void 0;
 	const lower = errText.toLowerCase().replaceAll("_", " ");
-	const code = readProviderErrorCode(errText)?.toUpperCase();
-	if (code === "USAGE_EXCEEDED" || code === "INSUFFICIENT_CREDITS" || code === "PREMIUM_CREDITS_EXHAUSTED" || code === "MODEL_NOT_IN_PLAN" || lower.includes("insufficient credits") || lower.includes("premium credits exhausted") || lower.includes("model not in plan") || /insufficient (credit|balance)/.test(lower) || /out of credit/.test(lower) || /not (available|included)[^.]{0,40}plan/.test(lower) || lower.includes("upgrade your plan")) return { reason: "unavailable" };
+	if (lower.includes("insufficient credits") || lower.includes("premium credits exhausted") || lower.includes("model not in plan") || /insufficient (credit|balance)/.test(lower) || /out of credit/.test(lower) || /not (available|included)[^.]{0,40}plan/.test(lower) || lower.includes("upgrade your plan")) return { reason: "unavailable" };
 }
 /** The machine-readable `error.code`/`error.type` of a pre-stream failure body. */
 function readProviderErrorCode(errText) {
@@ -4860,6 +5174,16 @@ function readProviderErrorCode(errText) {
 	}
 }
 /**
+* How far ahead a provider-published reset may be and still be trusted.
+*
+* Generous on purpose: the weekly window is the longest this provider meters,
+* and the value is a plausibility bound rather than a policy. Beyond it the
+* reset is dropped rather than clamped, which leaves the account's mark
+* `unknown` — the state the pool's probe pass re-checks — instead of a
+* cooldown that never expires.
+*/
+const MAX_TRUSTED_RESET_MS = 2592e6;
+/**
 * The usage-window evidence carried by a rejected request, mirroring the CLI's
 * `parseWindowLimitError` → `resolveWindowLabel`/`extractResetAtMs` pair.
 *
@@ -4893,7 +5217,8 @@ function readWindowLimitEvidence(errText) {
 	const window = named === "fiveHour" || named === "weekly" || named === "daily" ? named : /usage limit for your plan/i.test(message) || /usage limit for your plan/i.test(errText) ? /weekly/i.test(message) ? "weekly" : "fiveHour" : void 0;
 	const stamp = /resets at (\d{4}-\d{2}-\d{2}T[\d:.]+Z)/i.exec(message)?.[1] ?? /resets at (\d{4}-\d{2}-\d{2}T[\d:.]+Z)/i.exec(errText)?.[1];
 	const stamped = stamp === void 0 ? void 0 : Date.parse(stamp);
-	const resetAtMs = seconds !== void 0 && seconds > 0 ? Math.round(seconds * 1e3) : stamped !== void 0 && !Number.isNaN(stamped) ? stamped : void 0;
+	const published = seconds !== void 0 && seconds > 0 ? Math.round(seconds * 1e3) : stamped !== void 0 && !Number.isNaN(stamped) ? stamped : void 0;
+	const resetAtMs = published !== void 0 && Number.isFinite(published) && published - Date.now() <= MAX_TRUSTED_RESET_MS ? published : void 0;
 	return {
 		...window === void 0 ? {} : { window },
 		...resetAtMs === void 0 ? {} : { resetAtMs }
@@ -5693,7 +6018,10 @@ function isCallbackCredentials(value) {
 /**
 * One browser-login attempt machine. Single-flight by design: `begin()` while
 * waiting returns the live attempt's status instead of starting a second one;
-* a terminal state makes the next `begin()` start fresh.
+* a start that is still binding its port is REJOINED through
+* {@link CommandCodeLoginFlow.begin}'s in-flight promise, because the status
+* face cannot say `waiting` until that bind settles; a terminal state makes the
+* next `begin()` start fresh.
 */
 var CommandCodeLoginFlow = class {
 	deps;
@@ -5711,6 +6039,17 @@ var CommandCodeLoginFlow = class {
 	* the user cancelled and flipping the page back to success.
 	*/
 	attemptSeq = 0;
+	/**
+	* The start currently binding a port, if any. Every `begin()` that arrives
+	* before it settles joins it: two independent starts would each bind their
+	* own loopback server, and only the LAST one is reachable by
+	* {@link CommandCodeLoginFlow.teardown} — the orphan keeps listening and
+	* answering `/callback` for the process's lifetime, and ten of them exhaust
+	* the port window so browser login dies until the Host restarts.
+	*/
+	starting;
+	/** A `cancel()` that arrived while a start was still binding (see {@link CommandCodeLoginFlow.cancel}). */
+	cancelPending = false;
 	disposed = false;
 	constructor(deps) {
 		this.deps = deps;
@@ -5732,6 +6071,22 @@ var CommandCodeLoginFlow = class {
 	async begin() {
 		if (this.disposed) throw new Error("login flow has been disposed");
 		if (this.statusValue.state === "waiting" && this.server !== void 0) return this.statusValue;
+		if (this.starting !== void 0) return this.starting;
+		this.cancelPending = false;
+		const starting = this.startAttempt();
+		this.starting = starting;
+		try {
+			return await starting;
+		} finally {
+			if (this.starting === starting) this.starting = void 0;
+		}
+	}
+	/**
+	* The binding half of {@link CommandCodeLoginFlow.begin}: one attempt, one
+	* server, one published `waiting` status. Callers reach it only through
+	* `begin()`'s single-flight fence.
+	*/
+	async startAttempt() {
 		this.teardown();
 		const attempt = ++this.attemptSeq;
 		const port = await this.findPort();
@@ -5743,6 +6098,16 @@ var CommandCodeLoginFlow = class {
 			};
 		});
 		await this.bindServer(port, expectedState);
+		if (this.disposed || this.cancelPending) {
+			const cancelled = !this.disposed;
+			this.cancelPending = false;
+			this.teardown();
+			if (cancelled) this.setStatus({
+				state: "failed",
+				reason: "cancelled"
+			});
+			return this.statusValue;
+		}
 		const apiBase = this.readApiBase();
 		this.setStatus({
 			state: "waiting",
@@ -5764,19 +6129,29 @@ var CommandCodeLoginFlow = class {
 		settled.then((credentials) => this.complete(attempt, credentials), (failure) => this.failFrom(attempt, failure));
 		return this.statusValue;
 	}
-	/** Cancel a waiting attempt; terminal states are untouched. */
+	/**
+	* Cancel a waiting attempt; terminal states are untouched. A start that is
+	* still binding a port is flagged instead of ignored — it cannot be torn
+	* down from here (its server does not exist yet), so `startAttempt` observes
+	* the flag once the bind settles and retires it.
+	*/
 	cancel() {
-		if (this.disposed || this.statusValue.state !== "waiting") return;
-		this.teardown();
-		this.setStatus({
-			state: "failed",
-			reason: "cancelled"
-		});
+		if (this.disposed) return;
+		if (this.statusValue.state === "waiting") {
+			this.teardown();
+			this.setStatus({
+				state: "failed",
+				reason: "cancelled"
+			});
+			return;
+		}
+		if (this.starting !== void 0) this.cancelPending = true;
 	}
 	/** Stop everything; a waiting attempt ends cancelled. Idempotent. */
 	dispose() {
 		if (this.disposed) return;
 		this.disposed = true;
+		this.cancelPending = false;
 		const wasWaiting = this.statusValue.state === "waiting";
 		this.teardown();
 		if (wasWaiting) this.setStatus({
@@ -5812,8 +6187,12 @@ var CommandCodeLoginFlow = class {
 			const server = createServer((request, response) => this.handleCallback(request, response, expectedState));
 			this.server = server;
 			server.once("error", (error) => {
-				if (this.server !== server) return;
+				if (this.server !== server) {
+					closeServer(server);
+					return;
+				}
 				this.server = void 0;
+				closeServer(server);
 				const tagged = new LoginSettleError("error", `Could not bind the login callback server on port ${port}: ${error.code ?? error.message}`);
 				if (binding) {
 					binding = false;
@@ -5982,11 +6361,17 @@ var CommandCodeLoginFlow = class {
 	/** Close the server and watchdog without touching the published status. */
 	teardown() {
 		this.clearTimer();
-		this.server?.close();
+		closeServer(this.server);
 		this.server = void 0;
 		this.settle = void 0;
 	}
 };
+/** Close one loopback server without letting "not running"/"already closed" escape. */
+function closeServer(server) {
+	try {
+		server?.close();
+	} catch {}
+}
 /** A tagged settle failure carrying the stable copy reason. */
 var LoginSettleError = class extends Error {
 	reason;
@@ -6060,7 +6445,8 @@ function selectCommandCodeSearchProvider(web, enable) {
 function commandCodeSearchSelection() {
 	return {
 		owner: false,
-		displaced: void 0
+		displaced: void 0,
+		preexisting: false
 	};
 }
 /**
@@ -6078,8 +6464,14 @@ function commandCodeSearchSelection() {
 *   auto-select — already says what the user wants.
 * - When the field already reads `commandcode` at first touch (e.g. a
 *   surviving runtime the plugin did not set, or a manual
-*   `searchProvider: commandcode` pin), `displaced` stays undefined so the
-*   later disable is a no-op rather than a guess at the factory default.
+*   `searchProvider: commandcode` pin), `displaced` stays undefined and
+*   `preexisting` is set, so the later disable is a no-op rather than a guess
+*   at the factory default. A "no-op" means the field is left ALONE: writing
+*   that `undefined` back would destroy the user's own pin, and dsh-web reads
+*   a cleared `searchProviderId` as auto-select — where a second usable
+*   provider (the shipped `deepseek-official` is usable whenever a DeepSeek
+*   key resolves) makes EVERY later search throw
+*   `WEB_PROVIDER_AMBIGUOUS`.
 *
 * Never throws: like the low-level rewrite, a hardened runtime shape degrades
 * to registered-but-unselected.
@@ -6093,14 +6485,16 @@ function applyCommandCodeSearchSelection(web, state, enable) {
 				return;
 			}
 			const prior = field.searchProviderId;
-			state.displaced = prior === "commandcode" ? void 0 : prior;
+			state.preexisting = prior === COMMANDCODE_SEARCH_PROVIDER_ID;
+			state.displaced = state.preexisting ? void 0 : prior;
 			field.searchProviderId = COMMANDCODE_SEARCH_PROVIDER_ID;
 			state.owner = true;
 			return;
 		}
 		if (state.owner) {
 			state.owner = false;
-			field.searchProviderId = state.displaced;
+			if (!state.preexisting) field.searchProviderId = state.displaced;
+			state.preexisting = false;
 			return;
 		}
 	} catch {}
@@ -6402,8 +6796,8 @@ function buildCommandCodeTuiSection(deps) {
 				label: "API key",
 				descriptions: { zh: "API 密钥" },
 				secret: { ref },
-				hint: `Stored in the credential store as ${ref}, never in settings.yaml.`,
-				hintDescriptions: { zh: `保存在凭据库（${ref}），不会写入 settings.yaml。` }
+				hint: `Stored in the credential store as ${ref}, never in configuration files.`,
+				hintDescriptions: { zh: `保存在凭据库（${ref}），不会写入配置文件。` }
 			},
 			{
 				path: ["apiBase"],
@@ -6681,6 +7075,67 @@ function transportBudgetMessage(failureMessage, maxRetries) {
 	return `${failureMessage}；Command Code API 连接在连续重试后仍失败——已停止重试以免整轮卡死。插件已自动重试 ${maxRetries} 次。通常说明当前网络到 api.commandcode.ai 的连接不通，常见原因是代理未生效：DSH 只读取环境变量 HTTPS_PROXY/HTTP_PROXY（系统代理/PAC 不会被读取），请确认启动 DSH 的终端里已导出代理，或先关闭代理直连后重试。网络恢复后直接重发即可 — Command Code API transport still failed after ${maxRetries} automatic retries, which were stopped so the turn could not stall for minutes. This is a connectivity problem between this machine and api.commandcode.ai, not a context-window or request-size rejection. Common cause: the proxy is not reaching the harness — DSH reads HTTPS_PROXY/HTTP_PROXY from the environment only (a Windows system proxy/PAC setting is not consulted), so export it in the launching shell, or turn the proxy off and retry. Resend when the network recovers; the budget is per request and has been reset`;
 }
 //#endregion
+//#region src/config-volatile.ts
+/**
+* Mark one schema field volatile when the installed schemastery supports it.
+* @param schema - The field schema (any generation).
+* @returns The schema carrying `meta.volatile`, or the schema itself on an
+* engine whose schemastery predates `.volatile()`.
+*/
+function markVolatile(schema) {
+	const candidate = schema;
+	if (typeof candidate.volatile !== "function") return schema;
+	return candidate.volatile();
+}
+/**
+* Mark every field of a Config field dict volatile, except the named
+* composition-only secrets (`apiKey` here, which no settings surface writes).
+*
+* The result is a NEW dict of schema instances: callers that also need an
+* UNMARKED schema for the legacy settings generation must build the fields
+* twice (`configFields()`), never share one dict — `.volatile()` clones per
+* call, and a shared instance would carry the mark into the legacy schema.
+*
+* @param fields - Freshly built field schemas.
+* @param skip - Field names that must stay unmarked.
+* @returns The field dict with every non-skipped field marked.
+*/
+function markVolatileFields(fields, skip = []) {
+	return Object.fromEntries(Object.entries(fields).map(([name, schema]) => [name, skip.includes(name) ? schema : markVolatile(schema)]));
+}
+/**
+* Whether a resolved config value is a volatile reference.
+*
+* Duck-typed on the two properties `createVolatile` produces (frozen object
+* with a `get` method) rather than cosmokit's private `write` symbol, because
+* cosmokit is not a peer of this bundle. Config values are plain parsed JSON
+* (or `!!jsExpr` wrappers), which are never frozen, so the test cannot
+* misfire on an ordinary field.
+*/
+function isVolatileRef(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && Object.isFrozen(value) && typeof value.get === "function";
+}
+/**
+* Read one config object as PLAIN values across generations.
+*
+* Each top-level field found to be a volatile reference is read through
+* `.get()` — freshly on every call, so a live update lands on the very next
+* read. When no field is a reference the input object is returned as-is,
+* keeping reference identity stable for identity-keyed memos on engines that
+* hand `apply()` plain config.
+*/
+function unwrapVolatileConfig(config) {
+	const source = config;
+	if (typeof source !== "object" || source === null) return config;
+	let found = false;
+	const plain = {};
+	for (const [field, value] of Object.entries(source)) if (isVolatileRef(value)) {
+		plain[field] = value.get();
+		found = true;
+	} else plain[field] = value;
+	return found ? plain : config;
+}
+//#endregion
 //#region src/index.ts
 /**
 * dsh-commandcode-provider — DeepSeek Harness LLM provider plugin for Command
@@ -6690,9 +7145,10 @@ function transportBudgetMessage(failureMessage, maxRetries) {
 * the configurable-provider directory, so the web Models page shows a
 * "Command Code" card with an API-key field and the model picker lists the
 * live Command Code model catalog. Connection facts resolve per request over
-* the optional `llm-commandcode` user-settings section and the credential
-* seam, so a changed key, endpoint, or cache path reaches the next request
-* without a restart.
+* the plugin's live config — the `llm-commandcode` settings section through
+* dsh 0.1.6, profile Config (volatile fields, unwrapped per read) from 0.1.7
+* — and the credential seam, so a changed key, endpoint, or cache path
+* reaches the next request without a restart.
 *
 * ```yaml
 * - id: llm-commandcode
@@ -6717,41 +7173,84 @@ const DEFAULT_API_KEY_ENV = "COMMANDCODE_API_KEY";
 const PROVIDER = "commandcode";
 /** Default models cache path (mirrors the pi plugin's on-disk cache). */
 const DEFAULT_MODELS_CACHE_PATH = join(homedir(), ".commandcode", "models-cache.json");
-const Config = z.object({
-	apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
-	apiKey: z.string().role("secret"),
-	apiBase: z.string(),
-	workingDir: z.string(),
-	modelsCachePath: z.string(),
-	requestTimeoutMs: z.number().min(1).max(MAX_TIMER_DELAY_MS),
-	streamIdleTimeoutMs: z.number().min(1).max(MAX_TIMER_DELAY_MS),
-	transportMaxRetries: z.number().min(0).max(50),
-	filterModelsByPlan: z.boolean(),
-	visibleModels: z.array(z.string()),
-	/**
-	* Per-model visibility overrides for the terminal settings page's checkbox
-	* list, keyed by catalog id. dsh-TUI addresses a staged edit by its field
-	* PATH, so two checkboxes sharing one path would overwrite each other's
-	* draft and the section's last model would decide every write; a map gives
-	* each checkbox a path of its own. An id listed here wins over
-	* {@link visibleModels}; ids absent here keep following it.
-	*/
-	modelVisibility: z.dict(z.boolean()),
-	webSearch: z.boolean().default(true),
-	showSidebarQuota: z.boolean().default(false),
-	accounts: z.array(z.object({
-		label: z.string(),
-		apiKeyEnv: z.string().role("credential-ref"),
-		/** Literal key for one extra slot; see the top-level `apiKey` secret note. */
-		apiKey: z.string().role("secret")
-	})),
-	activeAccount: z.string(),
-	modelAccountRules: z.array(z.object({
-		models: z.array(z.string()),
-		account: z.string()
-	})),
-	lang: z.string().pattern(/^(zh|en)$/).default("zh")
-});
+/**
+* The Config schema's fields, freshly built on every call.
+*
+* A FACTORY, not a shared dict, and that is load-bearing: the exported
+* {@link Config} marks every field volatile while {@link LegacySettingsSchema}
+* must carry no mark at all, and schemastery's schema instances are
+* single-purpose objects — sharing one dict would leak the marks into the
+* legacy registration (see `config-volatile.ts` for why that is a boot-time
+* `ValidationError` on ≤0.1.6 engines whose schemastery resolved to ≥3.18.3).
+*
+* @returns One fresh schema instance per Config field.
+*/
+function configFields() {
+	return {
+		apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
+		apiKey: z.string().role("secret"),
+		apiBase: z.string(),
+		workingDir: z.string(),
+		modelsCachePath: z.string(),
+		requestTimeoutMs: z.number().min(1).max(MAX_TIMER_DELAY_MS),
+		streamIdleTimeoutMs: z.number().min(1).max(MAX_TIMER_DELAY_MS),
+		transportMaxRetries: z.number().min(0).max(50),
+		filterModelsByPlan: z.boolean(),
+		visibleModels: z.array(z.string()),
+		/**
+		* Per-model visibility overrides for the terminal settings page's checkbox
+		* list, keyed by catalog id. dsh-TUI addresses a staged edit by its field
+		* PATH, so two checkboxes sharing one path would overwrite each other's
+		* draft and the section's last model would decide every write; a map gives
+		* each checkbox a path of its own. An id listed here wins over
+		* {@link Config.visibleModels}; ids absent here keep following it.
+		*/
+		modelVisibility: z.dict(z.boolean()),
+		webSearch: z.boolean().default(true),
+		showSidebarQuota: z.boolean().default(false),
+		accounts: z.array(z.object({
+			label: z.string(),
+			apiKeyEnv: z.string().role("credential-ref"),
+			/** Literal key for one extra slot; see the top-level `apiKey` secret note. */
+			apiKey: z.string().role("secret")
+		})),
+		activeAccount: z.string(),
+		modelAccountRules: z.array(z.object({
+			models: z.array(z.string()),
+			account: z.string()
+		})),
+		lang: z.string().pattern(/^(zh|en)$/).default("zh")
+	};
+}
+/**
+* The 0.1.7-generation schema: every field volatile except the
+* composition-only `apiKey` secret.
+*
+* dsh 0.1.7's settings forms are projected from the schema's `meta.volatile`
+* nodes, so an unmarked field would be invisible to AND unwritable from the
+* settings page and refused by form-edit path validation — and on that
+* generation the loader hands `apply()` a live reference per marked field,
+* committing later writes without remounting this fiber (the
+* `loader/volatile-update` listener at the bottom of `apply` covers the facts
+* that are not re-derived per read). The mark is inert on engines whose
+* schemastery predates `.volatile()`.
+*/
+const Config = z.object(markVolatileFields(configFields(), ["apiKey"]));
+/**
+* The ≤0.1.6-generation registration schema: the same fields, NO volatile
+* marks.
+*
+* The legacy `installSection(owner, ns, schema, entry, hooks)` re-validates the
+* `entry` it is handed (`register()` → `resolve()` → `schema(mergeLayers(base,
+* section))`) and its `describe()` structuredClones that same `entry`. Since
+* schemastery ≥3.18.3 creates references at parse time on EVERY generation —
+* `dsh-settings` through 0.1.6 declares `schemastery: ^3.18.2`, so old engines
+* freshly installed today resolve 3.18.3 — a marked schema plus the raw
+* reference-carrying `config` is a boot-time `ValidationError` there. This
+* schema is therefore unmarked, and `apply` pairs it with
+* `unwrapVolatileConfig(config)`.
+*/
+const LegacySettingsSchema = z.object(configFields());
 /**
 * The one explicit resolve step from raw config to validated connection
 * facts. Programmatic construction may bypass Schemastery normalization, so
@@ -6785,7 +7284,8 @@ function readModelVisibility(raw) {
 }
 function apply(ctx, config) {
 	installCostProjection(ctx);
-	let current = () => config;
+	let source = () => config;
+	const current = () => unwrapVolatileConfig(source());
 	let lastRaw;
 	let lastGood;
 	const options = () => {
@@ -6998,18 +7498,38 @@ function apply(ctx, config) {
 		}, "dsh-commandcode-provider: tui settings handle");
 	});
 	ctx.inject(["settings"], (settingsCtx) => {
-		settingsCtx.settings.installSection(ctx, NS, Config, config, {
-			setSource: (source) => {
-				current = source;
-			},
-			onChange: () => {
-				applySearchSelection(current().webSearch ?? true);
-				refreshTuiSettings?.();
-			}
-		});
+		const service = settingsCtx.settings;
+		if (typeof service.installSection === "function") {
+			service.installSection(ctx, NS, LegacySettingsSchema, unwrapVolatileConfig(config), {
+				setSource: (next) => {
+					source = next;
+				},
+				onChange: () => {
+					applySearchSelection(current().webSearch ?? true);
+					refreshTuiSettings?.();
+				}
+			});
+			return;
+		}
+		if (typeof service.configure === "function") settingsCtx.effect(() => {
+			const dispose = service.configure?.({ auto: false }, ctx.fiber);
+			return () => {
+				dispose?.();
+			};
+		}, "dsh-commandcode-provider: settings auto-form policy");
 	});
+	const loaderEvents = ctx;
+	ctx.effect(() => {
+		const off = loaderEvents.on("loader/volatile-update", () => {
+			applySearchSelection(current().webSearch ?? true);
+			refreshTuiSettings?.();
+		});
+		return () => {
+			if (typeof off === "function") off();
+		};
+	}, "dsh-commandcode-provider: volatile config updates");
 }
 //#endregion
-export { ACTIVE_ACCOUNT_AUTO, BILLING_ACCESS_TTL_MS, COMMANDCODE_SEARCH_PROVIDER_ID, COMMAND_CODE_CLI_VERSION, CommandCodeAccountPool, CommandCodeAdapter, CommandCodeLoginFlow, CommandCodeSearchProvider, CommandCodeUsageService, Config, DEFAULT_API_BASE, DEFAULT_GENERATE_MAX_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_MODELS_CACHE_PATH, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DEFAULT_WEB_SEARCH_PROVIDER_ID, KNOWN_DEALS, KNOWN_EFFORTS, KNOWN_IMAGE_MODELS, KNOWN_PEAK_PRICING, KNOWN_PLANS, KNOWN_SUBSCRIPTION_PLANS, KNOWN_THINKING_MODELS, LANG_AUTO, LOGIN_ALLOWED_ORIGINS, LOGIN_BEGIN_ENDPOINT, LOGIN_BODY_LIMIT_BYTES, LOGIN_CANCEL_ENDPOINT, LOGIN_MAX_PORT_ATTEMPTS, LOGIN_START_PORT, LOGIN_STATUS_ENDPOINT, LOGIN_TIMEOUT_MS, PLAN_LABELS, PLAN_ORDER, PROVIDER, USAGE_REPORT_ENDPOINT, accountUsable, apply, applyCommandCodeSearchSelection, applyCommandCodeTuiSettings, applyCommands, applyUsageRemote, buildCommandAuthUrl, buildCommandCodeTuiSection, capabilityDescription, commandCodeSearchSelection, commandDefinition, compareByPlan, dealLabel, formatContext, inject, loginStatusSchema, matchModelRule, modelVisibleInPlan, name, parseLoginStatus, peakPricingLabel, peakPricingState, planLabel, projectSlugFromPath, resolveAdapterOptions, resolveAuthFileApiKey, selectAccountForModel, selectActiveAccount, selectCommandCodeSearchProvider, studioBaseForApiBase, subscriptionPlanInfo, usageReportSchema, validateCommandApiKey };
+export { ACTIVE_ACCOUNT_AUTO, BILLING_ACCESS_TTL_MS, COMMANDCODE_SEARCH_PROVIDER_ID, COMMAND_CODE_CLI_VERSION, CommandCodeAccountPool, CommandCodeAdapter, CommandCodeLoginFlow, CommandCodeSearchProvider, CommandCodeUsageService, Config, DEFAULT_API_BASE, DEFAULT_GENERATE_MAX_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_MODELS_CACHE_PATH, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DEFAULT_WEB_SEARCH_PROVIDER_ID, KNOWN_DEALS, KNOWN_EFFORTS, KNOWN_IMAGE_MODELS, KNOWN_PEAK_PRICING, KNOWN_PLANS, KNOWN_SUBSCRIPTION_PLANS, KNOWN_THINKING_MODELS, LANG_AUTO, LOGIN_ALLOWED_ORIGINS, LOGIN_BEGIN_ENDPOINT, LOGIN_BODY_LIMIT_BYTES, LOGIN_CANCEL_ENDPOINT, LOGIN_MAX_PORT_ATTEMPTS, LOGIN_START_PORT, LOGIN_STATUS_ENDPOINT, LOGIN_TIMEOUT_MS, LegacySettingsSchema, PLAN_LABELS, PLAN_ORDER, PROVIDER, USAGE_REPORT_ENDPOINT, accountUsable, apply, applyCommandCodeSearchSelection, applyCommandCodeTuiSettings, applyCommands, applyUsageRemote, buildCommandAuthUrl, buildCommandCodeTuiSection, capabilityDescription, commandCodeSearchSelection, commandDefinition, compareByPlan, dealLabel, formatContext, inject, loginStatusSchema, matchModelRule, modelVisibleInPlan, name, parseLoginStatus, peakPricingLabel, peakPricingState, planLabel, projectSlugFromPath, resolveAdapterOptions, resolveAuthFileApiKey, selectAccountForModel, selectActiveAccount, selectCommandCodeSearchProvider, studioBaseForApiBase, subscriptionPlanInfo, usageReportSchema, validateCommandApiKey };
 
 //# sourceMappingURL=index.js.map