@openspecui/server 6.0.1 → 6.1.0

package/dist/index.mjs

@@ -26,12 +26,16 @@ import { promisify } from "node:util";
 import { NotificationGroupKeySchema, NotificationPublishInputSchema as NotificationPublishInputSchema$1, getNotificationGroupKey } from "@openspecui/core/notifications";
 import { match } from "ts-pattern";
 import { buildSpecCatalog, specIdentityKey, specRoutePath } from "@openspecui/core/spec-catalog";
+import { DiagConsoleLogger, DiagLogLevel, SpanStatusCode, diag, trace } from "@opentelemetry/api";
 import { EventEmitter } from "node:events";
 import { ProjectSearchDocumentSchema, ProjectSearchHitSchema, ProjectSearchQuerySchema, parseProjectSearchHits } from "@openspecui/search";
 import { NodeWorkerSearchProvider } from "@openspecui/search/node";
 import * as pty from "@lydell/node-pty";
 import { EventEmitter as EventEmitter$1 } from "events";
-import { HostedCliProjectionNoticeSchema, HostedRootContextProjectionStateSchema, HostedRootContextResolvedStateSchema, HostedStoreDoctorEnvelopeSchema, HostedStoreDoctorProjectionStateSchema, HostedStoreListEnvelopeSchema, HostedStoreListProjectionStateSchema } from "@openspecui/core/hosted-contract";
+import { HostedCliProjectionNoticeSchema, HostedRootContextProjectionStateSchema, HostedRootContextResolvedStateSchema, HostedStoreContentChangesProjectionStateSchema, HostedStoreContentSpecsProjectionStateSchema, HostedStoreDoctorEnvelopeSchema, HostedStoreDoctorProjectionStateSchema, HostedStoreListEnvelopeSchema, HostedStoreListProjectionStateSchema } from "@openspecui/core/hosted-contract";
+import { StoreContentChangeListSchema, StoreContentSpecListSchema } from "@openspecui/core/store-content-projection";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { NodeSDK } from "@opentelemetry/sdk-node";
 import { Worker, isMainThread, parentPort, workerData } from "node:worker_threads";
 
 //#region src/access-gate.ts
@@ -2867,6 +2871,32 @@ function formatBytes$4(value) {
 //#endregion
 //#region src/port-utils.ts
 /**
+* Orthogonal intents (created 2026-07-31 Asia/Shanghai):
+* 1. Resolve an actual bindable port for explicit ranges and OS-assigned ephemeral requests.
+*
+* Owner-reported defect (2026-07-31): Managed directory launch published `http://localhost:0`
+* even though the backend was listening on an OS-assigned port.
+*/
+function findEphemeralPort() {
+	return new Promise((resolve$1, reject) => {
+		const server = createServer$1();
+		server.once("error", reject);
+		server.once("listening", () => {
+			const address = server.address();
+			if (!address || typeof address === "string") {
+				server.close();
+				reject(/* @__PURE__ */ new Error("OS-assigned TCP port did not expose a numeric address."));
+				return;
+			}
+			server.close((error) => {
+				if (error) reject(error);
+				else resolve$1(address.port);
+			});
+		});
+		server.listen(0);
+	});
+}
+/**
 * Check if a port is available by trying to listen on it.
 * Uses default binding (both IPv4 and IPv6) to detect conflicts.
 */
@@ -2892,6 +2922,7 @@ function isPortAvailable(port) {
 * @throws Error if no available port is found in the range
 */
 async function findAvailablePort(startPort, maxAttempts = 10) {
+	if (startPort === 0) return findEphemeralPort();
 	for (let i = 0; i < maxAttempts; i++) {
 		const port = startPort + i;
 		if (await isPortAvailable(port)) return port;
@@ -3001,6 +3032,7 @@ var ProjectionWorkScheduler = class {
 					work.started = true;
 					const queue$1 = this.queues[work.resourceClass];
 					queue$1.running.add(work);
+					request.onStarted?.();
 					request.run(controller.signal).then((value) => {
 						settle(() => resolve$1(value));
 						queue$1.running.delete(work);
@@ -3020,6 +3052,7 @@ var ProjectionWorkScheduler = class {
 				queue.foreground.push(work);
 				this.cancelOneBackgroundWork(request.resourceClass);
 			} else queue.background.push(work);
+			request.onQueued?.();
 			this.drain(request.resourceClass);
 		});
 	}
@@ -3073,6 +3106,22 @@ var ProjectionWorkScheduler = class {
 
 //#endregion
 //#region src/projection-work/types.ts
+/** Observable lifecycle phases. These describe actual work, never inferred page copy. */
+const projectionWorkPhases = [
+	"request",
+	"transport-start",
+	"root-ready",
+	"cache-hit",
+	"join",
+	"start",
+	"queue-enter",
+	"resource-admitted",
+	"leaf-settled",
+	"first-stable-payload",
+	"complete",
+	"error",
+	"cancel"
+];
 /** Produce a deterministic, collision-resistant-for-fields registry key without relying on object ordering. */
 function projectionWorkIdentityKey(identity) {
 	return JSON.stringify([
@@ -3091,15 +3140,16 @@ function projectionWorkIdentityKey(identity) {
 //#endregion
 //#region src/projection-work/registry.ts
 /**
-* Orthogonal intents (created 2026-07-23 Asia/Shanghai):
+* Orthogonal intents (updated 2026-07-31 Asia/Shanghai):
 * 1. Share same-identity in-flight projection work across Server subscribers.
 * 2. Retain bounded display snapshots while preserving freshness and provenance.
 * 3. Retire generations so late A work cannot publish into current B state.
-* 4. Expose explicit invalidation, cancellation, batches, and typed failures.
+* 4. Expose explicit invalidation, cancellation, batches, typed failures, and resource-admission trace boundaries.
 * 5. Expose immediate cached lifecycle reads and data-free lifecycle notices.
 *
 * Original request (2026-07-23): "现在页面数据的加载数据非常慢（比如dashboard页面、changes页面都要等待非常久，页面刷新后，似乎后台没有缓存一样，也要加载很久。"
 * Original request (2026-07-26): "界面上仍然可以读到缓存，但它也能知道这个缓存现在正在被更新中。"
+* Original request (2026-07-31): "检查它的工作到底做了什么，为什么需要那么多的时间"
 */
 var ProjectionWorkCapacityError = class extends Error {
 	constructor() {
@@ -3319,6 +3369,16 @@ var ProjectionWork = class {
 							resourceClass: this.request.resourceClass,
 							priority: this.request.priority,
 							signal: controller.signal,
+							onQueued: () => {
+								if (!this.isCurrentRun(generation, controller)) return;
+								this.record("queue-enter", generation);
+								this.publishStage("queue-enter", generation);
+							},
+							onStarted: () => {
+								if (!this.isCurrentRun(generation, controller)) return;
+								this.record("resource-admitted", generation);
+								this.publishStage("resource-admitted", generation);
+							},
 							run: (scheduleSignal) => context.runOnce(() => this.request.load({
 								signal: scheduleSignal,
 								workGeneration: generation,
@@ -3607,7 +3667,7 @@ const serverProjectionWorkCacheBudget = {
 	maxBytes: 2 * 1024 * 1024,
 	maxWorkEntries: 64,
 	traceCapacity: 256,
-	maxRegistryCount: 9
+	maxRegistryCount: 10
 };
 var ProjectionWorkRuntimeCapacityError = class extends Error {
 	constructor() {
@@ -3654,7 +3714,7 @@ function createServerProjectionWorkRuntime() {
 function createChangesProjectionWorkOwner(runtime) {
 	return { rows: runtime.createRegistry() };
 }
-function estimateSnapshotBytes$5(data) {
+function estimateSnapshotBytes$6(data) {
 	return Buffer$1.byteLength(JSON.stringify(data) ?? "", "utf8");
 }
 function normalizeRowError(changeId, cause) {
@@ -3733,7 +3793,7 @@ var ChangesProjectionService = class {
 			identity: this.identity(),
 			resourceClass: "filesystem",
 			priority: "foreground",
-			estimateSnapshotBytes: estimateSnapshotBytes$5,
+			estimateSnapshotBytes: estimateSnapshotBytes$6,
 			load: async (context) => {
 				context.reportStage("root-ready");
 				const ids = await this.options.adapter.listChanges();
@@ -5479,7 +5539,7 @@ var DashboardProjectionWorkOwner = class {
 function createDashboardProjectionWorkOwner(runtime) {
 	return new DashboardProjectionWorkOwner(runtime);
 }
-function estimateSnapshotBytes$4(data) {
+function estimateSnapshotBytes$5(data) {
 	return Buffer$1.byteLength(JSON.stringify(data) ?? "", "utf8");
 }
 /** Root-scoped facade over Server-owned regional Projection Work registries. */
@@ -5533,7 +5593,7 @@ var DashboardProjectionService = class {
 	getGit() {
 		return this.getCurrent((listener) => this.subscribeGit(listener));
 	}
-	/** Retire only the current Code Git projection after an explicit Git refresh mutation succeeds. */
+	/** Retire only the current Code Git projection after an explicit readonly Git refresh succeeds. */
 	invalidateGit() {
 		if (this.disposed) return;
 		this.options.workOwner.git.invalidate(this.identity("git"));
@@ -5567,7 +5627,7 @@ var DashboardProjectionService = class {
 			identity: this.identity("summary"),
 			resourceClass: "filesystem",
 			priority: "foreground",
-			estimateSnapshotBytes: estimateSnapshotBytes$4,
+			estimateSnapshotBytes: estimateSnapshotBytes$5,
 			load: async (context) => {
 				context.reportStage("root-ready");
 				const data = await this.options.loaders.loadSummary();
@@ -5606,7 +5666,7 @@ var DashboardProjectionService = class {
 			identity: this.identity("trends"),
 			resourceClass: "filesystem",
 			priority: "foreground",
-			estimateSnapshotBytes: estimateSnapshotBytes$4,
+			estimateSnapshotBytes: estimateSnapshotBytes$5,
 			load: async (context) => {
 				context.reportStage("root-ready");
 				const data = await this.options.loaders.loadTrends();
@@ -5620,10 +5680,10 @@ var DashboardProjectionService = class {
 			identity: this.identity("git"),
 			resourceClass: "git",
 			priority: "foreground",
-			estimateSnapshotBytes: estimateSnapshotBytes$4,
+			estimateSnapshotBytes: estimateSnapshotBytes$5,
 			load: async (context) => {
 				context.reportStage("root-ready");
-				const data = await this.options.loaders.loadGit();
+				const data = await this.options.loaders.loadGit(context.signal);
 				context.reportStage("leaf-settled");
 				return data;
 			}
@@ -5899,7 +5959,7 @@ function createEnvironmentGlobalProjectionWorkOwner(runtime) {
 		fileRegistry: runtime.createRegistry()
 	};
 }
-function estimateSnapshotBytes$3(data) {
+function estimateSnapshotBytes$4(data) {
 	return Buffer$1.byteLength(JSON.stringify(data) ?? "", "utf8");
 }
 /** CLI-backed Pull/Push owner for environment-global config, profile, and drift evidence. */
@@ -6027,7 +6087,7 @@ var EnvironmentGlobalProjectionService = class {
 			identity: this.identity(),
 			resourceClass: "cli",
 			priority: "foreground",
-			estimateSnapshotBytes: estimateSnapshotBytes$3,
+			estimateSnapshotBytes: estimateSnapshotBytes$4,
 			load: async ({ reportStage, signal, workGeneration }) => {
 				reportStage("root-ready");
 				const projection = await readEnvironmentGlobalConfig({
@@ -6142,13 +6202,15 @@ var EnvironmentGlobalProjectionService = class {
 //#endregion
 //#region src/git-shared.ts
 /**
-* Orthogonal intents (updated 2026-07-19 Asia/Shanghai):
+* Orthogonal intents (updated 2026-07-31 Asia/Shanghai):
 * 1. Execute Git commands and retain structured stdout/stderr/exit evidence.
 * 2. Distinguish a valid non-repository path from an identity-command failure.
 * 3. Canonicalize repository paths for binding identity and stale-intent checks.
+* 4. Propagate cooperative cancellation into Git subprocess ownership.
 *
 * Original request (2026-07-19): "代码已经提交，开始review。如果有问题，那么可更新change。"
 * Derived requirement (2026-07-19): Checkpoint 6.11 preserves objective Planning Git failures.
+* Original request (2026-07-31): "Code Git Snapshot，它非常慢，有时候甚至要十几秒"
 */
 const execFileAsync$2 = promisify(execFile);
 const EMPTY_DIFF = {
@@ -6156,18 +6218,20 @@ const EMPTY_DIFF = {
 	insertions: 0,
 	deletions: 0
 };
-async function defaultRunGit(cwd, args) {
+async function defaultRunGit(cwd, args, signal) {
 	try {
 		const { stdout } = await execFileAsync$2("git", args, {
 			cwd,
 			encoding: "utf8",
-			maxBuffer: 8 * 1024 * 1024
+			maxBuffer: 8 * 1024 * 1024,
+			signal
 		});
 		return {
 			ok: true,
 			stdout
 		};
 	} catch (error) {
+		if (signal?.aborted) throw error;
 		const stderrField = readErrorField(error, "stderr");
 		const stderr = typeof stderrField === "string" ? stderrField : void 0;
 		return {
@@ -8089,13 +8153,15 @@ var NotificationService = class {
 //#endregion
 //#region src/spec-catalog-service.ts
 /**
-* Orthogonal intents (updated 2026-07-27 Asia/Shanghai):
+* Orthogonal intents (updated 2026-07-31 Asia/Shanghai):
 * 1. Build CLI-owned Spec membership from the active planning root and direct References.
 * 2. Read owned documents from planning-root services and referenced documents from CLI JSON.
 * 3. Preserve live referenced command provenance and evidence without synthesizing document fields.
 * 4. Reject mismatched Root/Store/spec provenance before publishing a Catalog or document.
+* 5. Submit owned and referenced CLI enumeration lazily so one Catalog cannot monopolize CLI admission.
 *
 * Original request (2026-07-15): "Live and static modes share one source-aware Spec Catalog."
+* Original request (2026-07-31): "系统性地进行修复，因为List页面也有类似的问题。所有可能其它页面都有类似的问题。"
 */
 /** Exact compound identity was absent from the current direct project Catalog. */
 var SpecCatalogIdentityNotFoundError = class extends Error {
@@ -8108,7 +8174,9 @@ var SpecCatalogIdentityNotFoundError = class extends Error {
 /** Build one collision-safe Catalog from exact typed CLI lists. */
 async function readSpecCatalog(source, options = {}) {
 	const rootSelector = source.rootContext.storeId !== null ? { store: source.rootContext.storeId } : {};
-	const [ownedList, references] = await Promise.all([source.contracts.listSpecs(rootSelector), Promise.all(source.rootContext.references.map((reference) => enumerateReference(source, reference)))]);
+	const ownedList = await source.contracts.listSpecs(rootSelector);
+	const references = [];
+	for (const reference of source.rootContext.references) references.push(await enumerateReference(source, reference));
 	const ownedError = ownedListContractError(source.rootContext, ownedList);
 	if (!ownedList.success || !ownedList.data || ownedError) throw new CliProjectionCommandError(ownedError || ownedList.contractError || ownedList.stderr.trim() || "OpenSpec returned no owned Spec list.", ownedError ? {
 		...ownedList,
@@ -8255,7 +8323,7 @@ var PlanningCliRootContextState = class {
 function createPlanningCliProjectionWorkOwner(runtime) {
 	return { registry: runtime.createRegistry() };
 }
-function estimateSnapshotBytes$2(data) {
+function estimateSnapshotBytes$3(data) {
 	return Buffer$1.byteLength(JSON.stringify(data) ?? "", "utf8");
 }
 /** Planning-root owner for all normal-path CLI-backed OPSX and Spec live projections. */
@@ -8359,7 +8427,7 @@ var PlanningCliProjectionService = class {
 			identity: this.identity(selector),
 			resourceClass: "cli",
 			priority: "foreground",
-			estimateSnapshotBytes: estimateSnapshotBytes$2,
+			estimateSnapshotBytes: estimateSnapshotBytes$3,
 			load: async ({ reportStage }) => {
 				const rootContext = this.currentRootContext();
 				this.trackDependencies(selector);
@@ -8570,25 +8638,57 @@ async function listRecentGitEntries(options) {
 //#region src/dashboard-git-snapshot.ts
 async function collectCommitEntries(options) {
 	const { worktreePath, defaultBranch, maxCommitEntries, runGit, readPathTimestampMs } = options;
-	return listRecentGitEntries({
+	const entries = await listRecentGitEntries({
 		worktreePath,
 		defaultBranch,
 		maxCommitEntries,
 		runGit,
 		readPathTimestampMs
 	});
+	const uncommitted = entries.find((entry) => entry.type === "uncommitted");
+	const commits = entries.filter((entry) => entry.type === "commit");
+	return uncommitted?.type === "uncommitted" && (uncommitted.diff.files > 0 || uncommitted.diff.insertions > 0 || uncommitted.diff.deletions > 0) ? [uncommitted, ...commits.slice(0, Math.max(0, maxCommitEntries - 1))] : commits.slice(0, maxCommitEntries);
 }
 async function collectWorktree(options) {
-	const { projectDir, worktree, defaultBranch, runGit, maxCommitEntries, readPathTimestampMs } = options;
+	const { projectDir, worktree, defaultBranch, runGit, maxCommitEntries, readPathTimestampMs, pathAvailable } = options;
 	const worktreePath = resolve(worktree.path);
 	const resolvedProjectDir = resolve(projectDir);
 	const isCurrent = await sameGitPath(worktreePath, resolvedProjectDir);
-	const pathAvailable = await pathExists(worktreePath);
-	const aheadBehindResult = await runGit(worktreePath, [
-		"rev-list",
-		"--left-right",
-		"--count",
-		`${defaultBranch}...HEAD`
+	const isPathAvailable = await pathAvailable(worktreePath);
+	const baseWorktree = {
+		path: worktreePath,
+		relativePath: relativePath(resolvedProjectDir, worktreePath),
+		pathAvailable: isPathAvailable,
+		branchName: parseBranchName(worktree.branchRef, worktree.detached),
+		detached: worktree.detached,
+		isCurrent
+	};
+	if (!isPathAvailable || worktree.detached) return {
+		...baseWorktree,
+		ahead: 0,
+		behind: 0,
+		diff: EMPTY_DIFF,
+		entries: []
+	};
+	const [aheadBehindResult, diffResult, entries] = await Promise.all([
+		runGit(worktreePath, [
+			"rev-list",
+			"--left-right",
+			"--count",
+			`${defaultBranch}...HEAD`
+		]),
+		runGit(worktreePath, [
+			"diff",
+			"--shortstat",
+			`${defaultBranch}...HEAD`
+		]),
+		isCurrent ? collectCommitEntries({
+			worktreePath,
+			defaultBranch,
+			maxCommitEntries,
+			runGit,
+			readPathTimestampMs
+		}) : Promise.resolve([])
 	]);
 	let ahead = 0;
 	let behind = 0;
@@ -8597,26 +8697,9 @@ async function collectWorktree(options) {
 		ahead = Number(aheadRaw) || 0;
 		behind = Number(behindRaw) || 0;
 	}
-	const diffResult = await runGit(worktreePath, [
-		"diff",
-		"--shortstat",
-		`${defaultBranch}...HEAD`
-	]);
 	const diff = diffResult.ok ? parseShortStat(diffResult.stdout) : EMPTY_DIFF;
-	const entries = await collectCommitEntries({
-		worktreePath,
-		defaultBranch,
-		maxCommitEntries,
-		runGit,
-		readPathTimestampMs
-	});
 	return {
-		path: worktreePath,
-		relativePath: relativePath(resolvedProjectDir, worktreePath),
-		pathAvailable,
-		branchName: parseBranchName(worktree.branchRef, worktree.detached),
-		detached: worktree.detached,
-		isCurrent,
+		...baseWorktree,
 		ahead,
 		behind,
 		diff,
@@ -8645,18 +8728,21 @@ async function removeDetachedDashboardGitWorktree(options) {
 }
 async function buildDashboardGitSnapshot(options) {
 	const runGit = options.runGit ?? defaultRunGit;
-	const maxCommitEntries = options.maxCommitEntries ?? 8;
+	const maxCommitEntries = options.maxCommitEntries ?? 5;
 	const readPathTimestampMs = options.readPathTimestampMs ?? defaultReadPathTimestampMs;
+	const readPathAvailable = options.pathAvailable ?? pathExists;
+	const runSnapshotGit = (cwd, args) => runGit(cwd, args, options.signal);
 	const resolvedProjectDir = resolve(options.projectDir);
-	const defaultBranch = await resolveDefaultBranch(resolvedProjectDir, runGit);
-	const baseWorktrees = await listGitWorktrees(resolvedProjectDir, runGit);
+	const defaultBranch = await resolveDefaultBranch(resolvedProjectDir, runSnapshotGit);
+	const baseWorktrees = await listGitWorktrees(resolvedProjectDir, runSnapshotGit);
 	const worktrees = await Promise.all(baseWorktrees.map((worktree) => collectWorktree({
 		projectDir: resolvedProjectDir,
 		worktree,
 		defaultBranch,
-		runGit,
+		runGit: runSnapshotGit,
 		maxCommitEntries,
-		readPathTimestampMs
+		readPathTimestampMs,
+		pathAvailable: readPathAvailable
 	})));
 	worktrees.sort((a$1, b) => {
 		if (a$1.isCurrent !== b.isCurrent) return a$1.isCurrent ? -1 : 1;
@@ -8672,13 +8758,15 @@ async function buildDashboardGitSnapshot(options) {
 //#endregion
 //#region src/dashboard-git-projection.ts
 /**
-* Orthogonal intents (updated 2026-07-25 Asia/Shanghai):
+* Orthogonal intents (updated 2026-07-31 Asia/Shanghai):
 * 1. Load Dashboard Code Git snapshots independently from planning Summary and trends.
 * 2. Preserve backend-issued Code binding provenance and observable Git task lifecycle.
 * 3. Trigger explicit Git snapshot invalidation through a reactive stamp without broad Dashboard reloads.
+* 4. Propagate Projection Work cancellation into the Git subprocess tree.
 *
 * Original request (2026-07-23): "现在页面数据的加载数据非常慢（比如dashboard页面、changes页面都要等待非常久，页面刷新后，似乎后台没有缓存一样，也要加载很久。"
 * Derived requirement (2026-07-25): P4.3 settles a cached refresh stamp before Dashboard Git refresh returns.
+* Original request (2026-07-31): "Code Git Snapshot，它非常慢，有时候甚至要十几秒"
 */
 const execFileAsync$1 = promisify(execFile);
 const DASHBOARD_GIT_REFRESH_STAMP_NAME = "openspecui-dashboard-git-refresh.stamp";
@@ -8748,14 +8836,15 @@ async function touchDashboardGitRefreshStamp(projectDir, reason) {
 	return { skipped: false };
 }
 /** Load one Code Git snapshot and retain any failure as Git-region evidence only. */
-async function loadDashboardGitProjection(ctx, reason = "dashboard-git") {
+async function loadDashboardGitProjection(ctx, reason = "dashboard-git", signal) {
 	beginDashboardGitTask(reason);
 	try {
 		const gitMetadataDir = await resolveGitMetadataDir(ctx.projectDir);
 		if (gitMetadataDir) await reactiveReadFile(join(gitMetadataDir, DASHBOARD_GIT_REFRESH_STAMP_NAME));
 		const snapshot = await buildDashboardGitSnapshot({
 			projectDir: ctx.projectDir,
-			bindingToken: ctx.codeBindingToken
+			bindingToken: ctx.codeBindingToken,
+			signal
 		});
 		endDashboardGitTask(null);
 		return snapshot;
@@ -9204,6 +9293,19 @@ async function loadDashboardOverview(ctx, reason = "dashboard-refresh") {
 
 //#endregion
 //#region src/entity-read-options.ts
+/**
+* Orthogonal intents (updated 2026-07-31 Asia/Shanghai):
+* 1. Resolve the OPSX Schema detail and diagnostic metadata for one change/archive entity.
+* 2. Delegate schema resolution through the Kernel ensure contract while tolerating missing schemas.
+* 3. Never block on Kernel warmup: schema diagnostics are optional display enrichment, so return
+*    cached/empty data immediately and let reactive invalidation fill them after warmup settles.
+*
+* Original request (2026-07-15): "为不同命令建立强类型适配器，不实现平行解析规则。"
+* Performance correction (2026-07-23): Status must not block on Kernel warmup; schema diagnostics are optional.
+* Hotpath correction (2026-07-31): `buildEntityReadOptions` removed `waitForWarmup()` blocking because
+*   `fetchSchemas` (~1.2s) dominated detail-page latency. Schema data is now read opportunistically
+*   from whatever the Kernel has already cached; reactive invalidation fills the rest.
+*/
 async function readEntityMetadata(ctx, stage, id) {
 	return (stage === "change" ? await ctx.adapter.readChangeFiles(id) : await ctx.adapter.readArchivedChangeFiles(id)).find((file) => file.type === "file" && file.path === ".openspec.yaml")?.content ?? null;
 }
@@ -9211,14 +9313,12 @@ async function buildEntityReadOptions(ctx, stage, id) {
 	const schemaName = parseOpsxEntityMetadata(await readEntityMetadata(ctx, stage, id)).schemaName;
 	if (!schemaName) return {};
 	try {
-		await ctx.kernel.waitForWarmup();
-		await ctx.kernel.ensureSchemaDetail(schemaName);
-		await ctx.kernel.ensureSchemaYaml(schemaName);
-		const schemaYaml = ctx.kernel.getSchemaYaml(schemaName);
+		const schemaDetail = ctx.kernel.tryGetSchemaDetail(schemaName);
+		const schemaYaml = ctx.kernel.tryGetSchemaYaml(schemaName);
 		const diagnostics = schemaYaml ? parseOpsxSchemaDetail(schemaYaml, schemaName, { path: `schema:${schemaName}` }).diagnostics : [];
 		return {
-			schemas: { [schemaName]: ctx.kernel.getSchemaDetail(schemaName) },
-			schemaDiagnostics: diagnostics.length > 0 ? { [schemaName]: diagnostics } : void 0
+			...schemaDetail ? { schemas: { [schemaName]: schemaDetail } } : {},
+			...diagnostics.length > 0 ? { schemaDiagnostics: { [schemaName]: diagnostics } } : {}
 		};
 	} catch {
 		return { schemas: {} };
@@ -9402,6 +9502,197 @@ var FilePreviewService = class {
 	}
 };
 
+//#endregion
+//#region src/read-write-lock.ts
+/**
+* Orthogonal intents (created 2026-07-31 Asia/Shanghai):
+* 1. Provide a writer-preference async read-write lock for PlanningRootServiceManager.
+* 2. Multiple readers can hold the lock concurrently; writers get exclusive access.
+* 3. Writer preference prevents write starvation: when a writer is waiting, new readers queue.
+* 4. Export queue-to-release OTel evidence with explicit source stacks and reader blockers.
+*
+* Original request (2026-07-31): "使用读写锁的概念进行改进:Read 并行,Write 独占"
+* Original request (2026-07-31): "把所有write-lock打印上时间日志和来源堆栈，使用otel来进行trace。"
+*
+* Design: a single Promise chain resolves readers in batches and writers one-at-a-time.
+* Writers wait for all active readers to finish; readers arriving while a writer is pending
+* (or active) wait behind that writer. This guarantees writers are not starved by a continuous
+* stream of readers, at the cost of slightly higher reader latency when a write is pending.
+*/
+/** Convert an application Tracer into the narrow lock instrumentation boundary. */
+function createLockTracer(tracer) {
+	return { startActiveSpan: (name, options, callback) => tracer.startActiveSpan(name, options, (span) => callback(span)) };
+}
+function timestampAttributes(timestamp) {
+	return {
+		"lock.timestamp": new Date(timestamp).toISOString(),
+		"lock.timestamp_unix_ms": timestamp
+	};
+}
+var AsyncReadWriteLock = class {
+	name;
+	tracer;
+	nextOperationId = 1;
+	activeReaders = 0;
+	activeWriter = null;
+	waitingReaders = [];
+	waitingWriters = [];
+	constructor(options = { name: "async-read-write-lock" }) {
+		this.name = options.name;
+		this.tracer = options.tracer ?? createLockTracer(trace.getTracer("openspecui-server", "lock-instrumentation"));
+	}
+	/**
+	* Acquire a shared (read) lock and run `fn`. Multiple read locks can be held simultaneously.
+	* If a writer is waiting or active, this queues behind it (writer preference).
+	*/
+	async withReadLock(source, fn) {
+		const operation = this.createOperation(source);
+		return this.tracer.startActiveSpan("lock.read", {
+			attributes: this.baseAttributes("read", operation),
+			startTime: operation.queuedAt
+		}, async (span) => {
+			const blockers = await this.acquireRead();
+			const acquiredAt = Date.now();
+			const waitMs = acquiredAt - operation.queuedAt;
+			span.setAttributes({
+				"lock.blocked": blockers.length > 0,
+				"lock.wait_ms": waitMs
+			});
+			if (blockers.length > 0) {
+				const firstBlocker = blockers[0];
+				if (firstBlocker) span.setAttributes({
+					"lock.blocked_by.source": firstBlocker.source,
+					"lock.blocked_by.stack": firstBlocker.stack,
+					"lock.blocked_by.wait_ms": waitMs,
+					"lock.blocked_by.sources": blockers.map((blocker) => blocker.source),
+					"lock.blocked_by.stacks": blockers.map((blocker) => blocker.stack)
+				});
+			}
+			span.addEvent("read-lock.acquired", timestampAttributes(acquiredAt), acquiredAt);
+			try {
+				return await fn();
+			} catch (error) {
+				this.recordError(span, error);
+				throw error;
+			} finally {
+				this.releaseRead();
+				const releasedAt = Date.now();
+				span.setAttribute("lock.hold_ms", releasedAt - acquiredAt);
+				span.addEvent("read-lock.released", timestampAttributes(releasedAt), releasedAt);
+				span.end(releasedAt);
+			}
+		});
+	}
+	/**
+	* Acquire an exclusive (write) lock and run `fn`. Waits for all active readers/writers to finish.
+	* While active, new readers and writers queue behind this writer.
+	*/
+	async withWriteLock(source, fn) {
+		const operation = this.createOperation(source);
+		return this.tracer.startActiveSpan("lock.write", {
+			attributes: this.baseAttributes("write", operation),
+			startTime: operation.queuedAt
+		}, async (span) => {
+			span.addEvent("write-lock.queued", {
+				...timestampAttributes(operation.queuedAt),
+				"lock.active_readers": this.activeReaders,
+				"lock.waiting_readers": this.waitingReaders.length,
+				"lock.waiting_writers": this.waitingWriters.length
+			}, operation.queuedAt);
+			await this.acquireWrite(operation);
+			const acquiredAt = Date.now();
+			span.setAttribute("lock.wait_ms", acquiredAt - operation.queuedAt);
+			span.addEvent("write-lock.acquired", timestampAttributes(acquiredAt), acquiredAt);
+			try {
+				return await fn();
+			} catch (error) {
+				this.recordError(span, error);
+				throw error;
+			} finally {
+				this.releaseWrite();
+				const releasedAt = Date.now();
+				span.setAttribute("lock.hold_ms", releasedAt - acquiredAt);
+				span.addEvent("write-lock.released", timestampAttributes(releasedAt), releasedAt);
+				span.end(releasedAt);
+			}
+		});
+	}
+	createOperation(source) {
+		return {
+			...source,
+			id: this.nextOperationId++,
+			queuedAt: Date.now()
+		};
+	}
+	baseAttributes(mode, operation) {
+		return {
+			"lock.name": this.name,
+			"lock.mode": mode,
+			"lock.source": operation.source,
+			"lock.stack": operation.stack,
+			"lock.queue_started_at": new Date(operation.queuedAt).toISOString(),
+			"lock.queue_started_at_unix_ms": operation.queuedAt
+		};
+	}
+	recordError(span, error) {
+		const message = error instanceof Error ? error.message : String(error);
+		span.recordException(error instanceof Error ? error : message);
+		span.setStatus({
+			code: SpanStatusCode.ERROR,
+			message
+		});
+	}
+	acquireRead() {
+		if (this.activeWriter === null && this.waitingWriters.length === 0) {
+			this.activeReaders += 1;
+			return Promise.resolve([]);
+		}
+		const blockers = [...this.activeWriter ? [this.activeWriter] : [], ...this.waitingWriters.map((writer) => writer.operation)];
+		return new Promise((resolve$1) => {
+			this.waitingReaders.push({
+				resolve: () => resolve$1(blockers),
+				blockers
+			});
+		});
+	}
+	releaseRead() {
+		this.activeReaders -= 1;
+		if (this.activeReaders === 0 && this.waitingWriters.length > 0) this.drainNextWriter();
+	}
+	acquireWrite(operation) {
+		if (this.activeWriter === null && this.activeReaders === 0 && this.waitingWriters.length === 0) {
+			this.activeWriter = operation;
+			return Promise.resolve();
+		}
+		for (const reader of this.waitingReaders) reader.blockers.push(operation);
+		return new Promise((resolve$1) => {
+			this.waitingWriters.push({
+				resolve: resolve$1,
+				operation
+			});
+		});
+	}
+	releaseWrite() {
+		this.activeWriter = null;
+		if (this.waitingWriters.length > 0) {
+			this.drainNextWriter();
+			return;
+		}
+		this.drainWaitingReaders();
+	}
+	drainNextWriter() {
+		const writer = this.waitingWriters.shift();
+		if (!writer) return;
+		this.activeWriter = writer.operation;
+		writer.resolve();
+	}
+	drainWaitingReaders() {
+		const readers = this.waitingReaders.splice(0);
+		this.activeReaders += readers.length;
+		for (const reader of readers) reader.resolve();
+	}
+};
+
 //#endregion
 //#region src/root-context-service.ts
 /**
@@ -10195,9 +10486,9 @@ var WorkflowInvocationService = class {
 //#endregion
 //#region src/planning-root-service.ts
 /**
-* Orthogonal intents (updated 2026-07-27 Asia/Shanghai):
+* Orthogonal intents (updated 2026-07-31 Asia/Shanghai):
 * 1. Own every root-scoped operation, CLI projection, and project-Schema mutation for the selected Planning root.
-* 2. Serialize replacement and issue fresh record/generation provenance without reconstructing root selection.
+* 2. Single-flight Root resolution outside traced locks, then serialize short generation-checked record commits.
 * 3. Acquire and retire observation/invalidation leases with each active root.
 * 4. Keep reactive subscriptions and current-generation snapshots bound to Root Context dependencies and selection.
 * 5. Revoke leased service capabilities, cancel retiring streams outside blocked transitions, and
@@ -10210,6 +10501,10 @@ var WorkflowInvocationService = class {
 * Original request (2026-07-23): "现在页面数据的加载数据非常慢（比如dashboard页面、changes页面都要等待非常久，页面刷新后，似乎后台没有缓存一样，也要加载很久。"
 * Original request (2026-07-26): "展开全面的接口升级和内核升级和测试升级。"
 * Owner architecture clarification (2026-07-26): "将这些变更信息收集起来作为触发器，更新底层幂等计算的缓存结果。"
+* Built-runtime correction (2026-07-30): retiring a Planning root must retire its buffered CLI children.
+* Original request (2026-07-31): "把所有write-lock打印上时间日志和来源堆栈，使用otel来进行trace。"
+* Owner diagnosis (2026-07-31): readonly cache misses must merge before lock admission, and slow async work must remain outside write locks.
+* Full-gate correction (2026-07-31): imperative snapshots cannot become reactive replay authority before dependency-tracked validation.
 */
 /** Root resolution failure that retains the complete failed Root Context state. */
 var PlanningRootUnavailableError = class extends Error {
@@ -10225,7 +10520,9 @@ var PlanningRootServiceManager = class {
 	activeRecord = null;
 	currentRootContextSnapshot = null;
 	retiringRecords = /* @__PURE__ */ new Set();
-	transitionTail = Promise.resolve();
+	rootTransitionFlights = /* @__PURE__ */ new Map();
+	rootTransitionCommitTail = Promise.resolve();
+	transitionLock;
 	disposePromise = null;
 	disposed = false;
 	dashboardProjectionWorkOwner;
@@ -10234,6 +10531,10 @@ var PlanningRootServiceManager = class {
 	ownedProjectionWorkRuntime;
 	constructor(options) {
 		this.options = options;
+		this.transitionLock = new AsyncReadWriteLock({
+			name: "planning-root-transition",
+			tracer: createLockTracer(options.tracer ?? trace.getTracer("openspecui-server"))
+		});
 		if (options.dashboardProjectionWorkOwner && options.changesProjectionWorkOwner && options.planningCliProjectionWorkOwner) {
 			this.dashboardProjectionWorkOwner = options.dashboardProjectionWorkOwner;
 			this.changesProjectionWorkOwner = options.changesProjectionWorkOwner;
@@ -10295,10 +10596,10 @@ var PlanningRootServiceManager = class {
 					adapter,
 					configManager: this.options.configManager
 				}),
-				loadGit: () => loadDashboardGitProjection({
+				loadGit: (signal) => loadDashboardGitProjection({
 					projectDir: this.options.launchProjectDir,
 					codeBindingToken: this.options.codeBinding.bindingToken
-				}, "projection-work")
+				}, "projection-work", signal)
 			}
 		});
 		const changesProjectionService = new ChangesProjectionService({
@@ -10340,6 +10641,7 @@ var PlanningRootServiceManager = class {
 		});
 		return {
 			identity: this.rootIdentity(rootContext),
+			rootCliExecutor,
 			gitBindingToken,
 			schemaMutationService,
 			rootContext,
@@ -10363,10 +10665,23 @@ var PlanningRootServiceManager = class {
 			disposePromise: null
 		};
 	}
-	runTransition(task) {
-		const result = this.transitionTail.then(task, task);
-		this.transitionTail = result.then(() => void 0, () => void 0);
-		return result;
+	/** Run one short state commit under the exclusive transition lock. */
+	runWriteTransition(source, task) {
+		return this.transitionLock.withWriteLock({
+			source,
+			stack: (/* @__PURE__ */ new Error(`Write lock source: ${source}`)).stack ?? source
+		}, task);
+	}
+	/**
+	* Run `task` under a shared (read) lock. Used for cache-hit fast paths where only
+	* `activeRecord` and `currentRootContextSnapshot` are read. Multiple read transitions
+	* run concurrently; a pending writer blocks new readers.
+	*/
+	runReadTransition(source, task) {
+		return this.transitionLock.withReadLock({
+			source,
+			stack: (/* @__PURE__ */ new Error(`Read lock source: ${source}`)).stack ?? source
+		}, task);
 	}
 	async disposeRecord(record) {
 		if (record.disposePromise) return record.disposePromise;
@@ -10379,6 +10694,7 @@ var PlanningRootServiceManager = class {
 				Promise.resolve().then(() => record.dashboardProjectionService.dispose()),
 				Promise.resolve().then(() => record.changesProjectionService.dispose()),
 				Promise.resolve().then(() => record.planningCliProjectionService.dispose()),
+				Promise.resolve().then(() => record.rootCliExecutor.dispose()),
 				record.hookRuntime.dispose(),
 				record.searchService.dispose(),
 				record.observationRelease.then((releaseObservationRoot) => releaseObservationRoot?.())
@@ -10491,96 +10807,290 @@ var PlanningRootServiceManager = class {
 			observedAt: attempt.observedAt
 		};
 	}
-	async activate(state) {
+	traceRootContextCacheHit() {
+		(this.options.tracer ?? trace.getTracer("openspecui-server")).startActiveSpan("planningRoot.resolveRootContext", (span) => {
+			span.setAttribute("rootContext.cacheHit", true);
+			span.end();
+		});
+	}
+	resolvedStateForRecord(state, record) {
+		return {
+			...state,
+			data: record.rootContext
+		};
+	}
+	enqueueRootTransitionCommit(task) {
+		const result = this.rootTransitionCommitTail.then(task, task);
+		this.rootTransitionCommitTail = result.then(() => void 0, () => void 0);
+		return result;
+	}
+	getRootTransition(invalidationKey) {
+		const existing = this.rootTransitionFlights.get(invalidationKey);
+		if (existing) return {
+			transition: existing,
+			joined: true
+		};
+		const transition = this.resolveAndCommitRootTransition(invalidationKey);
+		this.rootTransitionFlights.set(invalidationKey, transition);
+		const clear = () => {
+			if (this.rootTransitionFlights.get(invalidationKey) === transition) this.rootTransitionFlights.delete(invalidationKey);
+		};
+		transition.then(clear, clear);
+		return {
+			transition,
+			joined: false
+		};
+	}
+	awaitRootTransition(invalidationKey) {
+		return (this.options.tracer ?? trace.getTracer("openspecui-server")).startActiveSpan("planningRoot.transition.wait", async (span) => {
+			const { transition, joined } = this.getRootTransition(invalidationKey);
+			span.setAttribute("rootContext.invalidationKey", invalidationKey);
+			span.setAttribute("rootContext.singleFlight.joined", joined);
+			try {
+				const result = await transition;
+				span.setAttribute("rootContext.transition.status", result.status);
+				return result;
+			} finally {
+				span.end();
+			}
+		});
+	}
+	async resolveAndCommitRootTransition(invalidationKey) {
+		if (this.disposed) throw new Error("Planning-root service manager is disposed.");
+		const state = await (this.options.tracer ?? trace.getTracer("openspecui-server")).startActiveSpan("planningRoot.resolveRootContext", async (span) => {
+			span.setAttribute("rootContext.cacheHit", false);
+			span.setAttribute("rootContext.invalidationKey", invalidationKey);
+			try {
+				return await resolveServerRootContext({
+					projectDir: this.options.launchProjectDir,
+					cliExecutor: this.options.cliExecutor
+				});
+			} finally {
+				span.end();
+			}
+		});
+		try {
+			return await this.enqueueRootTransitionCommit(() => this.commitRootTransition(invalidationKey, state));
+		} catch (error) {
+			return {
+				status: "current",
+				state: this.lifecycleErrorState(state, error),
+				services: null
+			};
+		}
+	}
+	async commitRootTransition(invalidationKey, state) {
+		if (this.disposed) throw new Error("Planning-root service manager is disposed.");
+		if (this.currentRootContextInvalidationKey() !== invalidationKey) return { status: "stale" };
 		if (state.state === "error") {
-			const previous = this.activeRecord;
-			this.activeRecord = null;
-			if (previous) await this.retireRecord(previous);
-			return null;
+			const detached = await this.runWriteTransition("root-transition.commit", () => {
+				if (this.disposed) throw new Error("Planning-root service manager is disposed.");
+				if (this.currentRootContextInvalidationKey() !== invalidationKey) return {
+					status: "stale",
+					record: null
+				};
+				const record = this.activeRecord;
+				this.activeRecord = null;
+				this.currentRootContextSnapshot = null;
+				if (record) this.retiringRecords.add(record);
+				return {
+					status: "current",
+					record
+				};
+			});
+			if (detached.status === "stale") return detached;
+			if (detached.record) await this.retireRecord(detached.record);
+			if (this.currentRootContextInvalidationKey() !== invalidationKey) return { status: "stale" };
+			return {
+				status: "current",
+				state,
+				services: null
+			};
 		}
-		if (!state.data.planningRoot) throw new Error("Root Context reached ready state without a planning root.");
+		if (!state.data.planningRoot) return {
+			status: "current",
+			state: this.lifecycleErrorState(state, "Root Context reached ready state without a planning root."),
+			services: null
+		};
+		const identity = this.rootIdentity(state.data);
 		const active = this.activeRecord;
-		if (active?.identity === this.rootIdentity(state.data)) {
+		if (active?.identity === identity) return this.runWriteTransition("root-transition.commit", () => {
+			if (this.disposed) throw new Error("Planning-root service manager is disposed.");
+			if (this.currentRootContextInvalidationKey() !== invalidationKey) return { status: "stale" };
+			if (this.activeRecord !== active) return { status: "stale" };
 			const currentRootContext = {
 				...state.data,
 				generation: active.gitBindingToken
 			};
 			active.rootContext = currentRootContext;
 			active.rootContextValue.set(currentRootContext);
-			return active;
-		}
-		this.activeRecord = null;
-		if (active) await this.retireRecord(active);
-		if (this.disposed) throw new Error("Planning-root service manager is disposed.");
-		const created = this.createRecord({
-			...state.data,
-			generation: state.data.generation ?? randomUUID()
-		});
-		this.activeRecord = created;
-		return created;
-	}
-	async resolveActiveTransition(reactive, useRuntimeInvalidationCache = true) {
-		if (this.disposed) throw new Error("Planning-root service manager is disposed.");
-		const invalidationKey = useRuntimeInvalidationCache ? this.currentRootContextInvalidationKey() : null;
-		const cached = this.currentRootContextSnapshot;
-		if (reactive && invalidationKey !== null && cached?.invalidationKey === invalidationKey && cached.services === this.activeRecord) {
-			if (reactive) await trackRootContextDependencies({ projectDir: this.options.launchProjectDir }, cached.state);
+			const resolvedState = this.resolvedStateForRecord(state, active);
+			this.currentRootContextSnapshot = {
+				invalidationKey,
+				state: resolvedState,
+				services: active,
+				reactiveReplayEligible: false
+			};
 			return {
-				state: cached.state,
-				services: cached.services
+				status: "current",
+				state: resolvedState,
+				services: active
 			};
-		}
-		this.currentRootContextSnapshot = null;
-		const state = await resolveServerRootContext({
-			projectDir: this.options.launchProjectDir,
-			cliExecutor: this.options.cliExecutor
 		});
-		if (reactive) await trackRootContextDependencies({ projectDir: this.options.launchProjectDir }, state);
+		if (active) {
+			if (!await this.runWriteTransition("root-transition.detach", () => {
+				if (this.disposed) throw new Error("Planning-root service manager is disposed.");
+				if (this.currentRootContextInvalidationKey() !== invalidationKey) return false;
+				if (this.activeRecord !== active) return false;
+				this.activeRecord = null;
+				this.currentRootContextSnapshot = null;
+				this.retiringRecords.add(active);
+				return true;
+			})) return { status: "stale" };
+			await this.retireRecord(active);
+			if (this.currentRootContextInvalidationKey() !== invalidationKey) return { status: "stale" };
+		}
+		if (this.disposed) throw new Error("Planning-root service manager is disposed.");
+		let created;
 		try {
-			const services = await this.activate(state);
-			if (state.state === "ready" && services) {
-				const resolvedState = {
-					...state,
-					data: services.rootContext
-				};
-				if (reactive && invalidationKey !== null && this.currentRootContextInvalidationKey() === invalidationKey) this.currentRootContextSnapshot = {
-					invalidationKey,
-					state: resolvedState,
-					services
-				};
-				return {
-					state: resolvedState,
-					services
-				};
-			}
-			return {
-				state,
-				services
-			};
+			created = this.createRecord({
+				...state.data,
+				generation: state.data.generation ?? randomUUID()
+			});
 		} catch (error) {
 			return {
+				status: "current",
 				state: this.lifecycleErrorState(state, error),
 				services: null
 			};
 		}
+		let committed;
+		try {
+			committed = await this.runWriteTransition("root-transition.commit", () => {
+				if (this.disposed) throw new Error("Planning-root service manager is disposed.");
+				if (this.currentRootContextInvalidationKey() !== invalidationKey) return false;
+				if (this.activeRecord !== null) return false;
+				this.activeRecord = created;
+				this.currentRootContextSnapshot = {
+					invalidationKey,
+					state: this.resolvedStateForRecord(state, created),
+					services: created,
+					reactiveReplayEligible: false
+				};
+				return true;
+			});
+		} catch (error) {
+			await this.retireRecord(created);
+			throw error;
+		}
+		if (!committed) {
+			await this.retireRecord(created);
+			return { status: "stale" };
+		}
+		return {
+			status: "current",
+			state: this.resolvedStateForRecord(state, created),
+			services: created
+		};
+	}
+	readCurrentSnapshot(invalidationKey) {
+		return this.runReadTransition("root-transition.cache-check", () => {
+			if (this.disposed) throw new Error("Planning-root service manager is disposed.");
+			const cached = this.currentRootContextSnapshot;
+			if (cached?.invalidationKey !== invalidationKey || cached.services !== this.activeRecord) return null;
+			return cached;
+		});
+	}
+	async trackReactiveRootContext(state) {
+		await trackRootContextDependencies({ projectDir: this.options.launchProjectDir }, state);
+	}
+	promoteReactiveSnapshot(invalidationKey, services) {
+		const snapshot = this.currentRootContextSnapshot;
+		if (!services || snapshot?.invalidationKey !== invalidationKey || snapshot.services !== services || this.activeRecord !== services) return;
+		snapshot.reactiveReplayEligible = true;
 	}
-	resolveTransition(reactive, useRuntimeInvalidationCache = true) {
-		return this.runTransition(() => this.resolveActiveTransition(reactive, useRuntimeInvalidationCache));
+	async resolveTransition(reactive, useRuntimeInvalidationCache = true, allowStaleCache = false) {
+		const cacheEligible = reactive || allowStaleCache;
+		while (true) {
+			if (this.disposed) throw new Error("Planning-root service manager is disposed.");
+			const invalidationKey = this.currentRootContextInvalidationKey();
+			if (useRuntimeInvalidationCache && cacheEligible) {
+				const cached = await this.readCurrentSnapshot(invalidationKey);
+				if (cached && (!reactive || cached.reactiveReplayEligible)) {
+					this.traceRootContextCacheHit();
+					if (reactive) await this.trackReactiveRootContext(cached.state);
+					return {
+						state: cached.state,
+						services: cached.services
+					};
+				}
+			}
+			const transition = await this.awaitRootTransition(invalidationKey);
+			if (transition.status === "stale") continue;
+			if (reactive) {
+				await this.trackReactiveRootContext(transition.state);
+				this.promoteReactiveSnapshot(invalidationKey, transition.services);
+			}
+			return transition;
+		}
 	}
 	requireActiveServices(result) {
 		if (result.state.state === "error" || !result.services) throw new PlanningRootUnavailableError(result.state.state === "error" ? result.state : this.lifecycleErrorState(result.state, "Planning-root services are unavailable."));
 		return result.services;
 	}
-	acquireOperation(reactive) {
-		return this.runTransition(async () => {
-			if (this.disposed) throw new Error("Planning-root service manager is disposed.");
-			const record = this.requireActiveServices(await this.resolveActiveTransition(reactive));
-			if (this.disposed) throw new Error("Planning-root service manager is disposed.");
-			return {
-				lease: this.createOperationLease(record),
-				record
-			};
-		});
+	async acquireOperation(reactive, allowStaleCache = false) {
+		const cacheEligible = reactive || allowStaleCache;
+		let acceptNewerSnapshot = false;
+		while (true) {
+			const invalidationKey = this.currentRootContextInvalidationKey();
+			const cached = cacheEligible || acceptNewerSnapshot ? await this.runReadTransition("acquire-operation.cache-check", () => {
+				if (this.disposed) throw new Error("Planning-root service manager is disposed.");
+				const snapshot = this.currentRootContextSnapshot;
+				if (snapshot?.invalidationKey !== invalidationKey || snapshot.services !== this.activeRecord || reactive && !snapshot.reactiveReplayEligible) return null;
+				return {
+					state: snapshot.state,
+					lease: this.createOperationLease(snapshot.services),
+					record: snapshot.services
+				};
+			}) : null;
+			if (cached) try {
+				this.traceRootContextCacheHit();
+				if (reactive) await this.trackReactiveRootContext(cached.state);
+				return {
+					lease: cached.lease,
+					record: cached.record
+				};
+			} catch (error) {
+				await cached.lease.release();
+				throw error;
+			}
+			const transition = await this.awaitRootTransition(invalidationKey);
+			if (transition.status === "stale") {
+				acceptNewerSnapshot = true;
+				continue;
+			}
+			const admitted = await this.runReadTransition("acquire-operation.commit", () => {
+				if (this.disposed) throw new Error("Planning-root service manager is disposed.");
+				if (this.currentRootContextInvalidationKey() !== invalidationKey) return null;
+				const record = this.requireActiveServices(transition);
+				if (this.activeRecord !== record) return null;
+				return {
+					lease: this.createOperationLease(record),
+					record
+				};
+			});
+			if (!admitted) continue;
+			try {
+				if (reactive) {
+					await this.trackReactiveRootContext(transition.state);
+					this.promoteReactiveSnapshot(invalidationKey, admitted.record);
+				}
+				return admitted;
+			} catch (error) {
+				await admitted.lease.release();
+				throw error;
+			}
+		}
 	}
 	/** Resolve Root Context only after the active Planning-root lifecycle has converged. */
 	async resolveRootContext() {
@@ -10595,8 +11105,8 @@ var PlanningRootServiceManager = class {
 		return (await this.resolveTransition(true, false)).state;
 	}
 	/** Run one complete operation without exposing a durable service handle. */
-	async runOperation(operation) {
-		const { lease } = await this.acquireOperation(false);
+	async runOperation(operation, allowStaleCache = false) {
+		const { lease } = await this.acquireOperation(false, allowStaleCache);
 		try {
 			return await operation(lease.services);
 		} finally {
@@ -10613,39 +11123,35 @@ var PlanningRootServiceManager = class {
 		}
 	}
 	/** Retain a revocable operation capability until the child process actually settles. */
-	startOperationStream(operation) {
-		return this.runTransition(async () => {
-			if (this.disposed) throw new Error("Planning-root service manager is disposed.");
-			const record = this.requireActiveServices(await this.resolveActiveTransition(false));
+	async startOperationStream(operation) {
+		const { lease, record } = await this.acquireOperation(false);
+		try {
 			if (this.disposed) throw new Error("Planning-root service manager is disposed.");
-			const lease = this.createOperationLease(record);
-			try {
-				const stream = operation(lease.services);
-				let managedStream;
-				const settled = stream.settled.then(async (settlement) => {
-					await lease.release();
-					record.activeStreams.delete(managedStream);
-					return settlement;
-				});
-				let cancelRequested = false;
-				managedStream = {
-					settled,
-					cancel: () => {
-						if (!cancelRequested) {
-							cancelRequested = true;
-							stream.cancel().catch(() => {});
-						}
-						return settled;
-					}
-				};
-				record.activeStreams.add(managedStream);
-				settled.catch(() => {});
-				return managedStream;
-			} catch (error) {
+			const stream = operation(lease.services);
+			let managedStream;
+			const settled = stream.settled.then(async (settlement) => {
 				await lease.release();
-				throw error;
-			}
-		});
+				record.activeStreams.delete(managedStream);
+				return settlement;
+			});
+			let cancelRequested = false;
+			managedStream = {
+				settled,
+				cancel: () => {
+					if (!cancelRequested) {
+						cancelRequested = true;
+						stream.cancel().catch(() => {});
+					}
+					return settled;
+				}
+			};
+			record.activeStreams.add(managedStream);
+			settled.catch(() => {});
+			return managedStream;
+		} catch (error) {
+			await lease.release();
+			throw error;
+		}
 	}
 	/** Run one Schema action inside the same operation-lifetime contract as every Router caller. */
 	async mutateSchema(action) {
@@ -10670,8 +11176,9 @@ var PlanningRootServiceManager = class {
 		}
 		const cancellation = this.cancelRetiringStreams();
 		cancellation.catch(() => {});
-		const teardown = this.runTransition(async () => {
-			await cancellation;
+		const teardown = cancellation.then(async () => {
+			await Promise.allSettled(this.rootTransitionFlights.values());
+			await this.rootTransitionCommitTail;
 			for (const record of this.retiringRecords) await this.retireRecord(record);
 			this.ownedProjectionWorkRuntime?.clear();
 		});
@@ -11883,7 +12390,7 @@ function createRootContextNotificationBridge(input) {
 function createRootContextProjectionWorkOwner(runtime) {
 	return { rootContext: runtime.createRegistry() };
 }
-function estimateSnapshotBytes$1(data) {
+function estimateSnapshotBytes$2(data) {
 	return Buffer$1.byteLength(JSON.stringify(data) ?? "", "utf8");
 }
 /** CLI-backed Root Context Pull/Push owner for one launch project. */
@@ -11955,7 +12462,7 @@ var RootContextProjectionService = class {
 			identity: this.identity(),
 			resourceClass: "cli",
 			priority: "foreground",
-			estimateSnapshotBytes: estimateSnapshotBytes$1,
+			estimateSnapshotBytes: estimateSnapshotBytes$2,
 			load: async ({ reportStage }) => {
 				await trackRootContextStaticDependencies({
 					launchProjectDir: this.options.launchProjectDir,
@@ -13250,12 +13757,58 @@ async function setTrackedTaskCompletion(options) {
 //#endregion
 //#region src/router.ts
 const t = initTRPC.context().create();
+/**
+* Diagnostic-only tRPC procedure span. Covers every query/mutation/subscription so per-procedure
+* transport latency is visible. When `--otel` is off the Context carries a no-op tracer, so this
+* middleware is effectively free. Subscription establishment (not the data fetch) is measured here;
+* the actual planning-root data resolution carries its own nested `planningRoot.runOperation` span.
+*/
+const tracingMiddleware = t.middleware(async ({ ctx, path, type, next }) => {
+	const tracer = ctx.tracer;
+	if (!tracer) return next();
+	return tracer.startActiveSpan(`trpc.${path}`, async (span) => {
+		span.setAttribute("trpc.path", path);
+		span.setAttribute("trpc.type", type);
+		try {
+			const result = await next();
+			span.setAttribute("trpc.ok", !("ok" in result) || result.ok);
+			return result;
+		} catch (err) {
+			span.recordException(err);
+			span.setStatus({
+				code: 2,
+				message: err instanceof Error ? err.message : String(err)
+			});
+			throw err;
+		} finally {
+			span.end();
+		}
+	});
+});
 /** Typed tRPC router factory bound to the OpenSpecUI Server context. */
 const router = t.router;
 /** Typed public tRPC procedure factory bound to the OpenSpecUI Server context. */
-const publicProcedure = t.procedure;
+const publicProcedure = t.procedure.use(tracingMiddleware);
 function runPlanningRoot(ctx, task, options = {}) {
-	return options.reactive ? ctx.planningRootServices.runReactiveOperation(task) : ctx.planningRootServices.runOperation(task);
+	const tracer = ctx.tracer;
+	const invoke = () => options.reactive ? ctx.planningRootServices.runReactiveOperation(task) : ctx.planningRootServices.runOperation(task, options.allowStaleCache ?? false);
+	if (!tracer) return invoke();
+	return tracer.startActiveSpan("planningRoot.runOperation", async (span) => {
+		span.setAttribute("planningRoot.reactive", !!options.reactive);
+		try {
+			return await invoke();
+		} finally {
+			span.end();
+		}
+	});
+}
+/**
+* Read-only Planning-root query helper. Equivalent to `runPlanningRoot` with `allowStaleCache: true`,
+* so read-only HTTP queries can reuse the cached Root Context snapshot instead of re-resolving on every
+* call. Write operations must use `runPlanningRoot` directly (default `allowStaleCache: false`).
+*/
+function runPlanningRootRead(ctx, task) {
+	return runPlanningRoot(ctx, task, { allowStaleCache: true });
 }
 function createPlanningRootSubscription(ctx, task) {
 	return createReactiveSubscription(() => runPlanningRoot(ctx, task, { reactive: true }));
@@ -13284,7 +13837,7 @@ function createPlanningRootProjectionWorkSubscription(ctx, subscribe, parseEvent
 				for await (const _ of reactiveContext.stream(() => {
 					retireRegionalSubscription();
 					const epoch = regionalEpoch;
-					return ctx.planningRootServices.runReactiveOperation((services) => {
+					return runPlanningRoot(ctx, (services) => {
 						regionalSubscription = subscribe(services, (event) => {
 							if (!active || epoch !== regionalEpoch) return;
 							try {
@@ -13293,7 +13846,7 @@ function createPlanningRootProjectionWorkSubscription(ctx, subscribe, parseEvent
 								emit.error(error instanceof Error ? error : new Error(String(error)));
 							}
 						});
-					});
+					}, { reactive: true });
 				}, controller.signal, { onRecomputeStarted: retireRegionalSubscription }));
 			} catch (error) {
 				if (active && !controller.signal.aborted) emit.error(error instanceof Error ? error : new Error(String(error)));
@@ -13412,6 +13965,7 @@ const projectionWorkIdentitySchema = z.object({
 	inputFingerprint: z.string(),
 	protocolVersion: z.number().int()
 });
+const projectionWorkPhaseSchema = z.enum(projectionWorkPhases);
 function dashboardProjectionEventSchema(dataSchema) {
 	const snapshotSchema = z.object({
 		data: dataSchema,
@@ -13426,19 +13980,7 @@ function dashboardProjectionEventSchema(dataSchema) {
 		}),
 		z.object({
 			type: z.literal("stage"),
-			phase: z.enum([
-				"request",
-				"transport-start",
-				"root-ready",
-				"cache-hit",
-				"join",
-				"start",
-				"leaf-settled",
-				"first-stable-payload",
-				"complete",
-				"error",
-				"cancel"
-			]),
+			phase: projectionWorkPhaseSchema,
 			workGeneration: z.number().int()
 		}),
 		z.object({
@@ -13551,19 +14093,7 @@ function changeProjectionEventSchema() {
 		}),
 		z.object({
 			type: z.literal("stage"),
-			phase: z.enum([
-				"request",
-				"transport-start",
-				"root-ready",
-				"cache-hit",
-				"join",
-				"start",
-				"leaf-settled",
-				"first-stable-payload",
-				"complete",
-				"error",
-				"cancel"
-			]),
+			phase: projectionWorkPhaseSchema,
 			workGeneration: z.number().int()
 		}),
 		z.object({
@@ -13830,7 +14360,7 @@ const localModelsRouter = router({
 	})).mutation(({ ctx, input }) => {
 		return ctx.localModelAssetService.deleteModel(input.modelId, input.groupId ?? input.selectedGroupId);
 	}),
-	refreshProfiles: publicProcedure.input(z.object({ modelId: z.string().min(1).optional() })).mutation(async ({ ctx, input }) => {
+	refreshProfiles: publicProcedure.input(z.object({ modelId: z.string().min(1).optional() })).query(async ({ ctx, input }) => {
 		const asset = await ctx.localModelAssetService.refreshProfiles(input.modelId);
 		return {
 			modelId: asset.modelId,
@@ -13839,7 +14369,7 @@ const localModelsRouter = router({
 			downloadPlan: asset.plan ?? null
 		};
 	}),
-	refreshArtifacts: publicProcedure.input(z.object({ modelId: z.string().min(1).optional() })).mutation(async ({ ctx, input }) => {
+	refreshArtifacts: publicProcedure.input(z.object({ modelId: z.string().min(1).optional() })).query(async ({ ctx, input }) => {
 		const asset = await ctx.localModelAssetService.refreshProfiles(input.modelId);
 		return {
 			modelId: asset.modelId,
@@ -13938,7 +14468,7 @@ const localCt2ModelsRouter = router({
 	})).mutation(({ ctx, input }) => {
 		return ctx.localCt2ModelAssetService.deleteModel(input.modelId, input.groupId ?? input.selectedGroupId);
 	}),
-	refreshArtifacts: publicProcedure.input(z.object({ modelId: z.string().min(1).optional() })).mutation(async ({ ctx, input }) => {
+	refreshArtifacts: publicProcedure.input(z.object({ modelId: z.string().min(1).optional() })).query(async ({ ctx, input }) => {
 		const asset = await ctx.localCt2ModelAssetService.refreshArtifacts(input.modelId);
 		return {
 			modelId: asset.modelId,
@@ -14037,7 +14567,7 @@ const localLlamaModelsRouter = router({
 	})).mutation(({ ctx, input }) => {
 		return ctx.localLlamaModelAssetService.deleteModel(input.modelId, input.groupId ?? input.selectedGroupId);
 	}),
-	refreshArtifacts: publicProcedure.input(z.object({ modelId: z.string().min(1).optional() })).mutation(async ({ ctx, input }) => {
+	refreshArtifacts: publicProcedure.input(z.object({ modelId: z.string().min(1).optional() })).query(async ({ ctx, input }) => {
 		const asset = await ctx.localLlamaModelAssetService.refreshArtifacts(input.modelId);
 		return {
 			modelId: asset.modelId,
@@ -14113,13 +14643,13 @@ function buildSystemStatus(ctx) {
 /** Source-aware Spec Catalog and document operations. */
 const specRouter = router({
 	catalog: publicProcedure.query(async ({ ctx }) => {
-		const data = await runPlanningRoot(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({ kind: "spec-catalog" }));
+		const data = await runPlanningRootRead(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({ kind: "spec-catalog" }));
 		if (data.kind !== "spec-catalog") throw new Error("Unexpected Spec Catalog projection.");
 		return data.value;
 	}),
 	document: publicProcedure.input(SpecIdentitySchema).query(async ({ ctx, input }) => {
 		try {
-			const data = await runPlanningRoot(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({
+			const data = await runPlanningRootRead(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({
 				kind: "spec-document",
 				identity: input
 			}));
@@ -14150,16 +14680,16 @@ const specRouter = router({
 */
 const changeRouter = router({
 	list: publicProcedure.query(async ({ ctx }) => {
-		return runPlanningRoot(ctx, ({ adapter }) => adapter.listChanges());
+		return runPlanningRootRead(ctx, ({ adapter }) => adapter.listChanges());
 	}),
 	listWithMeta: publicProcedure.query(async ({ ctx }) => {
-		return runPlanningRoot(ctx, ({ adapter }) => adapter.listChangesWithMeta());
+		return runPlanningRootRead(ctx, ({ adapter }) => adapter.listChangesWithMeta());
 	}),
 	listArchived: publicProcedure.query(async ({ ctx }) => {
-		return runPlanningRoot(ctx, ({ adapter }) => adapter.listArchivedChanges());
+		return runPlanningRootRead(ctx, ({ adapter }) => adapter.listArchivedChanges());
 	}),
 	get: publicProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
-		return runPlanningRoot(ctx, ({ documentService }) => documentService.readChange(input.id));
+		return runPlanningRootRead(ctx, ({ documentService }) => documentService.readChange(input.id));
 	}),
 	getRaw: publicProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
 		return runPlanningRoot(ctx, ({ adapter }) => adapter.readChangeRaw(input.id));
@@ -14216,7 +14746,7 @@ const changeRouter = router({
 		id: z.string(),
 		path: z.string()
 	})).query(async ({ ctx, input }) => {
-		return runPlanningRoot(ctx, ({ filePreviewService }) => filePreviewService.prepareEntityFilePreview({
+		return runPlanningRootRead(ctx, ({ filePreviewService }) => filePreviewService.prepareEntityFilePreview({
 			stage: "change",
 			changeId: input.id,
 			path: input.path
@@ -14235,16 +14765,16 @@ const initRouter = router({ init: publicProcedure.mutation(async ({ ctx }) => {
 */
 const archiveRouter = router({
 	list: publicProcedure.query(async ({ ctx }) => {
-		return runPlanningRoot(ctx, ({ adapter }) => adapter.listArchivedChanges());
+		return runPlanningRootRead(ctx, ({ adapter }) => adapter.listArchivedChanges());
 	}),
 	listWithMeta: publicProcedure.query(async ({ ctx }) => {
-		return runPlanningRoot(ctx, ({ adapter }) => adapter.listArchivedChangesWithMeta());
+		return runPlanningRootRead(ctx, ({ adapter }) => adapter.listArchivedChangesWithMeta());
 	}),
 	get: publicProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
-		return runPlanningRoot(ctx, async (services) => services.documentService.readEntityDetail("archive", input.id, "view", "processed", await buildEntityReadOptions(services, "archive", input.id)));
+		return runPlanningRootRead(ctx, async (services) => services.documentService.readEntityDetail("archive", input.id, "view", "processed", await buildEntityReadOptions(services, "archive", input.id)));
 	}),
 	getRaw: publicProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
-		return runPlanningRoot(ctx, async (services) => services.documentService.readEntityDetail("archive", input.id, "view", "source", await buildEntityReadOptions(services, "archive", input.id)));
+		return runPlanningRootRead(ctx, async (services) => services.documentService.readEntityDetail("archive", input.id, "view", "source", await buildEntityReadOptions(services, "archive", input.id)));
 	}),
 	subscribe: publicProcedure.subscription(({ ctx }) => {
 		return createPlanningRootProjectionSubscription(ctx, ({ adapter }) => adapter.listArchivedChangesWithMeta());
@@ -14267,7 +14797,7 @@ const archiveRouter = router({
 		id: z.string(),
 		path: z.string()
 	})).query(async ({ ctx, input }) => {
-		return runPlanningRoot(ctx, ({ filePreviewService }) => filePreviewService.prepareEntityFilePreview({
+		return runPlanningRootRead(ctx, ({ filePreviewService }) => filePreviewService.prepareEntityFilePreview({
 			stage: "archive",
 			changeId: input.id,
 			path: input.path
@@ -14371,7 +14901,6 @@ const configRouter = router({
 			"system"
 		]).optional(),
 		codeEditor: z.object({ theme: CodeEditorThemeSchema.optional() }).optional(),
-		appBaseUrl: z.string().optional(),
 		opsx: OpsxConfigSchema.partial().optional(),
 		terminal: TerminalConfigSchema.omit({ rendererEngine: true }).partial().extend({ rendererEngine: TerminalRendererEngineSchema.optional() }).optional(),
 		dashboard: DashboardConfigSchema.partial().optional(),
@@ -14383,10 +14912,9 @@ const configRouter = router({
 		const hasCliArgs = input.cli !== void 0 && Object.prototype.hasOwnProperty.call(input.cli, "args");
 		if (hasCliCommand && !hasCliArgs) {
 			await ctx.configManager.setCliCommand(input.cli?.command ?? "");
-			if (input.theme !== void 0 || input.codeEditor !== void 0 || input.appBaseUrl !== void 0 || input.opsx !== void 0 || input.terminal !== void 0 || input.dashboard !== void 0 || input.git !== void 0 || input.notifications !== void 0 || input.translation !== void 0) await ctx.configManager.writeConfig({
+			if (input.theme !== void 0 || input.codeEditor !== void 0 || input.opsx !== void 0 || input.terminal !== void 0 || input.dashboard !== void 0 || input.git !== void 0 || input.notifications !== void 0 || input.translation !== void 0) await ctx.configManager.writeConfig({
 				theme: input.theme,
 				codeEditor: input.codeEditor,
-				appBaseUrl: input.appBaseUrl,
 				opsx: input.opsx,
 				terminal: input.terminal,
 				dashboard: input.dashboard,
@@ -14606,7 +15134,7 @@ const cliRouter = router({
 */
 const planningCliProjectionRouter = router({
 	read: publicProcedure.input(PlanningCliProjectionSelectorSchema).query(({ ctx, input }) => runPlanningRoot(ctx, ({ planningCliProjectionService }) => PlanningCliProjectionStateSchema.parse(planningCliProjectionService.read(input)), { reactive: true })),
-	refresh: publicProcedure.input(PlanningCliProjectionSelectorSchema).mutation(({ ctx, input }) => runPlanningRoot(ctx, ({ planningCliProjectionService }) => PlanningCliProjectionStateSchema.parse(planningCliProjectionService.refresh(input)), { reactive: true })),
+	refresh: publicProcedure.input(PlanningCliProjectionSelectorSchema).query(({ ctx, input }) => runPlanningRoot(ctx, ({ planningCliProjectionService }) => PlanningCliProjectionStateSchema.parse(planningCliProjectionService.refresh(input)), { reactive: true })),
 	subscribe: publicProcedure.input(PlanningCliProjectionSelectorSchema).subscription(({ ctx, input }) => createPlanningRootCliProjectionSubscription(ctx, input))
 });
 const opsxRouter = router({
@@ -14620,7 +15148,7 @@ const opsxRouter = router({
 		change: z.string().optional(),
 		schema: z.string().optional()
 	})).query(async ({ ctx, input }) => {
-		const data = await runPlanningRoot(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({
+		const data = await runPlanningRootRead(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({
 			kind: "opsx-status",
 			change: requireChangeId(input.change),
 			schema: input.schema
@@ -14629,7 +15157,7 @@ const opsxRouter = router({
 		return data.value;
 	}),
 	statusList: publicProcedure.query(async ({ ctx }) => {
-		const data = await runPlanningRoot(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({ kind: "opsx-status-list" }));
+		const data = await runPlanningRootRead(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({ kind: "opsx-status-list" }));
 		if (data.kind !== "opsx-status-list") throw new Error("Unexpected OPSX Status-list projection.");
 		return data.value;
 	}),
@@ -14638,7 +15166,7 @@ const opsxRouter = router({
 		artifact: z.string(),
 		schema: z.string().optional()
 	})).query(async ({ ctx, input }) => {
-		const data = await runPlanningRoot(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({
+		const data = await runPlanningRootRead(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({
 			kind: "opsx-instructions",
 			change: requireChangeId(input.change),
 			artifact: input.artifact,
@@ -14651,7 +15179,7 @@ const opsxRouter = router({
 		change: z.string().optional(),
 		schema: z.string().optional()
 	})).query(async ({ ctx, input }) => {
-		const data = await runPlanningRoot(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({
+		const data = await runPlanningRootRead(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({
 			kind: "opsx-apply-instructions",
 			change: requireChangeId(input.change),
 			schema: input.schema
@@ -14660,12 +15188,12 @@ const opsxRouter = router({
 		return data.value;
 	}),
 	configBundle: publicProcedure.query(async ({ ctx }) => {
-		const data = await runPlanningRoot(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({ kind: "opsx-config-bundle" }));
+		const data = await runPlanningRootRead(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({ kind: "opsx-config-bundle" }));
 		if (data.kind !== "opsx-config-bundle") throw new Error("Unexpected OPSX Config-bundle projection.");
 		return data.value;
 	}),
 	templates: publicProcedure.input(z.object({ schema: z.string().optional() }).optional()).query(async ({ ctx, input }) => {
-		const data = await runPlanningRoot(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({
+		const data = await runPlanningRootRead(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({
 			kind: "opsx-templates",
 			schema: input?.schema
 		}));
@@ -14673,7 +15201,7 @@ const opsxRouter = router({
 		return data.value;
 	}),
 	templateContents: publicProcedure.input(z.object({ schema: z.string().optional() }).optional()).query(async ({ ctx, input }) => {
-		const data = await runPlanningRoot(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({
+		const data = await runPlanningRootRead(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({
 			kind: "opsx-template-contents",
 			schema: input?.schema
 		}));
@@ -14804,7 +15332,7 @@ const opsxRouter = router({
 		return result;
 	}),
 	listChanges: publicProcedure.query(async ({ ctx }) => {
-		const data = await runPlanningRoot(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({ kind: "opsx-change-list" }));
+		const data = await runPlanningRootRead(ctx, ({ planningCliProjectionService }) => planningCliProjectionService.getCurrent({ kind: "opsx-change-list" }));
 		if (data.kind !== "opsx-change-list") throw new Error("Unexpected OPSX Change-list projection.");
 		return data.value;
 	}),
@@ -14896,7 +15424,7 @@ const kvRouter = router({
 */
 const searchRouter = router({
 	query: publicProcedure.input(ProjectSearchQuerySchema).output(ProjectSearchHitSchema.array()).query(async ({ ctx, input }) => {
-		return runPlanningRoot(ctx, async ({ searchService }) => parseProjectSearchHits(await searchService.query(input), input.scope));
+		return runPlanningRootRead(ctx, async ({ searchService }) => parseProjectSearchHits(await searchService.query(input), input.scope));
 	}),
 	subscribe: publicProcedure.input(ProjectSearchQuerySchema).subscription(({ ctx, input }) => {
 		return createPlanningRootSubscription(ctx, async ({ searchService }) => parseProjectSearchHits(await searchService.queryReactive(input), input.scope));
@@ -14938,17 +15466,17 @@ const systemRouter = router({
 */
 const dashboardRouter = router({
 	get: publicProcedure.query(async ({ ctx }) => {
-		return runPlanningRoot(ctx, ({ dashboardOverviewService }) => dashboardOverviewService.getCurrent());
+		return runPlanningRootRead(ctx, ({ dashboardOverviewService }) => dashboardOverviewService.getCurrent());
 	}),
 	subscribe: publicProcedure.subscription(({ ctx }) => {
 		return createPlanningRootSubscription(ctx, ({ dashboardOverviewService }) => dashboardOverviewService.getCurrent());
 	}),
 	getSummary: publicProcedure.query(async ({ ctx }) => DashboardSummaryProjectionStateSchema.parse(await runPlanningRoot(ctx, ({ dashboardProjectionService }) => dashboardProjectionService.getSummary(), { reactive: true }))),
 	getTrends: publicProcedure.query(({ ctx }) => {
-		return runPlanningRoot(ctx, ({ dashboardProjectionService }) => dashboardProjectionService.getTrends());
+		return runPlanningRootRead(ctx, ({ dashboardProjectionService }) => dashboardProjectionService.getTrends());
 	}),
 	getGit: publicProcedure.query(({ ctx }) => {
-		return runPlanningRoot(ctx, ({ dashboardProjectionService }) => dashboardProjectionService.getGit());
+		return runPlanningRootRead(ctx, ({ dashboardProjectionService }) => dashboardProjectionService.getGit());
 	}),
 	subscribeSummary: publicProcedure.subscription(({ ctx }) => createPlanningRootSummaryInvalidationSubscription(ctx)),
 	subscribeTrends: publicProcedure.subscription(({ ctx }) => createPlanningRootProjectionWorkSubscription(ctx, (services, listener) => services.dashboardProjectionService.subscribeTrends(listener), (event) => dashboardProjectionEventSchema(DashboardTrendsProjectionSchema).parse(event))),
@@ -14957,7 +15485,7 @@ const dashboardRouter = router({
 		scope: z.literal("code"),
 		expectedBindingToken: gitBindingTokenSchema,
 		reason: z.string().optional()
-	})).mutation(async ({ ctx, input }) => {
+	})).query(async ({ ctx, input }) => {
 		const reason = input.reason?.trim() || "manual-refresh";
 		return runGitScope(ctx, input, async (codeRepository) => {
 			await touchDashboardGitRefreshStamp(gitRepositoryCwd(codeRepository), reason);
@@ -15108,7 +15636,7 @@ const gitRouter = router({
 		scope: gitRepositoryScopeSchema,
 		expectedBindingToken: gitBindingTokenSchema,
 		reason: z.string().optional()
-	})).mutation(async ({ ctx, input }) => {
+	})).query(async ({ ctx, input }) => {
 		return runGitScope(ctx, input, async (repository) => {
 			const projectDir = gitRepositoryCwd(repository);
 			const reason = input.reason?.trim() || "manual-refresh";
@@ -15171,7 +15699,7 @@ const storesRouter = router({
 	refreshProjection: publicProcedure.input(z.discriminatedUnion("kind", [z.object({ kind: z.literal("list") }), z.object({
 		kind: z.literal("doctor"),
 		id: z.string().optional()
-	})])).mutation(({ ctx, input }) => input.kind === "list" ? HostedStoreListProjectionStateSchema.parse(ctx.storeProjectionService.refreshList()) : HostedStoreDoctorProjectionStateSchema.parse(ctx.storeProjectionService.refreshDoctor(input.id))),
+	})])).query(({ ctx, input }) => input.kind === "list" ? HostedStoreListProjectionStateSchema.parse(ctx.storeProjectionService.refreshList()) : HostedStoreDoctorProjectionStateSchema.parse(ctx.storeProjectionService.refreshDoctor(input.id))),
 	subscribeProjection: publicProcedure.input(z.discriminatedUnion("kind", [z.object({ kind: z.literal("list") }), z.object({
 		kind: z.literal("doctor"),
 		id: z.string().optional()
@@ -15255,6 +15783,38 @@ const storesRouter = router({
 		});
 	})
 });
+/**
+* Demand-driven readonly Store-content (Specs/active Changes) Projection Work router (6.10).
+*
+* Read procedures expose the hosted typed Pull state for one composite `(envUri, Store id, kind)` identity; Store id
+* alone is never accepted as sufficient. The composite identity is validated and the envUri treated as opaque.
+* Procedures run only after normal Access Gate admission and never accept client credentials in projection payloads.
+*/
+const storeContentIdentityInput = z.object({
+	envUri: z.string().min(1),
+	storeId: z.string().min(1),
+	kind: z.enum(["specs", "changes"])
+});
+const storesContentRouter = router({
+	readSpecsProjection: publicProcedure.input(storeContentIdentityInput).query(({ ctx, input }) => HostedStoreContentSpecsProjectionStateSchema.parse(ctx.storeContentProjectionService.readContent({
+		envUri: input.envUri,
+		storeId: input.storeId,
+		kind: "specs"
+	}))),
+	readChangesProjection: publicProcedure.input(storeContentIdentityInput).query(({ ctx, input }) => HostedStoreContentChangesProjectionStateSchema.parse(ctx.storeContentProjectionService.readContent({
+		envUri: input.envUri,
+		storeId: input.storeId,
+		kind: "changes"
+	}))),
+	subscribeProjection: publicProcedure.input(storeContentIdentityInput).subscription(({ ctx, input }) => observable((emit) => {
+		const subscription = ctx.storeContentProjectionService.subscribeContent({
+			envUri: input.envUri,
+			storeId: input.storeId,
+			kind: input.kind
+		}, (notice) => emit.next(notice));
+		return () => subscription.unsubscribe();
+	}))
+});
 const runtimeInvalidationFacetSchema = z.enum(RUNTIME_INVALIDATION_FACETS);
 /** Push identity-only invalidation tokens; every client pulls its authoritative projection. */
 const runtimeInvalidationRouter = router({ subscribe: publicProcedure.input(z.object({ facets: z.array(runtimeInvalidationFacetSchema).min(1) })).subscription(({ ctx, input }) => {
@@ -15340,7 +15900,7 @@ const planningConfigRouter = router({
 	}),
 	environmentGlobal: publicProcedure.query(({ ctx }) => ctx.environmentGlobalProjectionService.getCurrentConfig()),
 	readEnvironmentGlobalProjection: publicProcedure.query(({ ctx }) => EnvironmentGlobalProjectionStateSchema.parse(ctx.environmentGlobalProjectionService.read())),
-	refreshEnvironmentGlobalProjection: publicProcedure.mutation(({ ctx }) => EnvironmentGlobalProjectionStateSchema.parse(ctx.environmentGlobalProjectionService.refresh())),
+	refreshEnvironmentGlobalProjection: publicProcedure.query(({ ctx }) => EnvironmentGlobalProjectionStateSchema.parse(ctx.environmentGlobalProjectionService.refresh())),
 	subscribeEnvironmentGlobalProjection: publicProcedure.subscription(({ ctx }) => observable((emit) => {
 		const subscription = ctx.environmentGlobalProjectionService.subscribe((notice) => emit.next(CliProjectionNoticeSchema.parse(notice)));
 		return () => subscription.unsubscribe();
@@ -15354,7 +15914,7 @@ const planningConfigRouter = router({
 		return runOpenSpecCliMutation(ctx, args, () => ctx.cliExecutor.execute(args));
 	}),
 	readEnvironmentGlobalFileProjection: publicProcedure.query(({ ctx }) => EnvironmentGlobalFileProjectionStateSchema.parse(ctx.environmentGlobalProjectionService.readFile())),
-	refreshEnvironmentGlobalFileProjection: publicProcedure.mutation(({ ctx }) => EnvironmentGlobalFileProjectionStateSchema.parse(ctx.environmentGlobalProjectionService.refreshFile())),
+	refreshEnvironmentGlobalFileProjection: publicProcedure.query(({ ctx }) => EnvironmentGlobalFileProjectionStateSchema.parse(ctx.environmentGlobalProjectionService.refreshFile())),
 	subscribeEnvironmentGlobalFileProjection: publicProcedure.subscription(({ ctx }) => observable((emit) => {
 		const subscription = ctx.environmentGlobalProjectionService.subscribeFile((notice) => emit.next(CliProjectionNoticeSchema.parse(notice)));
 		return () => subscription.unsubscribe();
@@ -15371,7 +15931,7 @@ const planningConfigRouter = router({
 const rootContextRouter = router({
 	get: publicProcedure.query(async ({ ctx }) => HostedRootContextResolvedStateSchema.parse(await ctx.rootContextProjectionService.getCurrent())),
 	readProjection: publicProcedure.query(({ ctx }) => HostedRootContextProjectionStateSchema.parse(ctx.rootContextProjectionService.read())),
-	refreshProjection: publicProcedure.mutation(({ ctx }) => HostedRootContextProjectionStateSchema.parse(ctx.rootContextProjectionService.refresh())),
+	refreshProjection: publicProcedure.query(({ ctx }) => HostedRootContextProjectionStateSchema.parse(ctx.rootContextProjectionService.refresh())),
 	subscribeProjection: publicProcedure.subscription(({ ctx }) => observable((emit) => {
 		const subscription = ctx.rootContextProjectionService.subscribe((notice) => emit.next(HostedCliProjectionNoticeSchema.parse(notice)));
 		return () => subscription.unsubscribe();
@@ -15404,11 +15964,205 @@ const appRouter = router({
 	planningCliProjection: planningCliProjectionRouter,
 	opsx: opsxRouter,
 	stores: storesRouter,
+	storesContent: storesContentRouter,
 	kv: kvRouter,
 	search: searchRouter,
 	system: systemRouter
 });
 
+//#endregion
+//#region src/store-content-projection-service.ts
+/**
+* Orthogonal intents (created 2026-07-30 Asia/Shanghai):
+* 1. Own Store Specs and active Changes as demand-driven CLI Projection Work (6.4/6.5).
+* 2. Call the official CLI contract with an explicit Store selector; never parse files or reparse stdout (6.6).
+* 3. Keep Specs and active Changes regions independent for load/refresh/error/recovery (6.7).
+* 4. Key Projection Work by composite (envUri, Store id, kind) identity; reject stale/cross-Store completion (6.8).
+* 5. Reuse Store-root observation invalidation and data-free Push -> Pull transport (6.9).
+*
+* Original request (2026-07-30): "Stores 完全可以融入 `Environment Center` 这个东西。"
+* Spec: hosted-environment-delivery › "Environment-Scoped Store Content Projection".
+*
+* This service mirrors `store-projection-service.ts` but projects typed Spec/active-Change lists for one selected
+* composite identity. It is demand-driven: only a subscribed Store Detail starts work (6.12).
+*/
+function createStoreContentProjectionWorkOwner(runtime) {
+	return { registry: runtime.createRegistry() };
+}
+function estimateSnapshotBytes$1(data) {
+	return Buffer$1.byteLength(JSON.stringify(data) ?? "", "utf8");
+}
+/** Demand-driven, Store-selected Spec/active-Change CLI Projection Work owner. */
+var StoreContentProjectionService = class {
+	releaseStoreObservation = null;
+	releaseRuntimeInvalidation = null;
+	disposed = false;
+	constructor(options) {
+		this.options = options;
+		this.releaseStoreObservation = options.storeObservation.subscribe((change) => this.invalidateStoreContent(change));
+		this.releaseRuntimeInvalidation = options.invalidation.subscribe(["stores"], () => this.invalidateAllStoreContent());
+	}
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.releaseStoreObservation?.();
+		this.releaseRuntimeInvalidation?.();
+	}
+	/** Subscribe to one composite Store-content Work item (demand-driven; only a Detail starts it). */
+	subscribeContent(identity, listener) {
+		return this.options.workOwner.registry.subscribeLifecycle(this.contentRequest(identity), listener);
+	}
+	/** Read the current Pull state for one composite Store-content Work item. */
+	readContent(identity) {
+		const request = this.contentRequest(identity);
+		const state = this.options.workOwner.registry.read(request.identity) ?? this.loadingState(request.identity);
+		return this.selectState(state, identity.kind);
+	}
+	/** Explicitly invalidate one composite Store-content Work item (e.g. after a Store mutation). */
+	refreshContent(identity) {
+		this.options.workOwner.registry.invalidate(this.contentIdentity(identity), "explicit-refresh");
+		return this.readContent(identity);
+	}
+	contentIdentity(identity) {
+		return {
+			projectionKind: `store-content-${identity.kind}`,
+			planningRoot: {
+				identity: this.options.dataScopePath,
+				source: "environment-data-home",
+				storeSelector: identity.storeId
+			},
+			owner: {
+				generation: null,
+				gitBindingToken: null
+			},
+			selector: JSON.stringify({
+				envUri: identity.envUri,
+				storeId: identity.storeId,
+				kind: identity.kind
+			}),
+			inputFingerprint: `openspec-cli-1.6:store-content:${identity.kind}`,
+			protocolVersion: 1
+		};
+	}
+	contentRequest(identity) {
+		return {
+			identity: this.contentIdentity(identity),
+			resourceClass: "cli",
+			priority: "foreground",
+			estimateSnapshotBytes: estimateSnapshotBytes$1,
+			load: async ({ reportStage }) => {
+				reportStage("root-ready");
+				const cliVersion = await this.resolveCliVersion();
+				const storeId = identity.storeId;
+				if (identity.kind === "specs") {
+					const classification$1 = classifyStoreCliResult({
+						result: await this.options.cliExecutor.contracts.listSpecs({ store: storeId }),
+						schema: StoreContentSpecListSchema,
+						cliVersion
+					});
+					const projection$1 = this.toSpecsEnvelope(classification$1, storeId, cliVersion);
+					reportStage("leaf-settled");
+					return {
+						kind: "specs",
+						value: projection$1
+					};
+				}
+				const classification = classifyStoreCliResult({
+					result: await this.options.cliExecutor.contracts.listChanges({ store: storeId }),
+					schema: StoreContentChangeListSchema,
+					cliVersion
+				});
+				const projection = this.toChangesEnvelope(classification, storeId, cliVersion);
+				reportStage("leaf-settled");
+				return {
+					kind: "changes",
+					value: projection
+				};
+			}
+		};
+	}
+	async resolveCliVersion() {
+		try {
+			const availability = await this.options.cliExecutor.checkAvailability();
+			return availability.available ? availability.version : void 0;
+		} catch {
+			return;
+		}
+	}
+	/** Build the Specs-content envelope from a CLI classification, matching the hosted schema. */
+	toSpecsEnvelope(classification, storeId, cliVersion) {
+		if (classification.kind === "ok") return {
+			available: true,
+			specs: classification.data.specs,
+			storeId,
+			...cliVersion ? { cliVersion } : {}
+		};
+		return {
+			available: false,
+			specs: [],
+			storeId,
+			error: {
+				kind: classification.kind,
+				message: classification.message
+			},
+			...classification.cliVersion ? { cliVersion: classification.cliVersion } : {}
+		};
+	}
+	/** Build the active-Changes-content envelope from a CLI classification, matching the hosted schema. */
+	toChangesEnvelope(classification, storeId, cliVersion) {
+		if (classification.kind === "ok") return {
+			available: true,
+			changes: classification.data.changes,
+			storeId,
+			...cliVersion ? { cliVersion } : {}
+		};
+		return {
+			available: false,
+			changes: [],
+			storeId,
+			error: {
+				kind: classification.kind,
+				message: classification.message
+			},
+			...classification.cliVersion ? { cliVersion: classification.cliVersion } : {}
+		};
+	}
+	invalidateStoreContent(change) {
+		const selectedStoreIds = new Set(change.kind === "inventory" ? change.storeIds : [change.storeId]);
+		this.options.workOwner.registry.invalidateMatching((identity) => {
+			if (!selectedStoreIds.has(identity.planningRoot.storeSelector ?? "")) return false;
+			if (change.kind === "spec-root") return identity.projectionKind === "store-content-specs";
+			return identity.projectionKind === "store-content-specs" || identity.projectionKind === "store-content-changes";
+		}, "dependency");
+	}
+	invalidateAllStoreContent() {
+		this.options.workOwner.registry.invalidateMatching((identity) => identity.projectionKind === "store-content-specs" || identity.projectionKind === "store-content-changes", "dependency");
+	}
+	loadingState(identity) {
+		return {
+			state: "loading",
+			identity: projectionWorkIdentityKey(identity),
+			workGeneration: 0,
+			invalidationCause: "initial",
+			data: null,
+			freshness: null,
+			snapshotGeneration: null,
+			error: null
+		};
+	}
+	selectState(state, kind) {
+		if (state.data === null) return {
+			...state,
+			data: null
+		};
+		if (state.data.kind !== kind) throw new Error(`Unexpected Store content kind: ${state.data.kind}`);
+		return {
+			...state,
+			data: state.data.value
+		};
+	}
+};
+
 //#endregion
 //#region src/store-observation-fallback.ts
 /**
@@ -16087,6 +16841,88 @@ var ToolCommandObservationService = class {
 	}
 };
 
+//#endregion
+//#region src/tracing.ts
+/**
+* Orthogonal intents (created 2026-07-30 Asia/Shanghai):
+* 1. Bootstrap OpenTelemetry tracing for the backend (diagnostic only, gated by `--otel`).
+* 2. Expose a single Tracer value (real or noop) so instrumentation sites stay branch-free.
+* 3. Let the NodeSDK auto-configure from standard OTEL_* environment variables, with an optional
+*    explicit `--otel-endpoint` override; refuse to pollute the console on incomplete config.
+*
+* Original request (2026-07-30): "我需要集成 OpenTelemetry ... 通过 --otel --otel-endpoint 来开启。
+*   因为我要你分析目前速度慢的根本原因。"
+* Owner correction (2026-07-30): --otel is just the switch; concrete config (endpoint, headers,
+*   sampling) should come from standard OTel ENV (OTEL_EXPORTER_OTLP_ENDPOINT etc.).
+*
+* Design: `--otel` flips the switch. When on, a NodeSDK is started WITHOUT an explicit
+* traceExporter so it auto-resolves from OTEL_* env vars (the canonical OTel workflow). An explicit
+* `--otel-endpoint` provides one convenience override for the OTLP/HTTP endpoint. When `--otel` is
+* off, `initTracing` returns a noop tracer and never touches the OTel SDK, so every span operation
+* is a side-effect-free no-op and the manager/lease/invalidation correctness models are untouched.
+*
+* Supported ENV (read by NodeSDK, not by us):
+*   OTEL_EXPORTER_OTLP_ENDPOINT   Collector base URL
+*   OTEL_EXPORTER_OTLP_HEADERS    e.g. "Authorization=Basic <base64>"
+*   OTEL_TRACES_SAMPLER ...       standard sampling config
+*/
+/** No-op tracer returned when tracing is disabled: span methods are inert. */
+const NOOP_TRACER = trace.getTracer("openspecui-noop");
+let activeSdk = null;
+/**
+* Initialize backend tracing and return the Tracer every instrumentation site should use.
+*
+* - `enabled` → start a NodeSDK that auto-configures from OTEL_* env vars. An explicit `endpoint`
+*   overrides the OTLP/HTTP export target; otherwise the SDK honors OTEL_EXPORTER_OTLP_ENDPOINT /
+*   OTEL_EXPORTER_OTLP_HEADERS etc. directly.
+* - `!enabled` → return NOOP_TRACER without constructing or starting any SDK.
+*/
+/** Whether any standard OTel exporter env var is set (so the SDK has something to export to). */
+function hasOtelExporterEnv() {
+	return Boolean(process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_HEADERS || process.env.OTEL_TRACES_EXPORTER);
+}
+/**
+* Normalize a user-supplied OTLP/HTTP endpoint into the full traces export URL.
+*
+* `OTLPTraceExporter({ url })` uses the url verbatim — it does NOT append the OTLP signal path.
+* A bare Collector base like `http://host:4318` therefore POSTs to the root and gets 404. Users
+* naturally pass a base URL (the same value they'd put in OTEL_EXPORTER_OTLP_ENDPOINT, which the
+* SDK *does* append to). To keep `--otel-endpoint` ergonomic and consistent with ENV semantics,
+* append `/v1/traces` only when the URL has no OTLP signal path of its own.
+*
+* Exported for unit testing.
+*/
+function normalizeOtlpHttpEndpoint(rawEndpoint) {
+	const endpoint = rawEndpoint.trim();
+	if (!endpoint) return endpoint;
+	if (/\/v1\/(traces|metrics|logs)$/i.test(endpoint)) return endpoint;
+	return `${endpoint.replace(/\/+$/, "")}/v1/traces`;
+}
+function initTracing(config) {
+	if (!config.enabled) return NOOP_TRACER;
+	const hasEndpoint = Boolean(config.endpoint && config.endpoint.length > 0);
+	if (!hasEndpoint && !hasOtelExporterEnv()) {
+		console.warn("[openspecui] --otel is enabled but no exporter is configured. Set OTEL_EXPORTER_OTLP_ENDPOINT (and OTEL_EXPORTER_OTLP_HEADERS if needed), or pass --otel-endpoint, to export spans. Tracing stays a no-op until configured.");
+		return NOOP_TRACER;
+	}
+	const rawLogLevel = process.env.OTEL_LOG_LEVEL;
+	diag.setLogger(new DiagConsoleLogger(), rawLogLevel ? Number(rawLogLevel) : DiagLogLevel.INFO);
+	const resolvedEndpoint = hasEndpoint ? normalizeOtlpHttpEndpoint(config.endpoint) : void 0;
+	activeSdk = new NodeSDK({
+		serviceName: "openspecui-server",
+		traceExporter: resolvedEndpoint ? new OTLPTraceExporter({ url: resolvedEndpoint }) : void 0
+	});
+	activeSdk.start();
+	diag.info("[openspecui] OpenTelemetry tracing started -> %s", resolvedEndpoint ?? "OTEL_* env");
+	return trace.getTracer("openspecui-server");
+}
+/** Flush and dispose any active SDK started by `initTracing`. Safe to call when none is active. */
+async function shutdownTracing() {
+	const sdk = activeSdk;
+	activeSdk = null;
+	if (sdk) await sdk.shutdown();
+}
+
 //#endregion
 //#region src/translation-cache-adapter.ts
 var SqliteTranslationCacheAdapter = class {
@@ -16321,6 +17157,14 @@ var TranslationCacheService = class {
 
 //#endregion
 //#region src/runtime-package-host.ts
+/**
+* Orthogonal intents (updated 2026-07-31 Asia/Shanghai):
+* 1. Resolve the physical host manifest that owns on-demand runtime installation.
+* 2. Read declared runtime ranges without treating optional peers as install-time dependencies.
+* 3. Normalize legacy on-demand optional dependency records after package-manager installation.
+*
+* Original request (2026-07-31): "这个依赖好像会导致安装的时候仍然会被强制装上去，可能要改成 peerDependencies 会更好"
+*/
 function resolveRuntimeHostPackageContext(startDir) {
 	let currentDir = startDir;
 	let openspecuiPackage = null;
@@ -16350,7 +17194,7 @@ function resolveRuntimeHostPackageContext(startDir) {
 }
 function readRuntimeHostPackageDependencyRequest(input) {
 	const parsed = readRuntimeHostPackageJson(input.runtimeHost.packageJsonPath);
-	const range = parsed.optionalDependencies?.[input.packageName] ?? parsed.dependencies?.[input.packageName] ?? input.fallbackRange;
+	const range = parsed.optionalDependencies?.[input.packageName] ?? parsed.dependencies?.[input.packageName] ?? parsed.peerDependencies?.[input.packageName] ?? input.fallbackRange;
 	return `${input.packageName}@${range}`;
 }
 async function readRuntimeHostPackageDependencyTree(input) {
@@ -17950,7 +18794,7 @@ if (!isMainThread) {
 //#endregion
 //#region src/server.ts
 /**
-* Orthogonal intents (updated 2026-07-27 Asia/Shanghai):
+* Orthogonal intents (updated 2026-07-31 Asia/Shanghai):
 * 1. Bootstrap the HTTP/tRPC server and launch-project runtime services.
 * 2. Delegate OpenSpec filesystem ownership to the CLI-selected planning-root manager.
 * 3. Host Server-local terminal/Root Context notifications, sound, preview-resource, and translation HTTP boundaries.
@@ -17959,6 +18803,9 @@ if (!isMainThread) {
 * 5. Own the runtime observation environment and external Codex command lease while deferring expensive
 *    root-scoped projections until a foreground consumer requests them; keep Store-list registry/mutation
 *    evidence distinct from selector-exact Store-root observation.
+* 6. Initialize backend OpenTelemetry tracing (--otel diagnostic only) and expose the resolved Tracer
+*    through Context so procedure/planning-root instrumentation stays branch-free.
+* 7. Admit dynamic loopback App origins while keeping remote browser origins explicitly allowlisted.
 *
 * Original request (2026-07-15): "你先负责后端（内核）的开发。"
 * Original request (2026-07-17): "Every Planning-root execution surface uses the same operation lifetime owner."
@@ -17972,6 +18819,8 @@ if (!isMainThread) {
 * Owner-reported defect (2026-07-26): App-embedded Project Web must enter its canonical Dashboard
 * route directly instead of visibly normalizing the backend root after iframe launch.
 * Original request (2026-07-26): "展开全面的接口升级和内核升级和测试升级。"
+* Built-runtime defect (2026-07-30): Direct Web shutdown must await HTTP closure and retire non-cooperative WebSocket and buffered CLI children after one signal.
+* Original request (2026-07-31): Trace every Planning-root write lock with timing, source, and stack evidence.
 *
 * @module server
 */
@@ -18005,6 +18854,7 @@ function createRootContextProjectionNotificationSource(service) {
 * Create an OpenSpecUI HTTP server with optional WebSocket support
 */
 function createServer(config) {
+	const tracer = initTracing(config.tracing ?? { enabled: false });
 	const accessGate = createAccessGate({
 		credential: config.accessGate ?? null,
 		loopback: true
@@ -18057,6 +18907,13 @@ function createServer(config) {
 		storeObservation,
 		workOwner: storeProjectionWorkOwner
 	});
+	const storeContentProjectionService = new StoreContentProjectionService({
+		dataScopePath: dataScope.path,
+		cliExecutor,
+		invalidation: runtimeInvalidation,
+		storeObservation,
+		workOwner: createStoreContentProjectionWorkOwner(projectionWorkRuntime)
+	});
 	const planningRootServices = new PlanningRootServiceManager({
 		launchProjectDir: config.projectDir,
 		previewAssetsDir: config.previewAssetsDir ?? join(__dirname, "..", "..", "web", "dist"),
@@ -18069,7 +18926,8 @@ function createServer(config) {
 		codeBinding: codeGitBinding,
 		dashboardProjectionWorkOwner,
 		changesProjectionWorkOwner,
-		planningCliProjectionWorkOwner
+		planningCliProjectionWorkOwner,
+		tracer
 	});
 	const rootContextProjectionService = new RootContextProjectionService({
 		launchProjectDir: config.projectDir,
@@ -18182,7 +19040,15 @@ function createServer(config) {
 	const app = new Hono();
 	const corsOrigins = config.corsOrigins ?? ["http://localhost:5173", "http://localhost:3000"];
 	app.use("*", cors({
-		origin: corsOrigins,
+		origin: (origin) => {
+			if (corsOrigins.includes(origin)) return origin;
+			try {
+				const url = new URL(origin);
+				return (url.protocol === "http:" || url.protocol === "https:") && isLoopbackHostname(url.hostname) ? origin : void 0;
+			} catch {
+				return;
+			}
+		},
 		credentials: true
 	}));
 	app.use("*", createAccessGateMiddleware(accessGate));
@@ -18259,6 +19125,7 @@ function createServer(config) {
 				runtimeInvalidation,
 				storeObservation,
 				storeProjectionService,
+				storeContentProjectionService,
 				rootContextProjectionService,
 				environmentGlobalProjectionService,
 				storeMutationService,
@@ -18277,7 +19144,8 @@ function createServer(config) {
 				gitWorktreeHandoff: config.gitWorktreeHandoff,
 				watcher,
 				projectDir: config.projectDir,
-				envUri
+				envUri,
+				tracer
 			})
 		});
 	});
@@ -18299,6 +19167,7 @@ function createServer(config) {
 			runtimeInvalidation,
 			storeObservation,
 			storeProjectionService,
+			storeContentProjectionService,
 			rootContextProjectionService,
 			environmentGlobalProjectionService,
 			storeMutationService,
@@ -18317,7 +19186,8 @@ function createServer(config) {
 			gitWorktreeHandoff: config.gitWorktreeHandoff,
 			watcher,
 			projectDir: config.projectDir,
-			envUri
+			envUri,
+			tracer
 		};
 	};
 	return {
@@ -18333,6 +19203,7 @@ function createServer(config) {
 		dataHomeObserver,
 		storeObservation,
 		storeProjectionService,
+		storeContentProjectionService,
 		rootContextProjectionService,
 		environmentGlobalProjectionService,
 		storeObservationFallback,
@@ -18353,6 +19224,7 @@ function createServer(config) {
 		projectionWorkRuntime,
 		watcher,
 		createContext,
+		tracer,
 		port: config.port ?? 3100
 	};
 }
@@ -18424,6 +19296,13 @@ async function createWebSocketServer(server, httpServer, config) {
 		const results = await Promise.allSettled(tasks.map((task) => Promise.resolve().then(task)));
 		for (const result of results) if (result.status === "rejected") failures.push(result.reason);
 	};
+	const closeWebSocketServer = (socketServer) => new Promise((resolve$1, reject) => {
+		for (const client of socketServer.clients) client.terminate();
+		socketServer.close((error) => {
+			if (error) reject(error);
+			else resolve$1();
+		});
+	});
 	return {
 		wss,
 		ptyWss,
@@ -18435,15 +19314,17 @@ async function createWebSocketServer(server, httpServer, config) {
 				await settleCleanupPhase(failures, [
 					() => handler.broadcastReconnectNotification(),
 					() => ptyManager.closeAll(),
-					() => ptyWss.close(),
-					() => wss.close(),
+					() => closeWebSocketServer(ptyWss),
+					() => closeWebSocketServer(wss),
 					() => server.watcher?.stop()
 				]);
 				await settleCleanupPhase(failures, [() => server.storeObservationFallback.dispose()]);
 				await settleCleanupPhase(failures, [() => server.storeMutationService.dispose()]);
 				await settleCleanupPhase(failures, [() => server.rootContextNotificationBridge.dispose()]);
 				await settleCleanupPhase(failures, [() => server.storeProjectionService.dispose()]);
+				await settleCleanupPhase(failures, [() => server.storeContentProjectionService.dispose()]);
 				await settleCleanupPhase(failures, [() => server.environmentGlobalProjectionService.dispose()]);
+				await settleCleanupPhase(failures, [() => server.cliExecutor.dispose()]);
 				await settleCleanupPhase(failures, [() => server.planningRootServices.dispose()]);
 				await settleCleanupPhase(failures, [() => server.projectionWorkRuntime.clear()]);
 				await settleCleanupPhase(failures, [() => server.storeObservation.dispose()]);
@@ -18491,6 +19372,13 @@ async function startServer(config, setupApp) {
 		fetch: server.app.fetch,
 		port
 	});
+	const closeHttpServer = () => new Promise((resolve$1, reject) => {
+		httpServer.close((error) => {
+			if (error) reject(error);
+			else resolve$1();
+		});
+		if ("closeAllConnections" in httpServer) httpServer.closeAllConnections();
+	});
 	const wsServer = await createWebSocketServer(server, httpServer, { projectDir: config.projectDir });
 	let closePromise = null;
 	return {
@@ -18507,11 +19395,13 @@ async function startServer(config, setupApp) {
 					Promise.resolve().then(() => context.localLlamaModelAssetService.close())
 				]);
 				const websocketResults = await Promise.allSettled([Promise.resolve().then(() => wsServer.close())]);
-				const httpResults = await Promise.allSettled([Promise.resolve().then(() => httpServer.close())]);
+				const httpResults = await Promise.allSettled([closeHttpServer()]);
+				const tracingResults = await Promise.allSettled([shutdownTracing()]);
 				const failures = [
 					...modelResults,
 					...websocketResults,
-					...httpResults
+					...httpResults,
+					...tracingResults
 				].flatMap((result) => result.status === "rejected" ? [result.reason] : []);
 				if (failures.length > 0) throw new AggregateError(failures, "Server shutdown failed.");
 			})();