@openspecui/server 2.1.0 → 2.1.1

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { createServer as createServer$1 } from "node:net";
 import { serve } from "@hono/node-server";
-import { CliExecutor, CodeEditorThemeSchema, ConfigManager, DASHBOARD_METRIC_KEYS, DashboardConfigSchema, OpenSpecAdapter, OpenSpecWatcher, OpsxKernel, PtyClientMessageSchema, ReactiveContext, TerminalConfigSchema, TerminalRendererEngineSchema, contextStorage, getAllTools, getAvailableTools, getConfiguredTools, getDefaultCliCommandString, getWatcherRuntimeStatus, initWatcherPool, isWatcherPoolInitialized, reactiveReadDir, reactiveReadFile, sniffGlobalCli } from "@openspecui/core";
+import { CliExecutor, CodeEditorThemeSchema, ConfigManager, DASHBOARD_METRIC_KEYS, DashboardConfigSchema, OpenSpecAdapter, OpenSpecWatcher, OpsxKernel, PtyClientMessageSchema, ReactiveContext, TerminalConfigSchema, TerminalRendererEngineSchema, getAllTools, getAvailableTools, getConfiguredTools, getDefaultCliCommandString, getWatcherRuntimeStatus, initWatcherPool, isWatcherPoolInitialized, sniffGlobalCli } from "@openspecui/core";
 import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
 import { applyWSSHandler } from "@trpc/server/adapters/ws";
 import { Hono } from "hono";
@@ -9,15 +9,15 @@ import { readFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { WebSocketServer } from "ws";
+import { EventEmitter } from "node:events";
+import { execFile } from "node:child_process";
+import { mkdir, rm, stat, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
 import * as pty from "@lydell/node-pty";
-import { EventEmitter } from "events";
+import { EventEmitter as EventEmitter$1 } from "events";
 import { SearchQuerySchema } from "@openspecui/search";
 import { initTRPC } from "@trpc/server";
 import { observable } from "@trpc/server/observable";
-import { execFile } from "node:child_process";
-import { EventEmitter as EventEmitter$1 } from "node:events";
-import { mkdir, rm, stat, writeFile } from "node:fs/promises";
-import { promisify } from "node:util";
 import { z } from "zod";
 import { NodeWorkerSearchProvider } from "@openspecui/search/node";
 
@@ -56,454 +56,112 @@ async function findAvailablePort(startPort, maxAttempts = 10) {
 }
 
 //#endregion
-//#region src/pty-manager.ts
-const DEFAULT_SCROLLBACK = 1e3;
-const DEFAULT_MAX_BUFFER_BYTES = 2 * 1024 * 1024;
-function detectPtyPlatform() {
-	if (process.platform === "win32") return "windows";
-	if (process.platform === "darwin") return "macos";
-	return "common";
-}
-function resolveDefaultShell(platform, env) {
-	if (platform === "windows") return env.ComSpec?.trim() || "cmd.exe";
-	return env.SHELL?.trim() || "/bin/sh";
-}
-function resolvePtyCommand(opts) {
-	const command = opts.command?.trim();
-	if (command) return {
-		command,
-		args: opts.args ?? []
-	};
-	return {
-		command: resolveDefaultShell(opts.platform, opts.env),
-		args: []
-	};
-}
-var PtySession = class extends EventEmitter {
-	id;
-	command;
-	args;
-	platform;
-	closeTip;
-	closeCallbackUrl;
-	createdAt;
-	process;
-	titleInterval = null;
-	lastTitle = "";
-	buffer = [];
-	bufferByteLength = 0;
-	maxBufferLines;
-	maxBufferBytes;
-	isExited = false;
-	exitCode = null;
-	constructor(id, opts) {
-		super();
-		this.id = id;
-		this.createdAt = Date.now();
-		const resolvedCommand = resolvePtyCommand({
-			platform: opts.platform,
-			command: opts.command,
-			args: opts.args,
-			env: process.env
-		});
-		this.command = resolvedCommand.command;
-		this.args = resolvedCommand.args;
-		this.platform = opts.platform;
-		this.closeTip = opts.closeTip;
-		this.closeCallbackUrl = opts.closeCallbackUrl;
-		this.maxBufferLines = opts.scrollback ?? DEFAULT_SCROLLBACK;
-		this.maxBufferBytes = opts.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
-		this.process = pty.spawn(this.command, this.args, {
-			name: "xterm-256color",
-			cols: opts.cols ?? 80,
-			rows: opts.rows ?? 24,
-			cwd: opts.cwd,
-			env: {
-				...process.env,
-				TERM: "xterm-256color"
-			}
-		});
-		this.process.onData((data) => {
-			this.appendBuffer(data);
-			this.emit("data", data);
-		});
-		this.process.onExit(({ exitCode }) => {
-			if (this.titleInterval) {
-				clearInterval(this.titleInterval);
-				this.titleInterval = null;
-			}
-			this.isExited = true;
-			this.exitCode = exitCode;
-			this.emit("exit", exitCode);
+//#region src/dashboard-overview-service.ts
+const REBUILD_DEBOUNCE_MS$1 = 250;
+var DashboardOverviewService = class {
+	current = null;
+	initialized = false;
+	initPromise = null;
+	refreshPromise = null;
+	refreshTimer = null;
+	pendingRefreshReason = null;
+	emitter = new EventEmitter();
+	constructor(loadOverview, watcher) {
+		this.loadOverview = loadOverview;
+		this.emitter.setMaxListeners(200);
+		watcher?.on("change", () => {
+			this.scheduleRefresh("watcher-change");
 		});
-		this.titleInterval = setInterval(() => {
-			try {
-				const title = this.process.process;
-				if (title && title !== this.lastTitle) {
-					this.lastTitle = title;
-					this.emit("title", title);
-				}
-			} catch {}
-		}, 1e3);
-	}
-	get title() {
-		return this.lastTitle;
 	}
-	appendBuffer(data) {
-		let chunk = data;
-		if (chunk.length > this.maxBufferBytes) chunk = chunk.slice(-this.maxBufferBytes);
-		this.buffer.push(chunk);
-		this.bufferByteLength += chunk.length;
-		while (this.bufferByteLength > this.maxBufferBytes && this.buffer.length > 0) {
-			const removed = this.buffer.shift();
-			this.bufferByteLength -= removed.length;
-		}
-		while (this.buffer.length > this.maxBufferLines) {
-			const removed = this.buffer.shift();
-			this.bufferByteLength -= removed.length;
+	async init() {
+		if (this.initialized && this.current) return this.current;
+		if (this.initPromise) return this.initPromise;
+		this.initPromise = this.refresh("init");
+		try {
+			return await this.initPromise;
+		} finally {
+			this.initPromise = null;
 		}
 	}
-	getBuffer() {
-		return this.buffer.join("");
+	async getCurrent() {
+		if (this.current) return this.current;
+		return this.init();
 	}
-	write(data) {
-		if (!this.isExited) this.process.write(data);
+	subscribe(listener, options) {
+		this.emitter.on("change", listener);
+		if (options?.emitCurrent) if (this.current) listener(this.current);
+		else this.init().catch((error) => {
+			options?.onError?.(error instanceof Error ? error : new Error(String(error)));
+		});
+		return () => {
+			this.emitter.off("change", listener);
+		};
 	}
-	resize(cols, rows) {
-		if (!this.isExited) this.process.resize(cols, rows);
+	scheduleRefresh(reason = "scheduled-refresh") {
+		this.cancelScheduledRefresh();
+		this.refreshTimer = setTimeout(() => {
+			this.refreshTimer = null;
+			this.refresh(reason).catch(() => {});
+		}, REBUILD_DEBOUNCE_MS$1);
 	}
-	close() {
-		if (this.titleInterval) {
-			clearInterval(this.titleInterval);
-			this.titleInterval = null;
+	async refresh(reason = "manual-refresh") {
+		this.cancelScheduledRefresh();
+		if (this.refreshPromise) {
+			this.pendingRefreshReason = reason;
+			return this.refreshPromise;
 		}
+		this.refreshPromise = (async () => {
+			const next = await this.loadOverview(reason);
+			this.current = next;
+			this.initialized = true;
+			this.emitter.emit("change", next);
+			return next;
+		})();
 		try {
-			this.process.kill();
-		} catch {}
-		this.removeAllListeners();
-	}
-	toInfo() {
-		return {
-			id: this.id,
-			title: this.lastTitle,
-			command: this.command,
-			args: this.args,
-			platform: this.platform,
-			isExited: this.isExited,
-			exitCode: this.exitCode,
-			closeTip: this.closeTip,
-			closeCallbackUrl: this.closeCallbackUrl,
-			createdAt: this.createdAt
-		};
-	}
-};
-var PtyManager = class {
-	sessions = /* @__PURE__ */ new Map();
-	idCounter = 0;
-	platform;
-	constructor(defaultCwd) {
-		this.defaultCwd = defaultCwd;
-		this.platform = detectPtyPlatform();
-	}
-	create(opts) {
-		const id = `pty-${++this.idCounter}`;
-		const session = new PtySession(id, {
-			cols: opts.cols,
-			rows: opts.rows,
-			command: opts.command,
-			args: opts.args,
-			closeTip: opts.closeTip,
-			closeCallbackUrl: opts.closeCallbackUrl,
-			cwd: this.defaultCwd,
-			scrollback: opts.scrollback,
-			maxBufferBytes: opts.maxBufferBytes,
-			platform: this.platform
-		});
-		this.sessions.set(id, session);
-		return session;
-	}
-	get(id) {
-		return this.sessions.get(id);
-	}
-	list() {
-		const result = [];
-		for (const session of this.sessions.values()) result.push(session.toInfo());
-		return result;
-	}
-	write(id, data) {
-		this.sessions.get(id)?.write(data);
-	}
-	resize(id, cols, rows) {
-		this.sessions.get(id)?.resize(cols, rows);
-	}
-	close(id) {
-		const session = this.sessions.get(id);
-		if (session) {
-			session.close();
-			this.sessions.delete(id);
+			return await this.refreshPromise;
+		} finally {
+			this.refreshPromise = null;
+			if (this.pendingRefreshReason) {
+				const pendingReason = this.pendingRefreshReason;
+				this.pendingRefreshReason = null;
+				this.refresh(pendingReason).catch(() => {});
+			}
 		}
 	}
-	closeAll() {
-		for (const session of this.sessions.values()) session.close();
-		this.sessions.clear();
+	dispose() {
+		this.cancelScheduledRefresh();
+		this.emitter.removeAllListeners();
+	}
+	cancelScheduledRefresh() {
+		if (!this.refreshTimer) return;
+		clearTimeout(this.refreshTimer);
+		this.refreshTimer = null;
 	}
 };
 
 //#endregion
-//#region src/pty-websocket.ts
-function createPtyWebSocketHandler(ptyManager) {
-	return (ws) => {
-		const cleanups = /* @__PURE__ */ new Map();
-		const send = (msg) => {
-			if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(msg));
+//#region src/dashboard-git-snapshot.ts
+const execFileAsync$1 = promisify(execFile);
+const EMPTY_DIFF = {
+	files: 0,
+	insertions: 0,
+	deletions: 0
+};
+async function defaultRunGit(cwd, args) {
+	try {
+		const { stdout } = await execFileAsync$1("git", args, {
+			cwd,
+			encoding: "utf8",
+			maxBuffer: 8 * 1024 * 1024
+		});
+		return {
+			ok: true,
+			stdout
 		};
-		const sendError = (code, message, opts) => {
-			send({
-				type: "error",
-				code,
-				message,
-				sessionId: opts?.sessionId
-			});
-		};
-		const attachToSession = (session, opts) => {
-			const sessionId = session.id;
-			cleanups.get(sessionId)?.();
-			if (opts?.cols && opts?.rows && !session.isExited) session.resize(opts.cols, opts.rows);
-			const onData = (data) => {
-				send({
-					type: "output",
-					sessionId,
-					data
-				});
-			};
-			const onExit = (exitCode) => {
-				send({
-					type: "exit",
-					sessionId,
-					exitCode
-				});
-			};
-			const onTitle = (title) => {
-				send({
-					type: "title",
-					sessionId,
-					title
-				});
-			};
-			session.on("data", onData);
-			session.on("exit", onExit);
-			session.on("title", onTitle);
-			cleanups.set(sessionId, () => {
-				session.removeListener("data", onData);
-				session.removeListener("exit", onExit);
-				session.removeListener("title", onTitle);
-				cleanups.delete(sessionId);
-			});
-		};
-		ws.on("message", (raw) => {
-			let parsed;
-			try {
-				parsed = JSON.parse(String(raw));
-			} catch {
-				sendError("INVALID_JSON", "Invalid JSON payload");
-				return;
-			}
-			const parsedMessage = PtyClientMessageSchema.safeParse(parsed);
-			if (!parsedMessage.success) {
-				const firstIssue = parsedMessage.error.issues[0]?.message;
-				sendError("INVALID_MESSAGE", firstIssue ?? "Invalid PTY message");
-				return;
-			}
-			const msg = parsedMessage.data;
-			switch (msg.type) {
-				case "create":
-					try {
-						const createMessage = msg;
-						const session = ptyManager.create({
-							cols: msg.cols,
-							rows: msg.rows,
-							command: msg.command,
-							args: msg.args,
-							closeTip: createMessage.closeTip,
-							closeCallbackUrl: createMessage.closeCallbackUrl
-						});
-						send({
-							type: "created",
-							requestId: msg.requestId,
-							sessionId: session.id,
-							platform: session.platform
-						});
-						attachToSession(session);
-					} catch (err) {
-						sendError("PTY_CREATE_FAILED", err instanceof Error ? err.message : String(err), { sessionId: msg.requestId });
-					}
-					break;
-				case "attach": {
-					const session = ptyManager.get(msg.sessionId);
-					if (!session) {
-						sendError("SESSION_NOT_FOUND", `Session not found: ${msg.sessionId}`, { sessionId: msg.sessionId });
-						send({
-							type: "exit",
-							sessionId: msg.sessionId,
-							exitCode: -1
-						});
-						break;
-					}
-					attachToSession(session, {
-						cols: msg.cols,
-						rows: msg.rows
-					});
-					const buffer = session.getBuffer();
-					if (buffer) send({
-						type: "buffer",
-						sessionId: session.id,
-						data: buffer
-					});
-					if (session.title) send({
-						type: "title",
-						sessionId: session.id,
-						title: session.title
-					});
-					if (session.isExited) send({
-						type: "exit",
-						sessionId: session.id,
-						exitCode: session.exitCode ?? -1
-					});
-					break;
-				}
-				case "list":
-					send({
-						type: "list",
-						sessions: ptyManager.list().map((s) => ({
-							id: s.id,
-							title: s.title,
-							command: s.command,
-							args: s.args,
-							platform: s.platform,
-							isExited: s.isExited,
-							exitCode: s.exitCode,
-							closeTip: s.closeTip,
-							closeCallbackUrl: s.closeCallbackUrl
-						}))
-					});
-					break;
-				case "input": {
-					const session = ptyManager.get(msg.sessionId);
-					if (!session) {
-						sendError("SESSION_NOT_FOUND", `Session not found: ${msg.sessionId}`, { sessionId: msg.sessionId });
-						break;
-					}
-					session.write(msg.data);
-					break;
-				}
-				case "resize": {
-					const session = ptyManager.get(msg.sessionId);
-					if (!session) {
-						sendError("SESSION_NOT_FOUND", `Session not found: ${msg.sessionId}`, { sessionId: msg.sessionId });
-						break;
-					}
-					session.resize(msg.cols, msg.rows);
-					break;
-				}
-				case "close": {
-					const session = ptyManager.get(msg.sessionId);
-					if (!session) {
-						sendError("SESSION_NOT_FOUND", `Session not found: ${msg.sessionId}`, { sessionId: msg.sessionId });
-						break;
-					}
-					cleanups.get(msg.sessionId)?.();
-					ptyManager.close(session.id);
-					break;
-				}
-			}
-		});
-		ws.on("close", () => {
-			for (const cleanup of cleanups.values()) cleanup();
-			cleanups.clear();
-		});
-	};
-}
-
-//#endregion
-//#region src/cli-stream-observable.ts
-/**
-* 创建安全的 CLI 流式 observable
-*
-* 解决的问题：
-* 1. 防止在 emit.complete() 之后调用 emit.next()（会导致 "Controller is already closed" 错误）
-* 2. 统一的错误处理，防止未捕获的异常导致服务器崩溃
-* 3. 确保取消时正确清理资源
-*
-* @param startStream 启动流的函数，接收 onEvent 回调，返回取消函数的 Promise
-*/
-function createCliStreamObservable(startStream) {
-	return observable((emit) => {
-		let cancel;
-		let completed = false;
-		/**
-		* 安全的事件处理器
-		* - 检查是否已完成，防止重复调用
-		* - 使用 try-catch 防止异常导致服务器崩溃
-		*/
-		const safeEventHandler = (event) => {
-			if (completed) return;
-			try {
-				emit.next(event);
-				if (event.type === "exit") {
-					completed = true;
-					emit.complete();
-				}
-			} catch (err) {
-				console.error("[CLI Stream] Error emitting event:", err);
-				if (!completed) {
-					completed = true;
-					try {
-						emit.error(err instanceof Error ? err : new Error(String(err)));
-					} catch {}
-				}
-			}
-		};
-		startStream(safeEventHandler).then((cancelFn) => {
-			cancel = cancelFn;
-		}).catch((err) => {
-			console.error("[CLI Stream] Error starting stream:", err);
-			if (!completed) {
-				completed = true;
-				try {
-					emit.error(err instanceof Error ? err : new Error(String(err)));
-				} catch {}
-			}
-		});
-		return () => {
-			completed = true;
-			cancel?.();
-		};
-	});
-}
-
-//#endregion
-//#region src/dashboard-git-snapshot.ts
-const execFileAsync$1 = promisify(execFile);
-const EMPTY_DIFF = {
-	files: 0,
-	insertions: 0,
-	deletions: 0
-};
-async function defaultRunGit(cwd, args) {
-	try {
-		const { stdout } = await execFileAsync$1("git", args, {
-			cwd,
-			encoding: "utf8",
-			maxBuffer: 8 * 1024 * 1024
-		});
-		return {
-			ok: true,
-			stdout
-		};
-	} catch {
-		return {
-			ok: false,
-			stdout: ""
+	} catch {
+		return {
+			ok: false,
+			stdout: ""
 		};
 	}
 }
@@ -712,6 +370,7 @@ async function collectWorktree(options) {
 		path: worktreePath,
 		relativePath: relativePath(resolvedProjectDir, worktreePath),
 		branchName: parseBranchName(worktree.branchRef, worktree.detached),
+		detached: worktree.detached,
 		isCurrent: resolvedProjectDir === worktreePath,
 		ahead,
 		behind,
@@ -719,6 +378,27 @@ async function collectWorktree(options) {
 		entries
 	};
 }
+async function removeDetachedDashboardGitWorktree(options) {
+	const runGit = options.runGit ?? defaultRunGit;
+	const resolvedProjectDir = resolve(options.projectDir);
+	const resolvedTargetPath = resolve(options.targetPath);
+	if (resolvedTargetPath === resolvedProjectDir) throw new Error("Cannot remove the current worktree.");
+	const worktreeResult = await runGit(resolvedProjectDir, [
+		"worktree",
+		"list",
+		"--porcelain"
+	]);
+	if (!worktreeResult.ok) throw new Error("Failed to inspect git worktrees.");
+	const matched = parseWorktreeList(worktreeResult.stdout).find((worktree) => resolve(worktree.path) === resolvedTargetPath);
+	if (!matched) throw new Error("Worktree not found.");
+	if (!matched.detached) throw new Error("Only detached worktrees can be removed from Dashboard.");
+	if (!(await runGit(resolvedProjectDir, [
+		"worktree",
+		"remove",
+		"--force",
+		resolvedTargetPath
+	])).ok) throw new Error("Failed to remove detached worktree.");
+}
 async function buildDashboardGitSnapshot(options) {
 	const runGit = options.runGit ?? defaultRunGit;
 	const maxCommitEntries = options.maxCommitEntries ?? 8;
@@ -753,95 +433,783 @@ async function buildDashboardGitSnapshot(options) {
 }
 
 //#endregion
-//#region src/dashboard-time-trends.ts
-const MIN_TREND_POINT_LIMIT = 20;
-const MAX_TREND_POINT_LIMIT = 500;
-const DEFAULT_TREND_POINT_LIMIT = 100;
-const TARGET_TREND_BARS = 20;
-const DAY_MS = 1440 * 60 * 1e3;
-function clampPointLimit(pointLimit) {
-	if (!Number.isFinite(pointLimit)) return DEFAULT_TREND_POINT_LIMIT;
-	return Math.max(MIN_TREND_POINT_LIMIT, Math.min(MAX_TREND_POINT_LIMIT, Math.trunc(pointLimit)));
-}
-function createEmptyTrendSeries() {
-	return Object.fromEntries(DASHBOARD_METRIC_KEYS.map((metric) => [metric, []]));
-}
-function normalizeEvents(events, pointLimit) {
-	return events.filter((event) => Number.isFinite(event.ts) && event.ts > 0 && Number.isFinite(event.value)).sort((a, b) => a.ts - b.ts).slice(-pointLimit);
-}
-function buildTimeWindow(options) {
-	const { probeEvents, targetBars, rightEdgeTs } = options;
-	if (probeEvents.length === 0) return null;
-	const probeEnd = probeEvents[probeEvents.length - 1].ts;
-	const end = typeof rightEdgeTs === "number" && Number.isFinite(rightEdgeTs) && rightEdgeTs > 0 ? Math.max(probeEnd, rightEdgeTs) : probeEnd;
-	const probeStart = probeEvents[0].ts;
-	const rangeMs = Math.max(1, end - probeStart);
-	const bucketMs = rangeMs >= DAY_MS ? Math.max(DAY_MS, Math.ceil(rangeMs / targetBars / DAY_MS) * DAY_MS) : Math.max(1, Math.ceil(rangeMs / targetBars));
-	const windowStart = end - bucketMs * targetBars;
-	return {
-		windowStart,
-		bucketMs,
-		bucketEnds: Array.from({ length: targetBars }, (_, index) => windowStart + bucketMs * (index + 1))
-	};
-}
-function bucketizeTrend(events, reducer, rightEdgeTs) {
-	if (events.length === 0) return [];
-	const timeWindow = buildTimeWindow({
-		probeEvents: events,
-		targetBars: TARGET_TREND_BARS,
-		rightEdgeTs
-	});
-	if (!timeWindow) return [];
-	const { windowStart, bucketMs, bucketEnds } = timeWindow;
-	const sums = Array.from({ length: bucketEnds.length }, () => 0);
-	const counts = Array.from({ length: bucketEnds.length }, () => 0);
-	let baseline = 0;
-	for (const event of events) {
-		if (event.ts <= windowStart) {
-			if (reducer === "sum-cumulative") baseline += event.value;
-			continue;
-		}
-		const offset = event.ts - windowStart;
-		const index = Math.max(0, Math.min(bucketEnds.length - 1, Math.ceil(offset / bucketMs) - 1));
-		sums[index] += event.value;
-		counts[index] += 1;
-	}
-	let cumulative = baseline;
-	let carry = baseline !== 0 ? baseline : events[0].value;
-	return bucketEnds.map((ts, index) => {
-		if (reducer === "sum") return {
-			ts,
-			value: sums[index]
+//#region src/dashboard-time-trends.ts
+const MIN_TREND_POINT_LIMIT = 20;
+const MAX_TREND_POINT_LIMIT = 500;
+const DEFAULT_TREND_POINT_LIMIT = 100;
+const TARGET_TREND_BARS = 20;
+const DAY_MS = 1440 * 60 * 1e3;
+function clampPointLimit(pointLimit) {
+	if (!Number.isFinite(pointLimit)) return DEFAULT_TREND_POINT_LIMIT;
+	return Math.max(MIN_TREND_POINT_LIMIT, Math.min(MAX_TREND_POINT_LIMIT, Math.trunc(pointLimit)));
+}
+function createEmptyTrendSeries() {
+	return Object.fromEntries(DASHBOARD_METRIC_KEYS.map((metric) => [metric, []]));
+}
+function normalizeEvents(events, pointLimit) {
+	return events.filter((event) => Number.isFinite(event.ts) && event.ts > 0 && Number.isFinite(event.value)).sort((a, b) => a.ts - b.ts).slice(-pointLimit);
+}
+function buildTimeWindow(options) {
+	const { probeEvents, targetBars, rightEdgeTs } = options;
+	if (probeEvents.length === 0) return null;
+	const probeEnd = probeEvents[probeEvents.length - 1].ts;
+	const end = typeof rightEdgeTs === "number" && Number.isFinite(rightEdgeTs) && rightEdgeTs > 0 ? Math.max(probeEnd, rightEdgeTs) : probeEnd;
+	const probeStart = probeEvents[0].ts;
+	const rangeMs = Math.max(1, end - probeStart);
+	const bucketMs = rangeMs >= DAY_MS ? Math.max(DAY_MS, Math.ceil(rangeMs / targetBars / DAY_MS) * DAY_MS) : Math.max(1, Math.ceil(rangeMs / targetBars));
+	const windowStart = end - bucketMs * targetBars;
+	return {
+		windowStart,
+		bucketMs,
+		bucketEnds: Array.from({ length: targetBars }, (_, index) => windowStart + bucketMs * (index + 1))
+	};
+}
+function bucketizeTrend(events, reducer, rightEdgeTs) {
+	if (events.length === 0) return [];
+	const timeWindow = buildTimeWindow({
+		probeEvents: events,
+		targetBars: TARGET_TREND_BARS,
+		rightEdgeTs
+	});
+	if (!timeWindow) return [];
+	const { windowStart, bucketMs, bucketEnds } = timeWindow;
+	const sums = Array.from({ length: bucketEnds.length }, () => 0);
+	const counts = Array.from({ length: bucketEnds.length }, () => 0);
+	let baseline = 0;
+	for (const event of events) {
+		if (event.ts <= windowStart) {
+			if (reducer === "sum-cumulative") baseline += event.value;
+			continue;
+		}
+		const offset = event.ts - windowStart;
+		const index = Math.max(0, Math.min(bucketEnds.length - 1, Math.ceil(offset / bucketMs) - 1));
+		sums[index] += event.value;
+		counts[index] += 1;
+	}
+	let cumulative = baseline;
+	let carry = baseline !== 0 ? baseline : events[0].value;
+	return bucketEnds.map((ts, index) => {
+		if (reducer === "sum") return {
+			ts,
+			value: sums[index]
+		};
+		if (reducer === "sum-cumulative") {
+			cumulative += sums[index];
+			return {
+				ts,
+				value: cumulative
+			};
+		}
+		if (counts[index] > 0) carry = sums[index] / counts[index];
+		return {
+			ts,
+			value: carry
+		};
+	});
+}
+function buildDashboardTimeTrends(options) {
+	const pointLimit = clampPointLimit(options.pointLimit);
+	const trends = createEmptyTrendSeries();
+	for (const metric of DASHBOARD_METRIC_KEYS) {
+		if (options.availability[metric].state !== "ok") continue;
+		trends[metric] = bucketizeTrend(normalizeEvents(options.events[metric], pointLimit), options.reducers?.[metric] ?? "sum", options.rightEdgeTs);
+	}
+	return {
+		trends,
+		trendMeta: {
+			pointLimit,
+			lastUpdatedAt: options.timestamp
+		}
+	};
+}
+
+//#endregion
+//#region src/dashboard-overview.ts
+const execFileAsync = promisify(execFile);
+const DASHBOARD_GIT_REFRESH_STAMP_NAME = "openspecui-dashboard-git-refresh.stamp";
+const dashboardGitTaskStatusEmitter = new EventEmitter();
+dashboardGitTaskStatusEmitter.setMaxListeners(200);
+const dashboardGitTaskStatus = {
+	running: false,
+	inFlight: 0,
+	lastStartedAt: null,
+	lastFinishedAt: null,
+	lastReason: null,
+	lastError: null
+};
+function createEmptyTriColorTrends() {
+	return Object.fromEntries(DASHBOARD_METRIC_KEYS.map((metric) => [metric, []]));
+}
+function resolveTrendTimestamp(primary, secondary) {
+	if (typeof primary === "number" && Number.isFinite(primary) && primary > 0) return primary;
+	if (typeof secondary === "number" && Number.isFinite(secondary) && secondary > 0) return secondary;
+	return null;
+}
+function parseDatedIdTimestamp(id) {
+	const match = /^(\d{4})-(\d{2})-(\d{2})(?:-|$)/.exec(id);
+	if (!match) return null;
+	const year = Number(match[1]);
+	const month = Number(match[2]);
+	const day = Number(match[3]);
+	if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day)) return null;
+	if (month < 1 || month > 12) return null;
+	if (day < 1 || day > 31) return null;
+	const ts = Date.UTC(year, month - 1, day);
+	return Number.isFinite(ts) ? ts : null;
+}
+async function readLatestCommitTimestamp(projectDir) {
+	try {
+		const { stdout } = await execFileAsync("git", [
+			"log",
+			"-1",
+			"--format=%ct"
+		], {
+			cwd: projectDir,
+			maxBuffer: 1024 * 1024,
+			encoding: "utf8"
+		});
+		const seconds = Number(stdout.trim());
+		return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : null;
+	} catch {
+		return null;
+	}
+}
+function emitDashboardGitTaskStatus() {
+	dashboardGitTaskStatusEmitter.emit("change", getDashboardGitTaskStatus());
+}
+function beginDashboardGitTask(reason) {
+	dashboardGitTaskStatus.inFlight += 1;
+	dashboardGitTaskStatus.running = true;
+	dashboardGitTaskStatus.lastStartedAt = Date.now();
+	dashboardGitTaskStatus.lastReason = reason;
+	dashboardGitTaskStatus.lastError = null;
+	emitDashboardGitTaskStatus();
+}
+function endDashboardGitTask(error) {
+	dashboardGitTaskStatus.inFlight = Math.max(0, dashboardGitTaskStatus.inFlight - 1);
+	dashboardGitTaskStatus.running = dashboardGitTaskStatus.inFlight > 0;
+	dashboardGitTaskStatus.lastFinishedAt = Date.now();
+	if (error) dashboardGitTaskStatus.lastError = error instanceof Error ? error.message : String(error);
+	emitDashboardGitTaskStatus();
+}
+function getDashboardGitTaskStatus() {
+	return { ...dashboardGitTaskStatus };
+}
+function subscribeDashboardGitTaskStatus(listener) {
+	dashboardGitTaskStatusEmitter.on("change", listener);
+	return () => {
+		dashboardGitTaskStatusEmitter.off("change", listener);
+	};
+}
+async function resolveGitMetadataDir(projectDir) {
+	try {
+		const { stdout } = await execFileAsync("git", ["rev-parse", "--git-dir"], {
+			cwd: projectDir,
+			maxBuffer: 1024 * 1024,
+			encoding: "utf8"
+		});
+		const gitDirRaw = stdout.trim();
+		if (!gitDirRaw) return null;
+		const gitDirPath = resolve(projectDir, gitDirRaw);
+		if (!(await stat(gitDirPath)).isDirectory()) return null;
+		return gitDirPath;
+	} catch {
+		return null;
+	}
+}
+function getDashboardGitRefreshStampPath(gitMetadataDir) {
+	return join(gitMetadataDir, DASHBOARD_GIT_REFRESH_STAMP_NAME);
+}
+async function touchDashboardGitRefreshStamp(projectDir, reason) {
+	const gitMetadataDir = await resolveGitMetadataDir(projectDir);
+	if (!gitMetadataDir) return { skipped: true };
+	const stampPath = getDashboardGitRefreshStampPath(gitMetadataDir);
+	await mkdir(dirname(stampPath), { recursive: true });
+	await writeFile(stampPath, `${Date.now()} ${reason}\n`, "utf8");
+	return { skipped: false };
+}
+async function loadDashboardOverview(ctx, reason = "dashboard-refresh") {
+	const now = Date.now();
+	const [specMetas, changeMetas, archiveMetas] = await Promise.all([
+		ctx.adapter.listSpecsWithMeta(),
+		ctx.adapter.listChangesWithMeta(),
+		ctx.adapter.listArchivedChangesWithMeta()
+	]);
+	const activeChanges = changeMetas.map((changeMeta) => ({
+		id: changeMeta.id,
+		name: changeMeta.name ?? changeMeta.id,
+		progress: changeMeta.progress,
+		updatedAt: changeMeta.updatedAt
+	})).sort((a, b) => b.updatedAt - a.updatedAt);
+	const archivedChanges = (await Promise.all(archiveMetas.map(async (meta) => {
+		const change = await ctx.adapter.readArchivedChange(meta.id);
+		if (!change) return null;
+		return {
+			id: meta.id,
+			createdAt: meta.createdAt,
+			updatedAt: meta.updatedAt,
+			tasksCompleted: change.tasks.filter((task) => task.completed).length
+		};
+	}))).filter((item) => item !== null);
+	const specifications = (await Promise.all(specMetas.map(async (meta) => {
+		const spec = await ctx.adapter.readSpec(meta.id);
+		if (!spec) return null;
+		return {
+			id: meta.id,
+			name: meta.name,
+			requirements: spec.requirements.length,
+			updatedAt: meta.updatedAt
+		};
+	}))).filter((item) => item !== null).sort((a, b) => b.requirements - a.requirements || b.updatedAt - a.updatedAt);
+	const requirements = specifications.reduce((sum, spec) => sum + spec.requirements, 0);
+	const tasksTotal = activeChanges.reduce((sum, change) => sum + change.progress.total, 0);
+	const tasksCompleted = activeChanges.reduce((sum, change) => sum + change.progress.completed, 0);
+	const archivedTasksCompleted = archivedChanges.reduce((sum, change) => sum + change.tasksCompleted, 0);
+	const taskCompletionPercent = tasksTotal > 0 ? Math.round(tasksCompleted / tasksTotal * 100) : null;
+	const inProgressChanges = activeChanges.filter((change) => change.progress.total > 0 && change.progress.completed < change.progress.total).length;
+	const specificationTrendEvents = specMetas.flatMap((spec) => {
+		const ts = resolveTrendTimestamp(spec.createdAt, spec.updatedAt);
+		return ts === null ? [] : [{
+			ts,
+			value: 1
+		}];
+	});
+	const completedTrendEvents = archivedChanges.flatMap((archive) => {
+		const ts = parseDatedIdTimestamp(archive.id) ?? resolveTrendTimestamp(archive.updatedAt, archive.createdAt);
+		return ts === null ? [] : [{
+			ts,
+			value: archive.tasksCompleted
+		}];
+	});
+	const specMetaById = new Map(specMetas.map((meta) => [meta.id, meta]));
+	const requirementTrendEvents = specifications.flatMap((spec) => {
+		const meta = specMetaById.get(spec.id);
+		const ts = resolveTrendTimestamp(meta?.updatedAt, meta?.createdAt);
+		return ts === null ? [] : [{
+			ts,
+			value: spec.requirements
+		}];
+	});
+	const hasObjectiveSpecificationTrend = specificationTrendEvents.length > 0 || specifications.length === 0;
+	const hasObjectiveRequirementTrend = requirementTrendEvents.length > 0 || requirements === 0;
+	const hasObjectiveCompletedTrend = completedTrendEvents.length > 0 || archiveMetas.length === 0;
+	const config = await ctx.configManager.readConfig();
+	beginDashboardGitTask(reason);
+	let latestCommitTs = null;
+	let git;
+	try {
+		const gitSnapshotPromise = buildDashboardGitSnapshot({ projectDir: ctx.projectDir }).catch(() => ({
+			defaultBranch: "main",
+			worktrees: []
+		}));
+		latestCommitTs = await readLatestCommitTimestamp(ctx.projectDir);
+		git = await gitSnapshotPromise;
+	} catch (error) {
+		endDashboardGitTask(error);
+		throw error;
+	}
+	endDashboardGitTask(null);
+	const cardAvailability = {
+		specifications: hasObjectiveSpecificationTrend ? { state: "ok" } : {
+			state: "invalid",
+			reason: "objective-history-unavailable"
+		},
+		requirements: hasObjectiveRequirementTrend ? { state: "ok" } : {
+			state: "invalid",
+			reason: "objective-history-unavailable"
+		},
+		activeChanges: {
+			state: "invalid",
+			reason: "objective-history-unavailable"
+		},
+		inProgressChanges: {
+			state: "invalid",
+			reason: "objective-history-unavailable"
+		},
+		completedChanges: hasObjectiveCompletedTrend ? { state: "ok" } : {
+			state: "invalid",
+			reason: "objective-history-unavailable"
+		},
+		taskCompletionPercent: {
+			state: "invalid",
+			reason: taskCompletionPercent === null ? "semantic-uncomputable" : "objective-history-unavailable"
+		}
+	};
+	const trendKinds = {
+		specifications: "monotonic",
+		requirements: "monotonic",
+		activeChanges: "bidirectional",
+		inProgressChanges: "bidirectional",
+		completedChanges: "monotonic",
+		taskCompletionPercent: "bidirectional"
+	};
+	const { trends: baselineTrends, trendMeta } = buildDashboardTimeTrends({
+		pointLimit: config.dashboard.trendPointLimit,
+		timestamp: now,
+		rightEdgeTs: latestCommitTs,
+		availability: cardAvailability,
+		events: {
+			specifications: specificationTrendEvents,
+			requirements: requirementTrendEvents,
+			activeChanges: [],
+			inProgressChanges: [],
+			completedChanges: completedTrendEvents,
+			taskCompletionPercent: []
+		},
+		reducers: {
+			specifications: "sum",
+			requirements: "sum",
+			completedChanges: "sum"
+		}
+	});
+	return {
+		summary: {
+			specifications: specifications.length,
+			requirements,
+			activeChanges: activeChanges.length,
+			inProgressChanges,
+			completedChanges: archiveMetas.length,
+			archivedTasksCompleted,
+			tasksTotal,
+			tasksCompleted,
+			taskCompletionPercent
+		},
+		trends: baselineTrends,
+		triColorTrends: createEmptyTriColorTrends(),
+		trendKinds,
+		cardAvailability,
+		trendMeta,
+		specifications,
+		activeChanges,
+		git
+	};
+}
+
+//#endregion
+//#region src/pty-manager.ts
+const DEFAULT_SCROLLBACK = 1e3;
+const DEFAULT_MAX_BUFFER_BYTES = 2 * 1024 * 1024;
+function detectPtyPlatform() {
+	if (process.platform === "win32") return "windows";
+	if (process.platform === "darwin") return "macos";
+	return "common";
+}
+function resolveDefaultShell(platform, env) {
+	if (platform === "windows") return env.ComSpec?.trim() || "cmd.exe";
+	return env.SHELL?.trim() || "/bin/sh";
+}
+function resolvePtyCommand(opts) {
+	const command = opts.command?.trim();
+	if (command) return {
+		command,
+		args: opts.args ?? []
+	};
+	return {
+		command: resolveDefaultShell(opts.platform, opts.env),
+		args: []
+	};
+}
+var PtySession = class extends EventEmitter$1 {
+	id;
+	command;
+	args;
+	platform;
+	closeTip;
+	closeCallbackUrl;
+	createdAt;
+	process;
+	titleInterval = null;
+	lastTitle = "";
+	buffer = [];
+	bufferByteLength = 0;
+	maxBufferLines;
+	maxBufferBytes;
+	isExited = false;
+	exitCode = null;
+	constructor(id, opts) {
+		super();
+		this.id = id;
+		this.createdAt = Date.now();
+		const resolvedCommand = resolvePtyCommand({
+			platform: opts.platform,
+			command: opts.command,
+			args: opts.args,
+			env: process.env
+		});
+		this.command = resolvedCommand.command;
+		this.args = resolvedCommand.args;
+		this.platform = opts.platform;
+		this.closeTip = opts.closeTip;
+		this.closeCallbackUrl = opts.closeCallbackUrl;
+		this.maxBufferLines = opts.scrollback ?? DEFAULT_SCROLLBACK;
+		this.maxBufferBytes = opts.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+		this.process = pty.spawn(this.command, this.args, {
+			name: "xterm-256color",
+			cols: opts.cols ?? 80,
+			rows: opts.rows ?? 24,
+			cwd: opts.cwd,
+			env: {
+				...process.env,
+				TERM: "xterm-256color"
+			}
+		});
+		this.process.onData((data) => {
+			this.appendBuffer(data);
+			this.emit("data", data);
+		});
+		this.process.onExit(({ exitCode }) => {
+			if (this.titleInterval) {
+				clearInterval(this.titleInterval);
+				this.titleInterval = null;
+			}
+			this.isExited = true;
+			this.exitCode = exitCode;
+			this.emit("exit", exitCode);
+		});
+		this.titleInterval = setInterval(() => {
+			try {
+				const title = this.process.process;
+				if (title && title !== this.lastTitle) {
+					this.lastTitle = title;
+					this.emit("title", title);
+				}
+			} catch {}
+		}, 1e3);
+	}
+	get title() {
+		return this.lastTitle;
+	}
+	appendBuffer(data) {
+		let chunk = data;
+		if (chunk.length > this.maxBufferBytes) chunk = chunk.slice(-this.maxBufferBytes);
+		this.buffer.push(chunk);
+		this.bufferByteLength += chunk.length;
+		while (this.bufferByteLength > this.maxBufferBytes && this.buffer.length > 0) {
+			const removed = this.buffer.shift();
+			this.bufferByteLength -= removed.length;
+		}
+		while (this.buffer.length > this.maxBufferLines) {
+			const removed = this.buffer.shift();
+			this.bufferByteLength -= removed.length;
+		}
+	}
+	getBuffer() {
+		return this.buffer.join("");
+	}
+	write(data) {
+		if (!this.isExited) this.process.write(data);
+	}
+	resize(cols, rows) {
+		if (!this.isExited) this.process.resize(cols, rows);
+	}
+	close() {
+		if (this.titleInterval) {
+			clearInterval(this.titleInterval);
+			this.titleInterval = null;
+		}
+		try {
+			this.process.kill();
+		} catch {}
+		this.removeAllListeners();
+	}
+	toInfo() {
+		return {
+			id: this.id,
+			title: this.lastTitle,
+			command: this.command,
+			args: this.args,
+			platform: this.platform,
+			isExited: this.isExited,
+			exitCode: this.exitCode,
+			closeTip: this.closeTip,
+			closeCallbackUrl: this.closeCallbackUrl,
+			createdAt: this.createdAt
+		};
+	}
+};
+var PtyManager = class {
+	sessions = /* @__PURE__ */ new Map();
+	idCounter = 0;
+	platform;
+	constructor(defaultCwd) {
+		this.defaultCwd = defaultCwd;
+		this.platform = detectPtyPlatform();
+	}
+	create(opts) {
+		const id = `pty-${++this.idCounter}`;
+		const session = new PtySession(id, {
+			cols: opts.cols,
+			rows: opts.rows,
+			command: opts.command,
+			args: opts.args,
+			closeTip: opts.closeTip,
+			closeCallbackUrl: opts.closeCallbackUrl,
+			cwd: this.defaultCwd,
+			scrollback: opts.scrollback,
+			maxBufferBytes: opts.maxBufferBytes,
+			platform: this.platform
+		});
+		this.sessions.set(id, session);
+		return session;
+	}
+	get(id) {
+		return this.sessions.get(id);
+	}
+	list() {
+		const result = [];
+		for (const session of this.sessions.values()) result.push(session.toInfo());
+		return result;
+	}
+	write(id, data) {
+		this.sessions.get(id)?.write(data);
+	}
+	resize(id, cols, rows) {
+		this.sessions.get(id)?.resize(cols, rows);
+	}
+	close(id) {
+		const session = this.sessions.get(id);
+		if (session) {
+			session.close();
+			this.sessions.delete(id);
+		}
+	}
+	closeAll() {
+		for (const session of this.sessions.values()) session.close();
+		this.sessions.clear();
+	}
+};
+
+//#endregion
+//#region src/pty-websocket.ts
+function createPtyWebSocketHandler(ptyManager) {
+	return (ws) => {
+		const cleanups = /* @__PURE__ */ new Map();
+		const send = (msg) => {
+			if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(msg));
+		};
+		const sendError = (code, message, opts) => {
+			send({
+				type: "error",
+				code,
+				message,
+				sessionId: opts?.sessionId
+			});
+		};
+		const attachToSession = (session, opts) => {
+			const sessionId = session.id;
+			cleanups.get(sessionId)?.();
+			if (opts?.cols && opts?.rows && !session.isExited) session.resize(opts.cols, opts.rows);
+			const onData = (data) => {
+				send({
+					type: "output",
+					sessionId,
+					data
+				});
+			};
+			const onExit = (exitCode) => {
+				send({
+					type: "exit",
+					sessionId,
+					exitCode
+				});
+			};
+			const onTitle = (title) => {
+				send({
+					type: "title",
+					sessionId,
+					title
+				});
+			};
+			session.on("data", onData);
+			session.on("exit", onExit);
+			session.on("title", onTitle);
+			cleanups.set(sessionId, () => {
+				session.removeListener("data", onData);
+				session.removeListener("exit", onExit);
+				session.removeListener("title", onTitle);
+				cleanups.delete(sessionId);
+			});
+		};
+		ws.on("message", (raw) => {
+			let parsed;
+			try {
+				parsed = JSON.parse(String(raw));
+			} catch {
+				sendError("INVALID_JSON", "Invalid JSON payload");
+				return;
+			}
+			const parsedMessage = PtyClientMessageSchema.safeParse(parsed);
+			if (!parsedMessage.success) {
+				const firstIssue = parsedMessage.error.issues[0]?.message;
+				sendError("INVALID_MESSAGE", firstIssue ?? "Invalid PTY message");
+				return;
+			}
+			const msg = parsedMessage.data;
+			switch (msg.type) {
+				case "create":
+					try {
+						const createMessage = msg;
+						const session = ptyManager.create({
+							cols: msg.cols,
+							rows: msg.rows,
+							command: msg.command,
+							args: msg.args,
+							closeTip: createMessage.closeTip,
+							closeCallbackUrl: createMessage.closeCallbackUrl
+						});
+						send({
+							type: "created",
+							requestId: msg.requestId,
+							sessionId: session.id,
+							platform: session.platform
+						});
+						attachToSession(session);
+					} catch (err) {
+						sendError("PTY_CREATE_FAILED", err instanceof Error ? err.message : String(err), { sessionId: msg.requestId });
+					}
+					break;
+				case "attach": {
+					const session = ptyManager.get(msg.sessionId);
+					if (!session) {
+						sendError("SESSION_NOT_FOUND", `Session not found: ${msg.sessionId}`, { sessionId: msg.sessionId });
+						send({
+							type: "exit",
+							sessionId: msg.sessionId,
+							exitCode: -1
+						});
+						break;
+					}
+					attachToSession(session, {
+						cols: msg.cols,
+						rows: msg.rows
+					});
+					const buffer = session.getBuffer();
+					if (buffer) send({
+						type: "buffer",
+						sessionId: session.id,
+						data: buffer
+					});
+					if (session.title) send({
+						type: "title",
+						sessionId: session.id,
+						title: session.title
+					});
+					if (session.isExited) send({
+						type: "exit",
+						sessionId: session.id,
+						exitCode: session.exitCode ?? -1
+					});
+					break;
+				}
+				case "list":
+					send({
+						type: "list",
+						sessions: ptyManager.list().map((s) => ({
+							id: s.id,
+							title: s.title,
+							command: s.command,
+							args: s.args,
+							platform: s.platform,
+							isExited: s.isExited,
+							exitCode: s.exitCode,
+							closeTip: s.closeTip,
+							closeCallbackUrl: s.closeCallbackUrl
+						}))
+					});
+					break;
+				case "input": {
+					const session = ptyManager.get(msg.sessionId);
+					if (!session) {
+						sendError("SESSION_NOT_FOUND", `Session not found: ${msg.sessionId}`, { sessionId: msg.sessionId });
+						break;
+					}
+					session.write(msg.data);
+					break;
+				}
+				case "resize": {
+					const session = ptyManager.get(msg.sessionId);
+					if (!session) {
+						sendError("SESSION_NOT_FOUND", `Session not found: ${msg.sessionId}`, { sessionId: msg.sessionId });
+						break;
+					}
+					session.resize(msg.cols, msg.rows);
+					break;
+				}
+				case "close": {
+					const session = ptyManager.get(msg.sessionId);
+					if (!session) {
+						sendError("SESSION_NOT_FOUND", `Session not found: ${msg.sessionId}`, { sessionId: msg.sessionId });
+						break;
+					}
+					cleanups.get(msg.sessionId)?.();
+					ptyManager.close(session.id);
+					break;
+				}
+			}
+		});
+		ws.on("close", () => {
+			for (const cleanup of cleanups.values()) cleanup();
+			cleanups.clear();
+		});
+	};
+}
+
+//#endregion
+//#region src/cli-stream-observable.ts
+/**
+* 创建安全的 CLI 流式 observable
+*
+* 解决的问题：
+* 1. 防止在 emit.complete() 之后调用 emit.next()（会导致 "Controller is already closed" 错误）
+* 2. 统一的错误处理，防止未捕获的异常导致服务器崩溃
+* 3. 确保取消时正确清理资源
+*
+* @param startStream 启动流的函数，接收 onEvent 回调，返回取消函数的 Promise
+*/
+function createCliStreamObservable(startStream) {
+	return observable((emit) => {
+		let cancel;
+		let completed = false;
+		/**
+		* 安全的事件处理器
+		* - 检查是否已完成，防止重复调用
+		* - 使用 try-catch 防止异常导致服务器崩溃
+		*/
+		const safeEventHandler = (event) => {
+			if (completed) return;
+			try {
+				emit.next(event);
+				if (event.type === "exit") {
+					completed = true;
+					emit.complete();
+				}
+			} catch (err) {
+				console.error("[CLI Stream] Error emitting event:", err);
+				if (!completed) {
+					completed = true;
+					try {
+						emit.error(err instanceof Error ? err : new Error(String(err)));
+					} catch {}
+				}
+			}
 		};
-		if (reducer === "sum-cumulative") {
-			cumulative += sums[index];
-			return {
-				ts,
-				value: cumulative
-			};
-		}
-		if (counts[index] > 0) carry = sums[index] / counts[index];
-		return {
-			ts,
-			value: carry
+		startStream(safeEventHandler).then((cancelFn) => {
+			cancel = cancelFn;
+		}).catch((err) => {
+			console.error("[CLI Stream] Error starting stream:", err);
+			if (!completed) {
+				completed = true;
+				try {
+					emit.error(err instanceof Error ? err : new Error(String(err)));
+				} catch {}
+			}
+		});
+		return () => {
+			completed = true;
+			cancel?.();
 		};
 	});
 }
-function buildDashboardTimeTrends(options) {
-	const pointLimit = clampPointLimit(options.pointLimit);
-	const trends = createEmptyTrendSeries();
-	for (const metric of DASHBOARD_METRIC_KEYS) {
-		if (options.availability[metric].state !== "ok") continue;
-		trends[metric] = bucketizeTrend(normalizeEvents(options.events[metric], pointLimit), options.reducers?.[metric] ?? "sum", options.rightEdgeTs);
-	}
-	return {
-		trends,
-		trendMeta: {
-			pointLimit,
-			lastUpdatedAt: options.timestamp
-		}
-	};
-}
 
 //#endregion
 //#region src/reactive-kv.ts
@@ -855,7 +1223,7 @@ function buildDashboardTimeTrends(options) {
 */
 var ReactiveKV = class {
 	store = /* @__PURE__ */ new Map();
-	emitter = new EventEmitter$1();
+	emitter = new EventEmitter();
 	constructor() {
 		this.emitter.setMaxListeners(200);
 	}
@@ -918,135 +1286,57 @@ const reactiveKV = new ReactiveKV();
 * })
 * ```
 */
-function createReactiveSubscription(task) {
-	return observable((emit) => {
-		const context = new ReactiveContext();
-		const controller = new AbortController();
-		(async () => {
-			try {
-				for await (const data of context.stream(task, controller.signal)) emit.next(data);
-			} catch (err) {
-				if (!controller.signal.aborted) emit.error(err);
-			}
-		})();
-		return () => {
-			controller.abort();
-		};
-	});
-}
-/**
-* 创建带输入参数的响应式订阅
-*
-* @param task 接收输入参数的异步任务
-* @returns 返回一个函数，接收输入参数并返回 tRPC observable
-*
-* @example
-* ```typescript
-* // 在 router 中使用
-* subscribeOne: publicProcedure
-*   .input(z.object({ id: z.string() }))
-*   .subscription(({ ctx, input }) => {
-*     return createReactiveSubscriptionWithInput(
-*       (id: string) => ctx.adapter.readSpec(id)
-*     )(input.id)
-*   })
-* ```
-*/
-function createReactiveSubscriptionWithInput(task) {
-	return (input) => {
-		return createReactiveSubscription(() => task(input));
-	};
-}
-
-//#endregion
-//#region src/router.ts
-const t = initTRPC.context().create();
-const router = t.router;
-const publicProcedure = t.procedure;
-const execFileAsync = promisify(execFile);
-const OPSX_CORE_PROFILE_WORKFLOWS = [
-	"propose",
-	"explore",
-	"apply",
-	"archive"
-];
-const dashboardGitTaskStatusEmitter = new EventEmitter$1();
-dashboardGitTaskStatusEmitter.setMaxListeners(200);
-const dashboardGitTaskStatus = {
-	running: false,
-	inFlight: 0,
-	lastStartedAt: null,
-	lastFinishedAt: null,
-	lastReason: null,
-	lastError: null
-};
-function getDashboardGitTaskStatus() {
-	return { ...dashboardGitTaskStatus };
-}
-function emitDashboardGitTaskStatus() {
-	dashboardGitTaskStatusEmitter.emit("change", getDashboardGitTaskStatus());
-}
-function beginDashboardGitTask(reason) {
-	dashboardGitTaskStatus.inFlight += 1;
-	dashboardGitTaskStatus.running = true;
-	dashboardGitTaskStatus.lastStartedAt = Date.now();
-	dashboardGitTaskStatus.lastReason = reason;
-	dashboardGitTaskStatus.lastError = null;
-	emitDashboardGitTaskStatus();
-}
-function endDashboardGitTask(error) {
-	dashboardGitTaskStatus.inFlight = Math.max(0, dashboardGitTaskStatus.inFlight - 1);
-	dashboardGitTaskStatus.running = dashboardGitTaskStatus.inFlight > 0;
-	dashboardGitTaskStatus.lastFinishedAt = Date.now();
-	if (error) dashboardGitTaskStatus.lastError = error instanceof Error ? error.message : String(error);
-	emitDashboardGitTaskStatus();
-}
-const DASHBOARD_GIT_REFRESH_STAMP_NAME = "openspecui-dashboard-git-refresh.stamp";
-async function resolveGitMetadataDir(projectDir) {
-	try {
-		const { stdout } = await execFileAsync("git", ["rev-parse", "--git-dir"], {
-			cwd: projectDir,
-			maxBuffer: 1024 * 1024,
-			encoding: "utf8"
-		});
-		const gitDirRaw = stdout.trim();
-		if (!gitDirRaw) return null;
-		const gitDirPath = resolve(projectDir, gitDirRaw);
-		if (!(await stat(gitDirPath)).isDirectory()) return null;
-		return gitDirPath;
-	} catch {
-		return null;
-	}
-}
-async function resolveGitMetadataDirReactive(projectDir) {
-	const gitMetadataDir = await resolveGitMetadataDir(projectDir);
-	if (!gitMetadataDir) return null;
-	await reactiveReadDir(gitMetadataDir, { includeHidden: true });
-	return gitMetadataDir;
-}
-function getDashboardGitRefreshStampPath(gitMetadataDir) {
-	return join(gitMetadataDir, DASHBOARD_GIT_REFRESH_STAMP_NAME);
-}
-async function touchDashboardGitRefreshStamp(projectDir, reason) {
-	const gitMetadataDir = await resolveGitMetadataDir(projectDir);
-	if (!gitMetadataDir) return { skipped: true };
-	const stampPath = getDashboardGitRefreshStampPath(gitMetadataDir);
-	await mkdir(dirname(stampPath), { recursive: true });
-	await writeFile(stampPath, `${Date.now()} ${reason}\n`, "utf8");
-	return { skipped: false };
-}
-async function registerDashboardGitReactiveDeps(projectDir) {
-	await reactiveReadDir(projectDir, {
-		includeHidden: true,
-		exclude: ["node_modules"]
+function createReactiveSubscription(task) {
+	return observable((emit) => {
+		const context = new ReactiveContext();
+		const controller = new AbortController();
+		(async () => {
+			try {
+				for await (const data of context.stream(task, controller.signal)) emit.next(data);
+			} catch (err) {
+				if (!controller.signal.aborted) emit.error(err);
+			}
+		})();
+		return () => {
+			controller.abort();
+		};
 	});
-	const gitMetadataDir = await resolveGitMetadataDirReactive(projectDir);
-	if (!gitMetadataDir) return;
-	await reactiveReadFile(getDashboardGitRefreshStampPath(gitMetadataDir));
-	await reactiveReadFile(join(gitMetadataDir, "HEAD"));
-	await reactiveReadFile(join(gitMetadataDir, "index"));
-	await reactiveReadFile(join(gitMetadataDir, "packed-refs"));
 }
+/**
+* 创建带输入参数的响应式订阅
+*
+* @param task 接收输入参数的异步任务
+* @returns 返回一个函数，接收输入参数并返回 tRPC observable
+*
+* @example
+* ```typescript
+* // 在 router 中使用
+* subscribeOne: publicProcedure
+*   .input(z.object({ id: z.string() }))
+*   .subscription(({ ctx, input }) => {
+*     return createReactiveSubscriptionWithInput(
+*       (id: string) => ctx.adapter.readSpec(id)
+*     )(input.id)
+*   })
+* ```
+*/
+function createReactiveSubscriptionWithInput(task) {
+	return (input) => {
+		return createReactiveSubscription(() => task(input));
+	};
+}
+
+//#endregion
+//#region src/router.ts
+const t = initTRPC.context().create();
+const router = t.router;
+const publicProcedure = t.procedure;
+const OPSX_CORE_PROFILE_WORKFLOWS = [
+	"propose",
+	"explore",
+	"apply",
+	"archive"
+];
 function requireChangeId(changeId) {
 	if (!changeId) throw new Error("change is required");
 	return changeId;
@@ -1216,200 +1506,6 @@ function buildSystemStatus(ctx) {
 		watcherLastReinitializeReason: runtime?.lastReinitializeReason ?? null
 	};
 }
-function resolveTrendTimestamp(primary, secondary) {
-	if (typeof primary === "number" && Number.isFinite(primary) && primary > 0) return primary;
-	if (typeof secondary === "number" && Number.isFinite(secondary) && secondary > 0) return secondary;
-	return null;
-}
-function parseDatedIdTimestamp(id) {
-	const match = /^(\d{4})-(\d{2})-(\d{2})(?:-|$)/.exec(id);
-	if (!match) return null;
-	const year = Number(match[1]);
-	const month = Number(match[2]);
-	const day = Number(match[3]);
-	if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day)) return null;
-	if (month < 1 || month > 12) return null;
-	if (day < 1 || day > 31) return null;
-	const ts = Date.UTC(year, month - 1, day);
-	return Number.isFinite(ts) ? ts : null;
-}
-function createEmptyTriColorTrends() {
-	return Object.fromEntries(DASHBOARD_METRIC_KEYS.map((metric) => [metric, []]));
-}
-async function readLatestCommitTimestamp(projectDir) {
-	try {
-		const { stdout } = await execFileAsync("git", [
-			"log",
-			"-1",
-			"--format=%ct"
-		], {
-			cwd: projectDir,
-			maxBuffer: 1024 * 1024,
-			encoding: "utf8"
-		});
-		const seconds = Number(stdout.trim());
-		return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : null;
-	} catch {
-		return null;
-	}
-}
-async function fetchDashboardOverview(ctx, reason = "dashboard-refresh") {
-	if (contextStorage.getStore()) await registerDashboardGitReactiveDeps(ctx.projectDir);
-	const now = Date.now();
-	const [specMetas, changeMetas, archiveMetas] = await Promise.all([
-		ctx.adapter.listSpecsWithMeta(),
-		ctx.adapter.listChangesWithMeta(),
-		ctx.adapter.listArchivedChangesWithMeta()
-	]);
-	const activeChanges = changeMetas.map((changeMeta) => ({
-		id: changeMeta.id,
-		name: changeMeta.name ?? changeMeta.id,
-		progress: changeMeta.progress,
-		updatedAt: changeMeta.updatedAt
-	})).sort((a, b) => b.updatedAt - a.updatedAt);
-	const archivedChanges = (await Promise.all(archiveMetas.map(async (meta) => {
-		const change = await ctx.adapter.readArchivedChange(meta.id);
-		if (!change) return null;
-		return {
-			id: meta.id,
-			createdAt: meta.createdAt,
-			updatedAt: meta.updatedAt,
-			tasksCompleted: change.tasks.filter((task) => task.completed).length
-		};
-	}))).filter((item) => item !== null);
-	const specifications = (await Promise.all(specMetas.map(async (meta) => {
-		const spec = await ctx.adapter.readSpec(meta.id);
-		if (!spec) return null;
-		return {
-			id: meta.id,
-			name: meta.name,
-			requirements: spec.requirements.length,
-			updatedAt: meta.updatedAt
-		};
-	}))).filter((item) => item !== null).sort((a, b) => b.requirements - a.requirements || b.updatedAt - a.updatedAt);
-	const requirements = specifications.reduce((sum, spec) => sum + spec.requirements, 0);
-	const tasksTotal = activeChanges.reduce((sum, change) => sum + change.progress.total, 0);
-	const tasksCompleted = activeChanges.reduce((sum, change) => sum + change.progress.completed, 0);
-	const archivedTasksCompleted = archivedChanges.reduce((sum, change) => sum + change.tasksCompleted, 0);
-	const taskCompletionPercent = tasksTotal > 0 ? Math.round(tasksCompleted / tasksTotal * 100) : null;
-	const inProgressChanges = activeChanges.filter((change) => change.progress.total > 0 && change.progress.completed < change.progress.total).length;
-	const specificationTrendEvents = specMetas.flatMap((spec) => {
-		const ts = resolveTrendTimestamp(spec.createdAt, spec.updatedAt);
-		return ts === null ? [] : [{
-			ts,
-			value: 1
-		}];
-	});
-	const completedTrendEvents = archivedChanges.flatMap((archive) => {
-		const ts = parseDatedIdTimestamp(archive.id) ?? resolveTrendTimestamp(archive.updatedAt, archive.createdAt);
-		return ts === null ? [] : [{
-			ts,
-			value: archive.tasksCompleted
-		}];
-	});
-	const specMetaById = new Map(specMetas.map((meta) => [meta.id, meta]));
-	const requirementTrendEvents = specifications.flatMap((spec) => {
-		const meta = specMetaById.get(spec.id);
-		const ts = resolveTrendTimestamp(meta?.updatedAt, meta?.createdAt);
-		return ts === null ? [] : [{
-			ts,
-			value: spec.requirements
-		}];
-	});
-	const hasObjectiveSpecificationTrend = specificationTrendEvents.length > 0 || specifications.length === 0;
-	const hasObjectiveRequirementTrend = requirementTrendEvents.length > 0 || requirements === 0;
-	const hasObjectiveCompletedTrend = completedTrendEvents.length > 0 || archiveMetas.length === 0;
-	const config = await ctx.configManager.readConfig();
-	beginDashboardGitTask(reason);
-	let latestCommitTs = null;
-	let git;
-	try {
-		const gitSnapshotPromise = buildDashboardGitSnapshot({ projectDir: ctx.projectDir }).catch(() => ({
-			defaultBranch: "main",
-			worktrees: []
-		}));
-		latestCommitTs = await readLatestCommitTimestamp(ctx.projectDir);
-		git = await gitSnapshotPromise;
-	} catch (error) {
-		endDashboardGitTask(error);
-		throw error;
-	}
-	endDashboardGitTask(null);
-	const cardAvailability = {
-		specifications: hasObjectiveSpecificationTrend ? { state: "ok" } : {
-			state: "invalid",
-			reason: "objective-history-unavailable"
-		},
-		requirements: hasObjectiveRequirementTrend ? { state: "ok" } : {
-			state: "invalid",
-			reason: "objective-history-unavailable"
-		},
-		activeChanges: {
-			state: "invalid",
-			reason: "objective-history-unavailable"
-		},
-		inProgressChanges: {
-			state: "invalid",
-			reason: "objective-history-unavailable"
-		},
-		completedChanges: hasObjectiveCompletedTrend ? { state: "ok" } : {
-			state: "invalid",
-			reason: "objective-history-unavailable"
-		},
-		taskCompletionPercent: {
-			state: "invalid",
-			reason: taskCompletionPercent === null ? "semantic-uncomputable" : "objective-history-unavailable"
-		}
-	};
-	const trendKinds = {
-		specifications: "monotonic",
-		requirements: "monotonic",
-		activeChanges: "bidirectional",
-		inProgressChanges: "bidirectional",
-		completedChanges: "monotonic",
-		taskCompletionPercent: "bidirectional"
-	};
-	const { trends: baselineTrends, trendMeta } = buildDashboardTimeTrends({
-		pointLimit: config.dashboard.trendPointLimit,
-		timestamp: now,
-		rightEdgeTs: latestCommitTs,
-		availability: cardAvailability,
-		events: {
-			specifications: specificationTrendEvents,
-			requirements: requirementTrendEvents,
-			activeChanges: [],
-			inProgressChanges: [],
-			completedChanges: completedTrendEvents,
-			taskCompletionPercent: []
-		},
-		reducers: {
-			specifications: "sum",
-			requirements: "sum",
-			completedChanges: "sum"
-		}
-	});
-	return {
-		summary: {
-			specifications: specifications.length,
-			requirements,
-			activeChanges: activeChanges.length,
-			inProgressChanges,
-			completedChanges: archiveMetas.length,
-			archivedTasksCompleted,
-			tasksTotal,
-			tasksCompleted,
-			taskCompletionPercent
-		},
-		trends: baselineTrends,
-		triColorTrends: createEmptyTriColorTrends(),
-		trendKinds,
-		cardAvailability,
-		trendMeta,
-		specifications,
-		activeChanges,
-		git
-	};
-}
 /**
 * Spec router - spec CRUD operations
 */
@@ -2111,30 +2207,52 @@ const systemRouter = router({
 */
 const dashboardRouter = router({
 	get: publicProcedure.query(async ({ ctx }) => {
-		return fetchDashboardOverview(ctx, "dashboard.get");
+		return ctx.dashboardOverviewService.getCurrent();
 	}),
 	subscribe: publicProcedure.subscription(({ ctx }) => {
-		return createReactiveSubscription(async () => {
-			return fetchDashboardOverview(ctx, "dashboard.subscribe");
+		return observable((emit) => {
+			const unsubscribe = ctx.dashboardOverviewService.subscribe((overview) => {
+				emit.next(overview);
+			}, {
+				emitCurrent: true,
+				onError: (error) => {
+					emit.error(error);
+				}
+			});
+			return () => {
+				unsubscribe();
+			};
 		});
 	}),
 	refreshGitSnapshot: publicProcedure.input(z.object({ reason: z.string().optional() }).optional()).mutation(async ({ ctx, input }) => {
 		const reason = input?.reason?.trim() || "manual-refresh";
 		await touchDashboardGitRefreshStamp(ctx.projectDir, reason);
+		await ctx.dashboardOverviewService.refresh(reason);
+		return { success: true };
+	}),
+	removeDetachedWorktree: publicProcedure.input(z.object({ path: z.string().min(1) })).mutation(async ({ ctx, input }) => {
+		await ctx.dashboardOverviewService.getCurrent();
+		await removeDetachedDashboardGitWorktree({
+			projectDir: ctx.projectDir,
+			targetPath: input.path
+		});
+		await touchDashboardGitRefreshStamp(ctx.projectDir, "remove-detached-worktree");
+		await ctx.dashboardOverviewService.refresh("remove-detached-worktree");
 		return { success: true };
 	}),
-	gitTaskStatus: publicProcedure.query(() => {
+	gitTaskStatus: publicProcedure.query(async ({ ctx }) => {
+		await ctx.dashboardOverviewService.getCurrent();
 		return getDashboardGitTaskStatus();
 	}),
-	subscribeGitTaskStatus: publicProcedure.subscription(() => {
+	subscribeGitTaskStatus: publicProcedure.subscription(({ ctx }) => {
 		return observable((emit) => {
+			ctx.dashboardOverviewService.getCurrent().catch(() => {});
 			emit.next(getDashboardGitTaskStatus());
-			const handler = (status) => {
+			const unsubscribe = subscribeDashboardGitTaskStatus((status) => {
 				emit.next(status);
-			};
-			dashboardGitTaskStatusEmitter.on("change", handler);
+			});
 			return () => {
-				dashboardGitTaskStatusEmitter.off("change", handler);
+				unsubscribe();
 			};
 		});
 	})
@@ -2325,6 +2443,11 @@ function createServer(config) {
 	const kernel = config.kernel;
 	const watcher = config.enableWatcher !== false ? new OpenSpecWatcher(config.projectDir) : void 0;
 	const searchService = new SearchService(adapter, watcher);
+	const dashboardOverviewService = new DashboardOverviewService((reason) => loadDashboardOverview({
+		adapter,
+		configManager,
+		projectDir: config.projectDir
+	}, reason), watcher);
 	const app = new Hono();
 	const corsOrigins = config.corsOrigins ?? ["http://localhost:5173", "http://localhost:3000"];
 	app.use("*", cors({
@@ -2351,6 +2474,7 @@ function createServer(config) {
 				cliExecutor,
 				kernel,
 				searchService,
+				dashboardOverviewService,
 				watcher,
 				projectDir: config.projectDir
 			})
@@ -2362,6 +2486,7 @@ function createServer(config) {
 		cliExecutor,
 		kernel,
 		searchService,
+		dashboardOverviewService,
 		watcher,
 		projectDir: config.projectDir
 	});
@@ -2372,6 +2497,7 @@ function createServer(config) {
 		cliExecutor,
 		kernel,
 		searchService,
+		dashboardOverviewService,
 		watcher,
 		createContext,
 		port: config.port ?? 3100
@@ -2419,6 +2545,7 @@ async function createWebSocketServer(server, httpServer, config) {
 			wss.close();
 			server.watcher?.stop();
 			server.searchService.dispose().catch(() => {});
+			server.dashboardOverviewService.dispose();
 		}
 	};
 }
@@ -2454,6 +2581,9 @@ async function startServer(config, setupApp) {
 	server.searchService.init().catch((err) => {
 		console.error("Search service warmup failed:", err);
 	});
+	server.dashboardOverviewService.init().catch((err) => {
+		console.error("Dashboard overview warmup failed:", err);
+	});
 	return {
 		url,
 		port,