dsh-ntr 0.3.1 → 0.3.3

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
@@ -223,6 +268,11 @@ export interface UiState {
   chatSessions: ChatSessionView[]
   /** The DSH chat session id {@link chatSessions} was loaded for. */
   chatSessionsFor?: string
+  /**
+   * Live burst aggregate per ACP session id, from `turn/metrics`. Absent means
+   * no measured burst yet; a row's persisted `burst` is the reload seed.
+   */
+  burstStats: Record<string, { outputTokens: number; burstMs: number; turnId: string; final: boolean }>
   /**
    * The agent tag's halo preference (settings-editable display choice). The
    * tag reads it per render; the host answer in `resync` is the authority and
@@ -236,6 +286,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
@@ -636,8 +692,10 @@ export class AcpStore {
     probingModels: {},
     probeErrors: {},
     chatSessions: [],
+    burstStats: {},
     tagHalo: { ...DEFAULT_TAG_HALO },
     approvalDeadlines: undefined,
+    idleRelease: undefined,
     chatTranscripts: {},
     acpMode: {},
     chatBoundAgent: {},
@@ -658,6 +716,13 @@ export class AcpStore {
   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
@@ -783,9 +848,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.
@@ -795,9 +867,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) {
@@ -818,6 +893,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)
   }
@@ -872,7 +948,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
@@ -886,6 +962,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),
@@ -903,8 +982,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) {
@@ -1365,9 +1449,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.
@@ -1386,7 +1470,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.
@@ -1535,6 +1619,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)
@@ -1618,12 +1709,98 @@ 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) ----
 
   /**
@@ -1799,6 +1976,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
@@ -1852,7 +2059,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
@@ -1867,10 +2086,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
@@ -1983,11 +2213,20 @@ 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': {
@@ -2001,11 +2240,20 @@ export class AcpStore {
         // entry would keep reading as a live session (the agent tag's halo
         // breathes on `!released`) until some future turn re-reads the list.
         const chatSessions = this.state.chatSessions.filter(s => s.sessionId !== event.sessionId)
+        // The burst aggregate belongs to this ACP session only; another
+        // session's entry must survive. Only patch when there was an entry.
+        const hadBurst = this.state.burstStats[event.sessionId] !== undefined
+        let burstStats = this.state.burstStats
+        if (hadBurst) {
+          burstStats = { ...burstStats }
+          delete burstStats[event.sessionId]
+        }
         this.mutate({
           sessions,
           activeSessionId: active,
           chatTranscripts: closedTranscripts,
           ...(chatSessions.length !== this.state.chatSessions.length ? { chatSessions } : {}),
+          ...(hadBurst ? { burstStats } : {}),
           permissions: this.state.permissions.filter(p => p.sessionId !== event.sessionId),
           ...(event.reason === 'agent-died'
             ? this.logPatch('error', this.locale('会话因 agent 进程退出而终止', 'session ended: agent process died'), closingSession?.agentId)
@@ -2023,9 +2271,7 @@ 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'
@@ -2076,8 +2322,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: {
@@ -2187,9 +2440,42 @@ export class AcpStore {
         })
         return Promise.resolve()
       }
+      case 'turn/metrics': {
+        // Plugin-side burst aggregate for one ACP session. A late LIVE frame
+        // must not regress a turn this page already saw finalized (frames can
+        // land out of order across a stream reconnect); any other frame writes
+        // the entry. Blocks / sessions stay untouched — this is a metric.
+        const prior = this.state.burstStats[event.sessionId]
+        if (event.final === false && prior !== undefined && prior.final === true && prior.turnId === event.turnId) {
+          return Promise.resolve()
+        }
+        this.mutate({
+          burstStats: {
+            ...this.state.burstStats,
+            [event.sessionId]: {
+              outputTokens: event.outputTokens,
+              burstMs: event.burstMs,
+              turnId: event.turnId,
+              final: event.final,
+            },
+          },
+        })
+        return Promise.resolve()
+      }
       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)
@@ -2365,6 +2651,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)
 }