@openspecui/core 1.1.2 → 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenSpecUI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -1022,53 +1022,6 @@ declare function clearCache(path?: string): void;
  */
 declare function getCacheSize(): number;
 //#endregion
-//#region src/reactive-fs/watcher-pool.d.ts
-/**
- * 初始化 watcher pool
- *
- * 必须在使用 acquireWatcher 之前调用。
- * 通常由 server 在启动时调用。
- *
- * @param projectDir 项目根目录
- */
-declare function initWatcherPool(projectDir: string): Promise<void>;
-/**
- * 获取或创建文件/目录监听器
- *
- * 特性：
- * - 使用 @parcel/watcher 监听项目根目录
- * - 自动处理新创建的目录（解决 init 后无法监听的问题）
- * - 同一路径共享订阅
- * - 引用计数管理生命周期
- * - 内置防抖机制
- *
- * @param path 要监听的路径
- * @param onChange 变更回调
- * @param options 监听选项
- * @returns 释放函数，调用后取消订阅
- */
-declare function acquireWatcher(path: string, onChange: () => void, options?: {
-  recursive?: boolean;
-  debounceMs?: number;
-  onError?: () => void;
-}): () => void;
-/**
- * 获取当前活跃的监听器数量（用于调试）
- */
-declare function getActiveWatcherCount(): number;
-/**
- * 关闭所有监听器（用于测试清理）
- */
-declare function closeAllWatchers(): Promise<void>;
-/**
- * 检查 watcher pool 是否已初始化
- */
-declare function isWatcherPoolInitialized(): boolean;
-/**
- * 获取当前监听的项目目录
- */
-declare function getWatchedProjectDir(): string | null;
-//#endregion
 //#region src/reactive-fs/project-watcher.d.ts
 /**
  * 事件类型
@@ -1085,6 +1038,15 @@ interface WatchEvent {
  * 路径订阅回调
  */
 type PathCallback = (events: WatchEvent[]) => void;
+/** watcher 重建原因 */
+type ProjectWatcherReinitializeReason = 'drop-events' | 'watcher-error' | 'missing-project-dir' | 'project-dir-replaced' | 'manual';
+/** watcher 运行时状态（用于调试和运维观测） */
+interface ProjectWatcherRuntimeStatus {
+  generation: number;
+  reinitializeCount: number;
+  lastReinitializeReason: ProjectWatcherReinitializeReason | null;
+  reinitializeReasonCounts: Readonly<Record<ProjectWatcherReinitializeReason, number>>;
+}
 /**
  * 项目监听器
  *
@@ -1107,17 +1069,18 @@ declare class ProjectWatcher {
   private ignore;
   private initialized;
   private initPromise;
-  private healthCheckTimer;
-  private lastEventTime;
-  private healthCheckPending;
-  private enableHealthCheck;
   private reinitializeTimer;
   private reinitializePending;
+  private reinitializeReasonPending;
+  private pathLivenessTimer;
+  private projectDirFingerprint;
+  private generation;
+  private reinitializeCount;
+  private lastReinitializeReason;
+  private reinitializeReasonCounts;
   constructor(projectDir: string, options?: {
     debounceMs?: number;
     ignore?: string[];
-    /** 是否启用健康检查（默认 true） */
-    enableHealthCheck?: boolean;
   });
   /**
    * 初始化 watcher
@@ -1127,13 +1090,30 @@ declare class ProjectWatcher {
   private doInit;
   /**
    * 处理 watcher 错误
-   * 对于 FSEvents dropped 错误，触发延迟重建
+   * 统一走错误驱动重建流程
    */
   private handleWatcherError;
   /**
    * 延迟重建 watcher（防抖，避免频繁重建）
    */
   private scheduleReinitialize;
+  /**
+   * 读取项目目录指纹（目录不存在时返回 null）
+   * 用于检测 path 对应实体是否被替换（inode/dev 漂移）
+   */
+  private getProjectDirFingerprint;
+  /**
+   * 启动路径语义监测（避免 watcher 绑定到已失效句柄）
+   */
+  private startPathLivenessMonitor;
+  /**
+   * 停止路径语义监测
+   */
+  private stopPathLivenessMonitor;
+  /**
+   * 只读检查 projectDir 是否仍指向初始化时的目录实体
+   */
+  private checkPathLiveness;
   /**
    * 处理原始事件
    */
@@ -1180,26 +1160,13 @@ declare class ProjectWatcher {
    */
   get isInitialized(): boolean;
   /**
-   * 启动健康检查定时器
+   * 获取 watcher 运行时状态
    */
-  private startHealthCheck;
+  get runtimeStatus(): ProjectWatcherRuntimeStatus;
   /**
-   * 停止健康检查定时器
+   * 记录重建统计
    */
-  private stopHealthCheck;
-  /**
-   * 执行健康检查
-   *
-   * 工作流程：
-   * 1. 如果最近有事件，无需检查
-   * 2. 如果上次探测还在等待中，说明 watcher 可能失效，尝试重建
-   * 3. 否则，创建临时文件触发事件，等待下次检查验证
-   */
-  private performHealthCheck;
-  /**
-   * 发送探测：通过 utimesSync 修改项目目录的时间戳来触发 watcher 事件
-   */
-  private sendProbe;
+  private markReinitialized;
   /**
    * 重新初始化 watcher
    */
@@ -1222,6 +1189,63 @@ declare function getProjectWatcher(projectDir: string, options?: ConstructorPara
  */
 declare function closeAllProjectWatchers(): Promise<void>;
 //#endregion
+//#region src/reactive-fs/watcher-pool.d.ts
+/** watcher 运行时状态（供 server 订阅） */
+interface WatcherRuntimeStatus extends ProjectWatcherRuntimeStatus {
+  projectDir: string | null;
+  initialized: boolean;
+  subscriptionCount: number;
+}
+/**
+ * 初始化 watcher pool
+ *
+ * 必须在使用 acquireWatcher 之前调用。
+ * 通常由 server 在启动时调用。
+ *
+ * @param projectDir 项目根目录
+ */
+declare function initWatcherPool(projectDir: string): Promise<void>;
+/**
+ * 获取或创建文件/目录监听器
+ *
+ * 特性：
+ * - 使用 @parcel/watcher 监听项目根目录
+ * - 自动处理新创建的目录（解决 init 后无法监听的问题）
+ * - 同一路径共享订阅
+ * - 引用计数管理生命周期
+ * - 内置防抖机制
+ *
+ * @param path 要监听的路径
+ * @param onChange 变更回调
+ * @param options 监听选项
+ * @returns 释放函数，调用后取消订阅
+ */
+declare function acquireWatcher(path: string, onChange: () => void, options?: {
+  recursive?: boolean;
+  debounceMs?: number;
+  onError?: () => void;
+}): () => void;
+/**
+ * 获取当前活跃的监听器数量（用于调试）
+ */
+declare function getActiveWatcherCount(): number;
+/**
+ * 关闭所有监听器（用于测试清理）
+ */
+declare function closeAllWatchers(): Promise<void>;
+/**
+ * 检查 watcher pool 是否已初始化
+ */
+declare function isWatcherPoolInitialized(): boolean;
+/**
+ * 获取当前监听的项目目录
+ */
+declare function getWatchedProjectDir(): string | null;
+/**
+ * 获取 watcher 运行时状态
+ */
+declare function getWatcherRuntimeStatus(): WatcherRuntimeStatus | null;
+//#endregion
 //#region src/watcher.d.ts
 /**
  * File change event types
@@ -1284,6 +1308,9 @@ declare function createFileChangeObservable(watcher: OpenSpecWatcher): {
 };
 //#endregion
 //#region src/config.d.ts
+declare const TerminalRendererEngineSchema: z.ZodEnum<["xterm", "ghostty"]>;
+type TerminalRendererEngine = z.infer<typeof TerminalRendererEngineSchema>;
+declare function isTerminalRendererEngine(value: string): value is TerminalRendererEngine;
 type RunnerId = 'configured' | 'openspec' | 'npx' | 'bunx' | 'deno' | 'pnpm' | 'yarn';
 interface CliRunnerCandidate {
   id: RunnerId;
@@ -1355,20 +1382,31 @@ declare const TerminalConfigSchema: z.ZodObject<{
   cursorBlink: z.ZodDefault<z.ZodBoolean>;
   cursorStyle: z.ZodDefault<z.ZodEnum<["block", "underline", "bar"]>>;
   scrollback: z.ZodDefault<z.ZodNumber>;
+  rendererEngine: z.ZodDefault<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
   fontSize: number;
   fontFamily: string;
   cursorBlink: boolean;
   cursorStyle: "block" | "underline" | "bar";
   scrollback: number;
+  rendererEngine: string;
 }, {
   fontSize?: number | undefined;
   fontFamily?: string | undefined;
   cursorBlink?: boolean | undefined;
   cursorStyle?: "block" | "underline" | "bar" | undefined;
   scrollback?: number | undefined;
+  rendererEngine?: string | undefined;
 }>;
 type TerminalConfig = z.infer<typeof TerminalConfigSchema>;
+declare const DashboardConfigSchema: z.ZodObject<{
+  trendPointLimit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+  trendPointLimit: number;
+}, {
+  trendPointLimit?: number | undefined;
+}>;
+type DashboardConfig = z.infer<typeof DashboardConfigSchema>;
 /**
  * OpenSpecUI 配置 Schema
  *
@@ -1397,18 +1435,29 @@ declare const OpenSpecUIConfigSchema: z.ZodObject<{
     cursorBlink: z.ZodDefault<z.ZodBoolean>;
     cursorStyle: z.ZodDefault<z.ZodEnum<["block", "underline", "bar"]>>;
     scrollback: z.ZodDefault<z.ZodNumber>;
+    rendererEngine: z.ZodDefault<z.ZodString>;
   }, "strip", z.ZodTypeAny, {
     fontSize: number;
     fontFamily: string;
     cursorBlink: boolean;
     cursorStyle: "block" | "underline" | "bar";
     scrollback: number;
+    rendererEngine: string;
   }, {
     fontSize?: number | undefined;
     fontFamily?: string | undefined;
     cursorBlink?: boolean | undefined;
     cursorStyle?: "block" | "underline" | "bar" | undefined;
     scrollback?: number | undefined;
+    rendererEngine?: string | undefined;
+  }>>;
+  /** Dashboard 配置 */
+  dashboard: z.ZodDefault<z.ZodObject<{
+    trendPointLimit: z.ZodDefault<z.ZodNumber>;
+  }, "strip", z.ZodTypeAny, {
+    trendPointLimit: number;
+  }, {
+    trendPointLimit?: number | undefined;
   }>>;
 }, "strip", z.ZodTypeAny, {
   cli: {
@@ -1422,6 +1471,10 @@ declare const OpenSpecUIConfigSchema: z.ZodObject<{
     cursorBlink: boolean;
     cursorStyle: "block" | "underline" | "bar";
     scrollback: number;
+    rendererEngine: string;
+  };
+  dashboard: {
+    trendPointLimit: number;
   };
 }, {
   cli?: {
@@ -1435,6 +1488,10 @@ declare const OpenSpecUIConfigSchema: z.ZodObject<{
     cursorBlink?: boolean | undefined;
     cursorStyle?: "block" | "underline" | "bar" | undefined;
     scrollback?: number | undefined;
+    rendererEngine?: string | undefined;
+  } | undefined;
+  dashboard?: {
+    trendPointLimit?: number | undefined;
   } | undefined;
 }>;
 type OpenSpecUIConfig = z.infer<typeof OpenSpecUIConfigSchema>;
@@ -1445,6 +1502,7 @@ type OpenSpecUIConfigUpdate = {
   };
   theme?: OpenSpecUIConfig['theme'];
   terminal?: Partial<TerminalConfig>;
+  dashboard?: Partial<DashboardConfig>;
 };
 /** 默认配置（静态，用于测试和类型） */
 declare const DEFAULT_CONFIG: OpenSpecUIConfig;
@@ -1663,6 +1721,99 @@ declare function getConfiguredTools(projectDir: string): Promise<string[]>;
  */
 declare function isToolConfigured(projectDir: string, toolId: string): Promise<boolean>;
 //#endregion
+//#region src/dashboard-types.d.ts
+declare const DASHBOARD_METRIC_KEYS: readonly ["specifications", "requirements", "activeChanges", "inProgressChanges", "completedChanges", "taskCompletionPercent"];
+type DashboardMetricKey = (typeof DASHBOARD_METRIC_KEYS)[number];
+interface DashboardTrendPoint {
+  ts: number;
+  value: number;
+}
+interface DashboardTriColorTrendPoint {
+  ts: number;
+  add: number;
+  modify: number;
+  delete: number;
+}
+type DashboardTrendKind = 'monotonic' | 'bidirectional';
+interface DashboardTrendMeta {
+  pointLimit: number;
+  lastUpdatedAt: number;
+}
+type DashboardCardAvailability = {
+  state: 'ok';
+} | {
+  state: 'invalid';
+  reason: 'semantic-uncomputable' | 'objective-history-unavailable';
+};
+interface DashboardSummary {
+  specifications: number;
+  requirements: number;
+  activeChanges: number;
+  inProgressChanges: number;
+  completedChanges: number;
+  archivedTasksCompleted: number;
+  tasksTotal: number;
+  tasksCompleted: number;
+  taskCompletionPercent: number | null;
+}
+interface DashboardGitDiffStats {
+  files: number;
+  insertions: number;
+  deletions: number;
+}
+interface DashboardGitCommitEntry {
+  type: 'commit';
+  hash: string;
+  title: string;
+  relatedChanges: string[];
+  diff: DashboardGitDiffStats;
+}
+interface DashboardGitUncommittedEntry {
+  type: 'uncommitted';
+  title: string;
+  relatedChanges: string[];
+  diff: DashboardGitDiffStats;
+}
+type DashboardGitEntry = DashboardGitCommitEntry | DashboardGitUncommittedEntry;
+interface DashboardGitWorktree {
+  path: string;
+  relativePath: string;
+  branchName: string;
+  isCurrent: boolean;
+  ahead: number;
+  behind: number;
+  diff: DashboardGitDiffStats;
+  entries: DashboardGitEntry[];
+}
+interface DashboardGitSnapshot {
+  defaultBranch: string;
+  worktrees: DashboardGitWorktree[];
+}
+interface DashboardOverview {
+  summary: DashboardSummary;
+  trends: Record<DashboardMetricKey, DashboardTrendPoint[]>;
+  triColorTrends: Record<DashboardMetricKey, DashboardTriColorTrendPoint[]>;
+  trendKinds: Record<DashboardMetricKey, DashboardTrendKind>;
+  cardAvailability: Record<DashboardMetricKey, DashboardCardAvailability>;
+  trendMeta: DashboardTrendMeta;
+  specifications: Array<{
+    id: string;
+    name: string;
+    requirements: number;
+    updatedAt: number;
+  }>;
+  activeChanges: Array<{
+    id: string;
+    name: string;
+    progress: {
+      total: number;
+      completed: number;
+    };
+    updatedAt: number;
+  }>;
+  git: DashboardGitSnapshot;
+}
+//#endregion
 //#region src/opsx-types.d.ts
 /** Check if an outputPath contains glob pattern characters */
 declare function isGlobPattern(pattern: string): boolean;
@@ -2067,6 +2218,8 @@ interface ExportSnapshot {
     changesCount: number;
     archivesCount: number;
   };
+  /** OpenSpecUI runtime config captured during export */
+  config?: OpenSpecUIConfig;
   /** All specs with parsed content */
   specs: Array<{
     id: string;
@@ -2251,6 +2404,8 @@ declare const PtySessionInfoSchema: z.ZodObject<{
   platform: z.ZodEnum<["windows", "macos", "common"]>;
   isExited: z.ZodBoolean;
   exitCode: z.ZodNullable<z.ZodNumber>;
+  closeTip: z.ZodOptional<z.ZodString>;
+  closeCallbackUrl: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
 }, "strip", z.ZodTypeAny, {
   command: string;
   args: string[];
@@ -2259,6 +2414,8 @@ declare const PtySessionInfoSchema: z.ZodObject<{
   title: string;
   id: string;
   isExited: boolean;
+  closeTip?: string | undefined;
+  closeCallbackUrl?: string | Record<string, string> | undefined;
 }, {
   command: string;
   args: string[];
@@ -2267,6 +2424,8 @@ declare const PtySessionInfoSchema: z.ZodObject<{
   title: string;
   id: string;
   isExited: boolean;
+  closeTip?: string | undefined;
+  closeCallbackUrl?: string | Record<string, string> | undefined;
 }>;
 declare const PtyCreateMessageSchema: z.ZodObject<{
   type: z.ZodLiteral<"create">;
@@ -2275,6 +2434,8 @@ declare const PtyCreateMessageSchema: z.ZodObject<{
   rows: z.ZodOptional<z.ZodNumber>;
   command: z.ZodOptional<z.ZodString>;
   args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+  closeTip: z.ZodOptional<z.ZodString>;
+  closeCallbackUrl: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
 }, "strip", z.ZodTypeAny, {
   type: "create";
   requestId: string;
@@ -2282,6 +2443,8 @@ declare const PtyCreateMessageSchema: z.ZodObject<{
   rows?: number | undefined;
   command?: string | undefined;
   args?: string[] | undefined;
+  closeTip?: string | undefined;
+  closeCallbackUrl?: string | Record<string, string> | undefined;
 }, {
   type: "create";
   requestId: string;
@@ -2289,6 +2452,8 @@ declare const PtyCreateMessageSchema: z.ZodObject<{
   rows?: number | undefined;
   command?: string | undefined;
   args?: string[] | undefined;
+  closeTip?: string | undefined;
+  closeCallbackUrl?: string | Record<string, string> | undefined;
 }>;
 declare const PtyInputMessageSchema: z.ZodObject<{
   type: z.ZodLiteral<"input">;
@@ -2359,6 +2524,8 @@ declare const PtyClientMessageSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObje
   rows: z.ZodOptional<z.ZodNumber>;
   command: z.ZodOptional<z.ZodString>;
   args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+  closeTip: z.ZodOptional<z.ZodString>;
+  closeCallbackUrl: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
 }, "strip", z.ZodTypeAny, {
   type: "create";
   requestId: string;
@@ -2366,6 +2533,8 @@ declare const PtyClientMessageSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObje
   rows?: number | undefined;
   command?: string | undefined;
   args?: string[] | undefined;
+  closeTip?: string | undefined;
+  closeCallbackUrl?: string | Record<string, string> | undefined;
 }, {
   type: "create";
   requestId: string;
@@ -2373,6 +2542,8 @@ declare const PtyClientMessageSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObje
   rows?: number | undefined;
   command?: string | undefined;
   args?: string[] | undefined;
+  closeTip?: string | undefined;
+  closeCallbackUrl?: string | Record<string, string> | undefined;
 }>, z.ZodObject<{
   type: z.ZodLiteral<"input">;
   sessionId: z.ZodString;
@@ -2509,6 +2680,8 @@ declare const PtyListResponseSchema: z.ZodObject<{
     platform: z.ZodEnum<["windows", "macos", "common"]>;
     isExited: z.ZodBoolean;
     exitCode: z.ZodNullable<z.ZodNumber>;
+    closeTip: z.ZodOptional<z.ZodString>;
+    closeCallbackUrl: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
   }, "strip", z.ZodTypeAny, {
     command: string;
     args: string[];
@@ -2517,6 +2690,8 @@ declare const PtyListResponseSchema: z.ZodObject<{
     title: string;
     id: string;
     isExited: boolean;
+    closeTip?: string | undefined;
+    closeCallbackUrl?: string | Record<string, string> | undefined;
   }, {
     command: string;
     args: string[];
@@ -2525,6 +2700,8 @@ declare const PtyListResponseSchema: z.ZodObject<{
     title: string;
     id: string;
     isExited: boolean;
+    closeTip?: string | undefined;
+    closeCallbackUrl?: string | Record<string, string> | undefined;
   }>, "many">;
 }, "strip", z.ZodTypeAny, {
   type: "list";
@@ -2536,6 +2713,8 @@ declare const PtyListResponseSchema: z.ZodObject<{
     title: string;
     id: string;
     isExited: boolean;
+    closeTip?: string | undefined;
+    closeCallbackUrl?: string | Record<string, string> | undefined;
   }[];
 }, {
   type: "list";
@@ -2547,6 +2726,8 @@ declare const PtyListResponseSchema: z.ZodObject<{
     title: string;
     id: string;
     isExited: boolean;
+    closeTip?: string | undefined;
+    closeCallbackUrl?: string | Record<string, string> | undefined;
   }[];
 }>;
 declare const PtyErrorCodeSchema: z.ZodEnum<["INVALID_JSON", "INVALID_MESSAGE", "SESSION_NOT_FOUND", "PTY_CREATE_FAILED"]>;
@@ -2639,6 +2820,8 @@ declare const PtyServerMessageSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObje
     platform: z.ZodEnum<["windows", "macos", "common"]>;
     isExited: z.ZodBoolean;
     exitCode: z.ZodNullable<z.ZodNumber>;
+    closeTip: z.ZodOptional<z.ZodString>;
+    closeCallbackUrl: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
   }, "strip", z.ZodTypeAny, {
     command: string;
     args: string[];
@@ -2647,6 +2830,8 @@ declare const PtyServerMessageSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObje
     title: string;
     id: string;
     isExited: boolean;
+    closeTip?: string | undefined;
+    closeCallbackUrl?: string | Record<string, string> | undefined;
   }, {
     command: string;
     args: string[];
@@ -2655,6 +2840,8 @@ declare const PtyServerMessageSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObje
     title: string;
     id: string;
     isExited: boolean;
+    closeTip?: string | undefined;
+    closeCallbackUrl?: string | Record<string, string> | undefined;
   }>, "many">;
 }, "strip", z.ZodTypeAny, {
   type: "list";
@@ -2666,6 +2853,8 @@ declare const PtyServerMessageSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObje
     title: string;
     id: string;
     isExited: boolean;
+    closeTip?: string | undefined;
+    closeCallbackUrl?: string | Record<string, string> | undefined;
   }[];
 }, {
   type: "list";
@@ -2677,6 +2866,8 @@ declare const PtyServerMessageSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObje
     title: string;
     id: string;
     isExited: boolean;
+    closeTip?: string | undefined;
+    closeCallbackUrl?: string | Record<string, string> | undefined;
   }[];
 }>, z.ZodObject<{
   type: z.ZodLiteral<"error">;
@@ -2699,4 +2890,4 @@ type PtyServerMessage = z.infer<typeof PtyServerMessageSchema>;
 type PtySessionInfo = z.infer<typeof PtySessionInfoSchema>;
 type PtyPlatform = z.infer<typeof PtyPlatformSchema>;
 //#endregion
-export { type AIToolOption, AI_TOOLS, type ApplyInstructions, ApplyInstructionsSchema, type ApplyTask, ApplyTaskSchema, type ArchiveMeta, type ArtifactInstructions, ArtifactInstructionsSchema, type ArtifactStatus, ArtifactStatusSchema, type Change, type ChangeFile, ChangeFileSchema, type ChangeMeta, ChangeSchema, type ChangeStatus, ChangeStatusSchema, CliExecutor, type CliResult, type CliRunnerAttempt, type CliSniffResult, type CliStreamEvent, ConfigManager, DEFAULT_CONFIG, type Delta, type DeltaOperation, DeltaOperationType, DeltaSchema, type DeltaSpec, DeltaSpecSchema, type DependencyInfo, DependencyInfoSchema, type ExportSnapshot, type FileChangeEvent, type FileChangeType, MarkdownParser, OpenSpecAdapter, type OpenSpecUIConfig, OpenSpecUIConfigSchema, type OpenSpecUIConfigUpdate, OpenSpecWatcher, OpsxKernel, type PathCallback, ProjectWatcher, PtyAttachMessageSchema, PtyBufferResponseSchema, type PtyClientMessage, PtyClientMessageSchema, PtyCloseMessageSchema, PtyCreateMessageSchema, PtyCreatedResponseSchema, PtyErrorCodeSchema, PtyErrorResponseSchema, PtyExitResponseSchema, PtyInputMessageSchema, PtyListMessageSchema, PtyListResponseSchema, PtyOutputResponseSchema, type PtyPlatform, PtyPlatformSchema, PtyResizeMessageSchema, type PtyServerMessage, PtyServerMessageSchema, type PtySessionInfo, PtyTitleResponseSchema, ReactiveContext, ReactiveState, type ReactiveStateOptions, type Requirement, RequirementSchema, type ResolvedCliRunner, type SchemaArtifact, SchemaArtifactSchema, type SchemaDetail, SchemaDetailSchema, type SchemaInfo, SchemaInfoSchema, type SchemaResolution, SchemaResolutionSchema, type Spec, type SpecMeta, SpecSchema, type Task, TaskSchema, type TemplateContentMap, type TemplatesMap, TemplatesSchema, type TerminalConfig, TerminalConfigSchema, type ToolConfig, type ValidationIssue, type ValidationResult, Validator, type WatchEvent, type WatchEventType, acquireWatcher, buildCliRunnerCandidates, clearCache, closeAllProjectWatchers, closeAllWatchers, contextStorage, createCleanCliEnv, createFileChangeObservable, getActiveWatcherCount, getAllToolIds, getAllTools, getAvailableToolIds, getAvailableTools, getCacheSize, getConfiguredTools, getDefaultCliCommand, getDefaultCliCommandString, getProjectWatcher, getToolById, getWatchedProjectDir, initWatcherPool, isGlobPattern, isToolConfigured, isWatcherPoolInitialized, parseCliCommand, reactiveExists, reactiveReadDir, reactiveReadFile, reactiveStat, sniffGlobalCli };
+export { type AIToolOption, AI_TOOLS, type ApplyInstructions, ApplyInstructionsSchema, type ApplyTask, ApplyTaskSchema, type ArchiveMeta, type ArtifactInstructions, ArtifactInstructionsSchema, type ArtifactStatus, ArtifactStatusSchema, type Change, type ChangeFile, ChangeFileSchema, type ChangeMeta, ChangeSchema, type ChangeStatus, ChangeStatusSchema, CliExecutor, type CliResult, type CliRunnerAttempt, type CliSniffResult, type CliStreamEvent, ConfigManager, DASHBOARD_METRIC_KEYS, DEFAULT_CONFIG, type DashboardCardAvailability, type DashboardConfig, DashboardConfigSchema, type DashboardGitCommitEntry, type DashboardGitDiffStats, type DashboardGitEntry, type DashboardGitSnapshot, type DashboardGitUncommittedEntry, type DashboardGitWorktree, type DashboardMetricKey, type DashboardOverview, type DashboardSummary, type DashboardTrendKind, type DashboardTrendMeta, type DashboardTrendPoint, type DashboardTriColorTrendPoint, type Delta, type DeltaOperation, DeltaOperationType, DeltaSchema, type DeltaSpec, DeltaSpecSchema, type DependencyInfo, DependencyInfoSchema, type ExportSnapshot, type FileChangeEvent, type FileChangeType, MarkdownParser, OpenSpecAdapter, type OpenSpecUIConfig, OpenSpecUIConfigSchema, type OpenSpecUIConfigUpdate, OpenSpecWatcher, OpsxKernel, type PathCallback, ProjectWatcher, type ProjectWatcherReinitializeReason, type ProjectWatcherRuntimeStatus, PtyAttachMessageSchema, PtyBufferResponseSchema, type PtyClientMessage, PtyClientMessageSchema, PtyCloseMessageSchema, PtyCreateMessageSchema, PtyCreatedResponseSchema, PtyErrorCodeSchema, PtyErrorResponseSchema, PtyExitResponseSchema, PtyInputMessageSchema, PtyListMessageSchema, PtyListResponseSchema, PtyOutputResponseSchema, type PtyPlatform, PtyPlatformSchema, PtyResizeMessageSchema, type PtyServerMessage, PtyServerMessageSchema, type PtySessionInfo, PtyTitleResponseSchema, ReactiveContext, ReactiveState, type ReactiveStateOptions, type Requirement, RequirementSchema, type ResolvedCliRunner, type SchemaArtifact, SchemaArtifactSchema, type SchemaDetail, SchemaDetailSchema, type SchemaInfo, SchemaInfoSchema, type SchemaResolution, SchemaResolutionSchema, type Spec, type SpecMeta, SpecSchema, type Task, TaskSchema, type TemplateContentMap, type TemplatesMap, TemplatesSchema, type TerminalConfig, TerminalConfigSchema, type TerminalRendererEngine, TerminalRendererEngineSchema, type ToolConfig, type ValidationIssue, type ValidationResult, Validator, type WatchEvent, type WatchEventType, type WatcherRuntimeStatus, acquireWatcher, buildCliRunnerCandidates, clearCache, closeAllProjectWatchers, closeAllWatchers, contextStorage, createCleanCliEnv, createFileChangeObservable, getActiveWatcherCount, getAllToolIds, getAllTools, getAvailableToolIds, getAvailableTools, getCacheSize, getConfiguredTools, getDefaultCliCommand, getDefaultCliCommandString, getProjectWatcher, getToolById, getWatchedProjectDir, getWatcherRuntimeStatus, initWatcherPool, isGlobPattern, isTerminalRendererEngine, isToolConfigured, isWatcherPoolInitialized, parseCliCommand, reactiveExists, reactiveReadDir, reactiveReadFile, reactiveStat, sniffGlobalCli };

package/dist/index.mjs

@@ -3,10 +3,10 @@ import { dirname, join } from "path";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { readFile as readFile$1, readdir, stat } from "node:fs/promises";
 import { dirname as dirname$1, join as join$1, matchesGlob, relative, resolve, sep } from "node:path";
-import { existsSync, realpathSync, utimesSync } from "node:fs";
+import { existsSync, lstatSync, realpathSync } from "node:fs";
 import { z } from "zod";
-import { watch } from "fs";
 import { EventEmitter } from "events";
+import { watch } from "fs";
 import { exec, spawn } from "child_process";
 import { promisify } from "util";
 import { parse } from "yaml";
@@ -220,14 +220,14 @@ var MarkdownParser = class {
 			if (currentOperation === "RENAMED") {
 				const fromMatch = line.match(/FROM:\s*`?###\s*Requirement:\s*(.+?)`?$/i);
 				const toMatch = line.match(/TO:\s*`?###\s*Requirement:\s*(.+?)`?$/i);
-				if (fromMatch) renameBuffer = {
-					...renameBuffer ?? {},
-					from: fromMatch[1].trim()
-				};
-				if (toMatch) renameBuffer = {
-					...renameBuffer ?? {},
-					to: toMatch[1].trim()
-				};
+				if (fromMatch) {
+					if (!renameBuffer) renameBuffer = {};
+					renameBuffer.from = fromMatch[1].trim();
+				}
+				if (toMatch) {
+					if (!renameBuffer) renameBuffer = {};
+					renameBuffer.to = toMatch[1].trim();
+				}
 				if (renameBuffer?.from && renameBuffer?.to) {
 					deltas.push({
 						spec: deltaSpec.specId,
@@ -312,86 +312,6 @@ var MarkdownParser = class {
 	}
 };
 
-//#endregion
-//#region src/validator.ts
-/**
-* Validator for OpenSpec documents
-*/
-var Validator = class {
-	/**
-	* Validate a spec document
-	*/
-	validateSpec(spec) {
-		const issues = [];
-		if (!spec.overview || spec.overview.trim().length === 0) issues.push({
-			severity: "ERROR",
-			message: "Spec must have a Purpose/Overview section",
-			path: "overview"
-		});
-		if (spec.requirements.length === 0) issues.push({
-			severity: "ERROR",
-			message: "Spec must have at least one requirement",
-			path: "requirements"
-		});
-		for (const req of spec.requirements) {
-			if (!req.text.includes("SHALL") && !req.text.includes("MUST")) issues.push({
-				severity: "WARNING",
-				message: `Requirement should contain "SHALL" or "MUST": ${req.id}`,
-				path: `requirements.${req.id}`
-			});
-			if (req.scenarios.length === 0) issues.push({
-				severity: "WARNING",
-				message: `Requirement should have at least one scenario: ${req.id}`,
-				path: `requirements.${req.id}.scenarios`
-			});
-			if (req.text.length > 1e3) issues.push({
-				severity: "WARNING",
-				message: `Requirement text is too long (max 1000 chars): ${req.id}`,
-				path: `requirements.${req.id}.text`
-			});
-		}
-		return {
-			valid: issues.filter((i) => i.severity === "ERROR").length === 0,
-			issues
-		};
-	}
-	/**
-	* Validate a change proposal
-	*/
-	validateChange(change) {
-		const issues = [];
-		if (!change.why || change.why.length < 50) issues.push({
-			severity: "ERROR",
-			message: "Change \"Why\" section must be at least 50 characters",
-			path: "why"
-		});
-		if (change.why && change.why.length > 500) issues.push({
-			severity: "WARNING",
-			message: "Change \"Why\" section should be under 500 characters",
-			path: "why"
-		});
-		if (!change.whatChanges || change.whatChanges.trim().length === 0) issues.push({
-			severity: "ERROR",
-			message: "Change must have a \"What Changes\" section",
-			path: "whatChanges"
-		});
-		if (change.deltas.length === 0) issues.push({
-			severity: "WARNING",
-			message: "Change should have at least one delta",
-			path: "deltas"
-		});
-		if (change.deltas.length > 50) issues.push({
-			severity: "WARNING",
-			message: "Change has too many deltas (max 50)",
-			path: "deltas"
-		});
-		return {
-			valid: issues.filter((i) => i.severity === "ERROR").length === 0,
-			issues
-		};
-	}
-};
-
 //#endregion
 //#region src/reactive-fs/reactive-state.ts
 /**
@@ -578,8 +498,10 @@ const DEFAULT_IGNORE = [
 	".git",
 	"**/.DS_Store"
 ];
-/** 健康检查间隔 (ms) - 3秒 */
-const HEALTH_CHECK_INTERVAL_MS = 3e3;
+/** 恢复重试间隔 (ms) */
+const RECOVERY_INTERVAL_MS = 3e3;
+/** 路径语义检查间隔 (ms) */
+const PATH_LIVENESS_INTERVAL_MS = 3e3;
 /**
 * 项目监听器
 *
@@ -602,17 +524,25 @@ var ProjectWatcher = class {
 	ignore;
 	initialized = false;
 	initPromise = null;
-	healthCheckTimer = null;
-	lastEventTime = 0;
-	healthCheckPending = false;
-	enableHealthCheck;
 	reinitializeTimer = null;
 	reinitializePending = false;
+	reinitializeReasonPending = null;
+	pathLivenessTimer = null;
+	projectDirFingerprint = null;
+	generation = 0;
+	reinitializeCount = 0;
+	lastReinitializeReason = null;
+	reinitializeReasonCounts = {
+		"drop-events": 0,
+		"watcher-error": 0,
+		"missing-project-dir": 0,
+		"project-dir-replaced": 0,
+		manual: 0
+	};
 	constructor(projectDir, options = {}) {
 		this.projectDir = getRealPath$1(projectDir);
 		this.debounceMs = options.debounceMs ?? DEBOUNCE_MS$1;
 		this.ignore = options.ignore ?? DEFAULT_IGNORE;
-		this.enableHealthCheck = options.enableHealthCheck ?? true;
 	}
 	/**
 	* 初始化 watcher
@@ -621,8 +551,11 @@ var ProjectWatcher = class {
 	async init() {
 		if (this.initialized) return;
 		if (this.initPromise) return this.initPromise;
-		this.initPromise = this.doInit();
-		await this.initPromise;
+		this.initPromise = this.doInit().catch((error) => {
+			this.initPromise = null;
+			throw error;
+		});
+		return this.initPromise;
 	}
 	async doInit() {
 		this.subscription = await (await import("@parcel/watcher")).subscribe(this.projectDir, (err, events) => {
@@ -633,43 +566,98 @@ var ProjectWatcher = class {
 			this.handleEvents(events);
 		}, { ignore: this.ignore });
 		this.initialized = true;
-		this.lastEventTime = Date.now();
-		if (this.enableHealthCheck) this.startHealthCheck();
+		this.generation += 1;
+		this.projectDirFingerprint = this.getProjectDirFingerprint();
+		this.startPathLivenessMonitor();
 	}
 	/**
 	* 处理 watcher 错误
-	* 对于 FSEvents dropped 错误，触发延迟重建
+	* 统一走错误驱动重建流程
 	*/
 	handleWatcherError(err) {
 		if ((err.message || String(err)).includes("Events were dropped")) {
 			if (!this.reinitializePending) {
 				console.warn("[ProjectWatcher] FSEvents dropped events, scheduling reinitialize...");
-				this.scheduleReinitialize();
+				this.scheduleReinitialize("drop-events");
 			}
 			return;
 		}
-		console.error("[ProjectWatcher] Error:", err);
+		console.error("[ProjectWatcher] Watcher error, scheduling reinitialize:", err);
+		this.scheduleReinitialize("watcher-error");
 	}
 	/**
 	* 延迟重建 watcher（防抖，避免频繁重建）
 	*/
-	scheduleReinitialize() {
+	scheduleReinitialize(reason) {
+		this.reinitializeReasonPending = reason;
 		if (this.reinitializePending) return;
 		this.reinitializePending = true;
 		if (this.reinitializeTimer) clearTimeout(this.reinitializeTimer);
 		this.reinitializeTimer = setTimeout(() => {
 			this.reinitializeTimer = null;
 			this.reinitializePending = false;
-			console.log("[ProjectWatcher] Reinitializing due to FSEvents error...");
-			this.reinitialize();
-		}, 1e3);
+			const pendingReason = this.reinitializeReasonPending ?? reason;
+			this.reinitializeReasonPending = null;
+			console.log(`[ProjectWatcher] Reinitializing (reason: ${pendingReason})...`);
+			this.reinitialize(pendingReason);
+		}, RECOVERY_INTERVAL_MS);
+		this.reinitializeTimer.unref();
+	}
+	/**
+	* 读取项目目录指纹（目录不存在时返回 null）
+	* 用于检测 path 对应实体是否被替换（inode/dev 漂移）
+	*/
+	getProjectDirFingerprint() {
+		try {
+			const stat$1 = lstatSync(this.projectDir);
+			return `${stat$1.dev}:${stat$1.ino}`;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* 启动路径语义监测（避免 watcher 绑定到已失效句柄）
+	*/
+	startPathLivenessMonitor() {
+		this.stopPathLivenessMonitor();
+		this.pathLivenessTimer = setInterval(() => {
+			this.checkPathLiveness();
+		}, PATH_LIVENESS_INTERVAL_MS);
+		this.pathLivenessTimer.unref();
+	}
+	/**
+	* 停止路径语义监测
+	*/
+	stopPathLivenessMonitor() {
+		if (this.pathLivenessTimer) {
+			clearInterval(this.pathLivenessTimer);
+			this.pathLivenessTimer = null;
+		}
+	}
+	/**
+	* 只读检查 projectDir 是否仍指向初始化时的目录实体
+	*/
+	checkPathLiveness() {
+		if (!this.initialized || this.reinitializePending) return;
+		const current = this.getProjectDirFingerprint();
+		if (current === null) {
+			console.warn("[ProjectWatcher] Project directory missing, scheduling reinitialize...");
+			this.scheduleReinitialize("missing-project-dir");
+			return;
+		}
+		if (this.projectDirFingerprint === null) {
+			this.projectDirFingerprint = current;
+			return;
+		}
+		if (current !== this.projectDirFingerprint) {
+			console.warn("[ProjectWatcher] Project directory replaced, scheduling reinitialize...");
+			this.scheduleReinitialize("project-dir-replaced");
+		}
 	}
 	/**
 	* 处理原始事件
 	*/
 	handleEvents(events) {
-		this.lastEventTime = Date.now();
-		this.healthCheckPending = false;
 		const watchEvents = events.map((e) => ({
 			type: e.type,
 			path: e.path
@@ -757,60 +745,29 @@ var ProjectWatcher = class {
 		return this.initialized;
 	}
 	/**
-	* 启动健康检查定时器
-	*/
-	startHealthCheck() {
-		this.stopHealthCheck();
-		this.healthCheckTimer = setInterval(() => {
-			this.performHealthCheck();
-		}, HEALTH_CHECK_INTERVAL_MS);
-		this.healthCheckTimer.unref();
-	}
-	/**
-	* 停止健康检查定时器
+	* 获取 watcher 运行时状态
 	*/
-	stopHealthCheck() {
-		if (this.healthCheckTimer) {
-			clearInterval(this.healthCheckTimer);
-			this.healthCheckTimer = null;
-		}
-		this.healthCheckPending = false;
-	}
-	/**
-	* 执行健康检查
-	*
-	* 工作流程：
-	* 1. 如果最近有事件，无需检查
-	* 2. 如果上次探测还在等待中，说明 watcher 可能失效，尝试重建
-	* 3. 否则，创建临时文件触发事件，等待下次检查验证
-	*/
-	async performHealthCheck() {
-		if (Date.now() - this.lastEventTime < HEALTH_CHECK_INTERVAL_MS) {
-			this.healthCheckPending = false;
-			return;
-		}
-		if (this.healthCheckPending) {
-			console.warn("[ProjectWatcher] Health check failed, watcher appears stale. Reinitializing...");
-			await this.reinitialize();
-			return;
-		}
-		this.healthCheckPending = true;
-		this.sendProbe();
+	get runtimeStatus() {
+		return {
+			generation: this.generation,
+			reinitializeCount: this.reinitializeCount,
+			lastReinitializeReason: this.lastReinitializeReason,
+			reinitializeReasonCounts: { ...this.reinitializeReasonCounts }
+		};
 	}
 	/**
-	* 发送探测：通过 utimesSync 修改项目目录的时间戳来触发 watcher 事件
+	* 记录重建统计
 	*/
-	sendProbe() {
-		try {
-			const now = /* @__PURE__ */ new Date();
-			utimesSync(this.projectDir, now, now);
-		} catch {}
+	markReinitialized(reason) {
+		this.reinitializeCount += 1;
+		this.lastReinitializeReason = reason;
+		this.reinitializeReasonCounts[reason] += 1;
 	}
 	/**
 	* 重新初始化 watcher
 	*/
-	async reinitialize() {
-		this.stopHealthCheck();
+	async reinitialize(reason) {
+		this.stopPathLivenessMonitor();
 		if (this.subscription) {
 			try {
 				await this.subscription.unsubscribe();
@@ -819,38 +776,50 @@ var ProjectWatcher = class {
 		}
 		this.initialized = false;
 		this.initPromise = null;
-		this.healthCheckPending = false;
+		this.projectDirFingerprint = null;
 		if (!existsSync(this.projectDir)) {
 			console.warn("[ProjectWatcher] Project directory does not exist, waiting for it to be created...");
-			this.waitForProjectDir();
+			this.waitForProjectDir("missing-project-dir");
 			return;
 		}
 		try {
 			await this.init();
+			this.markReinitialized(reason);
 			console.log("[ProjectWatcher] Reinitialized successfully");
 		} catch (err) {
 			console.error("[ProjectWatcher] Failed to reinitialize:", err);
-			setTimeout(() => this.reinitialize(), HEALTH_CHECK_INTERVAL_MS);
+			this.scheduleReinitialize(reason);
 		}
 	}
 	/**
 	* 等待项目目录被创建
 	*/
-	waitForProjectDir() {
-		const checkInterval = setInterval(() => {
-			if (existsSync(this.projectDir)) {
-				clearInterval(checkInterval);
-				console.log("[ProjectWatcher] Project directory created, reinitializing...");
-				this.reinitialize();
+	waitForProjectDir(reason) {
+		this.reinitializeReasonPending = reason;
+		this.reinitializePending = true;
+		if (this.reinitializeTimer) {
+			clearTimeout(this.reinitializeTimer);
+			this.reinitializeTimer = null;
+		}
+		this.reinitializeTimer = setTimeout(() => {
+			this.reinitializeTimer = null;
+			this.reinitializePending = false;
+			if (!existsSync(this.projectDir)) {
+				this.waitForProjectDir(reason);
+				return;
 			}
-		}, HEALTH_CHECK_INTERVAL_MS);
-		checkInterval.unref();
+			const pendingReason = this.reinitializeReasonPending ?? reason;
+			this.reinitializeReasonPending = null;
+			console.log("[ProjectWatcher] Project directory created, reinitializing...");
+			this.reinitialize(pendingReason);
+		}, RECOVERY_INTERVAL_MS);
+		this.reinitializeTimer.unref();
 	}
 	/**
 	* 关闭 watcher
 	*/
 	async close() {
-		this.stopHealthCheck();
+		this.stopPathLivenessMonitor();
 		if (this.debounceTimer) {
 			clearTimeout(this.debounceTimer);
 			this.debounceTimer = null;
@@ -860,6 +829,7 @@ var ProjectWatcher = class {
 			this.reinitializeTimer = null;
 		}
 		this.reinitializePending = false;
+		this.reinitializeReasonPending = null;
 		if (this.subscription) {
 			await this.subscription.unsubscribe();
 			this.subscription = null;
@@ -868,6 +838,7 @@ var ProjectWatcher = class {
 		this.pendingEvents = [];
 		this.initialized = false;
 		this.initPromise = null;
+		this.projectDirFingerprint = null;
 	}
 };
 /**
@@ -1032,6 +1003,22 @@ function isWatcherPoolInitialized() {
 function getWatchedProjectDir() {
 	return globalProjectDir;
 }
+/**
+* 获取 watcher 运行时状态
+*/
+function getWatcherRuntimeStatus() {
+	if (!globalProjectWatcher) return null;
+	const runtime = globalProjectWatcher.runtimeStatus;
+	return {
+		projectDir: globalProjectDir,
+		initialized: globalProjectWatcher.isInitialized,
+		subscriptionCount: globalProjectWatcher.subscriptionCount,
+		generation: runtime.generation,
+		reinitializeCount: runtime.reinitializeCount,
+		lastReinitializeReason: runtime.lastReinitializeReason,
+		reinitializeReasonCounts: runtime.reinitializeReasonCounts
+	};
+}
 
 //#endregion
 //#region src/reactive-fs/reactive-fs.ts
@@ -1229,6 +1216,86 @@ function getCacheSize() {
 	return stateCache$1.size;
 }
 
+//#endregion
+//#region src/validator.ts
+/**
+* Validator for OpenSpec documents
+*/
+var Validator = class {
+	/**
+	* Validate a spec document
+	*/
+	validateSpec(spec) {
+		const issues = [];
+		if (!spec.overview || spec.overview.trim().length === 0) issues.push({
+			severity: "ERROR",
+			message: "Spec must have a Purpose/Overview section",
+			path: "overview"
+		});
+		if (spec.requirements.length === 0) issues.push({
+			severity: "ERROR",
+			message: "Spec must have at least one requirement",
+			path: "requirements"
+		});
+		for (const req of spec.requirements) {
+			if (!req.text.includes("SHALL") && !req.text.includes("MUST")) issues.push({
+				severity: "WARNING",
+				message: `Requirement should contain "SHALL" or "MUST": ${req.id}`,
+				path: `requirements.${req.id}`
+			});
+			if (req.scenarios.length === 0) issues.push({
+				severity: "WARNING",
+				message: `Requirement should have at least one scenario: ${req.id}`,
+				path: `requirements.${req.id}.scenarios`
+			});
+			if (req.text.length > 1e3) issues.push({
+				severity: "WARNING",
+				message: `Requirement text is too long (max 1000 chars): ${req.id}`,
+				path: `requirements.${req.id}.text`
+			});
+		}
+		return {
+			valid: issues.filter((i) => i.severity === "ERROR").length === 0,
+			issues
+		};
+	}
+	/**
+	* Validate a change proposal
+	*/
+	validateChange(change) {
+		const issues = [];
+		if (!change.why || change.why.length < 50) issues.push({
+			severity: "ERROR",
+			message: "Change \"Why\" section must be at least 50 characters",
+			path: "why"
+		});
+		if (change.why && change.why.length > 500) issues.push({
+			severity: "WARNING",
+			message: "Change \"Why\" section should be under 500 characters",
+			path: "why"
+		});
+		if (!change.whatChanges || change.whatChanges.trim().length === 0) issues.push({
+			severity: "ERROR",
+			message: "Change must have a \"What Changes\" section",
+			path: "whatChanges"
+		});
+		if (change.deltas.length === 0) issues.push({
+			severity: "WARNING",
+			message: "Change should have at least one delta",
+			path: "deltas"
+		});
+		if (change.deltas.length > 50) issues.push({
+			severity: "WARNING",
+			message: "Change has too many deltas (max 50)",
+			path: "deltas"
+		});
+		return {
+			valid: issues.filter((i) => i.severity === "ERROR").length === 0,
+			issues
+		};
+	}
+};
+
 //#endregion
 //#region src/adapter.ts
 /**
@@ -1890,6 +1957,11 @@ const CURSOR_STYLE_VALUES = [
 	"underline",
 	"bar"
 ];
+const TERMINAL_RENDERER_ENGINE_VALUES = ["xterm", "ghostty"];
+const TerminalRendererEngineSchema = z.enum(TERMINAL_RENDERER_ENGINE_VALUES);
+function isTerminalRendererEngine(value) {
+	return TERMINAL_RENDERER_ENGINE_VALUES.includes(value);
+}
 const BASE_PACKAGE_MANAGER_RUNNERS = [
 	{
 		id: "npx",
@@ -2227,8 +2299,10 @@ const TerminalConfigSchema = z.object({
 	fontFamily: z.string().default(""),
 	cursorBlink: z.boolean().default(true),
 	cursorStyle: z.enum(CURSOR_STYLE_VALUES).default("block"),
-	scrollback: z.number().min(0).max(1e5).default(1e3)
+	scrollback: z.number().min(0).max(1e5).default(1e3),
+	rendererEngine: z.string().default("xterm")
 });
+const DashboardConfigSchema = z.object({ trendPointLimit: z.number().int().min(20).max(500).default(100) });
 /**
 * OpenSpecUI 配置 Schema
 *
@@ -2240,13 +2314,15 @@ const OpenSpecUIConfigSchema = z.object({
 		args: z.array(z.string()).optional()
 	}).default({}),
 	theme: z.enum(THEME_VALUES).default("system"),
-	terminal: TerminalConfigSchema.default(TerminalConfigSchema.parse({}))
+	terminal: TerminalConfigSchema.default(TerminalConfigSchema.parse({})),
+	dashboard: DashboardConfigSchema.default(DashboardConfigSchema.parse({}))
 });
 /** 默认配置（静态，用于测试和类型） */
 const DEFAULT_CONFIG = {
 	cli: {},
 	theme: "system",
-	terminal: TerminalConfigSchema.parse({})
+	terminal: TerminalConfigSchema.parse({}),
+	dashboard: DashboardConfigSchema.parse({})
 };
 /**
 * 配置管理器
@@ -2312,6 +2388,10 @@ var ConfigManager = class {
 			terminal: {
 				...current.terminal,
 				...config.terminal
+			},
+			dashboard: {
+				...current.dashboard,
+				...config.dashboard
 			}
 		};
 		const serialized = JSON.stringify(merged, null, 2);
@@ -3048,6 +3128,17 @@ async function isToolConfigured(projectDir, toolId) {
 	return (await getConfiguredTools(projectDir)).includes(toolId);
 }
 
+//#endregion
+//#region src/dashboard-types.ts
+const DASHBOARD_METRIC_KEYS = [
+	"specifications",
+	"requirements",
+	"activeChanges",
+	"inProgressChanges",
+	"completedChanges",
+	"taskCompletionPercent"
+];
+
 //#endregion
 //#region src/opsx-types.ts
 /** Check if an outputPath contains glob pattern characters */
@@ -3803,6 +3894,7 @@ const PtyPlatformSchema = z.enum([
 	"macos",
 	"common"
 ]);
+const CloseCallbackUrlSchema = z.union([z.string(), z.record(z.string())]);
 const PtySessionInfoSchema = z.object({
 	id: z.string().min(1),
 	title: z.string(),
@@ -3810,7 +3902,9 @@ const PtySessionInfoSchema = z.object({
 	args: z.array(z.string()),
 	platform: PtyPlatformSchema,
 	isExited: z.boolean(),
-	exitCode: z.number().int().nullable()
+	exitCode: z.number().int().nullable(),
+	closeTip: z.string().optional(),
+	closeCallbackUrl: CloseCallbackUrlSchema.optional()
 });
 const PtyCreateMessageSchema = z.object({
 	type: z.literal("create"),
@@ -3818,7 +3912,9 @@ const PtyCreateMessageSchema = z.object({
 	cols: PositiveInt.optional(),
 	rows: PositiveInt.optional(),
 	command: z.string().min(1).optional(),
-	args: z.array(z.string()).optional()
+	args: z.array(z.string()).optional(),
+	closeTip: z.string().optional(),
+	closeCallbackUrl: CloseCallbackUrlSchema.optional()
 });
 const PtyInputMessageSchema = z.object({
 	type: z.literal("input"),
@@ -3903,4 +3999,4 @@ const PtyServerMessageSchema = z.discriminatedUnion("type", [
 ]);
 
 //#endregion
-export { AI_TOOLS, ApplyInstructionsSchema, ApplyTaskSchema, ArtifactInstructionsSchema, ArtifactStatusSchema, ChangeFileSchema, ChangeSchema, ChangeStatusSchema, CliExecutor, ConfigManager, DEFAULT_CONFIG, DeltaOperationType, DeltaSchema, DeltaSpecSchema, DependencyInfoSchema, MarkdownParser, OpenSpecAdapter, OpenSpecUIConfigSchema, OpenSpecWatcher, OpsxKernel, ProjectWatcher, PtyAttachMessageSchema, PtyBufferResponseSchema, PtyClientMessageSchema, PtyCloseMessageSchema, PtyCreateMessageSchema, PtyCreatedResponseSchema, PtyErrorCodeSchema, PtyErrorResponseSchema, PtyExitResponseSchema, PtyInputMessageSchema, PtyListMessageSchema, PtyListResponseSchema, PtyOutputResponseSchema, PtyPlatformSchema, PtyResizeMessageSchema, PtyServerMessageSchema, PtyTitleResponseSchema, ReactiveContext, ReactiveState, RequirementSchema, SchemaArtifactSchema, SchemaDetailSchema, SchemaInfoSchema, SchemaResolutionSchema, SpecSchema, TaskSchema, TemplatesSchema, TerminalConfigSchema, Validator, acquireWatcher, buildCliRunnerCandidates, clearCache, closeAllProjectWatchers, closeAllWatchers, contextStorage, createCleanCliEnv, createFileChangeObservable, getActiveWatcherCount, getAllToolIds, getAllTools, getAvailableToolIds, getAvailableTools, getCacheSize, getConfiguredTools, getDefaultCliCommand, getDefaultCliCommandString, getProjectWatcher, getToolById, getWatchedProjectDir, initWatcherPool, isGlobPattern, isToolConfigured, isWatcherPoolInitialized, parseCliCommand, reactiveExists, reactiveReadDir, reactiveReadFile, reactiveStat, sniffGlobalCli };
+export { AI_TOOLS, ApplyInstructionsSchema, ApplyTaskSchema, ArtifactInstructionsSchema, ArtifactStatusSchema, ChangeFileSchema, ChangeSchema, ChangeStatusSchema, CliExecutor, ConfigManager, DASHBOARD_METRIC_KEYS, DEFAULT_CONFIG, DashboardConfigSchema, DeltaOperationType, DeltaSchema, DeltaSpecSchema, DependencyInfoSchema, MarkdownParser, OpenSpecAdapter, OpenSpecUIConfigSchema, OpenSpecWatcher, OpsxKernel, ProjectWatcher, PtyAttachMessageSchema, PtyBufferResponseSchema, PtyClientMessageSchema, PtyCloseMessageSchema, PtyCreateMessageSchema, PtyCreatedResponseSchema, PtyErrorCodeSchema, PtyErrorResponseSchema, PtyExitResponseSchema, PtyInputMessageSchema, PtyListMessageSchema, PtyListResponseSchema, PtyOutputResponseSchema, PtyPlatformSchema, PtyResizeMessageSchema, PtyServerMessageSchema, PtyTitleResponseSchema, ReactiveContext, ReactiveState, RequirementSchema, SchemaArtifactSchema, SchemaDetailSchema, SchemaInfoSchema, SchemaResolutionSchema, SpecSchema, TaskSchema, TemplatesSchema, TerminalConfigSchema, TerminalRendererEngineSchema, Validator, acquireWatcher, buildCliRunnerCandidates, clearCache, closeAllProjectWatchers, closeAllWatchers, contextStorage, createCleanCliEnv, createFileChangeObservable, getActiveWatcherCount, getAllToolIds, getAllTools, getAvailableToolIds, getAvailableTools, getCacheSize, getConfiguredTools, getDefaultCliCommand, getDefaultCliCommandString, getProjectWatcher, getToolById, getWatchedProjectDir, getWatcherRuntimeStatus, initWatcherPool, isGlobPattern, isTerminalRendererEngine, isToolConfigured, isWatcherPoolInitialized, parseCliCommand, reactiveExists, reactiveReadDir, reactiveReadFile, reactiveStat, sniffGlobalCli };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openspecui/core",
-  "version": "1.1.2",
+  "version": "1.5.0",
   "description": "Core OpenSpec adapter and parser",
   "type": "module",
   "main": "./dist/index.mjs",