dsh-git-ui 0.0.2 → 0.1.1

package/src/client/time-format.ts

@@ -0,0 +1,32 @@
+/**
+ * IDEA 式时间格式化：不足 60 分钟「x 分钟前」、今天「今天 HH:mm」、
+ * 昨天「昨天 HH:mm」、其余「Y/M/D HH:mm」。纯函数，可单元测试。
+ */
+
+/** 本地化标签由调用方注入（组件侧经字典提供）。 */
+export interface TimeLabels {
+  readonly minutesAgo: (n: number) => string
+  readonly today: string
+  readonly yesterday: string
+}
+
+const pad = (n: number): string => String(n).padStart(2, '0')
+
+/** 日历日键（本地时区），用于今天/昨天判定。 */
+function dayKey(x: Date): string {
+  return `${x.getFullYear()}-${x.getMonth()}-${x.getDate()}`
+}
+
+export function formatWhen(iso: string, now: number, labels: TimeLabels): string {
+  const then = Date.parse(iso)
+  if (!Number.isFinite(then)) return iso
+  const d = new Date(then)
+  const hm = `${pad(d.getHours())}:${pad(d.getMinutes())}`
+  const seconds = Math.floor((now - then) / 1000)
+  if (seconds >= 0 && seconds < 3600) {
+    return labels.minutesAgo(Math.max(1, Math.floor(seconds / 60)))
+  }
+  if (dayKey(d) === dayKey(new Date(now))) return `${labels.today} ${hm}`
+  if (dayKey(d) === dayKey(new Date(now - 86_400_000))) return `${labels.yesterday} ${hm}`
+  return `${d.getFullYear()}/${d.getMonth() + 1}/${d.getDate()} ${hm}`
+}

package/src/contracts/client-platform.ts

@@ -0,0 +1,147 @@
+/**
+ * Client 插件平台契约：业务层定义「我需要宿主做什么」，适配层实现「宿主怎么做」。
+ *
+ * 当 dsh 升级导致 Cordis / typert / slot API 变更时，只需更新
+ * `adapters/dsh/client-adapter.ts`，本文件及业务代码零改动。
+ */
+import type { GitAction, GitActionResult, GitActionRequest, GitQueryRequest, GitQueryResponse, GitSnapshotRequest, GitSnapshotResult } from '../host/types.ts'
+
+/** 国际化字典：中英双语。 */
+export interface LocaleDicts {
+  readonly zh: Record<string, string>
+  readonly en: Record<string, string>
+}
+
+/** RPC 信封：传输层结果（ok/error）包裹业务返回值。 */
+export type RemoteEnvelope<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: { readonly code?: string; readonly message?: string; readonly details?: unknown } }
+
+/** Git Remote 服务接口：客户端通过此接口与宿主 RPC 通信。 */
+export interface GitRemoteLike {
+  snapshot(request: GitSnapshotRequest): Promise<RemoteEnvelope<GitSnapshotResult>>
+  run(request: GitActionRequest): Promise<RemoteEnvelope<GitActionResult>>
+  query(request: GitQueryRequest): Promise<RemoteEnvelope<GitQueryResponse>>
+}
+
+/** 简化的查询结果：解包 RPC 信封和业务错误。 */
+export type GitQueryOutcome =
+  | { readonly ok: true; readonly value: Extract<GitQueryResponse, { ok: true }>['value'] }
+  | { readonly ok: false; readonly message: string }
+
+/** Git 视图状态：客户端组件消费的可观察快照。 */
+export type GitView =
+  | { readonly state: 'no-cwd' }
+  | { readonly state: 'cold' }
+  | { readonly state: 'loading' }
+  | { readonly state: 'ready'; readonly snapshot: import('../host/types.ts').GitSnapshot }
+  | { readonly state: 'error'; readonly error: import('../host/types.ts').GitSnapshotFailure }
+
+/** 可观察对象：useSyncExternalStore 形状。 */
+export interface GitObservable<V> {
+  subscribe(listener: () => void): () => void
+  getSnapshot(): V
+}
+
+/** Slot 注入接口：组件通过此接口与控制器交互。 */
+export interface GitInjected {
+  hooks: {
+    /** 会话的 Git 视图源。Slot 运行时将其绑定为 useGit 选择器钩子。 */
+    git: GitObservable<GitView>
+  }
+  /** 强制立即刷新（与轮询相同路径）。 */
+  refresh: () => Promise<void>
+  /** 执行一条管理操作（宿主返回新快照）。 */
+  run: (action: GitAction) => Promise<GitActionResult>
+  /** 执行一条只读查询（历史/差异/分支等）。 */
+  query: (query: GitQueryRequest['query']) => Promise<GitQueryOutcome>
+}
+
+/** Slot 条目描述符：注册到宿主 slot 系统的一条记录。 */
+export interface SlotEntryDescriptor {
+  /** Slot 名称（如 'conversation.session.header.utilities'）。 */
+  readonly name: string
+  /** 条目 ID（同一 slot 内唯一）。 */
+  readonly id: string
+  /** 渲染顺序（升序）。 */
+  readonly order?: number
+  /** 国际化命名空间。 */
+  readonly locale?: string
+  /** 注入工厂：每次渲染调用，返回该条目的业务接口。 */
+  readonly inject: (sessionId: string) => GitInjected
+}
+
+/**
+ * Client 平台能力：业务层需要的全部宿主服务。
+ *
+ * 设计原则：
+ *   - 只声明「做什么」，不暴露「怎么做」
+ *   - 方法签名取业务层实际使用的最小集
+ *   - 返回类型为业务层需要的接口，非宿主原始类型
+ */
+export interface ClientPlatform {
+  /** 注册国际化字典。 */
+  registerLocale(namespace: string, dicts: LocaleDicts): void
+
+  /**
+   * 挂载 Remote 贡献并返回命名空间服务对象。
+   *
+   * 挂载完成后，返回的对象可用于创建业务控制器。适配层负责处理
+   * 宿主的挂载机制（如 Cordis 的 child fiber + inject 模式）。
+   */
+  mountRemoteAndGetService(contribution: RemoteContribution, namespace: string): Promise<GitRemoteLike>
+
+  /**
+   * 注册一个 slot 条目。
+   *
+   * 宿主负责在合适的时机渲染该条目。返回释放函数，调用后注销条目。
+   */
+  registerSlotEntry(options: SlotEntryDescriptor, component: unknown): () => void
+
+  /** 订阅应用事件。返回取消订阅函数（若宿主支持）。 */
+  onEvent(event: string, listener: (...args: unknown[]) => void): (() => void) | void
+
+  /**
+   * 注册副作用。回调可返回清理函数，在插件卸载时调用。
+   * 用于管理定时器等需要生命周期管理的资源。
+   */
+  effect(callback: () => void | (() => void | Promise<void>), label?: string): void
+}
+
+/**
+ * Remote 贡献声明：描述一个命名空间下的全部 RPC 方法。
+ *
+ * 本接口是业务层对 RPC 声明的最小需求。适配层负责将其转换为宿主
+ * 的具体格式（如 TypertRemoteContribution）。
+ */
+export interface RemoteContribution {
+  readonly package: string
+  readonly descriptors: readonly RemoteMethodDescriptor[]
+}
+
+/** 单条 RPC 方法描述。 */
+export interface RemoteMethodDescriptor {
+  readonly id: string
+  readonly service: string
+  readonly namespace: string
+  readonly method: string
+  readonly invocation: { readonly kind: 'direct' } | { readonly kind: 'context'; readonly context: string; readonly wire: string }
+  readonly cancellation?: { readonly parameter: 'signal' }
+  readonly parameters: readonly RemoteParameterDescriptor[]
+  readonly result: RemoteCodecDescriptor
+}
+
+/** RPC 参数描述。 */
+export interface RemoteParameterDescriptor {
+  readonly name: string
+  readonly wire: string
+  readonly source: 'json'
+  readonly codec: RemoteCodecDescriptor
+}
+
+/** RPC 编解码器描述。 */
+export interface RemoteCodecDescriptor {
+  readonly mode: 'strict'
+  readonly typeSymbol: string
+  readonly schema: { parse(value: unknown): unknown }
+}

package/src/contracts/host-endpoints.ts

@@ -0,0 +1,58 @@
+/**
+ * Host 端点契约：纯业务逻辑，零框架依赖。
+ *
+ * 将 `snapshotForSession` / `runAction` / `runQuery` 聚合为统一的
+ * `HostEndpoints` 接口——宿主适配层（Cordis/typert 或其他框架）只需调用
+ * `createHostEndpoints(deps, config)` 即可获得全部端点方法，再以任何
+ * RPC 机制暴露。业务层对此一无所知。
+ */
+import { snapshotForSession, type GitStatusConfig, type SnapshotDeps } from '../host/core.ts'
+import { runAction } from '../host/actions.ts'
+import { runQuery } from '../host/queries.ts'
+import type { GitActionRequest, GitActionResult, GitQueryRequest, GitQueryResponse, GitSnapshotRequest, GitSnapshotResult } from '../host/types.ts'
+
+/**
+ * 业务端点集合：三个 RPC 方法的纯函数实现。
+ * 每个方法接收 wire 请求、可选取消信号，返回 wire 响应。
+ */
+export interface HostEndpoints {
+  snapshot(request: GitSnapshotRequest, signal?: AbortSignal): Promise<GitSnapshotResult>
+  run(request: GitActionRequest, signal?: AbortSignal): Promise<GitActionResult>
+  query(request: GitQueryRequest, signal?: AbortSignal): Promise<GitQueryResponse>
+}
+
+/**
+ * 构造业务端点实例。
+ *
+ * `deps` 携带全部宿主能力（子进程、会话查找、文件系统）；`config` 携带
+ * 运行参数。两者均为结构化接口，与任何框架无关。返回的端点对象可直接
+ * 绑定到 RPC 装饰器、HTTP 路由、或测试桩。
+ */
+export function createHostEndpoints(deps: SnapshotDeps, config: GitStatusConfig): HostEndpoints {
+  return {
+    snapshot(request, signal) {
+      // 合并调用方信号与 deps 自带信号（deps.signal 来自 Cordis Remote 的
+      // 取消槽；此处 signal 来自适配层传入——两者取并集，任一触发即中止）。
+      const merged = mergeSignals(deps.signal, signal)
+      const effectiveDeps = merged === deps.signal ? deps : { ...deps, signal: merged }
+      return snapshotForSession(effectiveDeps, config, request.sessionId)
+    },
+    run(request, signal) {
+      const merged = mergeSignals(deps.signal, signal)
+      const effectiveDeps = merged === deps.signal ? deps : { ...deps, signal: merged }
+      return runAction(effectiveDeps, config, request)
+    },
+    query(request, signal) {
+      const merged = mergeSignals(deps.signal, signal)
+      const effectiveDeps = merged === deps.signal ? deps : { ...deps, signal: merged }
+      return runQuery(effectiveDeps, config, request)
+    },
+  }
+}
+
+/** 合并两个可选信号：任一 undefined 取另一个，均存在则 AbortSignal.any。 */
+function mergeSignals(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal | undefined {
+  if (a === undefined) return b
+  if (b === undefined) return a
+  return AbortSignal.any([a, b])
+}

package/src/contracts/plugin-activation.ts

@@ -0,0 +1,129 @@
+/**
+ * 插件激活逻辑：纯业务编排，零框架依赖。
+ *
+ * 接收 `ClientPlatform` 接口和插件依赖，完成：
+ *   1. 注册国际化字典
+ *   2. 挂载 Remote 并获取 gitInfo 服务
+ *   3. 注册 header utility slot
+ *   4. 订阅连接重置事件
+ *
+ * 适配层（如 `adapters/dsh/client-adapter.ts`）负责将宿主 API 翻译为
+ * `ClientPlatform`，然后调用本函数。业务层对宿主一无所知。
+ */
+import type { ClientPlatform, SlotEntryDescriptor, GitInjected, GitRemoteLike } from './client-platform.ts'
+import type { RemoteContribution } from './client-platform.ts'
+import type { LocaleDicts } from './client-platform.ts'
+import type { GitAction } from '../host/types.ts'
+import type { GitQueryRequest, GitActionResult } from '../host/types.ts'
+import type { GitQueryOutcome } from './client-platform.ts'
+
+/** Slot 名称常量。 */
+const HEADER_UTILITIES_SLOT = 'conversation.session.header.utilities'
+
+/** 本插件的 slot 条目 ID。 */
+const SLOT_ENTRY_ID = 'git'
+
+/** 国际化命名空间。 */
+const LOCALE_NS = 'git'
+
+/** 控制器接口：插件激活逻辑依赖的控制器能力。 */
+export interface ControllerLike {
+  subscribe(listener: () => void): () => void
+  getSnapshot(): import('./client-platform.ts').GitView
+  refresh(): Promise<void>
+  resync(): void
+  run(action: GitAction): Promise<GitActionResult>
+  query(query: GitQueryRequest['query']): Promise<GitQueryOutcome>
+  dispose(): void
+}
+
+/** 插件依赖：由调用方提供的具体实现。 */
+export interface PluginDependencies {
+  /** Remote 贡献配置 */
+  remoteContribution: RemoteContribution
+  /** 国际化字典 */
+  locales: LocaleDicts
+  /** 控制器构造函数 */
+  createController: (remote: GitRemoteLike, sessionId: string) => ControllerLike
+}
+
+/**
+ * 激活插件。
+ *
+ * @param platform 宿主平台能力
+ * @param deps 插件依赖（由调用方提供）
+ * @param component 要注册的 UI 组件（已包裹 UI 基础组件上下文）
+ */
+export async function activatePlugin(
+  platform: ClientPlatform,
+  deps: PluginDependencies,
+  component: unknown,
+): Promise<void> {
+  // 1. 注册国际化字典
+  platform.effect(
+    () => platform.registerLocale(LOCALE_NS, deps.locales),
+    'dsh-git-ui: dictionaries',
+  )
+
+  // 2. 挂载 Remote 并获取 gitInfo 服务
+  const gitInfoService = await platform.mountRemoteAndGetService(deps.remoteContribution, 'gitInfo')
+
+  // 3. 控制器缓存（按 sessionId）
+  const controllers = new Map<string, ControllerLike>()
+  const faces = new Map<string, GitInjected>()
+
+  const controllerFor = (sessionId: string): ControllerLike => {
+    let controller = controllers.get(sessionId)
+    if (controller === undefined) {
+      controller = deps.createController(gitInfoService, sessionId)
+      controllers.set(sessionId, controller)
+    }
+    return controller
+  }
+
+  // 4. 注册 slot 条目
+  const slotOptions: SlotEntryDescriptor = {
+    name: HEADER_UTILITIES_SLOT,
+    id: SLOT_ENTRY_ID,
+    order: 10,
+    locale: LOCALE_NS,
+    inject: (sessionId): GitInjected => {
+      // Per-session stable face: the slot runtime may re-invoke the
+      // inject factory on every render, and components depend on the
+      // `refresh` reference staying stable (a fresh arrow function per
+      // call would re-run mount effects and loop: refresh → view
+      // change → re-render → new refresh → refresh …). Cache the face
+      // so the same controller (and its bound refresh/run) is always
+      // handed out per session.
+      let face = faces.get(sessionId)
+      if (face === undefined) {
+        const controller = controllerFor(sessionId)
+        face = {
+          hooks: { git: controller as GitInjected['hooks']['git'] },
+          refresh: () => controller.refresh(),
+          run: (action) => controller.run(action),
+          query: (query) => controller.query(query),
+        }
+        faces.set(sessionId, face)
+      }
+      return face
+    },
+  }
+
+  const disposeSlot = platform.registerSlotEntry(slotOptions, component)
+
+  // 5. 注册清理：释放 slot 并销毁全部控制器
+  platform.effect(() => {
+    return () => {
+      disposeSlot()
+      for (const controller of controllers.values()) controller.dispose()
+      controllers.clear()
+      faces.clear()
+    }
+  }, 'dsh-git-ui: slot and controller lifecycle')
+
+  // 6. 订阅连接重置事件：重连后刷新全部控制器
+  platform.onEvent('connection/reset', () => {
+    for (const controller of controllers.values()) controller.resync()
+  })
+}

package/src/contracts/ui-context.tsx

@@ -0,0 +1,28 @@
+/**
+ * UI 基础组件 React Context：业务组件通过 `useUI()` 获取实现，
+ * 适配层在插件激活时通过 `<UIPrimitivesProvider>` 注入宿主组件。
+ *
+ * 设计要点：
+ *   - 默认值为 null——若未提供则 `useUI()` 抛出明确错误，而非静默渲染空组件。
+ *   - Provider 在插件入口（client/index.ts）包裹整棵组件树。
+ *   - 测试可直接用 Provider 注入 mock 组件，无需模拟宿主环境。
+ */
+import { createContext, useContext } from 'react'
+import type { ReactNode } from 'react'
+import type { UIPrimitives } from './ui-primitives.ts'
+
+const UIPrimitivesContext = createContext<UIPrimitives | null>(null)
+
+/** 消费 UI 基础组件。必须在 `<UIPrimitivesProvider>` 内使用。 */
+export function useUI(): UIPrimitives {
+  const value = useContext(UIPrimitivesContext)
+  if (value === null) {
+    throw new Error('useUI(): missing <UIPrimitivesProvider> — 插件入口未注入 UI 基础组件')
+  }
+  return value
+}
+
+/** 注入 UI 基础组件实现。在插件入口包裹整棵组件树。 */
+export function UIPrimitivesProvider({ value, children }: { value: UIPrimitives; children?: ReactNode }): ReactNode {
+  return <UIPrimitivesContext.Provider value={value}>{children}</UIPrimitivesContext.Provider>
+}

package/src/contracts/ui-primitives.ts

@@ -0,0 +1,48 @@
+/**
+ * UI 基础组件契约：业务层只依赖此接口，不直接 import 任何宿主 UI 库。
+ *
+ * 属性集取「实际使用的最小并集」——GitPill / GitCenter 用到的全部 props
+ * 均已覆盖；宿主适配层可提供更丰富的实现，但业务代码保证只消费此处的
+ * 声明。未来 dsh 升级导致 Modal/Button/Toast 变更时，只需更新适配层，
+ * 业务组件零改动。
+ */
+import type { ButtonHTMLAttributes, ReactNode } from 'react'
+
+/** 受控全屏对话框：遮罩 + Escape 关闭。 */
+export interface ModalProps {
+  readonly open: boolean
+  readonly onClose: () => void
+  readonly title: string
+  readonly closeLabel?: string
+  readonly description?: string
+  readonly children?: ReactNode
+  readonly footer?: ReactNode
+  readonly className?: string
+  readonly contentClassName?: string
+  /** 隐藏默认标题栏（自定义头部时使用）。 */
+  readonly headless?: boolean
+}
+
+/** 令牌化按钮原子。原生 button 属性透传。 */
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  readonly variant?: 'primary' | 'ghost' | 'outline' | 'toolbar'
+  readonly size?: 'md' | 'sm'
+  readonly icon?: ReactNode
+  readonly className?: string | undefined
+  readonly children?: ReactNode
+}
+
+/** 瞬时顶部提示条：自动消失后调用 onDone 通知父级卸载。 */
+export interface ToastProps {
+  readonly text: string
+  readonly icon?: ReactNode
+  readonly anchor?: HTMLElement | null
+  readonly onDone: () => void
+}
+
+/** 三个基础组件的聚合：适配层一次性提供整套实现。 */
+export interface UIPrimitives {
+  readonly Modal: (props: ModalProps) => ReactNode
+  readonly Button: (props: ButtonProps) => ReactNode
+  readonly Toast: (props: ToastProps) => ReactNode
+}

package/src/host/actions.ts

@@ -15,21 +15,21 @@
  */
 import { resolve, sep } from 'node:path'
 import { resolveWorkspace, runCommand, snapshotForSession, type GitStatusConfig, type SnapshotDeps } from './core.ts'
-import type { GitAction, GitActionResult, GitActionRequest } from './types.ts'
+import type { GitAction, GitActionResult, GitActionRequest, GitOperationErrorCode } from './types.ts'
 
 /** Build the command sequence for one action, validating every path against the root. */
 function buildArgv(action: GitAction, root: string): { readonly argv: readonly (readonly string[])[] } | { readonly error: string } {
   switch (action.kind) {
     case 'stage':
-      return withPaths(['git', 'add', '--'], action.paths, root)
+      return withPaths([['git', 'add', '--']], action.paths, root)
     case 'stage-all':
       return { argv: [['git', 'add', '-A']] }
     case 'unstage':
-      return withPaths(['git', 'restore', '--staged', '--'], action.paths, root)
+      return withPaths([['git', 'restore', '--staged', '--']], action.paths, root)
     case 'unstage-all':
       return { argv: [['git', 'restore', '--staged', '--', '.']] }
     case 'discard':
-      return withPaths(['git', 'restore', '--'], action.paths, root)
+      return withPaths([['git', 'restore', '--']], action.paths, root)
     case 'discard-all':
       // Reset the index to HEAD first, then the work tree to the index — the
       // IDE-style "roll back everything tracked" semantics.
@@ -40,21 +40,49 @@ function buildArgv(action: GitAction, root: string): { readonly argv: readonly (
       if (action.paths === undefined || action.paths.length === 0) {
         return { argv: [['git', 'commit', '-m', message]] }
       }
-      // git commit -- <paths> stages those paths from the work tree and
-      // commits only them (index state of other paths is ignored) — the
-      // IDE-style "commit selected files" semantics.
-      return withPaths(['git', 'commit', '-m', message, '--'], action.paths, root)
+      // 两步序列（IDE 式「提交所选文件」语义，含未跟踪文件）：
+      // 1. `git add -- <paths>` 先把所选路径纳入索引——裸的
+      //    `git commit -- <未跟踪路径>` 会报 pathspec 错误，先行暂存使其可匹配；
+      // 2. `git commit -m <msg> -- <paths>` 按路径限定提交这些路径的工作区内容，
+      //    其余已暂存文件不受影响。对已跟踪路径与单命令完全等价（已实测验证）。
+      return withPaths([['git', 'add', '--'], ['git', 'commit', '-m', message, '--']], action.paths, root)
     }
+    case 'branch-create': {
+      // Name validity is validated by runAction (invalid-name), not here.
+      const from = action.from === undefined || action.from === '' ? [] : [action.from]
+      return { argv: [['git', 'branch', action.name, ...from]] }
+    }
+    case 'branch-checkout':
+      return { argv: [['git', 'checkout', action.name]] }
+    case 'branch-delete':
+      return { argv: [['git', 'branch', action.force === true ? '-D' : '-d', action.name]] }
+    case 'fetch':
+      // fetch --all --prune：拉取所有远程引用更新 + 清理已删除的远程跟踪分支。
+      return { argv: [['git', 'fetch', '--all', '--prune']] }
   }
 }
 
-/** Append validated repo-relative paths behind `--`. */
-function withPaths(prefix: readonly string[], paths: readonly string[], root: string): { readonly argv: readonly (readonly string[])[] } | { readonly error: string } {
+/**
+ * A branch name is valid when it matches git's ref-name grammar at the level
+ * we care about: non-empty, ASCII ref chars only, no leading `-` (option
+ * injection guard, though argv never shells out), no `..` (path traversal of
+ * refs), no trailing `/`, and no double slashes.
+ */
+export function isValidBranchName(name: string): boolean {
+  if (name === '' || name.startsWith('-') || name.includes('..') || name.endsWith('/') || name.includes('//')) return false
+  return /^[A-Za-z0-9._/-]+$/.test(name)
+}
+
+/**
+ * 校验仓库相对路径后追加到 `--` 之后；`prefixes` 可给出多条命令序列，
+ * 校验后的路径逐一附加到每条序列（commit 所选路径即两步序列）。
+ */
+function withPaths(prefixes: readonly (readonly string[])[], paths: readonly string[], root: string): { readonly argv: readonly (readonly string[])[] } | { readonly error: string } {
   if (paths.length === 0) return { error: 'no paths given' }
   for (const path of paths) {
     if (!isSafePath(path, root)) return { error: `unsafe path: ${path}` }
   }
-  return { argv: [[...prefix, ...paths]] }
+  return { argv: prefixes.map((prefix) => [...prefix, ...paths]) }
 }
 
 /**
@@ -71,13 +99,26 @@ export function isSafePath(path: string, root: string): boolean {
 }
 
 /** Map a snapshot-flow failure (which may carry git-unavailable) onto the operation error shape. */
-function operationError(failure: Extract<Awaited<ReturnType<typeof resolveWorkspace>>, { ok: false }>['error']): GitActionResult & { ok: false } {
+export function operationError(failure: Extract<Awaited<ReturnType<typeof resolveWorkspace>>, { ok: false }>['error']): GitActionResult & { ok: false } {
   if (failure.code === 'git-unavailable') {
     return { ok: false, error: { code: 'git-error', message: failure.detail } }
   }
   return { ok: false, error: failure }
 }
 
+/**
+ * 把 git 命令失败归类为可预期的业务错误（其余保持 git-error）。
+ * 切分支被工作区未提交变更阻止是最常见的可预期失败：git 输出
+ * "would be overwritten by checkout"（或中文本地化 "将被 checkout 覆盖"），
+ * 归一化为 local-changes-block，client 据此给友好提示 + 处理变更引导。
+ */
+export function classifyOperationError(kind: GitAction['kind'], message: string): GitOperationErrorCode {
+  if (kind === 'branch-checkout' && /would be overwritten by checkout|将被 checkout 覆盖|有未跟踪工作区文件将会被 checkout 覆盖/i.test(message)) {
+    return 'local-changes-block'
+  }
+  return 'git-error'
+}
+
 /**
  * Execute one management action against the session's repository and return
  * the refreshed snapshot on success (the caller re-renders from it, so the
@@ -96,11 +137,20 @@ export async function runAction(
     return { ok: false, error: { code: 'git-error', message: 'commit message is empty' } }
   }
 
+  const kind = request.action.kind
+  if (kind === 'branch-create' || kind === 'branch-checkout' || kind === 'branch-delete') {
+    const name = request.action.name
+    if (!isValidBranchName(name)) {
+      return { ok: false, error: { code: 'invalid-name', message: `invalid branch name: ${name}` } }
+    }
+  }
+
   const built = buildArgv(request.action, root)
   if ('error' in built) return { ok: false, error: { code: 'invalid-path', message: built.error } }
 
-  // Run the command sequence; a failure stops the rest (the first commands
-  // may already have taken effect — they are all idempotent restores).
+  // Run the command sequence; a failure stops the rest. 先行命令可能已生效：
+  // restore 类命令幂等可重入；两步提交若 add 成功后 commit 失败，所选路径
+  // 留在暂存区（IDE 行为相同，下次重试即可成功）。
   let lastStdout = ''
   for (const argv of built.argv) {
     const outcome = await runCommand(deps.run, argv, root, `action ${request.action.kind}`, deps.signal)
@@ -110,10 +160,11 @@ export async function runAction(
       // git writes user-facing failures to stderr OR stdout (e.g. a clean
       // repo's `git commit` reports "nothing to commit" on stdout).
       const message = outcome.run.stderr.trim() || outcome.run.stdout.trim()
+      const code = classifyOperationError(request.action.kind, message)
       return {
         ok: false,
         error: {
-          code: 'git-error',
+          code,
           message: message !== '' ? message : `git ${request.action.kind} exited ${String(outcome.run.exitCode)}`,
         },
       }

package/src/host/core.ts

@@ -157,8 +157,14 @@ export async function resolveWorkspace(
  *   1. `git rev-parse --show-toplevel`      — repo detection (exit 128 → not-a-git-repo)
  *   2. `git branch --show-current`          — null when detached
  *   3. `git rev-parse --short HEAD`         — null + unborn when the repo has no commits
- *   4. `git status --porcelain=v1 -z --branch`
+ *   4. `git status --porcelain=v1 -z --branch --untracked-files=all`
  *   5. `git log -n 5 --format=%H%x1f%h%x1f%s%x1f%an%x1f%aI`
+ *
+ * --untracked-files=all：git 默认 normal 模式会把整目录未跟踪折叠为单条
+ * `?? dir/`（尾斜杠）且不枚举其内部文件——隐藏目录（.agent/.tianqi 等）的
+ * 变更因此从不进入变更清单。`all` 强制逐文件枚举（与 IDEA / VSCode 一致），
+ * 内部文件得以展示；maxChanges 截断列表、maxStatusBytes spill 保计数精确，
+ * 超大未跟踪树（如未 gitignore 的构建产物）经此路径优雅降级。
  */
 export async function snapshotForSession(
   deps: SnapshotDeps,
@@ -182,7 +188,8 @@ export async function snapshotForSession(
   // main`), so a corrupt repo is never misreported as "no commits".
   const head = headRun.run.exitCode === 0 ? (headRun.run.stdout.trim() || null) : null
 
-  const status = await runCommand(deps.run, ['git', 'status', '--porcelain=v1', '-z', '--branch'], root, 'status', deps.signal)
+  // --untracked-files=all：强制枚举未跟踪目录内部文件（根因修复——见模块注释）。
+  const status = await runCommand(deps.run, ['git', 'status', '--porcelain=v1', '-z', '--branch', '--untracked-files=all'], root, 'status', deps.signal)
   if ('failure' in status) return { ok: false, error: status.failure }
   if (status.run.timedOut) return { ok: false, error: { code: 'timeout' } }
   if (status.run.exitCode !== 0) {