dsh-ntr 0.3.0 → 0.3.2

package/src/client/store.ts

@@ -6,7 +6,7 @@
  * Deliberately framework-free: React binds through `useSyncExternalStore`.
  */
 
-import type { AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentSavePayload, AgentTestResult, AgentView, ChatSessionView, ChatTranscriptView, ApprovalDeadlinesSetPayload, ApprovalDeadlinesResult, DetectedAgentInfo, PermissionTimeoutMode, PluginUpdateState, PluginVersionResult, SessionView } from '../protocol.ts'
+import type { AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpIdleRelease, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentSavePayload, AgentTestResult, AgentView, ChatSessionView, ChatTranscriptView, ApprovalDeadlinesSetPayload, ApprovalDeadlinesResult, DetectedAgentInfo, IdleReleaseResult, IdleReleaseSetPayload, PermissionTimeoutMode, PluginUpdateState, PluginVersionResult, SessionView } from '../protocol.ts'
 import { DEFAULT_TAG_HALO } from '../protocol.ts'
 
 /** One slash command the ACP agent declared, whole row (the menu draws name, description and `input.hint`). */
@@ -96,6 +96,51 @@ export function permissionsForSession(
   return permissions.filter(permission => permission.dshSessionId === dshSessionId)
 }
 
+/** The branch button's six states (the NTR message-actions plan, §D4). */
+export type ChatForkState =
+  | 'ready'
+  | 'unsupported'
+  | 'released'
+  | 'busy'
+  | 'notTail'
+  | 'hostUnavailable'
+
+/**
+ * The branch click's outcome: the child DSH session id on success, or one
+ * actionable failure line (also flashed into the notice banner — the line is
+ * the conversation's local copy of the same failure).
+ */
+export type ChatForkOutcome = { childId: string } | { failure: string }
+
+/**
+ * The branch button's state for one conversation, in the precedence it renders:
+ * the host service missing beats everything (nothing can work), then the
+ * agent's fork capability, then the session's own state (a parked session
+ * before a running one), then the DOM's tail verdict, and only then ready.
+ *
+ * Every input is a fact someone else owns — the row's `fork` verdict is the
+ * host's, `hostFork` is the structural probe of the runtime's `sessions.fork`,
+ * `isTail` is read from the host's own `[data-turn-tail]` marker, and
+ * `liveRunning` is the SSE-driven running flag (the row's own `running` only
+ * refreshes on a chat-list read, so it would answer last turn). `undefined`
+ * facts degrade CLOSED: no row and no `fork` verdict both read as not-ready,
+ * never as a click-through.
+ */
+export function forkStateOf(
+  row: ChatSessionView | undefined,
+  hostFork: boolean,
+  isTail: boolean,
+  liveRunning?: boolean,
+): ChatForkState {
+  if (!hostFork) return 'hostUnavailable'
+  if (row === undefined) return 'released'
+  if (row.fork === undefined) return 'unsupported'
+  if (row.fork.supported !== true) return row.fork.reason ?? 'unsupported'
+  if (liveRunning === true) return 'busy'
+  if (!isTail) return 'notTail'
+  return 'ready'
+}
+
 /**
  * Compact countdown for one ask, or `undefined` when there is nothing to count
  * down (`wait` mode, or a frame without a deadline). Pure so the formatting is
@@ -135,6 +180,22 @@ export interface ChatTranscript {
   seq: number
 }
 
+/**
+ * One line of the settings page's ACP runtime log. Agent-side notices and
+ * session-release reasons land here (bounded, append order oldest→newest);
+ * failures of the settings page's OWN actions stay in {@link UiState.notice}.
+ */
+export interface AcpLogEntry {
+  id: number
+  at: number
+  level: 'info' | 'error'
+  text: string
+  agentId?: string
+}
+
+/** Cap on retained runtime-log lines; older entries fall off the front. */
+export const LOG_MAX_ENTRIES = 200
+
 export interface UiState {
   open: boolean
   /**
@@ -156,7 +217,15 @@ export interface UiState {
   blocks: Block[]
   permissions: PendingPermission[]
   busy: boolean
+  /**
+   * The settings page's one-line banner for its OWN action failures. Agent-side
+   * runtime messages do not land here; they append to {@link logs} instead.
+   */
   notice?: string
+  /** Agent-side runtime log, append order oldest→newest, capped at {@link LOG_MAX_ENTRIES}. */
+  logs: AcpLogEntry[]
+  /** Lines appended since the user last opened the log; reset by {@link AcpStore.markLogsRead}. */
+  logUnread: number
   /**
    * The plugin's OWN default ACP agent (the panel's ★ gesture) — which agent a
    * new ACP-mode conversation starts on. NOT the deployment default model: that
@@ -212,6 +281,12 @@ export interface UiState {
    * host answer (returned by the same route) is the authority.
    */
   approvalDeadlines?: AcpApprovalDeadlines
+  /**
+   * The idle-release window in force, as the settings page edits it.
+   * Absent on a host half from before the tab existed, which hides the
+   * tab rather than showing a number this browser invented.
+   */
+  idleRelease?: AcpIdleRelease
   /**
    * Per-chat-session "does this conversation run the ACP preset" verdicts, as
    * reported by `session/chat-list` (host-read from the session log). The
@@ -603,6 +678,8 @@ export class AcpStore {
     blocks: [],
     permissions: [],
     busy: false,
+    logs: [],
+    logUnread: 0,
     detectedAgents: [...DEFAULT_KNOWN_PRESETS],
     detecting: false,
     modelCatalogs: {},
@@ -612,6 +689,7 @@ export class AcpStore {
     chatSessions: [],
     tagHalo: { ...DEFAULT_TAG_HALO },
     approvalDeadlines: undefined,
+    idleRelease: undefined,
     chatTranscripts: {},
     acpMode: {},
     chatBoundAgent: {},
@@ -625,11 +703,20 @@ export class AcpStore {
 
   private readonly listeners = new Set<Listener>()
   private source?: EventSource
+  /** Monotonic id source for {@link AcpLogEntry}s (never reset by `clearLogs`). */
+  private logSeq = 0
   private readonly lastSeq = new Map<string, number>()
   /** Sessions with a finalized turn (dedups the cancel-fallback + late real turn/end pair). */
   private readonly openTurns = new Set<string>()
   /** In-flight `session/chat-list` reads, keyed by chat session id. */
   private readonly chatSessionReads = new Map<string, { dropped: boolean; done: Promise<void> }>()
+  /**
+   * ACP session ids whose chat-list row was requested mid-turn (one read each).
+   * A conversation's first ACP session does not exist when the composer's
+   * mount/running read fires, so its first `usage_update` would find no row to
+   * patch; `turn/start` asks again once the host has materialized the session.
+   */
+  private readonly chatSessionRowReads = new Set<string>()
   /**
    * Chat sessions whose list has answered at least once in this page. The
    * FIRST answer only seeds the lock; a lock appearing on a later answer is a
@@ -712,6 +799,24 @@ export class AcpStore {
     for (const listener of [...this.listeners]) listener()
   }
 
+  /**
+   * Build the log patch for one line. Does NOT mutate: the caller merges it
+   * into the single `mutate` call it was already making for the same event.
+   */
+  private logPatch(level: 'info' | 'error', text: string, agentId?: string): Pick<UiState, 'logs' | 'logUnread'> {
+    const entry: AcpLogEntry = {
+      id: ++this.logSeq,
+      at: Date.now(),
+      level,
+      text,
+      ...(agentId === undefined ? {} : { agentId }),
+    }
+    return {
+      logs: [...this.state.logs, entry].slice(-LOG_MAX_ENTRIES),
+      logUnread: this.state.logUnread + 1,
+    }
+  }
+
   // ---- Streaming update coalescing ----
 
   /**
@@ -737,9 +842,16 @@ export class AcpStore {
       else list.push(item)
     }
     let chatTranscripts = this.state.chatTranscripts
+    let chatSessions = this.state.chatSessions
     let blocksChanged = false
     for (const [sessionId, items] of bySession) {
       const last = items[items.length - 1]
+      // `usage_update` is state, not stream content: it never becomes a block,
+      // but both observed snapshots that carry usage must move with it —
+      // otherwise the ACP view header and the composer's occupancy ring only
+      // refresh when some other RPC re-reads the session.
+      const usage = usageOfBatch(items)
+      if (usage !== undefined) chatSessions = withSessionUsage(chatSessions, sessionId, usage)
       // The observed transcript folds every frame (a watched session's cards
       // and prose); blocks are copied only when something actually changed, so
       // a usage-only tick costs one record object, not a re-render payload.
@@ -749,9 +861,12 @@ export class AcpStore {
         for (const item of items) {
           if (foldUpdate(record.blocks, item.update as Record<string, unknown>)) changed = true
         }
+        const session = usage !== undefined && !sameUsage(record.session.usage, usage)
+          ? { ...record.session, usage }
+          : record.session
         chatTranscripts = {
           ...chatTranscripts,
-          [sessionId]: { ...record, seq: last.seq, ...(changed ? { blocks: [...record.blocks] } : {}) },
+          [sessionId]: { ...record, session, seq: last.seq, ...(changed ? { blocks: [...record.blocks] } : {}) },
         }
       }
       if (sessionId !== this.state.activeSessionId) {
@@ -772,6 +887,7 @@ export class AcpStore {
     }
     const patch: Partial<UiState> = {}
     if (chatTranscripts !== this.state.chatTranscripts) patch.chatTranscripts = chatTranscripts
+    if (chatSessions !== this.state.chatSessions) patch.chatSessions = chatSessions
     if (blocksChanged) patch.blocks = [...this.state.blocks]
     if (Object.keys(patch).length > 0) this.mutate(patch)
   }
@@ -826,7 +942,7 @@ export class AcpStore {
   /** Snapshot refresh used on panel open and after a stream outage. */
   async resync(): Promise<void> {
     try {
-      const [{ agents }, { sessions }, defaultAgentInfo, detectResult, presetResult, tagHaloResult, deadlinesResult, versionResult] = await Promise.all([
+      const [{ agents }, { sessions }, defaultAgentInfo, detectResult, presetResult, tagHaloResult, deadlinesResult, idleReleaseResult, versionResult] = await Promise.all([
         this.call<{ agents: AgentView[] }>('agents/list'),
         this.call<{ sessions: SessionView[] }>('sessions/list'),
         // The plugin's OWN default ACP agent — a plugin-private id, not a DSH
@@ -840,6 +956,9 @@ export class AcpStore {
         // `undefined` (older half) hides the deadline card instead of showing a
         // number this browser made up.
         this.call<ApprovalDeadlinesResult>('ui/approval-deadlines').catch(() => ({ deadlines: undefined })),
+        // `undefined` (older half) hides the tab instead of showing a
+        // number this browser made up.
+        this.call<IdleReleaseResult>('ui/idle-release').catch(() => ({ idleRelease: undefined })),
         // The settings badge's data source; older halves answer `unknown
         // endpoint`, which hides the badge.
         this.call<PluginVersionResult>('plugin/version').catch(() => null),
@@ -857,8 +976,13 @@ export class AcpStore {
         preset: presetResult?.preset ?? undefined,
         tagHalo: tagHaloResult?.halo ?? { ...DEFAULT_TAG_HALO },
         approvalDeadlines: deadlinesResult.deadlines,
+        idleRelease: idleReleaseResult.idleRelease,
         pluginVersion: versionResult?.version !== undefined && versionResult.version !== '' ? versionResult.version : undefined,
       })
+      // `sessions/list` is the `/acp` RPC face; the composer's chat rows
+      // (agent modes, occupancy) are a separate list. A reconnect must refresh
+      // that list too or the ring keeps a pre-outage sample until a turn ends.
+      if (this.state.chatSessionsFor !== undefined) void this.loadChatSessions(this.state.chatSessionsFor)
       const active = this.state.activeSessionId ?? sessions[0]?.sessionId
       if (active !== undefined) await this.loadTranscript(active)
     } catch (error) {
@@ -1319,9 +1443,9 @@ export class AcpStore {
    * the frame's authority.
    */
   loadChatSessions(dshSessionId: string, options?: { settleVerdict?: boolean }): Promise<void> {
-    // Two composer entries read this (the agent-mode control and the ACP
-    // cluster) and both re-read when a turn settles; one round-trip answers
-    // for both instead of two racing ones. A caller arriving mid-read waits
+    // The composer entries (agent-mode control, ACP cluster, occupancy ring)
+    // read this and re-read when a turn settles; one round-trip answers for
+    // all of them instead of racing reads. A caller arriving mid-read waits
     // for THAT read rather than returning immediately: the slash source's
     // one-shot "do I have a verdict yet?" ask is only useful if it can
     // receive the answer of a read already in flight.
@@ -1340,7 +1464,7 @@ export class AcpStore {
   ): Promise<void> {
     const settle = options?.settleVerdict === true || !this.acpModeLive.has(dshSessionId)
     try {
-      const { sessions, acpMode, boundAgentId, lockedAgentId, choice } = await this.call<{ sessions: ChatSessionView[]; acpMode?: boolean; boundAgentId?: string; lockedAgentId?: string; choice?: AcpConversationChoice }>('session/chat-list', { dshSessionId, refresh: true })
+      const { sessions = [], acpMode, boundAgentId, lockedAgentId, choice } = await this.call<{ sessions: ChatSessionView[]; acpMode?: boolean; boundAgentId?: string; lockedAgentId?: string; choice?: AcpConversationChoice }>('session/chat-list', { dshSessionId, refresh: true })
       // A committed `agent-preset/selected` frame may have settled this
       // session's verdict while the read was in flight; the host answer then
       // describes the log as of BEFORE that switch and must not overwrite it.
@@ -1489,6 +1613,13 @@ export class AcpStore {
    * being the one authorized exception. Same no-op-when-unchanged discipline as
    * the other accessors, so a frame restating the held verdict costs no
    * listener churn.
+   *
+   * The seat gate (`syncAcpMode`) is the SECOND caller: it folds the runtime
+   * row's own `agentPreset` — the same session-log source the frames announce —
+   * through here, in both directions. That hands the row the frame's authority
+   * on purpose (one provenance, one rank): a stale projection is corrected by
+   * the gate's next evaluation with fresher row data, and only HOST READS are
+   * barred from regressing what the runtime itself already said.
    */
   noteAcpMode(dshSessionId: string, acpMode: boolean): void {
     this.acpModeLive.add(dshSessionId)
@@ -1572,10 +1703,96 @@ export class AcpStore {
   async setChatSessionMode(dshSessionId: string, modeId: string, agentId?: string): Promise<void> {
     try {
       await this.call('session/chat-mode-set', { dshSessionId, modeId, ...(agentId === undefined ? {} : { agentId }) })
+      const safeAgent = (agentId && agentId.trim()) || undefined
+      this.writeChoice(dshSessionId, choice => ({ ...choice, mode: modeId }), safeAgent)
+      if (this.state.chatSessionsFor === dshSessionId) {
+        const owner = safeAgent ?? this.state.chatChoice[dshSessionId]?.agentId ?? this.state.chatBoundAgent[dshSessionId] ?? this.state.defaultAgent
+        let changed = false
+        const chatSessions = this.state.chatSessions.map(s => {
+          if (s.agentId !== owner || !s.modes || s.modes.currentModeId === modeId) return s
+          changed = true
+          return { ...s, modes: { ...s.modes, currentModeId: modeId } }
+        })
+        if (changed) this.mutate({ chatSessions })
+      }
+    } catch (error) {
+      this.flashError(error)
+    }
+    await this.loadChatSessions(dshSessionId)
+  }
+
+  /**
+   * Bring the conversation's released ACP session back on a fresh process —
+   * the released banner's explicit form of the "next message resumes it"
+   * promise (`session/chat-resume`). A failure is reported through the notice
+   * AND rethrown (the `respondPermission` contract), so the banner can pin
+   * the message beside the button the user just pressed; the binding is
+   * re-read either way so the row follows the host's real answer.
+   */
+  async resumeChatSession(dshSessionId: string): Promise<void> {
+    let failure: unknown
+    try {
+      await this.call('session/chat-resume', { dshSessionId })
     } catch (error) {
       this.flashError(error)
+      failure = error
     }
     await this.loadChatSessions(dshSessionId)
+    if (failure !== undefined) throw failure
+  }
+
+  /**
+   * Branch one conversation (the NTR branch button's click): the fixed
+   * two-stage order — the HOST forks the DSH session tree first (copied
+   * history, `(1)` title, workspace), then the plugin adopts the ACP side via
+   * `session/chat-fork-adopt`, which runs the agent's own `session/fork` so
+   * the child actually remembers the parent context. Host first is structural:
+   * ACP fork has no cut-point parameter and nothing to return to if the host
+   * half failed second (see the plan's §D7).
+   *
+   * Resolves `{ childId }` on success, or `{ failure }` with one actionable
+   * line — the reason is ALSO flashed into the notice banner (a user-action
+   * failure, so the banner is its surface), and the local line is what the
+   * conversation renders beside the button (the user is not on the settings
+   * page). A failed adopt leaves the child an ordinary copied-history
+   * conversation (its first message starts a fresh `session/new` — today's
+   * behavior), never a half-bound one, and NOTHING is opened.
+   *
+   * `forkHost` is the runtime's `sessions.fork` face, resolved structurally by
+   * the entry and injected here: the store stays transport-free.
+   */
+  async forkChatSession(
+    dshSessionId: string,
+    forkHost: (sessionId: string) => Promise<unknown>,
+  ): Promise<ChatForkOutcome> {
+    let childId: unknown
+    try {
+      childId = await forkHost(dshSessionId)
+    } catch (error) {
+      const failure = error instanceof Error ? error.message : String(error)
+      this.flashError(failure)
+      return { failure }
+    }
+    if (typeof childId !== 'string' || childId === '') {
+      const failure = this.locale(
+        '宿主没有返回分支会话，分支未完成。',
+        'The host returned no branched session; the branch did not complete.',
+      )
+      this.flashError(new Error(failure))
+      return { failure }
+    }
+    try {
+      await this.call('session/chat-fork-adopt', { dshSessionId: childId, parentDshSessionId: dshSessionId })
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      const failure = this.locale(
+        `分支会话已创建，但没有接上 agent 的上下文（${reason}）；在子会话里发送的第一条消息会开启全新会话。`,
+        `The branched session was created but the agent context was not attached (${reason}); its first message will start a fresh session.`,
+      )
+      this.flashError(new Error(failure))
+      return { failure }
+    }
+    return { childId }
   }
 
   // ---- ACP transcript observation (the conversation's ACP view) ----
@@ -1753,6 +1970,36 @@ export class AcpStore {
     await this.writeApprovalDeadlines({ reset: true })
   }
 
+  /**
+   * Write the idle-release window (in ms).
+   *
+   * The host answer — the same route returns the window now in force — is
+   * the authority, so an optimistic write that the host trims self-corrects
+   * instead of drifting from what runs.
+   */
+  async setIdleRelease(idleTimeoutMs: number): Promise<void> {
+    await this.writeIdleRelease({ idleTimeoutMs })
+  }
+
+  /**
+   * Drop the persisted override: the config file (or the built-in default)
+   * decides again.
+   */
+  async resetIdleRelease(): Promise<void> {
+    await this.writeIdleRelease({ reset: true })
+  }
+
+  private async writeIdleRelease(payload: IdleReleaseSetPayload): Promise<void> {
+    const previous = this.state.idleRelease
+    try {
+      const result = await this.call<IdleReleaseResult>('ui/idle-release-set', payload)
+      this.mutate({ idleRelease: result.idleRelease })
+    } catch (error) {
+      this.mutate({ idleRelease: previous })
+      this.flashError(error)
+    }
+  }
+
   private async writeApprovalDeadlines(payload: ApprovalDeadlinesSetPayload): Promise<void> {
     const previous = this.state.approvalDeadlines
     // Optimistic only where it is safe: the effective numbers and the mode move
@@ -1806,7 +2053,19 @@ export class AcpStore {
       // Optimistic for the same reason the binding is: the host recorded the
       // pick, and a conversation with no ACP session yet would otherwise show
       // the agent's default until its first turn created one.
-      this.writeChoice(dshSessionId, choice => ({ ...choice, modelId }), agentId)
+      const safeAgent = (agentId && agentId.trim()) || undefined
+      const targetAgent = safeAgent ?? (modelId ? splitModelAgentId(modelId) : undefined)
+      this.writeChoice(dshSessionId, choice => ({ ...choice, modelId }), targetAgent)
+      if (this.state.chatSessionsFor === dshSessionId) {
+        const owner = targetAgent ?? this.state.chatChoice[dshSessionId]?.agentId ?? this.state.chatBoundAgent[dshSessionId] ?? this.state.defaultAgent
+        let changed = false
+        const chatSessions = this.state.chatSessions.map(s => {
+          if (s.agentId !== owner || s.modelId === modelId) return s
+          changed = true
+          return { ...s, modelId }
+        })
+        if (changed) this.mutate({ chatSessions })
+      }
     } catch (error) {
       this.flashError(error)
       throw error
@@ -1821,10 +2080,21 @@ export class AcpStore {
         ...(effort === undefined ? {} : { effort }),
         ...(agentId === undefined ? {} : { agentId }),
       })
+      const targetAgent = (agentId && agentId.trim()) || undefined
       this.writeChoice(dshSessionId, choice => {
         const { effort: _dropped, ...rest } = choice
         return effort === undefined ? rest : { ...rest, effort }
-      }, agentId)
+      }, targetAgent)
+      if (this.state.chatSessionsFor === dshSessionId) {
+        const owner = targetAgent ?? this.state.chatChoice[dshSessionId]?.agentId ?? this.state.chatBoundAgent[dshSessionId] ?? this.state.defaultAgent
+        let changed = false
+        const chatSessions = this.state.chatSessions.map(s => {
+          if (s.agentId !== owner || s.reasoningEffort === effort) return s
+          changed = true
+          return { ...s, reasoningEffort: effort }
+        })
+        if (changed) this.mutate({ chatSessions })
+      }
     } catch (error) {
       this.flashError(error)
       throw error
@@ -1895,6 +2165,17 @@ export class AcpStore {
     this.mutate({ notice: undefined })
   }
 
+  /** Drop every retained runtime-log line (the unread counter restarts too). */
+  clearLogs(): void {
+    this.mutate({ logs: [], logUnread: 0 })
+  }
+
+  /** The user looked at the log: clear the unread badge. */
+  markLogsRead(): void {
+    if (this.state.logUnread === 0) return
+    this.mutate({ logUnread: 0 })
+  }
+
   private flashError(error: unknown): void {
     this.mutate({ notice: error instanceof Error ? error.message : String(error) })
   }
@@ -1904,7 +2185,7 @@ export class AcpStore {
   private applyEvent(event: AcpEvent): Promise<void> {
     switch (event.type) {
       case 'agent/notice': {
-        this.mutate({ notice: event.text })
+        this.mutate(this.logPatch(event.level, event.text, event.agentId))
         return Promise.resolve()
       }
       case 'agent/status': {
@@ -1926,14 +2207,24 @@ export class AcpStore {
         return Promise.resolve()
       }
       case 'session/meta': {
-        // Host re-published the session view after mode/config changes.
+        // Host re-published the session view after mode/config changes or a
+        // resume. The composer's occupancy ring reads the chat-list row, so
+        // that row must follow the snapshot's usage too — including an absent
+        // one, which must clear an older reading rather than outlive it.
         const sessions = this.state.sessions.some(s => s.sessionId === event.sessionId)
           ? this.state.sessions.map(s => (s.sessionId === event.sessionId ? event.session : s))
           : this.state.sessions
-        this.mutate({ sessions, ...this.watchedSessionPatch(event.sessionId, event.session) })
+        let chatSessions = withSessionUsage(this.state.chatSessions, event.sessionId, event.session.usage)
+        chatSessions = withSessionModes(chatSessions, event.sessionId, event.session.modes)
+        this.mutate({
+          sessions,
+          ...(chatSessions === this.state.chatSessions ? {} : { chatSessions }),
+          ...this.watchedSessionPatch(event.sessionId, event.session),
+        })
         return Promise.resolve()
       }
       case 'session/closed': {
+        const closingSession = this.state.sessions.find(s => s.sessionId === event.sessionId)
         const sessions = this.state.sessions.filter(s => s.sessionId !== event.sessionId)
         const active = this.state.activeSessionId === event.sessionId ? sessions[0]?.sessionId : this.state.activeSessionId
         this.openTurns.delete(event.sessionId)
@@ -1949,7 +2240,9 @@ export class AcpStore {
           chatTranscripts: closedTranscripts,
           ...(chatSessions.length !== this.state.chatSessions.length ? { chatSessions } : {}),
           permissions: this.state.permissions.filter(p => p.sessionId !== event.sessionId),
-          ...(event.reason === 'agent-died' ? { notice: this.locale('会话因 agent 进程退出而终止', 'session ended: agent process died') } : {}),
+          ...(event.reason === 'agent-died'
+            ? this.logPatch('error', this.locale('会话因 agent 进程退出而终止', 'session ended: agent process died'), closingSession?.agentId)
+            : {}),
         })
         return Promise.resolve()
       }
@@ -1963,9 +2256,32 @@ export class AcpStore {
         // The composer's own list (`session/chat-list` views) must flip too, or
         // the agent tag's live halo keeps breathing for a process that is gone:
         // nothing else re-reads this list until the next turn settles.
-        const chatSessions = this.state.chatSessions.some(s => s.sessionId === event.sessionId)
-          ? this.state.chatSessions.map(s => (s.sessionId === event.sessionId ? { ...s, released: true } : s))
-          : this.state.chatSessions
+        const chatSessions = withSessionReleased(this.state.chatSessions, event.sessionId, true)
+        // One runtime-log line per release cause; `idle` stays silent on
+        // purpose (an expected lifecycle transition, not a fault).
+        const cause = event.cause ?? 'died'
+        let log: Partial<Pick<UiState, 'logs' | 'logUnread'>> = {}
+        if (cause === 'workspace') {
+          log = this.logPatch('info', this.locale(
+            'agent 为切换工作区重启，会话已挂起；再次发送消息将自动恢复。',
+            'agent restarted for its workspace; the session is paused and will resume on your next message.',
+          ), event.session.agentId)
+        } else if (cause === 'resume-failed') {
+          log = this.logPatch('error', this.locale(
+            '会话恢复失败；再次发送消息将重试恢复。',
+            'session resume failed; your next message will retry it.',
+          ), event.session.agentId)
+        } else if (cause === 'stalled') {
+          log = this.logPatch('error', this.locale(
+            'agent 未响应卡死的回合，会话已挂起；再次发送消息将自动恢复。',
+            'agent did not acknowledge the stalled turn; the session is paused and will resume on your next message.',
+          ), event.session.agentId)
+        } else if (cause === 'died') {
+          log = this.logPatch('error', this.locale(
+            'agent 进程已退出，会话已挂起；再次发送消息将自动恢复。',
+            'agent process died; the session is paused and will resume on your next message.',
+          ), event.session.agentId)
+        }
         this.mutate({
           sessions,
           ...(chatSessions !== this.state.chatSessions ? { chatSessions } : {}),
@@ -1973,10 +2289,7 @@ export class AcpStore {
           // An observed transcript keeps its buffer but flips to released, so
           // the ACP view can say "会恢复" instead of silently looking dead.
           ...this.watchedSessionPatch(event.sessionId, event.session),
-          notice: this.locale(
-            'agent 进程已退出，会话已挂起；再次发送消息将自动恢复。',
-            'agent process died; the session is paused and will resume on your next message.',
-          ),
+          ...log,
         })
         return Promise.resolve()
       }
@@ -1994,8 +2307,15 @@ export class AcpStore {
         // an observed transcript must drop both its blocks and its watermark
         // or the replay would be read as a gap and refetched forever.
         const watched = this.state.chatTranscripts[event.sessionId]
+        // ...and the composer's own list must flip back to live on the same
+        // event (mirror of the `session/released` flip): the released banner
+        // and the tag's halo read that row, and nothing else re-reads it until
+        // a turn settles — a resume would leave the banner claiming a parked
+        // process that is already back.
+        const chatSessions = withSessionReleased(this.state.chatSessions, event.sessionId, false)
         this.mutate({
           sessions,
+          ...(chatSessions === this.state.chatSessions ? {} : { chatSessions }),
           ...(isActive ? { blocks: [] } : {}),
           ...(watched === undefined ? {} : {
             chatTranscripts: {
@@ -2108,6 +2428,17 @@ export class AcpStore {
       case 'turn/start': {
         this.openTurns.add(event.sessionId)
         this.markWatchedRunning(event.sessionId, true)
+        // The session materializes inside this turn; if the composer's list
+        // has not seen its row yet (the mount/running read beat session/new),
+        // read once now so the occupancy ring has a row for the live usage
+        // ticks. The per-session set bounds this to one extra read.
+        const chatSessionId = this.state.chatSessionsFor
+        if (chatSessionId !== undefined
+          && !this.state.chatSessions.some(row => row.sessionId === event.sessionId)
+          && !this.chatSessionRowReads.has(event.sessionId)) {
+          this.chatSessionRowReads.add(event.sessionId)
+          void this.loadChatSessions(chatSessionId)
+        }
         if (event.sessionId === this.state.activeSessionId) {
           this.state.blocks.push({ kind: 'user', text: event.text })
           trimBlocks(this.state.blocks)
@@ -2283,6 +2614,118 @@ export const STATE_ONLY_UPDATES: ReadonlySet<string> = new Set([
   'session_info_update',
 ])
 
+/**
+ * Context occupancy carried by one raw `usage_update` frame, in the shape the
+ * session snapshots already use. A malformed frame is ignored (the last good
+ * sample stays on screen) instead of zeroing the meter.
+ */
+export function usageFromUpdate(update: Record<string, unknown>): SessionView['usage'] | undefined {
+  const used = update.used
+  const size = update.size
+  if (typeof used !== 'number' || !Number.isFinite(used)) return undefined
+  if (typeof size !== 'number' || !Number.isFinite(size)) return undefined
+  const cost = update.cost
+  if (cost !== null && typeof cost === 'object' && !Array.isArray(cost)) {
+    const row = cost as Record<string, unknown>
+    if (typeof row.amount === 'number' && Number.isFinite(row.amount)
+      && typeof row.currency === 'string' && row.currency !== '') {
+      return { used, size, cost: { amount: row.amount, currency: row.currency } }
+    }
+  }
+  return { used, size }
+}
+
+function sameUsage(left: SessionView['usage'], right: SessionView['usage']): boolean {
+  if (left === right) return true
+  if (left === undefined || right === undefined) return false
+  if (left.used !== right.used || left.size !== right.size) return false
+  const leftCost = left.cost
+  const rightCost = right.cost
+  if (leftCost === undefined || rightCost === undefined) return leftCost === rightCost
+  return leftCost.amount === rightCost.amount && leftCost.currency === rightCost.currency
+}
+
+/** Patch one session row's usage; other rows and an unchanged value keep their identities. */
+function withSessionUsage<T extends { sessionId: string; usage?: SessionView['usage'] }>(
+  rows: T[],
+  sessionId: string,
+  usage: SessionView['usage'],
+): T[] {
+  let changed = false
+  const next = rows.map(row => {
+    if (row.sessionId !== sessionId || sameUsage(row.usage, usage)) return row
+    changed = true
+    return { ...row, usage }
+  })
+  return changed ? next : rows
+}
+
+/**
+ * Flip one chat row's `released` flag (release/resume bookkeeping). The
+ * composer's own list (`session/chat-list` rows) has no other live writer —
+ * `session/released` must mark it, `session/reset` must un-mark it, or the
+ * agent tag's halo and the released banner read yesterday's process state.
+ */
+function withSessionReleased<T extends { sessionId: string; released?: boolean }>(
+  rows: T[],
+  sessionId: string,
+  released: boolean,
+): T[] {
+  let changed = false
+  const next = rows.map(row => {
+    if (row.sessionId !== sessionId || (row.released === true) === released) return row
+    changed = true
+    return { ...row, released }
+  })
+  return changed ? next : rows
+}
+
+function sameModes(a?: SessionView['modes'], b?: SessionView['modes']): boolean {
+  if (a === b) return true
+  if (!a || !b) return false
+  if (a.currentModeId !== b.currentModeId) return false
+  const aModes = a.availableModes ?? []
+  const bModes = b.availableModes ?? []
+  if (aModes.length !== bModes.length) return false
+  return aModes.every((m, i) => {
+    const o = bModes[i]
+    return m != null && o != null && m.id === o.id && m.name === o.name && m.description === o.description
+  })
+}
+
+function withSessionModes<T extends { sessionId: string; modes?: SessionView['modes'] }>(
+  rows: T[],
+  sessionId: string,
+  modes?: SessionView['modes'],
+): T[] {
+  if (!modes) return rows
+  let changed = false
+  const next = rows.map(row => {
+    if (row.sessionId !== sessionId || sameModes(row.modes, modes)) return row
+    changed = true
+    return { ...row, modes }
+  })
+  return changed ? next : rows
+}
+
+function splitModelAgentId(modelId: string): string | undefined {
+  const at = modelId.indexOf('@')
+  const agent = at === -1 ? modelId.trim() : (at === 0 ? '' : modelId.slice(0, at).trim())
+  return agent || undefined
+}
+
+/** Last well-formed `usage_update` in one coalesced batch (later ticks win). */
+function usageOfBatch(items: ReadonlyArray<{ update: unknown }>): SessionView['usage'] | undefined {
+  let usage: SessionView['usage'] | undefined
+  for (const item of items) {
+    const update = item.update as Record<string, unknown>
+    if (update.sessionUpdate !== 'usage_update') continue
+    const parsed = usageFromUpdate(update)
+    if (parsed !== undefined) usage = parsed
+  }
+  return usage
+}
+
 function trimBlocks(blocks: Block[]): void {
   if (blocks.length > MAX_BLOCKS) blocks.splice(0, blocks.length - MAX_BLOCKS)
 }