Merge remote-tracking branch 'origin/master' into worktree/web-model-request-retry

# Conflicts:
#	apps/cli/README.i18n.yaml
#	packages/client/ui-conversation/README.i18n.yaml
#	packages/client/ui-conversation/README.zh.md
#	packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx

packages/client/runtime/src/client/contract/session.ts

@@ -46,6 +46,13 @@ export interface ISession {
    * @returns completion; failures land in snapshot.openState/loadingOlder.
    */
   loadOlder(): Promise<void>
+  /**
+   * Execute one slash-command line against this session's agent — pure
+   * admission semantics (the host executor durably logs the lifecycle).
+   * @param line - the full command line, leading slash included.
+   * @returns the admission result, or the error branch on transport failure.
+   */
+  command(line: string): Promise<RpcResult<{ matched: boolean }>>
 }
 
 /**

packages/client/runtime/src/client/contract/workspaces.ts

@@ -6,7 +6,7 @@
  * the concrete class. Widening this interface is the explicit act of
  * widening what features may do to the workspaces domain.
  */
-import type { SessionId, WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-connection/client'
+import type { DirectoryListing, SessionId, WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-connection/client'
 import type { WorkspaceListState } from '../workspaces/service.ts'
 import type { ObservableSnapshot } from './store.ts'
 
@@ -37,6 +37,20 @@ export interface IWorkspaces {
    * @returns the selected path, or null when the user cancelled.
    */
   pickDirectory(): Promise<string | null>
+  /**
+   * List one directory level through the Host's `browse` capability.
+   * @param path - absolute directory to list; absent lists the Host home directory.
+   * @param signal - aborts the wire request (and the Host's scan) when the caller supersedes it.
+   * @returns the level's listing with breadcrumb ancestry.
+   */
+  listDirectory(path?: string, signal?: AbortSignal): Promise<DirectoryListing>
+  /**
+   * Create one child directory through the Host's `browse` capability.
+   * @param path - absolute existing parent directory.
+   * @param name - single non-blank path segment.
+   * @returns the created directory's absolute path.
+   */
+  createDirectory(path: string, name: string): Promise<string>
   /**
    * Open a filesystem path with the Host operating system's default application.
    * @param path - absolute or host-resolvable path.

packages/client/runtime/src/client/index.ts

@@ -18,7 +18,7 @@ export { SessionProvideChannel } from './sessions/provide.ts'
 export type { SessionProvideChannelHost } from './sessions/provide.ts'
 export { createScope } from './agents/scope.ts'
 export type { AgentScopeHandle } from './agents/scope.ts'
-export { WorkspaceCreateError, WorkspacesService } from './workspaces/service.ts'
+export { DirectoryBrowseError, WorkspaceCreateError, WorkspacesService } from './workspaces/service.ts'
 export type { Session } from './sessions/session.ts'
 export type { ISession, ProjectionsFace, SessionFace } from './contract/session.ts'
 export type { ISessions } from './contract/sessions.ts'
@@ -29,7 +29,9 @@ export type {
 export type { SessionListPhase } from './sessions/manager.ts'
 export type { WorkspaceListPhase } from './workspaces/manager.ts'
 export type { WorkspaceListState } from './workspaces/service.ts'
-export type { WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-connection/client'
+export type {
+  DirectoryEntry, DirectoryListing, WorkspaceId, WorkspaceView,
+} from '@deepseek-ai/dsh-client-connection/client'
 // Runtime owns the snapshot store; web-react only binds it to React.
 export { createSnapshotStore, defineStore, shallowEqual } from './contract/store.ts'
 export type {
@@ -152,6 +154,12 @@ export function apply(ctx: Context): void {
       workspaces.handleConnected()
       ctx.emit('connection/reset')
     },
+    onStateChange: (state) => {
+      // Generation death fires before any next-generation frame can arrive
+      // (reconnect replays flow from stream open, ahead of onConnected):
+      // the only safe moment to drop generation-scoped interaction state.
+      if (state === 'reconnecting') sessions.handleDisconnected()
+    },
   })
   ctx.effect(() => () => { loop.stop() }, 'runtime: connection stream loop')
 }

packages/client/runtime/src/client/sessions/lineage.ts

@@ -9,7 +9,7 @@ export interface TitledSessionSummary extends SessionSummary {
   title?: string
 }
 
-/** One flattened session-list row (summary + lineage indent depth). */
+/** One flattened session-list row (summary + lineage indent depth + live pending-approval bit). */
 export interface SessionListEntry {
   sessionId: SessionId
   title?: string
@@ -19,6 +19,8 @@ export interface SessionListEntry {
   blank: boolean
   parentSessionId?: SessionId
   cwd?: string
+  /** An approval question is pending on this session (mux-frame derived; the sidebar's amber dot). */
+  waitingApproval: boolean
   /** Lineage indent depth: root = 0; the UI just multiplies by the indent width. */
   depth: number
 }
@@ -28,9 +30,10 @@ export interface SessionListEntry {
  * follows the established input order; this projection never re-sorts a
  * hydrated list from mutable timestamps.
  * @param summaries - the host's session.list items.
+ * @param waitingApproval - sessions with a pending approval question (manager-owned live fact; absent = false).
  * @returns display rows in render order.
  */
-export function flattenLineage(summaries: readonly TitledSessionSummary[]): SessionListEntry[] {
+export function flattenLineage(summaries: readonly TitledSessionSummary[], waitingApproval?: ReadonlySet<SessionId>): SessionListEntry[] {
   const byId = new Map<SessionId, TitledSessionSummary>()
   for (const s of summaries) byId.set(s.sessionId, s)
 
@@ -54,7 +57,7 @@ export function flattenLineage(summaries: readonly TitledSessionSummary[]): Sess
       return
     }
     visited.add(s.sessionId)
-    out.push({ ...s, depth })
+    out.push({ ...s, waitingApproval: waitingApproval?.has(s.sessionId) ?? false, depth })
     const kids = children.get(s.sessionId)
     if (kids === undefined) return
     for (const kid of kids) walk(kid, depth + 1)

packages/client/runtime/src/client/sessions/manager.ts

@@ -57,6 +57,11 @@ export class SessionManager {
    *  drop-and-backfill path; replayed and cleared on instantiation. Bounded per session (these
    *  frames are low-frequency; overflow drops oldest) and dropped on session-removed (audit S7). */
   private readonly pendingBuffers = new Map<SessionId, RpcRequest<MuxFrame>[]>()
+  /** Outstanding approval questions per session, keyed by approvalId (idempotent under mux-open
+   *  replays of the same requested frame). Manager-owned rather than read off Session instances
+   *  because the sidebar must light up for sessions never instantiated. Cleared per connection
+   *  generation — the reopen replay re-adds still-pending questions — and on session-removed. */
+  private readonly waitingApprovals = new Map<SessionId, Set<string>>()
   /** Per-session projection value stores, retained independently of instance arrival (the
    *  title-snapshot precedent, generalized): push frames land here whether or not the Session
    *  is instantiated (list rows read the 'title' key), and an instantiated Session adopts the
@@ -360,6 +365,22 @@ export class SessionManager {
         }
       }
     }
+    // List-level waiting-approval bit (the sidebar amber dot): tracked here for
+    // every session, instantiated or not; approvalId keys make replays idempotent.
+    if (frame.type === 'approval/requested') {
+      let ids = this.waitingApprovals.get(frame.sessionId)
+      if (ids === undefined) this.waitingApprovals.set(frame.sessionId, ids = new Set())
+      if (!ids.has(frame.approvalId)) {
+        ids.add(frame.approvalId)
+        this.notifier.markDirty()
+      }
+    } else if (frame.type === 'approval/resolved') {
+      const ids = this.waitingApprovals.get(frame.sessionId)
+      if (ids !== undefined && ids.delete(frame.approvalId)) {
+        if (ids.size === 0) this.waitingApprovals.delete(frame.sessionId)
+        this.notifier.markDirty()
+      }
+    }
     const session = this.sessions.get(frame.sessionId)
     if (session === undefined) {
       // Approval/question/queued frames never hit history: buffer for replay on
@@ -404,6 +425,7 @@ export class SessionManager {
         this.recordMutation({ kind: 'remove', sessionId: frame.sessionId })
         this.sessions.get(frame.sessionId)?.handleRemoved() // instance survives (resident-instance rule), only flagged in the snapshot
         this.pendingBuffers.delete(frame.sessionId) // a removed session's buffered frames must not replay on a future instantiation
+        this.waitingApprovals.delete(frame.sessionId) // a removed session cannot wait on anyone
         this.projectionStores.delete(frame.sessionId) // removed sessions drop their projection rows with the instance
         return
       }
@@ -421,6 +443,30 @@ export class SessionManager {
     }
   }
 
+  /**
+   * The moment a connection generation dies (before any next-generation frame
+   * can arrive — onConnected waits for the readiness handshake while replayed
+   * frames flow from stream open, so clearing there would race the replay):
+   * drop generation-scoped live state. Approvals resolved while disconnected
+   * send no frame, so the stale bits and the buffered answerable frames must
+   * not survive into the next generation — the mux-open replay re-adds every
+   * still-pending question with its live rpcId.
+   */
+  handleDisconnected(): void {
+    if (this.waitingApprovals.size > 0) {
+      this.waitingApprovals.clear()
+      this.notifier.markDirty()
+    }
+    for (const [sessionId, buffer] of [...this.pendingBuffers]) {
+      const kept = buffer.filter(item =>
+        item.payload.type !== 'approval/requested' && item.payload.type !== 'approval/resolved'
+        && item.payload.type !== 'question/requested' && item.payload.type !== 'question/resolved')
+      if (kept.length === buffer.length) continue
+      if (kept.length === 0) this.pendingBuffers.delete(sessionId)
+      else this.pendingBuffers.set(sessionId, kept)
+    }
+  }
+
   /** After each connection generation: refresh the session baseline and rebuild opened windows. */
   handleConnected(): void {
     void this.refreshList()
@@ -436,7 +482,7 @@ export class SessionManager {
         ? { ...summary, title }
         : summary
     })
-    const fresh = flattenLineage(merged)
+    const fresh = flattenLineage(merged, new Set(this.waitingApprovals.keys()))
     const items = fresh.map((entry) => {
       const prev = this.entryCache.get(entry.sessionId)
       if (
@@ -444,6 +490,7 @@ export class SessionManager {
         && prev.blank === entry.blank
         && prev.parentSessionId === entry.parentSessionId && prev.cwd === entry.cwd
         && prev.title === entry.title && prev.depth === entry.depth
+        && prev.waitingApproval === entry.waitingApproval
       ) return prev
       this.entryCache.set(entry.sessionId, entry)
       return entry

packages/client/runtime/src/client/sessions/service.ts

@@ -40,6 +40,8 @@ export interface SessionSummary {
   cwd?: string
   parentId?: SessionId
   running: boolean
+  /** An approval question is pending on this session (sidebar amber-dot state). */
+  waitingApproval: boolean
   /**
    * Empty-log bit (host summary derivation mirror). New Session reuses a blank
    * one targeting the same workspace. Filtering stays with the consumer: the
@@ -292,6 +294,11 @@ export class SessionsService implements ISessions {
     this.manager.handleConnected()
   }
 
+  /** Drop generation-scoped live interaction state the moment a connection generation dies. */
+  handleDisconnected(): void {
+    this.manager.handleDisconnected()
+  }
+
   /**
    * Create a session on the host. Resolution guarantee: by the time the
    * promise resolves, the created session is in the list store and
@@ -463,6 +470,7 @@ export class SessionsService implements ISessions {
         id: entry.sessionId,
         displayTitle: displayTitleOf(entry.title, entry.cwd, entry.sessionId),
         running: entry.running,
+        waitingApproval: entry.waitingApproval,
         blank: entry.blank,
         updatedAt: entry.updatedAt,
         ...(entry.title !== undefined ? { title: entry.title } : {}),

packages/client/runtime/src/client/sessions/session.ts

@@ -257,6 +257,21 @@ export class Session implements SessionFace {
     return result
   }
 
+  /**
+   * Execute one slash-command line against this session's agent — pure
+   * admission semantics (the host executor durably logs the lifecycle;
+   * outcomes render as flow nodes, never as a response echo).
+   * @param line - the full command line, leading slash included.
+   * @returns the admission result, or the error branch on transport failure.
+   */
+  async command(line: string): Promise<RpcResult<{ matched: boolean }>> {
+    try {
+      return (await this.api.commands.execute({ sessionId: this.sessionId, line })).result
+    } catch (error) {
+      return transportError(error)
+    }
+  }
+
   /** First open: pull the tail page (idempotent — in-flight/already-open returns the existing promise). */
   open(): Promise<void> {
     if (this.openState === 'open') return Promise.resolve()
@@ -865,7 +880,10 @@ export class Session implements SessionFace {
       queue: this.queueCache.value,
       running: this.running,
       composerPhase: derivePhase(
-        nodes.length > 0 || partial !== null || this.running || this.pendingCache.value.length > 0,
+        // Command lifecycle nodes are not conversation: running /permission
+        // or /plan on a fresh session keeps the hero (the client mirror of
+        // the host's no-turn sessionBlank predicate).
+        nodes.some(node => node.kind !== 'command') || partial !== null || this.running || this.pendingCache.value.length > 0,
         this.promptAttempted,
       ),
       removed: this.removed,
@@ -938,7 +956,9 @@ function positiveSafeInteger(value: unknown): value is number {
  * object: `hasContent` only grows within a window and `promptAttempted` is
  * sticky, so blank → engaging → active never steps back; a failed first
  * prompt stays engaging (retry semantics — see ComposerPhase).
- * @param hasContent - any conversation material exists (nodes, partial, running turn, pending waits).
+ * @param hasContent - any conversation material exists (non-command nodes,
+ *   partial, running turn, pending waits; command lifecycle rows alone keep
+ *   the session blank).
  * @param promptAttempted - a prompt was initiated on this session object.
  * @returns the derived phase.
  */

packages/client/runtime/src/client/workspaces/service.ts

@@ -2,7 +2,8 @@
 
 import type { Context } from 'cordis'
 import type {
-  IApiClient, RpcError, SessionId, WorkspaceId, WorkspaceView,
+  DirectoryListing, IApiClient, RpcError,
+  SessionId, WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotStore } from '../contract/store.ts'
 import { createSnapshotStore } from '../contract/store.ts'
@@ -30,6 +31,14 @@ export class WorkspaceCreateError extends Error {
   }
 }
 
+/** Structured browse failure so the directory browser can branch on Host business codes. */
+export class DirectoryBrowseError extends Error {
+  constructor(readonly rpcError: RpcError) {
+    super(`directory browse failed: ${rpcError.code}: ${rpcError.message}`)
+    this.name = 'DirectoryBrowseError'
+  }
+}
+
 /** Real Workspace object layer and Host actions. */
 export class WorkspacesService implements IWorkspaces {
   /** UI-facing immutable projection; the manager remains wire truth. */
@@ -172,7 +181,7 @@ export class WorkspacesService implements IWorkspaces {
   }
 
   /**
-   * Open the Host's native directory picker.
+   * Open the Host's native directory picker (the `native` capability).
    * @returns the selected path, or null when the user cancelled.
    */
   async pickDirectory(): Promise<string | null> {
@@ -183,6 +192,30 @@ export class WorkspacesService implements IWorkspaces {
     return response.result.value.path
   }
 
+  /**
+   * List one directory level through the Host's `browse` capability.
+   * @param path - absolute directory to list; absent lists the Host home directory.
+   * @param signal - aborts the wire request (and the Host's scan) when the caller supersedes it.
+   * @returns the level's listing with breadcrumb ancestry.
+   */
+  async listDirectory(path?: string, signal?: AbortSignal): Promise<DirectoryListing> {
+    const response = await this.api.host.listDirectory(path === undefined ? {} : { path }, signal)
+    if (!response.result.ok) throw new DirectoryBrowseError(response.result.error)
+    return response.result.value
+  }
+
+  /**
+   * Create one child directory through the Host's `browse` capability.
+   * @param path - absolute existing parent directory.
+   * @param name - single non-blank path segment.
+   * @returns the created directory's absolute path.
+   */
+  async createDirectory(path: string, name: string): Promise<string> {
+    const response = await this.api.host.createDirectory({ path, name })
+    if (!response.result.ok) throw new DirectoryBrowseError(response.result.error)
+    return response.result.value.path
+  }
+
   /**
    * Open a filesystem path with the Host operating system's default application.
    * @param path - absolute or host-resolvable path.