feat(gui): step1 skeleton — dsc web serves built web UI over booted harness host

Five new modules: apps/dsc (bin: parseArgs + node:http static server +
signal shutdown), packages/host/apiproxy (programmatic harness core
composition, agents:[]), packages/client/web-runtime (React-free browser
runtime), packages/client/web-ui (React mount), apps/web (vite build
entry producing dist consumed by apps/dsc via package exports).

Root wiring: apps/* workspace glob, dsh-* paths for host/client groups,
demo:web script, apps/web/dist gitignore. No protocol/API routes yet —
contract lands in step2 (see missions/tasks/20260719-1902-apiproxy-api-design).

Includes the design + implementation archives (spec v2.1, deepseekchat
baseline and harness boot research, implementation run log).

Acceptance: 12/12 passed incl. real-key llm.stream smoke (51 chunks).

feat(gui): apiproxy — four-quadrant RPC contract + fetch carriers, live end to end

Contract layer (src/api/, 14 files): four named wire message types
(ClientRequest / ServerResponse / ServerRequest / ClientResponse) as a
discriminated union over strict bidirectional rpcId (initiator mints,
responder echoes; channel and message fully decoupled — HTTP is the
client->server pipe, SSE the reverse); narrow RpcRequest<P>/
RpcResponse<T> signature forms; RpcMethodMap with RequestPayload<K>/
ResponseValue<K> derivation; typed RpcError details map; approval/
question responses modeled as ClientResponse via a single /api/respond
endpoint (RpcReceipt carrier ack); zod schemas anchored per Wire<T>
against exactOptionalPropertyTypes.

impl/api-proxy.ts: describe/list/create, both SSE streams (frame queue
pump, subscribed baseline, lifecycle frames, signal cleanup); history
pages on message boundaries (tail-back scan, partial included in the
tail page); prompt dispatches queue->agent.send / steer->agent.steer
with rpcId carried through MessageSource; cancel for attached sessions;
cold-session resume deduped via a per-id promise map; host-level
provider/model defaults injected at create/resume.

fetch/: mechanical UNARY_ROUTES table, two-level parse with
path==method check, SSE frames completed to ServerRequest full form;
client mints -> narrows -> envelopes outbound, verifies rpcId echo
inbound, streams SSE frames, four-quadrant onEnvelope tap (debug panel
choke point). Real-browser fixes: URL base resolves to location.origin
(hardcoded internal base broke real pages), browser-safe export paths.

Design archives: contract design.md v2.0 with decision log,
core-coverage audit, comparative studies, step2 impl run log. Probed
end to end over real HTTP: prompt -> live model stream -> history
returns the finished reply.

feat(gui): RpcLog debug panel — fixture-driven milestone, playwright-verified 10/10

web-runtime: rpcLog + ui slices (zustand), four-quadrant RpcLogEntry
(client-request / server-response / server-request / client-response),
onEnvelope tap -> microtask-batched pump with 500-entry ring buffer,
ConnectionController (private state, backoff reconnect), fixture API
with fake envelopes (?fixture switch), bootWebRuntime; contract types
via temporary local copies (api-types.ts, swapped for real imports when
W3 client lands).

web-ui: components/panels/RpcLog five-piece set (badge with unread
count, floating panel, direction glyphs per quadrant, same-rpcId
pair highlighting in two families, JSON payload expand, follow/pause,
clear), App shell, utils/formatRelative, light-theme CSS variables with
dark placeholders.

dsc bin: mime lookup fixed to use the actually-served file (naked
'/?query' no longer falls through to octet-stream download); shutdown
closes SSE keep-alive connections so SIGTERM actually exits.

Acceptance: scripts/verify-rpclog-panel.mjs (chromium headless) ALL
PASS 10/10 over design.md §D 1-6.

pkg: add web scripts for building

feat(gui): session milestone — list + conversation over Session OOP, styled RpcLog v2.1

web-runtime: Session/SessionManager object layer (resident instances,
mux frame routing, lineage flattening), foldSurface adapter with padding
sentinels for paged windows, chunk accumulator for streaming partials,
batched change notification (useSyncExternalStore contract), connection
sinks + reconnect fix (the 300ms self-abort reconnect storm that made
the session list flap is gone), fixture rewritten as a scripted host
(60-turn history, typewriter replay, resident pending approval, child
session); temporary contract copies deleted in favor of real apiproxy
imports.

web-ui: sessions screen (list with lineage indent + selection as
container-local state), conversation view (turn grouping, reasoning
fold, tool cards, steering, pending interaction cards, upward paging
with scroll anchoring), input bar with queue/steer/stop; RpcLog panel
restyled per docs/web-styling.md (tokenized palette, quadrant badge
glyphs now vertical ↑↓⇟⇞, pair highlighting, floating shadow).

docs/web-styling.md: living style guide (tokens, visual baseline,
coding rules, evolution log).

Acceptance: verify-session.mjs 31/31, verify-session-real.mjs 5/5
(real model streaming), verify-rpclog-panel.mjs 10/10.

feat(gui): hostruntime split + repo-wide package prefix rename

Package split (design: 20260720-0101-hostruntime-split-design):
dsh-host-runtime carries bootHost + createApiProxy + startHost()
(RunningHost {api, handler, defaults, ctx, dispose} — the seam Electron
and any future shell reuses; ctx is the official front-door mount
point); dsh-host-webserver carries the node:http static+API bridge
(fixed: abort now keys on res 'close' + writableEnded — req 'close'
fires on body end since Node 16 and was killing every SSE stream
instantly, the reconnect-storm root cause); apps/dsc is now a thin
assembly with web/-p subcommands. dsc -p runs the full isomorphic
carrier chain in process (second real protocol consumer; probed
end-to-end against the live model).

Naming rule (user decree): packages under host/ and client/ carry the
directory prefix in their npm name — dsh-host-apiproxy,
dsh-client-web-runtime, dsh-client-web-ui renamed repo-wide in one
frozen batch; explicit tsconfig paths entries added where the wildcard
no longer matches.

Acceptance: verify-session 31/31, verify-rpclog-panel 10/10,
verify-session-real 7/7 (incl. new 12s connection-stability sentinels),
tsc green, dsc web + dsc -p smoke both pass.

refactor(gui): AbstractApiClient class hierarchy — OO client with inheritable seams

AbstractApiClient (apiproxy) carries every protocol invariant: rpcId
minting, four-quadrant envelope wrap/unwrap, zod parsing, SSE frame
parsing, the payload-direct IApiClient surface (callers no longer mint
rpcIds — the carrier does), and the instance-level envelope observation
pump (batched via microtask; moved off module-level globals in
rpc-log.ts, which is now a pure subscriber mapping envelopes into store
entries — the debug panel observes the connection, it is not part of
it).

Platform subclasses own two abstract seams (doFetch, onEnvelope) plus
three protocol-level virtuals for transportless overrides:
InProcessApiClient (apiproxy; dsc -p uses new InProcessApiClient(
host.handler)), WebApiClient (web-runtime), FixtureApiClient (fixture
now subclasses instead of wrapping). Naming per decree: AbstractApiClient
/ IApiClient; ApiProxy stays the impl-side narrow-form contract.

headless.ts call sites drop rpcRequest wrappers (payload-direct);
split-design archive updated with the naming-rule ledger.

tsc green; verify-session 31/31, verify-rpclog-panel 10/10,
verify-session-real 7/7 (12s connection sentinel count=4); dsc -p smoke
CALLER-OK.

feat(gui): InputBar final form — bug batch, deepseekchat layout, single primary button, running locks input

Squashes the whole InputBar iteration batch: IME/caret/auto-grow/focus/dedup
bug fixes, layout aligned to the deepseekchat baseline, single primary button
with hover flyout, finalized button semantics with the Codex-style icon
circle, and running-state locking where stop is the only mid-turn action.
The same batch carried the Chinese-to-English code comment sweep
(density pruned), folded in here.

docs(gui): purge work-log references from code comments

76 design-doc references cleared across the GUI packages: section
pointers inlined as self-contained constraint statements, pure pointer
comments dropped, milestone codenames and ruling tags out, and the 14
contract file headers switched to the formal RFC (the only sanctioned
external reference). web-styling.md now cites the styling RFC instead
of the disposable research archive. grep for work-log reference
variants is clean across the GUI packages.

docs(gui): file-header comments self-contained — drop RFC filename references

RFC renames/reorgs must not require a source sweep (the 2026-07-20
two-way merge proved it). 11 headers lose only the '(RFC …)' tail and
stay self-contained; api-proxy.ts keeps its minimal-first note.

fix(gui): session streaming — freeze interrupted partials, sweep stale running calls, send force-scrolls

Aborted turns never emit the finalizing assistant/message, so the
accumulated partial and its running tool cards kept rendering below
later messages — the "new message lands above the stopped reply"
illusion. turn/end side effects now freeze content-bearing partials
into interrupted terminal nodes (fractional seq keeps flow order; the
live freeze and history replay converge through applyEventSideEffects,
so a refresh reconstructs identical frozen nodes) and turn running tool
cards into interrupted terminal cards; only content-free partials are
swept outright. ConversationView gains the send-force-scroll rule (own
words must be visible) alongside the pre-update atBottom follow flag.
Regressions pinned as E2-4a–c (real host) and §E1-11h (fixture).

feat(gui): webserver hardening verify script

feat(gui): dark-mode toggle pinned to the sidebar bottom

Interim home before the Settings page exists (the button re-homes with
zero logic change — mechanics live in utils/theme.ts): html[data-theme]
flip + dsc.theme localStorage, stored choice wins over the OS
prefers-color-scheme default, applied in mount() before first paint so
a dark reload never flashes light. Moon/sun inline SVG icon button at
the sidebar's pinned bottom row. Pure front-end local concern: no RPC,
no Session/store involvement. Dark sweep of list/conversation/input
card/RPC panel found no unreadable pairs — no token changes needed.

docs(gui): GUI RFCs and web styling handbook

Layering+RPC protocol and web client architecture RFCs (post-reorg,
developer-facing polish folded in) plus the styling engineering
handbook. Mission work logs live in the commit above; PRs can be cut
from this commit to include formal docs only.

fix(gui): client object-layer hardening — audit timing/reference/resilience batches (S3-S5,C1-C3,C5-C8)

fix(gui): carrier error channel + webserver backpressure (audit A1-A5,A7-A10,R2,R5)

feat(gui): session persistence surface — cold list, project cwd, legacy no-cwd retirement

refactor: rename dsc CLI to dsh — apps/cli, bin name, package scope

Includes the root tsconfig project-references fix for host/* and
client/web-runtime (originally a separate build fix commit).

test(gui): three-tier suite — protocol/object/browser lanes, tier-a fill to per-file 100%

test(gui): jsdom lane for web-ui + web-runtime coverage gate entry

docs(gui): GUI testing system RFC (zh)

feat(gui): tool-card views — contract slot, host-computed delivery, three-level card fallback

fix(gui): lint clean across GUI packages — wrap long doc comments, drop dead type args, sync-return methods without awaits

docs(gui): doc-sync mechanical fixes — JSDoc on apiproxy/host exports, RFC sketch fences ignore-check, md-wrap paragraphs, drop missions links, web-ui plain-ts entry

chore(gui): module-graph regen + knip clean — drop dead re-exports, internalize createFixtureApi, scan web-ui tsx and verify mjs scripts

build(gui): wire client/host packages into the lib build shape — tsc references + tsdown (web-ui css-external), lib manifests, cordis peer, apiproxy typed subpaths, vite src aliases

test(gui): host-side per-file 100% coverage — apiproxy schema/carrier suites, webserver http-bridge suite, host-runtime composition suite; client/* coverage excluded pending the browser-side testing work item

docs(gui): package READMEs for the five GUI packages — model-experience audit entries, limitations sections

docs(gui): bilingual RFC pairs + client JSDoc completion — translate the three GUI RFCs to English with i18n records and manifest ratchet, Consequences sections both sides, full client/* export JSDoc, regen doc graphs and RFC index

fix(scripts): doc-typecheck built-declarations mode maps /src/* subpath wildcards (apiproxy browser-safe channels)

docs(gui): apply dsh rename across pr-gates docs — READMEs, layering RFC en, web-ui entry comment, i18n re-record

fix(gui): post-rebase lint reconciliation — wrap main-tree long doc comments, read-through narrowing guards, abortError Error normalization, handleUnary generic justification

fix(gui): post-rebase doc/test reconciliation — align host specs with evolved carrier contracts (sentinel rpcId, stream/error surfacing, url-path transport messages, defaults.cwd), Agent Note titles and relocated links, KV Cache effect sections, JSDoc on evolved exports

fix(gui): second-rebase reconciliation to 509db0cb3 — restore api panel exports the baseline suites consume, knip workspace entries for jsdom lane and apps/web smokes, hoist result narrowing, align testing.md to the narrowed web-ui exclusion

fix(test): vitest-scoped tsconfig maps bare imports for tsx specs — with GUI manifests now pointing at lib, an unmapped importer loaded a second copy of the web-runtime singletons

fix(gui): typecheck + lint clean over the tool-card batch — brand callIds and object-form turn/end reason in the view spec, narrow fixture arg stringification, wrap long v8-ignore comments

docs(gui): export JSDoc for tool-card surfaces + testing-note pairing header

docs: rfc for web testing

feat: add tools to host-runtime

fix(gui): dispatch agent/error via agentEvents in host-runtime spec — mounted invariants plugin rejects raw ctx.emit without the scope carrier

fix(gui): restore GUI knip workspaces + scripts/mjs entries and regenerate lockfile after master rebase

fix(gui): post-rebase gate repairs — drop context-node envelope (master unwrapped injected content envelopes), regen event matrix, condense testing.md web-ui exclusion within budget

fix(session): browser-safe deep-equal in surface — node:util import broke the vite bundle

ci(gates): frontend vite build joins pre-push — node: imports in the client closure pass tsc but break the browser bundle

test(tui): drop the checkout-dependent process.cwd() harness default — a long worktree path pushes the footer token counters past the 88-column fake terminal

test(gui): jsdom behavior E2E — conversation main path over fixture runtime, reconnect banner lifecycle

test(gui): jsdom RPC panel behavior — ledger rows, expand, pairing, pause/clear, follow-pause, payload truncation

test(gui): jsdom tier-2 — InputBar guards, reasoning fold, JSON blocks, message variants, theme, create-then-select; act-harden banner case

test(gui): jsdom tier-3 — ConversationView states/paging/force-bottom, ToolCallCard arms, PendingCard, list rows

test(gui): jsdom tails — view-card variants, LogRow directions, registry hygiene, badge overflow, hook ops, mount glue

test(gui): jsdom tails round 2 — call-ref blocks, resume follow, view precedence, failed create, empty-diff arm

test(gui): jsdom final arms — anchor compensation, follow-off, interval ticks, view halves, node-over-running precedence

test(gui): web-ui joins the per-file 100% coverage gate

Annotation-only src changes plus the config swap. The web-ui exclusion is
replaced by a single index.tsx entry (stale byte-identical duplicate of
mount.tsx, nothing imports it; same entry-glue treatment as bin.ts) and the
coverage include gains .tsx.

v8-ignore sites (each with its reason inline):
- ConversationView 3x ref-null guards; InputBar disabled-click guard
- ToolCallCard both-null arms + windowless-custom argsRaw arm
- LogRow css-module key fallbacks (start/stop block); RpcLogBody 3x ref-null guards
- web-runtime drift from the tool-card batch: fixture presenter catch/str
  typo-guards, dense-array guards (fold-adapter reset, session rebuild,
  fixture backscan), live view-present arm (fixture replays are text-only;
  view vocabulary is covered by the history samples)

test(gui): close the PR #443 host-side coverage gaps — apiproxy client abort arms, api-proxy cold/view paths, webserver drain

- apiproxy fetch/client.ts: 3 new cases (pre-aborted signal short-circuits
  before transport + string reason mapping, non-Error/string reason falls to
  the default AbortError message, signal-less doFetch passthrough)
- runtime/api-proxy.ts: one v8-ignore (summarizeCold cwd arm — list()
  filters cwd-less legacy metas) + api-proxy-cold.spec.ts (cold list merge:
  mtime source, locate-undefined and vanished-log fallbacks, lineage;
  no-persistence/no-factory resume → internal) + 2 view cases (history views
  with meta passthrough and orphan/bad-args/presenterless soft-falls,
  session/disposed open-call cleanup on the mux stream)
- webserver/index.ts: /api/big fixture drives both drain-wait legs (full
  8MiB readback after drain, mid-chunk disconnect wakes via 'close')

feat: app shell

fix: rebase conflicts

fix: coverage

fix(gui): lint clean after rebase — wrap long v8-ignore comments, unconditional v1 detail-block claim

chore(gui): remove browser/probe verify scripts from scripts/

The six GUI acceptance/probe scripts (carrier-errors, rpclog-panel,
session, session-real, webserver-backpressure, webserver-hardening)
leave the repo's scripts/ tree; the three code comments that pointed at
them now describe the coverage lane without naming a script path.

fix(webserver): guard the request callback — one malformed request must not kill the process

The async handle() had no top-level catch, so any throw inside it (a bad
%-escape reaching decodeURIComponent, a client dropping mid-body, a
response stream erroring) became an unhandled rejection and took the whole
process down (audit R1 must-fix). The guard answers 400 when headers are
not out yet, destroys the socket when they are, and reports the failure to
onError (the package never prints). Spec covers all three legs: %-escape
barrage → 400 + server stays alive, non-Error throw wrapped for onError,
mid-stream explosion → socket teardown.

feat: client AGENTS.md

fix: client/AGENTS.md

fix: rebase

feat(gui): T0 cut 1 — 12 client package skeletons with contract stubs, dshClient declarations, tsdown client preset, theme token sheets

feat(gui): T0 cut 2 — pure git mv migration per v3 §11 (connection six, runtime sessions/kernel, ui-conversation chat, ui-primitives markdown family, web shell + e2e)

feat(gui): T0 cuts 3+4 — import rewiring to new package names, .legacy demotion of owner-rewrite files, legacy web-runtime/web-ui/apps-web retired to attic

feat(gui): connection 对账刀——index.ts 精确导出清单替换 export *，intents.legacy 溶解删除

feat(client/ui-slots): SlotCore real implementation — kind semantics, sync version + microtask-batched notify, onMutate bridge

feat(gui): web shell vite alias — retarget to new client packages, shell static surface only

feat(gui): host 侧刀属地半——HostWebPluginRegistry（entries 扫描+internal/plugin 去抖重扫+dshClient 校验+exports./client 解析）、GET /plugins/<id>/client.js 分发端点、GET / 与 SPA fallback 注入 __DSH_BOOT__（webPlugins 可选注入，不传行为不变）

feat(web-react): add use-sync-external-store dep + local shim typings

feat(web-react): bindSnapshotSelector via uSES with-selector shim

feat(gui): ui-layout concession-chain solver — pure computeColumns with contract geometry

feat(gui): ui-layout LayoutService — four persisted stores, clamped actions, list-driven prune

feat(gui): ui-layout AppFrame styles — grid columns, collapse-safe borders, edge drag handles

test(gui): 存量 spec 平移——connection 三件+runtime 六件自 attic 捞回改包名路径全绿；api-helpers 按归属拆分（wire 半留 connection、classifier 半随 conversation.ts 入 runtime）；boot-intents/preinit/rpc-log 随 intents/rpc-log 退役不迁（记 v3 §3.2 溶解项）

feat(client/ui-primitives): StateDot/Button/Pill/Input/Menu atoms, ConnectionBanner de-legacied to pure props, JsonBlock CSS on --dsw tokens

feat(web-react): createSnapshotStore engine (rafFlush batch, persist opt-in, dev freeze) + spec

feat(gui): ui-layout AppFrame — grid tracks, pointer-capture drag handles with rAF throttle, frame ResizeObserver

feat(web-react): useInvoke (external pending store, stable invoke, concurrency count) + spec

test(web-react): bind spec — equality bail, custom eq, zero resubscribe, StrictMode, method sources

feat(gui): ui-layout index rewiring — real exports, client apply provides ctx.layout and defines three slots

feat(web-react): SessionProvider (renderBody deps) + RootBindingProvider + binding contexts + spec

feat(gui): web shell AppRoot boot-page styles — self-contained with neutral token fallbacks

feat(gui): web shell AppRoot — boot gate over loader status, fail-loud plugin failure list

fix(gui): AppRoot gates on explicit settled signal — status-derived readiness races the incrementally filled table

feat(client/ui-theme): ThemeService real implementation — registry with built-in light/dark, apply toggles body[data-ds-dark-theme], third-party token overrides as body inline vars

feat(web-react): scopedSlots outlet (kind matrix, inject WeakMap caches, per-entry error boundary) + spec

feat(gui): web shell module-table seed — pure-library entities for the loader require surface

feat(client/i18n): I18nService real implementation — ns×locale registry, stable bind(ns) reference, zh fallback chain, zh/en skeleton dictionaries

feat(gui): web shell assembly closure — layout exports via module table, SessionProvider + scopedSlots + RootBindingProvider

feat: client/ui-conversation

feat: code

codedoc

build(gui): root bundle green — web shell excluded from the lib workspace (vite app), ui-primitives lib externalizes css side-effect imports (web-ui precedent)

gates(gui): verify-cordis-config follows aggregate tsconfig references (root is a shell over host/client programs); module graph regenerated for the twelve client packages

chore(gui): retire legacy migration sources — every owner rewrite landed (t0-checklist §7 ledger honored); orphan css of retired components removed

gates(gui): knip green groundwork — e2e/tsx entries for the new packages, loader-runtime deps ignored where loading is by specifier string, fake plugin ids un-bare-named, dead test export dropped

chore(client): manifest shape batch A — ui-slots/web-react/ui-primitives invariant companions, files whitelist, cordis+invariants peer/dev, tsconfig refs

chore(client): manifest shape batch B — connection/runtime/ui-conversation/ui-trajectory files whitelist, cordis peer+dev, explicit invariant lib entries (clientBundle signature)

chore(client): manifest shape batch C — i18n/ui-layout/ui-sidebar/ui-theme invariant companions, files whitelist, invariants peer/dev, tsconfig refs

chore(client): manifest shape batch D — web shell gains node-half lib entry + invariant companion + uniform files whitelist

chore(client): drop verified-unused deps — dsh-tools from runtime/ui-conversation (types ride /presentation), ui-primitives+clsx from ui-layout

gates(gui): doc-gate fixes — theme JSDoc prose, three client type-link exemptions, agent-note paths follow the migration, config catalog regenerated

gates(gui): type-equiv manifest follows the types.ts extraction, approval JSDoc keeps its link form, persistence catalog regenerated

docs(gui): per-constant JSDoc on the contract geometry exports (export-jsdoc gate)

test(gates): loader-composition budget covers cold tsx resolution after the program split (was flaking at the default 5s)

docs(gui): README substantiation batch 1 — ui-slots/ui-primitives/web-react/connection: Model Experience short form, real deferred-work ledgers, description accuracy pass

fix(client): theme/i18n dual-entry split — service classes + cordis merges move to src/client (host catalog scanner no longer misclassifies client services), node halves keep types + empty apply; catalogs regenerated

docs(gui): README substantiation batch 2 — runtime/ui-layout/ui-sidebar/ui-conversation: Model Experience short form, package-owned deferred-work ledgers (unload stub, watch approximation, /client value-import rule, global details state, two-state dots, stats duration gap, single-bundle caches)

docs(gui): README substantiation batch 3 — ui-trajectory/ui-theme/i18n/web: Model Experience short form, deferred-work ledgers (placeholder charter, no theme toggle owner, empty locale dictionaries, one-shot rendering); both README gates green

test(scripts): purity spec adopts clientBundle two-arg signature (explicit libEntry, no default)

gates(gui): knip green — declaration-merge dep ignored, fake plugin id assembled at runtime, invariants dep de-duplicated to peer+dev, stale apps/web section dropped

feat(gui): 门禁波次 host 三包 invariant 形状——apiproxy explained-empty 伴生（wire 契约层零事件面）、webserver 真关系伴生（manifest 行必解析出 clientPath，防 __DSH_BOOT__ 广告 404 bundle；apps/cli 发布 webPlugins 键供审计）、runtime 补 files 白名单；三包 exports/files/peer+dev/tsconfig refs 齐 fw-react 形状；constraints+invariants 双 gate 零违规

build(client): ui-layout/ui-sidebar tsdown configs adopt the explicit two-arg clientBundle signature (orphaned follow-up of the manifest shape batch)

refactor(gui): shell boot becomes a library face — bootWebShell(el) exported for the apps/web entry; main.ts retired

refactor(gui): exports 纪律刀1——ui-theme/i18n node index 收敛为只空 apply（Translate/LocaleDict/ThemeTokens 类型下沉 src/client/），ui-conversation 的 I18nService import 改 /client 子路径

build(typecheck): converge to root host aggregate + tsconfig.client.json — delete tsconfig.host.json, verify-cordis-config seeds both aggregates

feat(gui): apps/web restored as the vite application — thin main over bootWebShell; dsh-client-web becomes a plain lib (index exports shell surface, vite files and e2e moved out)

chore(gates): knip.json rewritten on the master base — same semantics, minimal diff (formatting churn dropped)

docs(gui): 时效清扫②——testing.md 删 web-ui 覆盖豁免残句；web-styling.md 加 token 换代头注（--dsw-* 现行、工程约束条款仍有效并注明收编处）

docs(gui): 时效清扫③——四对 GUI Agent Note 加路径更新头注（web-runtime/web-ui/dsh-frontend→现行 12 包结构；设计结论存续声明；双语对同步）

docs(gui): 时效清扫③b——四对 note 头注的 i18n 配对哈希重录

build(typecheck): minimal-diff tsconfig shape — drop root files entry (purity spec + preset move to client program), compress comments, drop redundant util/home root ref

feat(gui): apps/web restoration follow-through — dsh-frontend package name, cli dist resolve, root build:web filter, tsdown exemption dropped, vitest web lane + knip + client aggregate retargeted, e2e paths rebased

refactor(gui): exports 纪律刀2——connection wire 六件 git mv 进 src/client/（wire 即该 dshClient 插件的 client 半），node index=只空 apply，/client 半边整面导出（v3 §3.2 清单原样），包内 tests 改 src/client 直取

refactor(gui): exports 纪律刀3——runtime 实现整体下沉 src/client/（sessions/slots/loader；契约类型与 cordis merge 随迁 client/index），node index=只空 apply；./loader exports 指 client/loader；全消费面（web 壳/ui-sidebar/ui-trajectory/tests）bare→/client 机械跟改；vitest.e2e 换 tsconfig.vitest paths（root tsconfig 排除 client 会把 /client import 掉到 exports 的浏览器 dist bundle）

refactor(gui): exports 纪律刀3 补遗——ui-layout 三处 bare runtime import 改 /client（刀3 消费面机械跟改漏提交件；跨属地机械一行×3 报备 ui-shell）

test(gui): drop the getSessionManager singleton case — the init/get pair is a dead legacy-boot surface with zero live consumers (SessionsService constructs and holds the manager under the plugin architecture); source removal tracked with rt-core

refactor(gui): 删 manager.ts 尾部 initSessionManager/getSessionManager 单例对——旧 boot 直连遗物，插件化下 SessionsService 构造持有 manager，全仓零活消费者（convo-b 测试清扫对表，其测试用例已先行退役 7e2c51898）；头注释同步去单例措辞

code

refactor

packages/client/runtime/README.md

@@ -0,0 +1,18 @@
+# @deepseek-ai/dsh-client-runtime
+
+Client cordis boot + core services: SlotsService (Service wrapper over SlotCore + 'slots/changed' bridge), SessionsService (list store projection, scope tree, bindings, ancestry), Session object layer, ClientLoader (`./loader` subpath, statically held by the shell). Contract: api-contracts v3 §4.
+
+## Model Experience
+
+None, as the client runtime hosts browser-side services and the session object layer; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **`loader.unload` is a stub (throws not-implemented)** — the full chain (fiber dispose → registration cascade → style removal) lands with the HMR project.
+- **Scope teardown is watch-approximated** — the most recently resolved binding stands in for "who is watching"; a removed-while-watched session's scope survives until the watch moves away, not until true observer count reaches zero.
+- **Value imports of this package from plugin bundles must use the `/client` subpath** — the bare package name is not in the loader externals table and inlines a second module instance, whose private scope-tag Symbol never matches (the empty-state P0 postmortem).
+- **`SessionSummary.title` is a display projection** — the wire summary carries no title yet; the cwd basename stands in, then the raw id.

packages/client/runtime/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@deepseek-ai/dsh-client-runtime",
+  "description": "Client cordis boot and core services: SlotsService, SessionsService (scope tree + object layer), ClientLoader",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./loader": {
+      "types": "./lib/types/client/loader/index.d.ts",
+      "default": "./lib/loader.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-connection"
+    ],
+    "platform": "web",
+    "immediately": true
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-session": "workspace:^"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/loader.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}

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

@@ -0,0 +1,128 @@
+/**
+ * Browser half: the whole runtime contract surface (api-contracts v3 §4) —
+ * SlotsService, SessionsService (list store + scope tree + object layer),
+ * the ClientLoader interface, and the cordis Context/Events merges. apply
+ * mounts ctx.slots + ctx.sessions and wires the connection stream loop into
+ * the object layer. The loader machinery implementation is NOT in the plugin
+ * bundle — it ships via the package's `./loader` subpath, statically held by
+ * the web shell (a loader cannot load itself).
+ */
+import type { Context } from 'cordis'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import type { SessionBinding as GenericSessionBinding } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SnapshotStore, UseSession } from '@deepseek-ai/dsh-client-web-react'
+import { SlotsService } from './slots.ts'
+import { SessionsService } from './sessions/service.ts'
+import type { ConversationSnapshot, RunningToolCall, ToolResultNode } from './sessions/conversation.ts'
+
+export { SlotsService } from './slots.ts'
+export { SessionsService, scopeOf } from './sessions/service.ts'
+export type { SessionBinding, SessionListState, SessionSummary } from './sessions/service.ts'
+export { SessionManager } from './sessions/manager.ts'
+export type { SessionListSnapshot } from './sessions/manager.ts'
+export { Session, PAGE_MESSAGES } from './sessions/session.ts'
+export type { SessionListEntry } from './sessions/lineage.ts'
+export type {
+  AssistantBlock, AssistantMessageNode, ContextMessageNode, ConversationNode, ConversationSnapshot,
+  OpenState, PartialAssistant, PendingInteraction, PromptError, RunningToolCall, SteeringMessageNode,
+  ToolResultNode, UnknownSurfaceNode, UserMessageNode,
+} from './sessions/conversation.ts'
+export type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+
+// ---- Narrowed aliases (the single narrowing point of the slot type chain:
+// ui-slots/web-react stay generic and dependency-inverted; the client-tree
+// concrete types live here, where their subjects live) ----
+
+/**
+ * The client cordis context face: the base Context plus the service keys
+ * this package's declaration merge contributes (slots/sessions/loader) and
+ * every later plugin's merge. A plain alias — the merges land on Context
+ * itself inside the client program; the name marks intent at consumer seams.
+ */
+export type ClientContext = Context
+
+/** SessionBinding narrowed to the client context (inject factories dot services directly). */
+export type ClientSessionBinding = GenericSessionBinding<ClientContext>
+
+/** The conversation-snapshot selector hook (ConvViewProps/ToolViewProps take this). */
+export type UseConversationSession = UseSession<ConversationSnapshot>
+
+/**
+ * One tool call as the chat flow renders it: still-running (spinner card) or
+ * settled (result node). The fold produces both shapes; toolview components
+ * narrow on the discriminant fields.
+ */
+export type ToolCallBlock = RunningToolCall | ToolResultNode
+
+declare module 'cordis' {
+  interface Events {
+    /**
+     * A slot's definition or registration set changed.
+     * @mode emit
+     * @param key - the mutated SlotMap key.
+     */
+    'slots/changed'(key: string): void
+  }
+  interface Context {
+    slots: import('./slots.ts').SlotsService
+    sessions: import('./sessions/service.ts').SessionsService
+    loader: ClientLoader
+  }
+}
+
+/** One __DSH_BOOT__ manifest row. */
+export interface BootPluginEntry { id: string; url: string; inject: string[]; immediately?: boolean }
+
+/** Per-plugin load status store shape. */
+export type LoaderStatus = Record<string, 'loading' | 'active' | 'failed'>
+
+/**
+ * Client bundle loader. The immediately group loads first (parallel fetch,
+ * apply in inject topology order); remaining plugins follow in inject
+ * topology. Loaded bundle export surfaces are registered back into the
+ * require module table. Implementation lives in the `./loader` subpath
+ * (shell-held machinery).
+ */
+export interface ClientLoader {
+  /** Start loading from window.__DSH_BOOT__ (non-blocking). */
+  start(): void
+  /**
+   * Load one plugin bundle (script inject, factory handoff, ctx.plugin, style registration).
+   * @param id - plugin id (package name).
+   */
+  load(id: string): Promise<void>
+  /**
+   * Unload a plugin. P-I: not implemented (full chain lands with HMR).
+   * @param id - plugin id.
+   */
+  unload(id: string): Promise<void>
+  /** Resolves when every manifest plugin reached active (AppRoot gates the real UI on this). */
+  settled(): Promise<void>
+  /**
+   * Read a loaded module's export surface from the module table (same
+   * implementation the bundle-facing require uses; unknown spec throws).
+   * @param spec - module specifier (package name or seeded library id).
+   */
+  requireModule(spec: string): unknown
+  /** Per-plugin status store. */
+  readonly status: SnapshotStore<LoaderStatus>
+}
+
+/** Required services: the wire handle mounted by the connection plugin. */
+export const inject = ['connection']
+
+/**
+ * Client plugin body: mount slots + sessions, start the stream loop.
+ * @param ctx - client cordis context.
+ */
+export function apply(ctx: Context): void {
+  ctx.plugin(SlotsService)
+  const connection = ctx.get('connection') as ConnectionHandle
+  const sessions = new SessionsService(ctx, connection.api)
+  const loop = connection.start({
+    onMuxEnvelope: (envelope) => { sessions.manager.handleMuxEnvelope(envelope) },
+    onHostEnvelope: (envelope) => { sessions.manager.handleHostEnvelope(envelope) },
+    onConnected: () => { sessions.manager.handleConnected() },
+  })
+  ctx.effect(() => () => { loop.stop() }, 'runtime: connection stream loop')
+}

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

@@ -0,0 +1,247 @@
+/**
+ * ClientLoader implementation (shell-held machinery — the loader cannot load
+ * itself, so the web shell imports this subpath statically and mounts the
+ * instance as ctx.loader; the runtime package's own client bundle never
+ * includes it).
+ *
+ * Load chain per plugin: fetch bundle text → execute (script injection) → the
+ * bundle calls window.DSHClientProxy.loadPlugin({id, factory}) (single-slot
+ * handoff, id reconciled) → factory(require) with require bound to the module
+ * table → ctx.plugin(exports.apply) → the export surface is registered into
+ * the module table under the plugin id (inject topology guarantees later
+ * loaders can require earlier ones) → <style data-plugin> ownership recorded.
+ *
+ * start(): the `immediately` group is fetched in parallel and executed in
+ * group-internal inject topology (execution is serial — the handoff slot is
+ * single); a full-group barrier precedes the remaining plugins, which then
+ * load one by one in inject topology.
+ */
+import type { Context } from 'cordis'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { BootPluginEntry, ClientLoader, LoaderStatus } from '../index.ts'
+
+export type { BootPluginEntry, ClientLoader, LoaderStatus } from '../index.ts'
+
+/** The shape a client bundle hands to window.DSHClientProxy.loadPlugin. */
+export interface ClientPluginHandoff {
+  /** Plugin id (package name) — must match the manifest row being loaded. */
+  id: string
+  /**
+   * Closure factory: receives the DI require and returns the module's export
+   * surface; an `apply` export is applied as a cordis plugin.
+   */
+  factory: (require: (spec: string) => unknown) => Record<string, unknown>
+}
+
+/** Window surface the loader owns (bundle side of the handoff protocol). */
+interface DshWindow {
+  __DSH_BOOT__?: { plugins: BootPluginEntry[] }
+  DSHClientProxy?: { loadPlugin(handoff: ClientPluginHandoff): void }
+}
+
+/** Options for createClientLoader (assembled by the web shell at boot). */
+export interface ClientLoaderOptions {
+  /** Client root context: plugin applies mount under it. */
+  ctx: Context
+  /**
+   * Seeded module table: pure-library entities (react, react-dom, cordis,
+   * ui-slots, web-react, ui-primitives). The loader takes ownership and
+   * registers loaded bundle export surfaces alongside them.
+   */
+  modules: Record<string, unknown>
+  /**
+   * Boot manifest; defaults to window.__DSH_BOOT__. Fixture pages inject the
+   * same protocol shape.
+   */
+  boot?: { plugins: BootPluginEntry[] }
+  /** Bundle fetch seam (parallelizable half). Defaults to same-origin fetch().text(). */
+  fetchBundle?: (url: string) => Promise<string>
+  /**
+   * Bundle execution seam (serial half; execution synchronously performs the
+   * loadPlugin handoff). Defaults to a <script> element carrying the code.
+   */
+  executeBundle?: (code: string, url: string) => void
+}
+
+/** Per-plugin bookkeeping across the load chain. */
+interface PluginRecord {
+  entry: BootPluginEntry
+  state: 'idle' | 'loading' | 'active' | 'failed'
+  fetch?: Promise<string>
+  load?: Promise<void>
+}
+
+const NOT_LOADED = Symbol('dsh.loader.not-loaded')
+
+/**
+ * Build the client bundle loader.
+ * @param options - ctx, seeded module table, boot manifest, fetch/execute seams.
+ * @returns the ClientLoader the shell mounts as ctx.loader.
+ */
+export function createClientLoader(options: ClientLoaderOptions): ClientLoader {
+  const { ctx } = options
+  const win = globalThis as DshWindow
+  const boot = options.boot ?? win.__DSH_BOOT__
+  if (boot === undefined) throw new Error('client-loader: no boot manifest (window.__DSH_BOOT__ missing)')
+
+  const modules = new Map<string, unknown>(Object.entries(options.modules))
+  const records = new Map<string, PluginRecord>()
+  for (const entry of boot.plugins) {
+    if (records.has(entry.id)) throw new Error(`client-loader: duplicate manifest id "${entry.id}"`)
+    records.set(entry.id, { entry, state: 'idle' })
+  }
+
+  const status = createSnapshotStore<LoaderStatus>({})
+  const publish = (id: string, state: 'loading' | 'active' | 'failed'): void => {
+    status.update((draft) => { draft[id] = state })
+  }
+
+  // Single-slot handoff: bundle execution synchronously calls loadPlugin;
+  // doLoad arms the slot before executing and reconciles the id after.
+  let slot: ClientPluginHandoff | typeof NOT_LOADED = NOT_LOADED
+  if (win.DSHClientProxy !== undefined) throw new Error('client-loader: window.DSHClientProxy already installed (double boot?)')
+  win.DSHClientProxy = {
+    loadPlugin: (handoff: ClientPluginHandoff): void => {
+      if (slot !== NOT_LOADED) {
+        throw new Error(`client-loader: overlapping loadPlugin handoff (got "${handoff.id}" while a previous handoff is unclaimed)`)
+      }
+      slot = handoff
+    },
+  }
+
+  const fetchBundle = options.fetchBundle ?? (async (url: string): Promise<string> => {
+    const res = await fetch(url)
+    if (!res.ok) throw new Error(`client-loader: bundle fetch ${url} answered ${String(res.status)}`)
+    return res.text()
+  })
+
+  const executeBundle = options.executeBundle ?? ((code: string, url: string): void => {
+    const el = document.createElement('script')
+    // Inline execution (not src) so the fetch half stays parallelizable; the
+    // sourceURL comment keeps devtools stack frames attributed to the bundle.
+    el.textContent = `${code}\n//# sourceURL=${url}`
+    document.head.appendChild(el)
+  })
+
+  const requireModule = (spec: string): unknown => {
+    if (!modules.has(spec)) {
+      throw new Error(`client-loader: module "${spec}" is not available — not a seeded library and no loaded plugin registered it (check dshClient.inject ordering)`)
+    }
+    return modules.get(spec)
+  }
+
+  /** Tag styles the bundle injected during execution (unload bookkeeping; plugin CSS lands untagged). */
+  const claimStyles = (id: string): void => {
+    if (typeof document === 'undefined') return
+    for (const el of document.querySelectorAll('style:not([data-plugin])')) {
+      el.setAttribute('data-plugin', id)
+    }
+  }
+
+  /** Start (or reuse) the parallelizable fetch half. */
+  const prefetch = (record: PluginRecord): Promise<string> =>
+    (record.fetch ??= fetchBundle(record.entry.url))
+
+  async function doLoad(record: PluginRecord): Promise<void> {
+    const { id } = record.entry
+    record.state = 'loading'
+    publish(id, 'loading')
+    try {
+      // Dependencies must already be active (start() sequences this; direct
+      // load() callers get the same fail-loud check).
+      for (const dep of record.entry.inject) {
+        const depRecord = records.get(dep)
+        if (depRecord === undefined) throw new Error(`client-loader: "${id}" injects unknown plugin "${dep}"`)
+        if (depRecord.state !== 'active') throw new Error(`client-loader: "${id}" loaded before its dependency "${dep}" is active`)
+      }
+      const code = await prefetch(record)
+      executeBundle(code, record.entry.url)
+      if (slot === NOT_LOADED) throw new Error(`client-loader: bundle ${record.entry.url} executed without calling DSHClientProxy.loadPlugin`)
+      const handoff = slot
+      slot = NOT_LOADED
+      if (handoff.id !== id) throw new Error(`client-loader: bundle id mismatch — manifest "${id}" vs handoff "${handoff.id}"`)
+      const exports = handoff.factory(requireModule)
+      if (typeof exports.apply !== 'function') throw new Error(`client-loader: plugin "${id}" exports no apply function`)
+      // The whole export surface is the plugin: cordis object-plugin form
+      // keeps the bundle's exported `inject`/`name` (an apply-only pass would
+      // silently drop the dependency declaration — postmortem 0001).
+      const fiber = ctx.plugin(exports as { apply: (ctx: Context) => void })
+      await fiber.await()
+      // Register under both specifier forms bundles emit: the bare package
+      // name (deep-import rewrites) and the /client subpath (CLIENT_EXTERNALS
+      // form) — the loaded surface IS the client half either way.
+      modules.set(id, exports)
+      modules.set(`${id}/client`, exports)
+      claimStyles(id)
+      record.state = 'active'
+      publish(id, 'active')
+    } catch (error) {
+      record.state = 'failed'
+      publish(id, 'failed')
+      throw error
+    }
+  }
+
+  const load = (id: string): Promise<void> => {
+    const record = records.get(id)
+    if (record === undefined) return Promise.reject(new Error(`client-loader: unknown plugin "${id}"`))
+    record.load ??= doLoad(record)
+    return record.load
+  }
+
+  /** Topologically order `ids` by inject (edges inside the set only — an early-group member never waits on a later-group one). */
+  const topo = (ids: string[]): string[] => {
+    const pool = new Set(ids)
+    const ordered: string[] = []
+    const done = new Set<string>()
+    const visiting = new Set<string>()
+    const visit = (id: string): void => {
+      if (done.has(id)) return
+      if (visiting.has(id)) throw new Error(`client-loader: inject cycle through "${id}"`)
+      visiting.add(id)
+      const record = records.get(id)
+      /* v8 ignore next -- ids come from records; unknown ids are caught per-dep below. */
+      if (record === undefined) throw new Error(`client-loader: manifest references unknown plugin "${id}"`)
+      for (const dep of record.entry.inject) {
+        if (!records.has(dep)) throw new Error(`client-loader: "${id}" injects unknown plugin "${dep}"`)
+        if (pool.has(dep)) visit(dep)
+      }
+      visiting.delete(id)
+      done.add(id)
+      ordered.push(id)
+    }
+    for (const id of ids) visit(id)
+    return ordered
+  }
+
+  let settledPromise: Promise<void> | undefined
+
+  async function run(): Promise<void> {
+    const all = [...records.values()]
+    const early = all.filter(r => r.entry.immediately === true)
+    const rest = all.filter(r => r.entry.immediately !== true)
+    // Early group: parallel fetch (all requests in flight at once), serial
+    // inject-topology execution, full-group barrier before anything else.
+    const earlyOrder = topo(early.map(r => r.entry.id))
+    for (const record of early) void prefetch(record).catch(() => {}) // surfaced by the awaited load below
+    for (const id of earlyOrder) await load(id)
+    // Remaining plugins: one by one in inject topology.
+    for (const id of topo(rest.map(r => r.entry.id))) await load(id)
+  }
+
+  return {
+    start: () => {
+      settledPromise ??= run()
+      // Failures surface through settled()/status — start() itself is fire-and-forget.
+      settledPromise.catch(() => {})
+    },
+    load,
+    unload: (id: string) => Promise.reject(new Error(`client-loader: unload("${id}") is not implemented (lands with HMR)`)),
+    settled: () => {
+      if (settledPromise === undefined) throw new Error('client-loader: settled() before start()')
+      return settledPromise
+    },
+    requireModule,
+    status,
+  }
+}

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

@@ -0,0 +1,165 @@
+// ConversationSnapshot / ConversationNode: the only data shape the logic layer feeds the UI.
+// Immutability contract: every change swaps the top-level object; unchanged
+// substructures keep their references (the React.memo premise). callId/approvalId stay plain
+// string here (narrow to real brands when convenient).
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { RpcError, RpcId, SessionId, ToolCallView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+
+/** Assistant content blocks sorted by what the UI cares about
+ *  (text body / collapsible reasoning / tool-call card head / other fallback). */
+export type AssistantBlock =
+  | { kind: 'text'; text: string }
+  | { kind: 'reasoning'; text: string }
+  | { kind: 'tool-call'; callId: string; name: string; argsRaw: string }
+  | { kind: 'other'; block: unknown }
+
+/**
+ * core ContentBlock[] -> AssistantBlock[] (classifier shared by finalized messages and partial block-end).
+ * @param content - core content blocks verbatim.
+ * @returns UI-classified blocks in source order.
+ */
+export function toAssistantBlocks(content: readonly ContentBlock[]): AssistantBlock[] {
+  return content.map(toAssistantBlock)
+}
+
+/**
+ * Classify one block (ToolCallBlock fields are id/arguments, mapped to callId/argsRaw).
+ * @param block - one core content block.
+ * @returns the UI classification.
+ */
+export function toAssistantBlock(block: ContentBlock): AssistantBlock {
+  switch (block.type) {
+    case 'text': return { kind: 'text', text: block.text }
+    case 'reasoning': return { kind: 'reasoning', text: block.text }
+    case 'tool-call': return { kind: 'tool-call', callId: String(block.id), name: block.name, argsRaw: block.arguments }
+    default: return { kind: 'other', block }
+  }
+}
+
+/** A finalized user message. */
+export interface UserMessageNode {
+  kind: 'user'
+  seq: number
+  content: readonly ContentBlock[]
+  source: unknown
+}
+
+/** A finalized (or interruption-frozen) assistant message. */
+export interface AssistantMessageNode {
+  kind: 'assistant'
+  seq: number
+  turn: number
+  step: number
+  blocks: readonly AssistantBlock[]
+  usage?: unknown
+  /** Frozen partial of an aborted turn (no finalize ever arrives): rendered with a 已停止 marker.
+   *  Synthetic seq (fractional, derived from the turn/end seq) keeps it ordered inside the flow. */
+  interrupted?: true
+}
+
+/** A steering message injected mid-turn. */
+export interface SteeringMessageNode {
+  kind: 'steering'
+  seq: number
+  turn: number
+  content: readonly ContentBlock[]
+  source: unknown
+}
+
+/** A context/system injection surfaced in the flow. */
+export interface ContextMessageNode {
+  kind: 'context'
+  seq: number
+  content: readonly ContentBlock[]
+  source: unknown
+  meta?: unknown
+}
+
+/** A tool result paired (when in-window) with its call head. */
+export interface ToolResultNode {
+  kind: 'tool-result'
+  seq: number
+  callId: string
+  /** Call head backfilled from the in-window tool/call; null when window truncation left the call outside (card head shows callId). */
+  call: { name: string; argsRaw: string } | null
+  content: readonly ContentBlock[]
+  isError: boolean
+  error?: { name: string; code: string }
+  meta?: unknown
+  /** Host-computed render intent from the paired tool/call's wire view; null = generic JSON card (documented default). */
+  callView: ToolCallView | null
+  /** Host-computed render intent from this tool/result's wire view; null = same default. */
+  resultView: ToolResultView | null
+}
+
+/** Fallback for surface events this UI version does not know. */
+export interface UnknownSurfaceNode {
+  kind: 'unknown'
+  seq: number
+  type: string
+  data: unknown
+}
+
+/** Finalized conversation node union (kind discriminates; seq is the React key). */
+export type ConversationNode =
+  | UserMessageNode
+  | AssistantMessageNode
+  | SteeringMessageNode
+  | ContextMessageNode
+  | ToolResultNode
+  | UnknownSurfaceNode
+
+/** In-flight tool card material: tool/call seen, tool/result not yet. */
+export interface RunningToolCall {
+  callId: string
+  name: string
+  argsRaw: string
+  turn: number
+  step: number
+  /** Host-computed render intent riding the tool/call frame; null = generic JSON card. */
+  callView: ToolCallView | null
+}
+
+/** Approval/question placeholder cards (visible, not answerable;
+ *  rpcId = the requested frame's envelope id, the future respond backfill key). */
+export type PendingInteraction =
+  | { kind: 'approval'; rpcId: RpcId; approvalId: string; toolName: string; callId?: string; reason?: string }
+  | { kind: 'question'; rpcId: RpcId; questions: readonly unknown[] }
+
+/** In-progress assistant output (chunk accumulator product). */
+export interface PartialAssistant {
+  turn: number
+  step: number
+  blocks: readonly AssistantBlock[]
+}
+
+/** History-open lifecycle of a Session window. */
+export type OpenState = 'cold' | 'loading' | 'open' | 'error'
+
+/** Send/stop failure surfaced in the input error strip; op picks the user-facing copy (发送失败 vs 停止失败). */
+export interface PromptError {
+  op: 'send' | 'stop'
+  error: RpcError
+}
+
+/** The immutable snapshot contract Session hands to uSES (see the web client architecture RFC). */
+export interface ConversationSnapshot {
+  sessionId: SessionId
+  /** Surface fold product (finalized conversation nodes in surface order). */
+  nodes: readonly ConversationNode[]
+  /** Fold degradation flag (cross-window replace defense): when true, nodes come from the lenient linear scan. */
+  foldDegraded: boolean
+  partial: PartialAssistant | null
+  runningCalls: readonly RunningToolCall[]
+  pending: readonly PendingInteraction[]
+  running: boolean
+  /** Set after host/session-removed; the UI grays out and disables input. */
+  removed: boolean
+  openState: OpenState
+  openError: RpcError | null
+  hasMore: boolean
+  loadingOlder: boolean
+  promptError: PromptError | null
+  lastAgentError: string | null
+}

packages/client/runtime/src/client/sessions/fold-adapter.ts

@@ -0,0 +1,194 @@
+// FoldAdapter: core SurfaceManager wiring + node materialization cache.
+// Padding sentinels solve the paged-window seq offset (core fold asserts seq === index);
+// a cross-window replace throw degrades to a lenient linear scan (foldDegraded —
+// the degradation lives in one branch function in this file, zero scattered removal points).
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+// Subpath export (package.json exports "./surface", alias added for this): all value imports
+// go through it — the package root points at lib/index.js (needs a build) which the vite
+// browser bundle cannot resolve; surface.ts has no Node dependencies.
+import { SurfaceManager, isSurfaceEligibleType } from '@deepseek-ai/dsh-session/surface'
+import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type { ConversationNode } from './conversation.ts'
+import { toAssistantBlocks } from './conversation.ts'
+
+/** In-window tool/call index entry (result-card backfill + runningCalls material). */
+export interface CallIndexEntry {
+  name: string
+  argsRaw: string
+  turn: number
+  step: number
+  /** Wire view riding the tool/call (envelope-level; never inside the event). */
+  callView: ToolCallView | null
+}
+
+/** Non-surface-eligible sentinel event (safely skipped by surfaceOpOf's undefined branch).
+ *  'noop/padding' is not a real event type on purpose: a genuine type with fake data would
+ *  surface as garbage the day anyone adds handling for it (design §D.1; the cast is the one
+ *  place a synthetic event enters the window). */
+function paddingEvent(seq: number): SessionEvent {
+  return { type: 'noop/padding', seq, time: 0, data: {} } as unknown as SessionEvent
+}
+
+/** One event -> UI node (pure function; the six-variant ConversationNode union). */
+function materializeNode(
+  event: SessionEvent,
+  callIndex: ReadonlyMap<string, CallIndexEntry>,
+  resultView: ToolResultView | null,
+): ConversationNode {
+  switch (event.type) {
+    case 'user/message':
+      return { kind: 'user', seq: event.seq, content: event.data.content, source: event.data.source }
+    case 'assistant/message':
+      return {
+        kind: 'assistant', seq: event.seq, turn: event.data.turn, step: event.data.step,
+        blocks: toAssistantBlocks(event.data.content), usage: event.data.usage,
+      }
+    case 'steering/message':
+      return { kind: 'steering', seq: event.seq, turn: event.data.turn, content: event.data.content, source: event.data.source }
+    case 'context/message':
+      return {
+        kind: 'context', seq: event.seq, content: event.data.content, source: event.data.source,
+        meta: event.data.meta,
+      }
+    case 'tool/result': {
+      const call = callIndex.get(String(event.data.callId))
+      return {
+        kind: 'tool-result', seq: event.seq, callId: String(event.data.callId),
+        call: call ? { name: call.name, argsRaw: call.argsRaw } : null,
+        content: event.data.content, isError: event.data.isError,
+        ...(event.data.error !== undefined ? { error: event.data.error } : {}),
+        meta: event.data.meta,
+        callView: call?.callView ?? null,
+        resultView,
+      }
+    }
+    /* v8 ignore next 2 -- defensive arm: fold output only carries the five
+    surface-eligible types, and each has a case above; reachable only if core
+    adds an eligible type. */
+    default:
+      return { kind: 'unknown', seq: event.seq, type: event.type, data: (event as { data?: unknown }).data }
+  }
+}
+
+/** Window fold over the core SurfaceManager (sentinel padding for the seq offset; degrades to a linear scan on cross-window replace). */
+export class FoldAdapter {
+  /** padded = [sentinel x baseSeq, ...window events]; SurfaceManager borrows this reference for lazy incremental folding. */
+  private padded: SessionEvent[] = []
+  private baseSeq = 0
+  private surface = new SurfaceManager(this.padded)
+  private nodeCache = new Map<number, ConversationNode>()
+  private degraded = false
+  private callIdx = new Map<string, CallIndexEntry>()
+  /** Wire result views keyed by the tool/result event's seq (views ride the envelope, not the event). */
+  private resultViews = new Map<number, ToolResultView>()
+  /** Window revision (bumped on reset/append) keying the nodes() result cache: an unchanged
+   *  window returns the previous ARRAY reference, not just cached elements — the snapshot's
+   *  reference-stability contract (§A.9.4) starts here. */
+  private rev = 0
+  private nodesResult: { rev: number; value: { nodes: ConversationNode[]; degraded: boolean } } | null = null
+
+  /** In-window tool/call index (Session uses it for runningCalls and result-card backfill). */
+  get callIndex(): ReadonlyMap<string, CallIndexEntry> {
+    return this.callIdx
+  }
+
+  /**
+   * Window rebuild (after open/resync/page prepend): new padded array, new
+   * SurfaceManager, cleared cache, rebuilt callIndex.
+   * @param events - the new window contents (seq-ascending).
+   * @param baseSeq - seq of the window head (sentinels pad below it).
+   * @param views - per-event wire views aligned with `events` by index (undefined slots for view-less events).
+   */
+  reset(events: readonly SessionEvent[], baseSeq: number, views?: readonly (ToolEventView | undefined)[]): void {
+    this.rev++
+    this.baseSeq = baseSeq
+    this.padded = []
+    for (let i = 0; i < baseSeq; i++) this.padded.push(paddingEvent(i))
+    for (const event of events) this.padded.push(event)
+    this.surface = new SurfaceManager(this.padded)
+    this.nodeCache.clear()
+    this.degraded = false
+    this.callIdx = new Map()
+    this.resultViews.clear()
+    for (let i = 0; i < events.length; i++) {
+      const event = events[i]
+      /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
+      if (event !== undefined) this.indexCall(event, views?.[i])
+    }
+  }
+
+  /**
+   * Tail append (live session/event): push into the same array (incremental
+   * lazy fold applies) + incremental callIndex upkeep.
+   * @param event - the live event (seq = window tail + 1).
+   * @param view - host-computed tool view paired with the event when it is a tool call/result; indexed for card rendering.
+   */
+  append(event: SessionEvent, view?: ToolEventView): void {
+    this.rev++
+    this.padded.push(event)
+    this.indexCall(event, view)
+  }
+
+  /**
+   * Current node array + degradation flag. Same revision -> same array
+   * reference (memo boundary); node object references always come from the per-seq cache.
+   * @returns the fold projection for the current window revision.
+   */
+  nodes(): { nodes: ConversationNode[]; degraded: boolean } {
+    if (this.nodesResult !== null && this.nodesResult.rev === this.rev) return this.nodesResult.value
+    let seqs: readonly number[]
+    if (this.degraded) {
+      seqs = this.degradedSeqs()
+    } else {
+      try {
+        seqs = this.surface.nodes
+      } catch (error) {
+        console.error('[web-runtime] surface fold failed, degrading to linear scan:', error)
+        this.degraded = true
+        seqs = this.degradedSeqs()
+      }
+    }
+    const out: ConversationNode[] = []
+    for (const seq of seqs) {
+      const cached = this.nodeCache.get(seq)
+      if (cached !== undefined) {
+        out.push(cached)
+        continue
+      }
+      const event = this.padded[seq]
+      /* v8 ignore next -- sparse guard: both seq sources (surface fold and degradedSeqs) only emit indexes present in padded. */
+      if (event === undefined) continue
+      const node = materializeNode(event, this.callIdx, this.resultViews.get(seq) ?? null)
+      this.nodeCache.set(seq, node)
+      out.push(node)
+    }
+    const value = { nodes: out, degraded: this.degraded }
+    this.nodesResult = { rev: this.rev, value }
+    return value
+  }
+
+  /** Degradation branch: lenient linear scan ignoring surfaceOp/replace (all surface-eligible events in append order). */
+  private degradedSeqs(): number[] {
+    const seqs: number[] = []
+    for (let i = this.baseSeq; i < this.padded.length; i++) {
+      const event = this.padded[i]
+      if (event !== undefined && isSurfaceEligibleType(event.type)) seqs.push(event.seq)
+    }
+    return seqs
+  }
+
+  private indexCall(event: SessionEvent, view?: ToolEventView): void {
+    if (event.type === 'tool/result') {
+      if (view?.for === 'result') this.resultViews.set(event.seq, view.view)
+      return
+    }
+    if (event.type !== 'tool/call') return
+    this.callIdx.set(String(event.data.callId), {
+      name: event.data.name, argsRaw: event.data.arguments, turn: event.data.turn, step: event.data.step,
+      callView: view?.for === 'call' ? view.view : null,
+    })
+    // No backfill into already-materialized tool-result nodes for this callId
+    // (window order puts the call before its result; cannot happen on the normal path).
+  }
+}

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

@@ -0,0 +1,63 @@
+// flattenLineage: summaries -> flat list with lineage indentation (pure function).
+// Roots sort by updatedAt desc, DFS expansion with children in the same order; orphaned lineage
+// degrades to root level; cycles fail soft and emit as roots.
+
+import type { SessionId, SessionSummary } from '@deepseek-ai/dsh-client-connection/client'
+
+/** One flattened session-list row (summary + lineage indent depth). */
+export interface SessionListEntry {
+  sessionId: SessionId
+  updatedAt: number
+  running: boolean
+  parentSessionId?: SessionId
+  cwd?: string
+  /** Lineage indent depth: root = 0; the UI just multiplies by the indent width. */
+  depth: number
+}
+
+/**
+ * summaries -> flat list with lineage indentation (pure; roots by updatedAt
+ * desc, DFS children in the same order, orphans degrade to roots).
+ * @param summaries - the host's session.list items.
+ * @returns display rows in render order.
+ */
+export function flattenLineage(summaries: readonly SessionSummary[]): SessionListEntry[] {
+  const byId = new Map<SessionId, SessionSummary>()
+  for (const s of summaries) byId.set(s.sessionId, s)
+
+  const children = new Map<SessionId, SessionSummary[]>()
+  const roots: SessionSummary[] = []
+  for (const s of summaries) {
+    if (s.parentSessionId !== undefined && byId.has(s.parentSessionId)) {
+      const list = children.get(s.parentSessionId) ?? []
+      list.push(s)
+      children.set(s.parentSessionId, list)
+    } else {
+      roots.push(s) // root, or an orphan whose parent is absent from summaries (degrade to root, never drop)
+    }
+  }
+
+  const byUpdatedDesc = (a: SessionSummary, b: SessionSummary): number => b.updatedAt - a.updatedAt
+  roots.sort(byUpdatedDesc)
+
+  const out: SessionListEntry[] = []
+  const visited = new Set<SessionId>()
+  const walk = (s: SessionSummary, depth: number): void => {
+    if (visited.has(s.sessionId)) {
+      console.warn(`[web-runtime] lineage cycle at ${s.sessionId}; emitting as root`)
+      return
+    }
+    visited.add(s.sessionId)
+    out.push({ ...s, depth })
+    const kids = children.get(s.sessionId)
+    if (kids === undefined) return
+    kids.sort(byUpdatedDesc)
+    for (const kid of kids) walk(kid, depth + 1)
+  }
+  for (const root of roots) walk(root, 0)
+  // Cycle members (unreachable from any root): emit as roots so no entry is lost.
+  for (const s of summaries) {
+    if (!visited.has(s.sessionId)) walk(s, 0)
+  }
+  return out
+}

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

@@ -0,0 +1,250 @@
+// SessionManager: the instance cluster Map<SessionId, Session> (lazy-built, resident) + the frame
+// dispatch entry + list state, constructed and held by SessionsService (one per client runtime).
+// List data never enters zustand; React connects via subscribe/getListSnapshot.
+
+import type { IApiClient, HostFrame, MuxFrame, RpcError, RpcRequest, RpcResult, SessionId, SessionSummary } from '@deepseek-ai/dsh-client-connection/client'
+import { transportError } from '@deepseek-ai/dsh-client-connection/client'
+import type { SessionListEntry } from './lineage.ts'
+import { flattenLineage } from './lineage.ts'
+import { Notifier } from './notifier.ts'
+import { Session } from './session.ts'
+
+/** Immutable session-list snapshot for useSessionList. */
+export interface SessionListSnapshot {
+  items: readonly SessionListEntry[]
+  state: 'idle' | 'loading' | 'error'
+  error: RpcError | null
+}
+
+/** Per-session cap for pre-instantiation approval/question buffering (low-frequency frames; a few dozen covers any real backlog). */
+const PENDING_BUFFER_CAP = 32
+
+/** Instance cluster + frame entry + the session list (see the web client architecture RFC). */
+export class SessionManager {
+  private readonly sessions = new Map<SessionId, Session>()
+  /** Approval/question frame buffer for uninstantiated sessions: pending interactions never hit
+   *  history (cannot be backfilled on open), the one frame class that must not take the
+   *  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>[]>()
+  private summaries: SessionSummary[] = []
+  private listState: 'idle' | 'loading' | 'error' = 'idle'
+  private listError: RpcError | null = null
+  private listInflight: Promise<void> | null = null
+
+  private listSnapshotCache: SessionListSnapshot
+  /** Entry-identity cache (§C.2 reference stability): list rebuilds reuse the previous entry
+   *  object when every field matches — wire refreshes mint all-new summary objects, so identity
+   *  must be recovered by value or every SessionListItem memo misses on every refresh (audit S5). */
+  private entryCache = new Map<SessionId, SessionListEntry>()
+  private itemsCache: readonly SessionListEntry[] = []
+  private readonly notifier = new Notifier(() => {
+    this.listSnapshotCache = this.buildListSnapshot()
+  })
+
+  constructor(private readonly api: IApiClient) {
+    this.listSnapshotCache = this.buildListSnapshot()
+  }
+
+  // ---- Instance management ----
+
+  /**
+   * Lazy build: return the existing instance or construct one (no auto-open —
+   * open is triggered by the container's select callback).
+   * @param sessionId - the session to get.
+   * @returns the resident instance.
+   */
+  get(sessionId: SessionId): Session {
+    let session = this.sessions.get(sessionId)
+    if (session === undefined) {
+      session = new Session(sessionId, this.api)
+      this.sessions.set(sessionId, session)
+      // Sync the running bit from the list snapshot into the new instance (consistency when the list precedes open).
+      const summary = this.summaries.find(s => s.sessionId === sessionId)
+      if (summary !== undefined) session.handleRunning(summary.running)
+      // Replay approval/question frames buffered before instantiation (rpcId verbatim, same semantics as the subscribed baseline replay).
+      const buffered = this.pendingBuffers.get(sessionId)
+      if (buffered !== undefined) {
+        this.pendingBuffers.delete(sessionId)
+        for (const envelope of buffered) session.handleMuxEnvelope(envelope.rpcId, envelope.payload)
+      }
+    }
+    return session
+  }
+
+  // ---- List surface ----
+
+  /** Full refresh via session.list (single-flight: an in-flight call is reused). */
+  refreshList(): Promise<void> {
+    if (this.listInflight !== null) return this.listInflight
+    this.listState = 'loading'
+    this.listError = null
+    this.notifier.markDirty()
+    this.listInflight = (async () => {
+      try {
+        const { result } = await this.api.sessions.list({})
+        if (result.ok) {
+          this.summaries = result.value.items
+          this.listState = 'idle'
+          // Push running bits down to instantiated Sessions (the list is the authoritative summary source).
+          for (const s of this.summaries) this.sessions.get(s.sessionId)?.handleRunning(s.running)
+        } else {
+          this.listState = 'error'
+          this.listError = result.error
+        }
+      } catch (error) {
+        this.listState = 'error'
+        const folded = transportError<never>(error)
+        /* v8 ignore next -- the `? null` arm is unreachable: transportError always returns ok:false. */
+        this.listError = folded.ok ? null : folded.error
+      } finally {
+        this.listInflight = null
+        this.notifier.markDirty()
+      }
+    })()
+    return this.listInflight
+  }
+
+  /**
+   * Contract session.create; on success merge into summaries immediately (no
+   * wait for the next refresh).
+   * @param cwd - optional working directory for the new session.
+   * @returns the create result.
+   */
+  async create(cwd?: string): Promise<RpcResult<{ sessionId: SessionId }>> {
+    try {
+      const { result } = await this.api.sessions.create(cwd === undefined ? {} : { cwd })
+      if (result.ok && !this.summaries.some(s => s.sessionId === result.value.sessionId)) {
+        this.summaries = [
+          { sessionId: result.value.sessionId, updatedAt: Date.now(), running: false, ...(cwd !== undefined ? { cwd } : {}) },
+          ...this.summaries,
+        ]
+        this.notifier.markDirty()
+      }
+      return result
+    } catch (error) {
+      return transportError(error)
+    }
+  }
+
+  // ---- Subscription surface (for useSessionList) ----
+
+  /**
+   * uSES subscription entry for useSessionList.
+   * @param listener - change callback.
+   * @returns the unsubscribe function.
+   */
+  subscribe(listener: () => void): () => void {
+    return this.notifier.subscribe(listener)
+  }
+
+  /**
+   * Cached list snapshot (rebuilt lazily when dirty with no listeners).
+   * @returns the cached reference (stable until the next flush).
+   */
+  getListSnapshot(): SessionListSnapshot {
+    this.notifier.ensureFresh()
+    return this.listSnapshotCache
+  }
+
+  // ---- ConnectionController sinks (wired by boot) ----
+
+  /**
+   * Mux frame entry: sessionId-bearing frames go only to instantiated sessions
+   * (no lazy build; non-pending frames for uninstantiated sessions drop —
+   * history backfills them on open).
+   * @param envelope - the frame with its wire rpcId.
+   */
+  handleMuxEnvelope(envelope: RpcRequest<MuxFrame>): void {
+    const frame = envelope.payload
+    if (frame.type === 'stream/error') return // Controller already treats this as stream failure
+    const session = this.sessions.get(frame.sessionId)
+    if (session === undefined) {
+      // Approval/question frames never hit history: buffer for replay on instantiation;
+      // everything else drops (not instantiated — history fully backfills on open).
+      switch (frame.type) {
+        case 'approval/requested':
+        case 'approval/resolved':
+        case 'question/requested':
+        case 'question/resolved': {
+          const buffer = this.pendingBuffers.get(frame.sessionId) ?? []
+          buffer.push(envelope)
+          if (buffer.length > PENDING_BUFFER_CAP) buffer.splice(0, buffer.length - PENDING_BUFFER_CAP)
+          this.pendingBuffers.set(frame.sessionId, buffer)
+          return
+        }
+        default:
+          return
+      }
+    }
+    session.handleMuxEnvelope(envelope.rpcId, frame)
+  }
+
+  /**
+   * Host frame entry: list upkeep + per-instance running/removed/agent-error relay.
+   * @param envelope - the frame with its wire rpcId.
+   */
+  handleHostEnvelope(envelope: RpcRequest<HostFrame>): void {
+    const frame = envelope.payload
+    switch (frame.type) {
+      case 'host/session-added': {
+        if (!this.summaries.some(s => s.sessionId === frame.sessionId)) {
+          this.summaries = [
+            {
+              sessionId: frame.sessionId, updatedAt: Date.now(), running: false,
+              ...(frame.parentSessionId !== undefined ? { parentSessionId: frame.parentSessionId } : {}),
+            },
+            ...this.summaries,
+          ]
+          this.notifier.markDirty()
+        }
+        return
+      }
+      case 'host/session-removed': {
+        this.summaries = this.summaries.filter(s => s.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.notifier.markDirty()
+        return
+      }
+      case 'host/session-status': {
+        this.summaries = this.summaries.map(s =>
+          s.sessionId === frame.sessionId && s.running !== frame.running ? { ...s, running: frame.running } : s)
+        this.sessions.get(frame.sessionId)?.handleRunning(frame.running)
+        this.notifier.markDirty()
+        return
+      }
+      case 'host/agent-error': {
+        this.sessions.get(frame.sessionId)?.handleAgentError(frame.message)
+        return // not reflected in the list
+      }
+      default:
+        return // stream/error ignored; unknown frames ignored (documented default)
+    }
+  }
+
+  /** After each connection generation (first connect included): refresh the list + resync opened instances (reconnect = rebuild). */
+  handleConnected(): void {
+    void this.refreshList()
+    for (const session of this.sessions.values()) void session.resync()
+  }
+
+  private buildListSnapshot(): SessionListSnapshot {
+    const fresh = flattenLineage(this.summaries)
+    const items = fresh.map((entry) => {
+      const prev = this.entryCache.get(entry.sessionId)
+      if (
+        prev !== undefined && prev.updatedAt === entry.updatedAt && prev.running === entry.running
+        && prev.parentSessionId === entry.parentSessionId && prev.cwd === entry.cwd && prev.depth === entry.depth
+      ) return prev
+      this.entryCache.set(entry.sessionId, entry)
+      return entry
+    })
+    for (const id of this.entryCache.keys()) {
+      if (!items.some(e => e.sessionId === id)) this.entryCache.delete(id)
+    }
+    const sameOrder = items.length === this.itemsCache.length && items.every((e, i) => e === this.itemsCache[i])
+    if (!sameOrder) this.itemsCache = items
+    return { items: this.itemsCache, state: this.listState, error: this.listError }
+  }
+}

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

@@ -0,0 +1,61 @@
+// Notifier: subscription + microtask-batched notification primitive shared by Session and
+// SessionManager. Semantics: N markDirty calls collapse into one microtask flush;
+// the flush rebuilds the snapshot cache BEFORE notifying (useSyncExternalStore requires a stable
+// getSnapshot reference). With no listeners the rebuild is skipped and only the dirty bit is set
+// (keeps frame storms cheap); the next getSnapshot rebuilds lazily.
+
+/** Subscription + microtask-batched notification primitive (shared by Session and SessionManager). */
+export class Notifier {
+  private listeners = new Set<() => void>()
+  private dirty = false
+  private scheduled = false
+
+  /** @param rebuild - snapshot rebuild function injected by the owner (writes the owner's snapshotCache). */
+  constructor(private readonly rebuild: () => void) {}
+
+  /**
+   * uSES subscription entry.
+   * @param listener - change callback.
+   * @returns the unsubscribe function.
+   */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  /** State-change entry: mark dirty and schedule the batched flush. */
+  markDirty(): void {
+    this.dirty = true
+    if (this.scheduled) return
+    this.scheduled = true
+    queueMicrotask(() => {
+      this.scheduled = false
+      if (!this.dirty) return
+      if (this.listeners.size === 0) return // lazy: no subscribers, keep dirty for the next getSnapshot
+      this.dirty = false
+      this.rebuild()
+      for (const listener of this.listeners) listener()
+    })
+  }
+
+  /**
+   * Synchronous flush: controlled-input writes must notify in the same tick as
+   * onChange, or React rolls the DOM back to the stale value and the caret jumps to the end.
+   */
+  notifyNow(): void {
+    this.dirty = true
+    if (this.listeners.size === 0) return // lazy: same as markDirty, next getSnapshot rebuilds
+    this.dirty = false
+    this.rebuild()
+    for (const listener of this.listeners) listener()
+  }
+
+  /** Pre-getSnapshot check: rebuild synchronously when dirty (read path before first subscribe / while unobserved). */
+  ensureFresh(): void {
+    if (!this.dirty) return
+    this.dirty = false
+    this.rebuild()
+  }
+}

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

@@ -0,0 +1,89 @@
+// PartialAccumulator: assistant/chunk accumulator.
+// Folds the six StreamChunk variants into AssistantBlock[] keyed by block index;
+// block-level immutability (a delta only swaps that block's reference).
+
+import type { StreamChunk } from '@deepseek-ai/dsh-llm/types'
+import type { AssistantBlock, PartialAssistant } from './conversation.ts'
+import { toAssistantBlock } from './conversation.ts'
+
+/** assistant/chunk accumulator: folds StreamChunks into AssistantBlock[] with block-level immutability. */
+export class PartialAccumulator {
+  // Sparse on purpose: block-start may arrive out of order, leaving holes until compaction.
+  private blocks: (AssistantBlock | undefined)[] = []
+  private changed = true
+  private snapshot: PartialAssistant
+
+  constructor(readonly turn: number, readonly step: number) {
+    this.snapshot = { turn, step, blocks: [] }
+  }
+
+  /**
+   * Fold one chunk.
+   * @param chunk - the stream chunk.
+   * @returns whether it caused a visible change (usage/finish return false, skipping notification).
+   */
+  push(chunk: StreamChunk): boolean {
+    switch (chunk.type) {
+      case 'block-start': {
+        this.blocks[chunk.index] = emptyBlock(chunk.blockType)
+        this.changed = true
+        return true
+      }
+      case 'text-delta': {
+        const prev = this.blocks[chunk.index]
+        this.blocks[chunk.index] = { kind: 'text', text: (prev?.kind === 'text' ? prev.text : '') + chunk.text }
+        this.changed = true
+        return true
+      }
+      case 'reasoning-delta': {
+        const prev = this.blocks[chunk.index]
+        this.blocks[chunk.index] = { kind: 'reasoning', text: (prev?.kind === 'reasoning' ? prev.text : '') + chunk.text }
+        this.changed = true
+        return true
+      }
+      case 'tool-call-delta': {
+        const prev = this.blocks[chunk.index]
+        const base = prev?.kind === 'tool-call' ? prev : { kind: 'tool-call' as const, callId: '', name: '', argsRaw: '' }
+        this.blocks[chunk.index] = {
+          kind: 'tool-call',
+          callId: base.callId || String(chunk.id),
+          name: chunk.name ?? base.name,
+          argsRaw: base.argsRaw + chunk.argumentsDelta,
+        }
+        this.changed = true
+        return true
+      }
+      case 'block-end': {
+        this.blocks[chunk.index] = toAssistantBlock(chunk.block)
+        this.changed = true
+        return true
+      }
+      default:
+        // usage / finish / merge-extensible unknown variants: no visible block change
+        // (finish is immediately followed by the assistant/message that supersedes the partial).
+        return false
+    }
+  }
+
+  /**
+   * Current partial projection.
+   * @returns the cached snapshot (the blocks array reference only changes after a mutation).
+   */
+  toPartial(): PartialAssistant {
+    if (this.changed) {
+      // Compact sparse indexes (out-of-order block-start) into render order.
+      this.snapshot = { turn: this.turn, step: this.step, blocks: this.blocks.filter((b): b is AssistantBlock => b !== undefined) }
+      this.changed = false
+    }
+    return this.snapshot
+  }
+}
+
+function emptyBlock(blockType: string): AssistantBlock {
+  switch (blockType) {
+    case 'text': return { kind: 'text', text: '' }
+    case 'reasoning': return { kind: 'reasoning', text: '' }
+    case 'tool-call': return { kind: 'tool-call', callId: '', name: '', argsRaw: '' }
+    default: return { kind: 'other', block: null }
+  }
+}

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

@@ -0,0 +1,221 @@
+/**
+ * SessionsService: root sessions service — list snapshot store (manager
+ * projection), session scope tree (mintScope pattern: no-op plugin Fiber +
+ * ctx.extend scope tag), stable SessionBinding cache, ancestry walk.
+ *
+ * Scope lifecycle is watch-driven: a scope is minted lazily on first
+ * resolution; a session leaving the list tears its scope down only when
+ * nobody is watching it. "Watched" is approximated as the most recently
+ * resolved binding id — SessionProvider re-resolves on every selection
+ * change (keyed remount), so a switch away always re-evaluates the deferred
+ * teardown; a host-side death without list removal keeps the scope (frozen
+ * read-only view).
+ */
+import type { Context, Fiber } from 'cordis'
+import type { IApiClient, SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import { SessionManager } from './manager.ts'
+import type { Session } from './session.ts'
+
+/** Session list row projected from the host list RPC plus live stream increments. */
+export interface SessionSummary {
+  id: SessionId
+  title: string
+  cwd?: string
+  parentId?: SessionId
+  running: boolean
+  updatedAt: number
+}
+
+/** Session list store shape. */
+export interface SessionListState { ids: SessionId[]; byId: Record<SessionId, SessionSummary> }
+
+/** Session assembly handle for SessionProvider/inject factories (identity-stable per session). */
+export interface SessionBinding {
+  readonly sessionId: SessionId
+  readonly session: Session
+  readonly ctx: Context
+}
+
+/** Scope tag key (client counterpart of the host dsh-scope pattern). */
+const kScope = Symbol('dsh.client.scope')
+
+/**
+ * Read the session scope tag off a context.
+ * @param ctx - any client context.
+ * @returns the session id, or undefined on root contexts.
+ */
+export function scopeOf(ctx: Context): SessionId | undefined {
+  return (ctx as Context & { [kScope]?: SessionId })[kScope]
+}
+
+/** Shared no-op plugin backing each session scope fiber. */
+function sessionScope(): void {}
+
+/**
+ * Display title projection. The wire summary carries no title yet (P-I
+ * ledger): the project directory's basename stands in, then the raw id.
+ */
+function titleOf(cwd: string | undefined, id: SessionId): string {
+  if (cwd !== undefined && cwd !== '') {
+    const base = cwd.replace(/[/\\]+$/, '').split(/[/\\]/).pop()
+    if (base !== undefined && base !== '') return base
+  }
+  return id
+}
+
+interface ScopeRecord {
+  fiber: Fiber
+  ctx: Context
+  binding: SessionBinding
+}
+
+/** Root sessions service: list store, object-layer manager, scope tree, bindings, ancestry. */
+export class SessionsService {
+  /** List snapshot store (list RPC + host stream increments; re-pulled on reconnect). */
+  readonly list: SnapshotStore<SessionListState>
+  /** The object-layer instance cluster and frame dispatch entry (wired to the connection by the runtime apply). */
+  readonly manager: SessionManager
+
+  private readonly scopes = new Map<SessionId, ScopeRecord>()
+  /** Most recently resolved binding id — the watch approximation for deferred teardown. */
+  private watched: SessionId | undefined
+  /** Removed-while-watched sessions whose teardown waits for the watch to move away. */
+  private readonly deferredRemovals = new Set<SessionId>()
+
+  /**
+   * @param ctx - client root context (scope fibers mount under it).
+   * @param api - wire client shared with every Session.
+   */
+  constructor(private readonly rootCtx: Context, api: IApiClient) {
+    this.manager = new SessionManager(api)
+    this.list = createSnapshotStore<SessionListState>({ ids: [], byId: {} })
+    // The manager owns wire truth; the store is its projection. Manager
+    // notifications are already microtask-batched.
+    this.manager.subscribe(() => { this.projectList() })
+    rootCtx.reflect.provide('sessions', this, undefined)
+  }
+
+  /**
+   * Create a session on the host.
+   * @param opts - creation options (project directory).
+   * @returns the new session id.
+   */
+  async create(opts: { cwd?: string } = {}): Promise<SessionId> {
+    const result = await this.manager.create(opts.cwd)
+    if (!result.ok) throw new Error(`session create failed: ${result.error.code}: ${result.error.message}`)
+    return result.value.sessionId
+  }
+
+  /**
+   * Resolve a session-scoped context view (use-and-discard).
+   * @param id - session id.
+   * @returns scoped ctx, or undefined for a session neither listed nor already scoped.
+   */
+  scope(id: SessionId): Context | undefined {
+    return this.resolve(id)?.ctx
+  }
+
+  /**
+   * Resolve the stable session binding (SessionProvider's resolveBinding feed).
+   * @param id - session id.
+   * @returns binding, or undefined for a session neither listed nor already scoped.
+   */
+  binding(id: SessionId): SessionBinding | undefined {
+    const record = this.resolve(id)
+    if (record === undefined) return undefined
+    if (this.watched !== id) {
+      this.watched = id
+      this.sweepDeferred()
+    }
+    return record.binding
+  }
+
+  /**
+   * Breadcrumb feed: walk parentId links inside the list store.
+   * @param id - session id.
+   * @returns summaries from root ancestor to the session itself (empty when unknown; a broken link stops the walk).
+   */
+  ancestry(id: SessionId): SessionSummary[] {
+    const { byId } = this.list.getSnapshot()
+    const chain: SessionSummary[] = []
+    let cursor: SessionId | undefined = id
+    while (cursor !== undefined) {
+      const summary: SessionSummary | undefined = byId[cursor]
+      if (summary === undefined || chain.includes(summary)) break
+      chain.unshift(summary)
+      cursor = summary.parentId
+    }
+    return chain
+  }
+
+  /** Lazily mint the scope + binding for a listed (or already-scoped) session. */
+  private resolve(id: SessionId): ScopeRecord | undefined {
+    const existing = this.scopes.get(id)
+    if (existing !== undefined) return existing
+    // Frozen scopes outlive the list; new scopes are only minted for listed sessions.
+    if (this.list.getSnapshot().byId[id] === undefined) return undefined
+    const fiber = this.rootCtx.plugin(sessionScope)
+    const ctx = fiber.ctx.extend({ [kScope]: id })
+    const record: ScopeRecord = {
+      fiber,
+      ctx,
+      binding: { sessionId: id, session: this.manager.get(id), ctx },
+    }
+    this.scopes.set(id, record)
+    return record
+  }
+
+  /** Project the manager's list snapshot into the store (title derivation is display-only). */
+  private projectList(): void {
+    const items = this.manager.getListSnapshot().items
+    const ids: SessionId[] = []
+    const byId: Record<SessionId, SessionSummary> = {}
+    for (const entry of items) {
+      ids.push(entry.sessionId)
+      byId[entry.sessionId] = {
+        id: entry.sessionId,
+        title: titleOf(entry.cwd, entry.sessionId),
+        running: entry.running,
+        updatedAt: entry.updatedAt,
+        ...(entry.cwd !== undefined ? { cwd: entry.cwd } : {}),
+        ...(entry.parentSessionId !== undefined ? { parentId: entry.parentSessionId } : {}),
+      }
+    }
+    this.list.set({ ids, byId })
+    this.pruneScopes(byId)
+  }
+
+  /** Tear down scopes for removed sessions nobody watches; the watched one defers until the watch moves. */
+  private pruneScopes(byId: Record<SessionId, SessionSummary>): void {
+    for (const [id, record] of this.scopes) {
+      if (byId[id] !== undefined) continue
+      if (id === this.watched) {
+        this.deferredRemovals.add(id)
+        continue
+      }
+      this.scopes.delete(id)
+      this.deferredRemovals.delete(id)
+      void record.fiber.dispose()
+    }
+  }
+
+  /** Run deferred teardowns whose session is no longer watched (called when the watch moves). */
+  private sweepDeferred(): void {
+    for (const id of [...this.deferredRemovals]) {
+      if (id === this.watched) continue
+      // Still absent from the list? (A re-added id cancels the deferred teardown.)
+      if (this.list.getSnapshot().byId[id] !== undefined) {
+        this.deferredRemovals.delete(id)
+        continue
+      }
+      const record = this.scopes.get(id)
+      this.deferredRemovals.delete(id)
+      if (record !== undefined) {
+        this.scopes.delete(id)
+        void record.fiber.dispose()
+      }
+    }
+  }
+}

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

@@ -0,0 +1,527 @@
+// Session: wraps every contract call that needs a sessionId + all conversation state for this
+// session (design §A.2/§A.9/§D.2/§D.3). Instances are resident (ruling 2): never destroyed once
+// created, they keep consuming mux frames in the background; React connects directly via
+// subscribe/getSnapshot.
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type { HistoryEntry, IApiClient, MuxFrame, RpcError, RpcId, RpcResult, SessionId, ToolEventView } from '@deepseek-ai/dsh-client-connection/client'
+import { transportError } from '@deepseek-ai/dsh-client-connection/client'
+import type { ObservableSnapshot, SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import type {
+  ConversationNode, ConversationSnapshot, OpenState, PendingInteraction, PromptError, RunningToolCall,
+} from './conversation.ts'
+import { FoldAdapter } from './fold-adapter.ts'
+import { Notifier } from './notifier.ts'
+import { PartialAccumulator } from './partial.ts'
+
+/** Messages per page (F.4 ledger: promote to Config at graduation; every call site references this constant). */
+export const PAGE_MESSAGES = 50
+
+/** Per-session state owner: event window + fold + partial, snapshot out via uSES (see the web client architecture RFC). */
+export class Session implements ObservableSnapshot<ConversationSnapshot> {
+  /** Typed selector hook bound to this instance (the SessionBinding `useSession` source). */
+  readonly useSelector: SnapshotSelectorHook<ConversationSnapshot> = bindSnapshotSelector(this)
+
+  // ---- Window and derived state (all private; the snapshot is the only read surface) ----
+  private events: SessionEvent[] = []
+  /** Wire views aligned with `events` by index (envelope-level annotations; undefined = no view).
+   *  Kept parallel rather than merged so `events` stays the raw log slice (model-visible ⟺ logged). */
+  private views: (ToolEventView | undefined)[] = []
+  private baseSeq = 0
+  private hasMore = false
+  private openState: OpenState = 'cold'
+  private openError: RpcError | null = null
+  private openPromise: Promise<void> | null = null
+  /** Bumped by resync to invalidate an in-flight doOpen: a reconnect must rebuild, never adopt
+   *  a pre-disconnect open whose history request is already doomed (audit S4). Stale doOpen
+   *  passes drop all writes once the generation moves on. */
+  private openGeneration = 0
+  private loadingOlder = false
+  private readonly foldAdapter = new FoldAdapter()
+  private partial: PartialAccumulator | null = null
+  private openCalls = new Map<string, RunningToolCall>()
+  /** Interrupted-turn terminal nodes (frozen partial text / aborted tool cards), merged into the flow by seq.
+   *  Derived from window events (turn/end sweep) — rebuilt by rebuildDerivedFromWindow like partial/openCalls. */
+  private frozenNodes: ConversationNode[] = []
+  private pending = new Map<string, PendingInteraction>()
+  // Revision counters + caches backing the snapshot's reference-stability contract (§A.9.4/§C.2,
+  // audit S5): buildSnapshot reuses the previous array when the revision is unchanged, so
+  // React.memo children survive unrelated snapshot swaps (chunk storms must not re-render every
+  // tool card and pending card). Mutation sites bump the matching revision. partial needs no
+  // counter — PartialAccumulator.toPartial already returns a cached reference when unchanged.
+  private callsRev = 0
+  private callsCache: { rev: number; value: RunningToolCall[] } | null = null
+  private pendingRev = 0
+  private pendingCache: { rev: number; value: PendingInteraction[] } | null = null
+  private frozenRev = 0
+  private nodesCache: { folded: readonly ConversationNode[]; frozenRev: number; value: readonly ConversationNode[] } | null = null
+  private running = false
+  private removed = false
+  private promptError: PromptError | null = null
+  private lastAgentError: string | null = null
+  /** Buffer for live events arriving while open/resync is in flight (stitched by seq once history lands, §D.3). */
+  private liveBuffer: { event: SessionEvent; view: ToolEventView | undefined }[] = []
+  /** Gap-repair (resync-lite) in flight: acceptLiveEvent detours to liveBuffer until the tail page lands (audit S3). */
+  private stitching = false
+  /** subscribed.lastSeq baseline (gap detection; null when no subscribed frame arrived — degrade to the liveBuffer dedup path). */
+  private subscribedLastSeq: number | null = null
+
+  private snapshotCache: ConversationSnapshot
+  private readonly notifier = new Notifier(() => {
+    this.snapshotCache = this.buildSnapshot()
+  })
+
+  constructor(readonly sessionId: SessionId, private readonly api: IApiClient) {
+    this.snapshotCache = this.buildSnapshot()
+  }
+
+  // ---- Operations ----
+
+  /**
+   * Send (queue/steer passed through 1:1); failures land in the snapshot's promptError.
+   * @param content - core content blocks verbatim.
+   * @param mode - queue appends after the current turn; steer interrupts it.
+   * @returns the prompt result (also mirrored into promptError on failure).
+   */
+  async prompt(content: ContentBlock[], mode: 'queue' | 'steer'): Promise<RpcResult<{ accepted: true }>> {
+    this.promptError = null
+    this.lastAgentError = null
+    this.notifier.markDirty()
+    let result: RpcResult<{ accepted: true }>
+    try {
+      result = (await this.api.sessions.prompt({ sessionId: this.sessionId, mode, content })).result
+    } catch (error) {
+      result = transportError(error)
+    }
+    if (!result.ok) {
+      this.promptError = { op: 'send', error: result.error }
+      this.notifier.markDirty()
+    }
+    return result
+  }
+
+  /**
+   * Stop: contract session.cancel 1:1; failures land in promptError (same error-strip display slot).
+   * @returns the cancel result.
+   */
+  async cancel(): Promise<RpcResult<{ accepted: true }>> {
+    let result: RpcResult<{ accepted: true }>
+    try {
+      result = (await this.api.sessions.cancel({ sessionId: this.sessionId })).result
+    } catch (error) {
+      result = transportError(error)
+    }
+    if (!result.ok) {
+      this.promptError = { op: 'stop', error: result.error }
+      this.notifier.markDirty()
+    }
+    return result
+  }
+
+  /** 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()
+    if (this.openPromise !== null) return this.openPromise
+    const promise = this.doOpen(this.openGeneration).finally(() => {
+      // Identity-guarded: a superseded open must not null out the promise resync just started.
+      if (this.openPromise === promise) this.openPromise = null
+    })
+    this.openPromise = promise
+    return promise
+  }
+
+  /** Page up: pull one earlier page with the window's first seq as beforeSeq and prepend (§D.2). */
+  async loadOlder(): Promise<void> {
+    if (this.openState !== 'open' || !this.hasMore || this.loadingOlder) return
+    this.loadingOlder = true
+    this.notifier.markDirty()
+    try {
+      const { result } = await this.api.sessions.history({
+        sessionId: this.sessionId, beforeSeq: this.baseSeq, maxMessages: PAGE_MESSAGES,
+      })
+      if (!result.ok) return // keep the window as-is; do not overwrite openError (open already succeeded)
+      const older = result.value.events
+      if (older.length === 0) {
+        this.hasMore = result.value.hasMore
+        return
+      }
+      const tail = older[older.length - 1]
+      if (tail === undefined || tail.event.seq + 1 !== this.baseSeq) {
+        // §D.2 continuity assertion: on violation drop the page fail-soft rather than render an out-of-order stream.
+        console.error(`[web-runtime] history page discontinuous: tail seq ${tail?.event.seq} vs baseSeq ${this.baseSeq}`)
+        this.hasMore = false
+        return
+      }
+      this.events = [...older.map(e => e.event), ...this.events]
+      this.views = [...older.map(e => e.view), ...this.views]
+      /* v8 ignore next -- the ?? arm needs older[0] undefined, but the empty-page branch above already returned. */
+      this.baseSeq = older[0]?.event.seq ?? this.baseSeq
+      this.hasMore = result.value.hasMore
+      this.foldAdapter.reset(this.events, this.baseSeq, this.views) // prepend forces a rebuild (sentinel count changed)
+      this.rebuildDerivedFromWindow()
+    } catch (error) {
+      console.error('[web-runtime] loadOlder failed:', error)
+    } finally {
+      this.loadingOlder = false
+      this.notifier.markDirty()
+    }
+  }
+
+  /** Reconnect rebuild (manager calls this on onConnected for instances that were opened):
+   *  reset the window and rerun open; pending waits for the baseline replay. Invalidates any
+   *  in-flight open first — its history request rode the dead connection and must not settle
+   *  the fresh generation into 'error' (audit S4). */
+  async resync(): Promise<void> {
+    if (this.openState === 'cold') return // never opened: no window to rebuild (doOpen flips to 'loading' synchronously, so cold implies no in-flight open)
+    this.openGeneration++
+    this.openPromise = null
+    this.openState = 'cold'
+    this.openError = null
+    this.events = []
+    this.views = []
+    this.baseSeq = 0
+    this.pending.clear() // the subscribed baseline replay re-sends still-pending requested frames verbatim
+    this.pendingRev++
+    this.subscribedLastSeq = null
+    this.liveBuffer = []
+    this.notifier.markDirty()
+    await this.open()
+  }
+
+  // ---- Subscription surface (useSyncExternalStore direct wiring) ----
+
+  /**
+   * uSES subscription entry.
+   * @param listener - change callback.
+   * @returns the unsubscribe function.
+   */
+  subscribe(listener: () => void): () => void {
+    return this.notifier.subscribe(listener)
+  }
+
+  /**
+   * Cached conversation snapshot (rebuilt lazily when dirty with no listeners).
+   * @returns the cached reference (stable until the next flush).
+   */
+  getSnapshot(): ConversationSnapshot {
+    this.notifier.ensureFresh()
+    return this.snapshotCache
+  }
+
+  // ---- Manager-only entry points (@internal; never called by the UI) ----
+
+  /**
+   * Mux frame arrival (the dispatch switch).
+   * @param rpcId - the frame envelope id (the respond backfill key for requested frames).
+   * @param frame - the routed frame.
+   */
+  handleMuxEnvelope(rpcId: RpcId, frame: MuxFrame): void {
+    switch (frame.type) {
+      case 'session/event': {
+        this.acceptLiveEvent(frame.event, frame.view)
+        return
+      }
+      case 'session/subscribed': {
+        this.subscribedLastSeq = frame.lastSeq
+        return // pure baseline bookkeeping, no visible change
+      }
+      case 'approval/requested': {
+        this.pending.set(`a:${rpcId}`, {
+          kind: 'approval', rpcId, approvalId: frame.approvalId, toolName: frame.toolName,
+          ...(frame.callId !== undefined ? { callId: frame.callId } : {}),
+          ...(frame.reason !== undefined ? { reason: frame.reason } : {}),
+        })
+        this.pendingRev++
+        this.notifier.markDirty()
+        return
+      }
+      case 'approval/resolved': {
+        for (const [key, item] of this.pending) {
+          if (item.kind === 'approval' && item.approvalId === frame.approvalId) {
+            this.pending.delete(key)
+            this.pendingRev++
+          }
+        }
+        this.notifier.markDirty()
+        return
+      }
+      case 'question/requested': {
+        this.pending.set(`q:${rpcId}`, { kind: 'question', rpcId, questions: frame.questions })
+        this.pendingRev++
+        this.notifier.markDirty()
+        return
+      }
+      case 'question/resolved': {
+        if (this.pending.delete(`q:${frame.questionRpcId}`)) this.pendingRev++
+        this.notifier.markDirty()
+        return
+      }
+      default:
+        return // stream/error never reaches Session (Controller converges it); unknown frames ignored (documented default)
+    }
+  }
+
+  /**
+   * Running-bit relay from the host stream (list entry and snapshot stay consistent).
+   * @param running - the new running state.
+   */
+  handleRunning(running: boolean): void {
+    if (this.running === running) return
+    this.running = running
+    this.notifier.markDirty()
+  }
+
+  /** host/session-removed relay: flag the snapshot (instance survives — resident-instance rule). */
+  handleRemoved(): void {
+    this.removed = true
+    this.notifier.markDirty()
+  }
+
+  /**
+   * host/agent-error relay: the only outlet for live failures with no turn position.
+   * @param message - the stringified error.
+   */
+  handleAgentError(message: string): void {
+    this.lastAgentError = message
+    this.notifier.markDirty()
+  }
+
+  /** Instance-eviction hook, reserved no-op (design §F.6): resident instances are never destroyed
+   *  in v1; an eviction policy lands here (unsubscribe, drop buffers) without touching call sites. */
+  dispose(): void {}
+
+  // ---- 私有 ----
+
+  /** @param generation - openGeneration at launch; every await re-checks it and a stale pass
+   *  drops all writes (resync superseded this open — its outcome belongs to a dead connection). */
+  private async doOpen(generation: number): Promise<void> {
+    this.openState = 'loading'
+    this.openError = null
+    this.notifier.markDirty()
+    try {
+      let { result } = await this.api.sessions.history({ sessionId: this.sessionId, maxMessages: PAGE_MESSAGES })
+      if (generation !== this.openGeneration) return
+      if (!result.ok) {
+        this.openState = 'error'
+        this.openError = result.error
+        return
+      }
+      this.installWindow(result.value.events, result.value.hasMore)
+      // Gap detection (§D.3-4): baseline past the window tail and liveBuffer did not cover it -> pull the tail page once more.
+      const tailSeq = this.windowTailSeq()
+      if (this.subscribedLastSeq !== null && tailSeq !== null && this.subscribedLastSeq > tailSeq) {
+        result = (await this.api.sessions.history({ sessionId: this.sessionId, maxMessages: PAGE_MESSAGES })).result
+        if (generation !== this.openGeneration) return
+        if (result.ok) this.installWindow(result.value.events, result.value.hasMore)
+      }
+      this.openState = 'open'
+    } catch (error) {
+      if (generation !== this.openGeneration) return
+      this.openState = 'error'
+      const folded = transportError<never>(error)
+      /* v8 ignore next -- the `? null` arm is unreachable: transportError always returns ok:false. */
+      this.openError = folded.ok ? null : folded.error
+    } finally {
+      if (generation === this.openGeneration) this.notifier.markDirty()
+    }
+  }
+
+  /** Install the history window + stitch the liveBuffer (seq is the sole dedup key).
+   *  Stitching MUST NOT route through acceptLiveEvent: openState is still 'loading' here
+   *  (doOpen flips it after install), so recursing would push every buffered event straight
+   *  back into liveBuffer where nothing ever drains it — a silent drop loop (audit S1). */
+  private installWindow(entries: HistoryEntry[], hasMore: boolean): void {
+    this.events = entries.map(e => e.event)
+    this.views = entries.map(e => e.view)
+    this.baseSeq = this.events[0]?.seq ?? 0
+    this.hasMore = hasMore
+    this.foldAdapter.reset(this.events, this.baseSeq, this.views)
+    this.rebuildDerivedFromWindow()
+    const buffered = this.liveBuffer
+    this.liveBuffer = []
+    for (const item of buffered) this.appendLive(item.event, item.view)
+    this.notifier.markDirty()
+  }
+
+  /** Seq-guarded append shared by stitching and the open-state live path. */
+  private appendLive(event: SessionEvent, view?: ToolEventView): void {
+    const tailSeq = this.windowTailSeq()
+    if (tailSeq !== null && event.seq <= tailSeq) return // replay overlap, drop
+    this.events.push(event)
+    this.views.push(view)
+    this.foldAdapter.append(event, view)
+    this.applyEventSideEffects(event, view)
+  }
+
+  /** Land a live session/event (open/repair in flight -> buffer; overlapping seq -> drop;
+   *  a seq gap -> buffer + tail-page repull instead of appending a hole (audit S3: a gap is an
+   *  expected reconnect-window artifact, repaired by refetch — never fed to the fold to trip
+   *  its continuity assertion into the degraded view). */
+  private acceptLiveEvent(event: SessionEvent, view?: ToolEventView): void {
+    if (this.openState === 'loading' || this.stitching) {
+      this.liveBuffer.push({ event, view })
+      return
+    }
+    if (this.openState !== 'open') return // cold/error: no window upkeep (history fully backfills on open)
+    const tailSeq = this.windowTailSeq()
+    if (tailSeq !== null && event.seq > tailSeq + 1) {
+      this.liveBuffer.push({ event, view })
+      void this.repairGap()
+      return
+    }
+    this.appendLive(event, view)
+    this.notifier.markDirty()
+  }
+
+  /** Resync-lite (audit S3): repull the tail page and stitch the liveBuffer through the shared
+   *  installWindow path. No openState transition — the UI keeps the current window (no loading
+   *  flash); events arriving meanwhile detour to liveBuffer via the stitching flag. */
+  private async repairGap(): Promise<void> {
+    /* v8 ignore next -- re-entry guard: acceptLiveEvent already detours to liveBuffer while stitching, so no second call reaches here. */
+    if (this.stitching) return
+    this.stitching = true
+    const generation = this.openGeneration
+    try {
+      const { result } = await this.api.sessions.history({ sessionId: this.sessionId, maxMessages: PAGE_MESSAGES })
+      // Failure or superseded by a full resync: drop — the resync path rebuilds and clears the buffer itself.
+      if (result.ok && generation === this.openGeneration && this.openState === 'open') {
+        this.installWindow(result.value.events, result.value.hasMore)
+      }
+    } catch (error) {
+      console.error('[web-runtime] gap repair failed:', error)
+    } finally {
+      this.stitching = false
+    }
+  }
+
+  /** Per-event side effects (right column of the §A.9 dispatch table):
+   *  chunk accumulation / partial clear on finalize / openCalls add-remove. */
+  private applyEventSideEffects(event: SessionEvent, view?: ToolEventView): void {
+    switch (event.type) {
+      case 'assistant/chunk': {
+        const { turn, step, chunk } = event.data
+        if (this.partial === null || this.partial.turn !== turn || this.partial.step !== step) {
+          this.partial = new PartialAccumulator(turn, step)
+        }
+        this.partial.push(chunk)
+        return
+      }
+      case 'assistant/message': {
+        if (this.partial !== null && this.partial.turn === event.data.turn && this.partial.step === event.data.step) {
+          this.partial = null // finalize swaps in place (same notification batch, no flicker)
+        }
+        return
+      }
+      case 'tool/call': {
+        this.openCalls.set(String(event.data.callId), {
+          callId: String(event.data.callId), name: event.data.name, argsRaw: event.data.arguments,
+          turn: event.data.turn, step: event.data.step,
+          callView: view?.for === 'call' ? view.view : null,
+        })
+        this.callsRev++
+        return
+      }
+      case 'tool/result': {
+        if (this.openCalls.delete(String(event.data.callId))) this.callsRev++
+        return
+      }
+      case 'turn/end': {
+        // Aborted turns never finalize. The accumulated partial is VALUE, not residue: freeze it
+        // into an interrupted terminal node (pulse stops, text survives) instead of deleting it.
+        // Shared by live and window-replay paths, so a refresh reconstructs the same frozen node
+        // from the logged chunks. Content-free partials are dropped outright.
+        if (this.partial !== null && this.partial.turn === event.data.turn) {
+          const { blocks } = this.partial.toPartial()
+          const visible = blocks.some(b => (b.kind === 'text' || b.kind === 'reasoning' ? b.text !== '' : true))
+          if (visible) {
+            // Fractional seq: strictly after every event of this turn (all < turn/end seq), before the next turn.
+            this.frozenNodes.push({
+              kind: 'assistant', seq: event.seq - 0.9, turn: this.partial.turn, step: this.partial.step,
+              blocks, interrupted: true,
+            })
+            this.frozenRev++
+          }
+          this.partial = null
+        }
+        let callOffset = 0
+        for (const [callId, call] of this.openCalls) {
+          if (call.turn !== event.data.turn) continue
+          this.openCalls.delete(callId)
+          this.callsRev++
+          // The spinner card becomes an interrupted terminal card (never vanishes mid-flow).
+          this.frozenNodes.push({
+            kind: 'tool-result', seq: event.seq - 0.8 + callOffset++ * 0.01, callId,
+            call: { name: call.name, argsRaw: call.argsRaw },
+            content: [], isError: true, error: { name: 'Interrupted', code: 'interrupted' },
+            callView: call.callView, resultView: null,
+          })
+          this.frozenRev++
+        }
+        return
+      }
+      default:
+        return
+    }
+  }
+
+  /** Re-derive state (partial/openCalls/frozenNodes) from raw window events after a rebuild — keeps
+   *  paging/stitching consistent, and makes the live freeze and the history replay converge on the
+   *  same interrupted nodes (chunks are logged, so the replayed sweep re-freezes identical text). */
+  private rebuildDerivedFromWindow(): void {
+    this.partial = null
+    this.openCalls.clear()
+    this.callsRev++
+    this.frozenNodes = []
+    this.frozenRev++
+    for (let i = 0; i < this.events.length; i++) {
+      const event = this.events[i]
+      /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
+      if (event !== undefined) this.applyEventSideEffects(event, this.views[i])
+    }
+  }
+
+  private windowTailSeq(): number | null {
+    const tail = this.events[this.events.length - 1]
+    return tail === undefined ? null : tail.seq
+  }
+
+  private buildSnapshot(): ConversationSnapshot {
+    const { nodes: folded, degraded } = this.foldAdapter.nodes()
+    // Frozen interrupted nodes ride fractional seqs: a stable merge keeps them in flow order.
+    // The merged array is cached on (folded reference, frozenRev) so an unchanged flow keeps its
+    // reference across snapshot swaps (§A.9.4).
+    let nodes: readonly ConversationNode[]
+    if (this.nodesCache !== null && this.nodesCache.folded === folded && this.nodesCache.frozenRev === this.frozenRev) {
+      nodes = this.nodesCache.value
+    } else {
+      nodes = this.frozenNodes.length === 0
+        ? folded
+        : [...folded, ...this.frozenNodes].sort((a, b) => a.seq - b.seq)
+      this.nodesCache = { folded, frozenRev: this.frozenRev, value: nodes }
+    }
+    if (this.callsCache === null || this.callsCache.rev !== this.callsRev) {
+      this.callsCache = { rev: this.callsRev, value: [...this.openCalls.values()] }
+    }
+    if (this.pendingCache === null || this.pendingCache.rev !== this.pendingRev) {
+      this.pendingCache = { rev: this.pendingRev, value: [...this.pending.values()] }
+    }
+    return {
+      sessionId: this.sessionId,
+      nodes,
+      foldDegraded: degraded,
+      partial: this.partial?.toPartial() ?? null,
+      runningCalls: this.callsCache.value,
+      pending: this.pendingCache.value,
+      running: this.running,
+      removed: this.removed,
+      openState: this.openState,
+      openError: this.openError,
+      hasMore: this.hasMore,
+      loadingOlder: this.loadingOlder,
+      promptError: this.promptError,
+      lastAgentError: this.lastAgentError,
+    }
+  }
+}

packages/client/runtime/src/client/slots.ts

@@ -0,0 +1,107 @@
+/**
+ * SlotsService: cordis Service wrapper over the pure SlotCore (ui-slots).
+ * Every mutation re-emits as the 'slots/changed' cordis event; define/register
+ * run through the caller's ctx.effect so a plugin's registrations are
+ * collected when its fiber unloads (cordis-native cascade).
+ */
+/* eslint-disable @typescript-eslint/no-redundant-type-constituents --
+ * `keyof SlotMap & string` is the declare-merge key pattern: SlotMap is empty
+ * in this compilation unit (intersection reads `never`) but consumers merge
+ * keys in; the rule fires on the empty-map view, not on real redundancy. */
+import { Service } from 'cordis'
+import type { Context } from 'cordis'
+import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ComposedProps, RegisterArgs, SlotComponent, SlotEntry, SlotEntryDef, SlotMap, SlotSpec } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ClientContext } from './index.ts'
+
+/** cordis Service wrapper over the pure SlotCore; mutations re-emit as 'slots/changed'. */
+export class SlotsService extends Service {
+  private readonly _core = new SlotCore()
+
+  /**
+   * @param ctx - owning root context.
+   */
+  constructor(ctx: Context) {
+    super(ctx, 'slots')
+    this._core.onMutate((key) => { ctx.emit('slots/changed', key) })
+  }
+
+  /**
+   * Record a slot spec (delegates to SlotCore.define; disposal follows the caller's fiber).
+   * @param key - SlotMap key.
+   * @param spec - kind/scope spec.
+   * @returns disposer.
+   */
+  define<K extends keyof SlotMap & string>(key: K, spec: SlotSpec<SlotMap[K]>): () => void {
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
+    return this.ctx.effect(() => this._core.define(key, spec), 'slots.define()')
+  }
+
+  /**
+   * Contribute a component (delegates to SlotCore.register; disposal follows the caller's fiber).
+   * @param key - SlotMap key.
+   * @param component - contributed component.
+   * @param args - kind-shaped options (mandatory for keyed/list kinds); the
+   * inject factory's binding is pinned to ClientContext.
+   * @returns disposer.
+   */
+  register<K extends keyof SlotMap & string, I extends object = Record<string, unknown>>(
+    // Client-context registrations have exactly one ctx shape: pin Ctx to
+    // ClientContext so inject factories dot services without a cast.
+    key: K, component: SlotComponent<ComposedProps<K, NoInfer<I>>>,
+    ...args: RegisterArgs<SlotMap[K], I, ClientContext>): () => void {
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
+    return this.ctx.effect(() => this._core.register<K, I, ClientContext>(key, component, ...args), 'slots.register()')
+  }
+
+  /**
+   * Snapshot entries for a key.
+   * @param key - SlotMap key.
+   * @returns registered entries (stable reference between mutations).
+   */
+  entries<K extends keyof SlotMap & string>(key: K): readonly SlotEntry<SlotMap[K]>[] {
+    return this._core.entries(key)
+  }
+
+  /**
+   * Look up a defined spec.
+   * @param key - SlotMap key.
+   * @returns spec or undefined.
+   */
+  spec<K extends keyof SlotMap & string>(key: K): SlotSpec<SlotMap[K]> | undefined {
+    return this._core.spec(key)
+  }
+
+  /**
+   * Dynamic-key escape hatch for spec lookup (renderer-side string keys).
+   * @param key - candidate slot key.
+   * @returns wide-typed spec or undefined.
+   */
+  specDynamic(key: string): SlotSpec<SlotEntryDef> | undefined {
+    return this._core.specDynamic(key)
+  }
+
+  /**
+   * Subscribe to a key's registration changes (microtask-batched).
+   * @param key - SlotMap key.
+   * @param fn - change callback.
+   * @returns unsubscribe.
+   */
+  subscribe(key: keyof SlotMap & string, fn: () => void): () => void {
+    return this._core.subscribe(key, fn)
+  }
+
+  /**
+   * Version counter for uSES pairing.
+   * @param key - SlotMap key.
+   * @returns current version.
+   */
+  getVersion(key: keyof SlotMap & string): number {
+    return this._core.getVersion(key)
+  }
+
+  /** The wrapped pure core (web-react's scopedSlots outlet reads through this). */
+  get core(): SlotCore {
+    return this._core
+  }
+}

packages/client/runtime/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Runtime plugin, node half. The implementation lives entirely in the client
+ * half (src/client/ — SlotsService, SessionsService + object layer, and the
+ * shell-held ClientLoader under ./loader); consumers import the /client or
+ * /loader subpaths. The empty apply exists so the plugin appears in the host
+ * Loader (lifecycle governance + dshClient discovery). Contract:
+ * api-contracts v3 section 4.
+ */
+
+/** Host plugin body — no host-side behavior for the runtime plugin. */
+export function apply(_ctx: unknown): void {}

packages/client/runtime/src/invariant.ts

@@ -0,0 +1,52 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-runtime`.
+ * @module @deepseek-ai/dsh-client-runtime/invariant
+ */
+
+/* jscpd:ignore-start */
+/* eslint-disable @typescript-eslint/no-redundant-type-constituents --
+ * `keyof SlotMap & string` is the declare-merge key pattern: SlotMap is empty
+ * in this compilation unit (intersection reads `never`) but consumers merge
+ * keys in; the rule fires on the empty-map view, not on real redundancy. */
+import type { Context } from 'cordis'
+import type { SlotMap } from '@deepseek-ai/dsh-client-ui-slots'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-runtime'
+
+/** Cordis companion plugin name. */
+export const name = 'client-runtime-invariant'
+/** Service required before the companion can register. */
+export const inject = ['invariants']
+
+/**
+ * Owned relation: every 'slots/changed'(key) emission must observe the
+ * mutation already applied — SlotCore bumps the key's version synchronously
+ * before the service re-emits, so a zero version at dispatch time means the
+ * event fired without (or ahead of) its mutation.
+ */
+const install: InvariantInstaller = (ctx, fail) => {
+  ctx.on('internal/dispatch', (_mode, eventName, args) => {
+    if (eventName !== 'slots/changed') return
+    const key: unknown = args[0]
+    if (typeof key !== 'string' || key === '') {
+      fail("'slots/changed' dispatched without a slot key argument")
+      return
+    }
+    const slots = ctx.get('slots')
+    // Event payloads carry keys as plain strings; getVersion is statically
+    // keyed, so restore the SlotMap-key type after the runtime string check.
+    if (slots !== undefined && slots.getVersion(key as keyof SlotMap & string) === 0) {
+      fail(`'slots/changed' fired for "${key}" before any mutation bumped its version — emission must follow the applied mutation`)
+    }
+  }, { global: true })
+}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/client/runtime/tests/client-loader-bundle.e2e.ts

@@ -0,0 +1,77 @@
+/**
+ * Real-bundle smoke: the actual tsdown client bundle of ui-layout runs
+ * through the loader chain (execute → handoff → factory(require) → apply →
+ * export re-registration). Skips when the bundle is not built (dist/ is a
+ * build product; `pnpm --filter @deepseek-ai/dsh-client-ui-layout build`).
+ */
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import * as uiSlots from '@deepseek-ai/dsh-client-ui-slots'
+import * as webReact from '@deepseek-ai/dsh-client-web-react'
+import { createClientLoader } from '../src/client/loader/index.ts'
+import type { ClientPluginHandoff } from '../src/client/loader/index.ts'
+import { SessionsService } from '../src/client/sessions/service.ts'
+import { SlotsService } from '../src/client/slots.ts'
+import { FakeApiClient } from './fake-api.ts'
+
+const LAYOUT_ID = '@deepseek-ai/dsh-client-ui-layout'
+
+type Win = { DSHClientProxy?: { loadPlugin(h: ClientPluginHandoff): void }; window?: unknown }
+
+afterEach(() => {
+  delete (globalThis as Win).DSHClientProxy
+  delete (globalThis as Win).window
+})
+
+function readLayoutBundle(): string | undefined {
+  try {
+    const require = createRequire(import.meta.url)
+    return readFileSync(require.resolve(`${LAYOUT_ID}/client`), 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+describe('real tsdown bundle through the loader', () => {
+  const code = readLayoutBundle()
+
+  it.skipIf(code === undefined)('loads ui-layout lib/client.js: handoff, DI require, apply, export surface', async () => {
+    // The bundle banner addresses window.DSHClientProxy; node has no window —
+    // alias it to globalThis so the loader-installed proxy is reachable.
+    ;(globalThis as Win).window = globalThis
+    const ctx = new Context()
+    // The layout apply consumes the slots + sessions services; the real chain
+    // loads the runtime bundle first — stand both up directly here.
+    ctx.plugin(SlotsService)
+    await ctx.fiber.await()
+    new SessionsService(ctx, new FakeApiClient())
+    const loader = createClientLoader({
+      ctx,
+      // The real bundle externals resolved from the seeded table. React is a
+      // type-only import in the layout bundle today, but jsx-runtime is real.
+      modules: {
+        'react': await import('react'),
+        'react/jsx-runtime': await import('react/jsx-runtime'),
+        '@deepseek-ai/dsh-client-ui-slots': uiSlots,
+        '@deepseek-ai/dsh-client-web-react': webReact,
+      },
+      boot: { plugins: [{ id: LAYOUT_ID, url: `/plugins/${LAYOUT_ID}/client.js`, inject: [] }] },
+      fetchBundle: () => Promise.resolve(code as string),
+      // node has no DOM: evaluate the bundle body directly (same synchronous
+      // handoff contract as the <script> path).
+      executeBundle: (bundleCode) => {
+        // Node has no <script>: Function-evaluating the built bundle IS the
+        // system under test (same synchronous handoff as the browser path).
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval, @typescript-eslint/no-unsafe-call
+        new Function(bundleCode)()
+      },
+    })
+    loader.start()
+    await loader.settled()
+    expect(loader.status.getSnapshot()[LAYOUT_ID]).toBe('active')
+    const surface = loader.requireModule(LAYOUT_ID) as Record<string, unknown>
+    expect(typeof surface.apply).toBe('function')
+  })
+})

packages/client/runtime/tests/client-loader.spec.ts

@@ -0,0 +1,192 @@
+/**
+ * ClientLoader: handoff protocol (single slot, id reconciliation), DI require
+ * with export-surface re-registration, immediately-group barrier (parallel
+ * fetch / topology execution / full-group barrier), status store, settled,
+ * failure modes (missing handoff, unknown dep, cycle, unload stub).
+ */
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import { createClientLoader } from '../src/client/loader/index.ts'
+import type { BootPluginEntry, ClientPluginHandoff } from '../src/client/loader/index.ts'
+
+type Win = { DSHClientProxy?: { loadPlugin(h: ClientPluginHandoff): void }; __DSH_BOOT__?: { plugins: BootPluginEntry[] } }
+const win = globalThis as Win
+
+afterEach(() => {
+  delete win.DSHClientProxy
+  delete win.__DSH_BOOT__
+})
+
+interface FakeBundle {
+  handoff: ClientPluginHandoff | null | ((require: (spec: string) => unknown) => Record<string, unknown>)
+}
+
+interface Bench {
+  loader: ReturnType<typeof createClientLoader>
+  fetched: string[]
+  executed: string[]
+  fetchGate: Map<string, () => void>
+}
+
+/** Build a loader over scripted fake bundles keyed by url; fetches resolve when released (or immediately). */
+function bench(
+  plugins: BootPluginEntry[],
+  bundles: Record<string, FakeBundle>,
+  opts: { modules?: Record<string, unknown>; gated?: string[] } = {},
+): Bench {
+  const ctx = new Context()
+  const fetched: string[] = []
+  const executed: string[] = []
+  const fetchGate = new Map<string, () => void>()
+  const loader = createClientLoader({
+    ctx,
+    modules: opts.modules ?? { react: { marker: 'react' } },
+    boot: { plugins },
+    fetchBundle: (url) => {
+      fetched.push(url)
+      if (opts.gated?.includes(url) === true) {
+        return new Promise<string>((resolve) => { fetchGate.set(url, () => { resolve(url) }) })
+      }
+      return Promise.resolve(url)
+    },
+    executeBundle: (code) => {
+      executed.push(code)
+      const bundle = bundles[code]
+      if (bundle === undefined) throw new Error(`no fake bundle for ${code}`)
+      if (bundle.handoff === null) return // simulates a bundle that never calls loadPlugin
+      if (typeof bundle.handoff === 'function') {
+        win.DSHClientProxy?.loadPlugin({ id: code.replace('/client.js', '').replace('/plugins/', ''), factory: bundle.handoff })
+        return
+      }
+      win.DSHClientProxy?.loadPlugin(bundle.handoff)
+    },
+  })
+  return { loader, fetched, executed, fetchGate }
+}
+
+const entry = (id: string, inject: string[] = [], immediately?: boolean): BootPluginEntry =>
+  ({ id, url: `/plugins/${id}/client.js`, inject, ...(immediately === true ? { immediately: true } : {}) })
+
+const okBundle = (applied?: string[], exports: Record<string, unknown> = {}): FakeBundle => ({
+  handoff: require => ({
+    apply: (pluginCtx: Context) => { void pluginCtx; applied?.push('applied') },
+    require,
+    ...exports,
+  }),
+})
+
+describe('load chain', () => {
+  it('runs fetch→execute→handoff→factory(require)→apply→export re-registration→status active', async () => {
+    const applied: string[] = []
+    const b = bench(
+      [entry('fake-base', [], true), entry('feature', ['fake-base'])],
+      {
+        '/plugins/fake-base/client.js': { handoff: () => ({ apply: () => { applied.push('fake-base') }, helper: 'base-helper' }) },
+        '/plugins/feature/client.js': {
+          handoff: (require) => {
+            // Later loader requires the earlier one's export surface (inject topology guarantee).
+            const fakeBase = ['fake','base'].join('-') // assembled so knip's static require() scan skips the fake id
+            const base = require(fakeBase) as { helper: string }
+            expect(base.helper).toBe('base-helper')
+            expect((require('react') as { marker: string }).marker).toBe('react')
+            return { apply: () => { applied.push('feature') } }
+          },
+        },
+      },
+    )
+    b.loader.start()
+    await b.loader.settled()
+    expect(applied).toEqual(['fake-base', 'feature'])
+    expect(b.loader.status.getSnapshot()).toEqual({ 'fake-base': 'active', feature: 'active' })
+    expect((b.loader.requireModule('fake-base') as { helper: string }).helper).toBe('base-helper')
+    expect(() => b.loader.requireModule('ghost')).toThrow(/not available/)
+  })
+
+  it('fetches the immediately group in parallel and holds the barrier before the rest', async () => {
+    const b = bench(
+      [entry('a', [], true), entry('b', ['a'], true), entry('later')],
+      {
+        '/plugins/a/client.js': okBundle(),
+        '/plugins/b/client.js': okBundle(),
+        '/plugins/later/client.js': okBundle(),
+      },
+      { gated: ['/plugins/a/client.js'] },
+    )
+    b.loader.start()
+    await Promise.resolve()
+    // Both early fetches are in flight before any execution; the late plugin is not fetched yet.
+    expect(b.fetched).toEqual(['/plugins/a/client.js', '/plugins/b/client.js'])
+    expect(b.executed).toEqual([])
+    b.fetchGate.get('/plugins/a/client.js')?.()
+    await b.loader.settled()
+    expect(b.executed).toEqual(['/plugins/a/client.js', '/plugins/b/client.js', '/plugins/later/client.js'])
+  })
+
+  it('orders execution by inject topology within each group', async () => {
+    const b = bench(
+      [entry('z-ui', ['a-base']), entry('a-base')],
+      { '/plugins/a-base/client.js': okBundle(), '/plugins/z-ui/client.js': okBundle() },
+    )
+    b.loader.start()
+    await b.loader.settled()
+    expect(b.executed).toEqual(['/plugins/a-base/client.js', '/plugins/z-ui/client.js'])
+  })
+})
+
+describe('failure modes (fail loud)', () => {
+  it('rejects settled and marks failed when a bundle never calls loadPlugin', async () => {
+    const b = bench([entry('silent')], { '/plugins/silent/client.js': { handoff: null } })
+    b.loader.start()
+    await expect(b.loader.settled()).rejects.toThrow(/without calling DSHClientProxy.loadPlugin/)
+    expect(b.loader.status.getSnapshot().silent).toBe('failed')
+  })
+
+  it('rejects on manifest/handoff id mismatch', async () => {
+    const b = bench([entry('expected')], {
+      '/plugins/expected/client.js': { handoff: { id: 'imposter', factory: () => ({ apply: () => {} }) } },
+    })
+    b.loader.start()
+    await expect(b.loader.settled()).rejects.toThrow(/id mismatch/)
+  })
+
+  it('rejects unknown inject targets, cycles, missing apply, unknown load ids, duplicate manifest ids', async () => {
+    // Sequential benches: each loader owns the window proxy, so release it between them.
+    const fresh = <T>(build: () => T): T => {
+      delete win.DSHClientProxy
+      return build()
+    }
+
+    const missing = fresh(() => bench([entry('x', ['nope'])], { '/plugins/x/client.js': okBundle() }))
+    missing.loader.start()
+    await expect(missing.loader.settled()).rejects.toThrow(/injects unknown plugin "nope"/)
+
+    const cyclic = fresh(() => bench(
+      [entry('p', ['q']), entry('q', ['p'])],
+      { '/plugins/p/client.js': okBundle(), '/plugins/q/client.js': okBundle() },
+    ))
+    cyclic.loader.start()
+    await expect(cyclic.loader.settled()).rejects.toThrow(/inject cycle/)
+
+    const applyless = fresh(() => bench([entry('noap')], { '/plugins/noap/client.js': { handoff: { id: 'noap', factory: () => ({}) } } }))
+    applyless.loader.start()
+    await expect(applyless.loader.settled()).rejects.toThrow(/exports no apply/)
+
+    const b = fresh(() => bench([entry('a')], { '/plugins/a/client.js': okBundle() }))
+    await expect(b.loader.load('ghost')).rejects.toThrow(/unknown plugin "ghost"/)
+
+    expect(() => fresh(() => bench([entry('dup'), entry('dup')], {}))).toThrow(/duplicate manifest id/)
+  })
+
+  it('throws on missing boot manifest, double proxy install, and pre-start settled', () => {
+    expect(() => createClientLoader({ ctx: new Context(), modules: {} })).toThrow(/no boot manifest/)
+    const b = bench([], {})
+    expect(() => b.loader.settled()).toThrow(/settled\(\) before start\(\)/)
+    // First bench installed the proxy; a second loader must refuse.
+    expect(() => createClientLoader({ ctx: new Context(), modules: {}, boot: { plugins: [] } })).toThrow(/already installed/)
+  })
+
+  it('unload is the P-I stub', async () => {
+    const b = bench([], {})
+    await expect(b.loader.unload('x')).rejects.toThrow(/not implemented/)
+  })
+})

packages/client/runtime/tests/conversation.spec.ts

@@ -0,0 +1,23 @@
+/** Assistant block classifier (moved here with sessions/conversation.ts). */
+
+import { describe, expect, it } from 'vitest'
+import type { ContentBlock } from '@deepseek-ai/dsh-client-connection/client'
+import { toAssistantBlock, toAssistantBlocks } from '../src/client/sessions/conversation.ts'
+
+describe('toAssistantBlock', () => {
+  it('classifies the four block shapes', () => {
+    const blocks: ContentBlock[] = [
+      { type: 'text', text: '正文' },
+      { type: 'reasoning', text: '思考' },
+      { type: 'tool-call', id: 'c1', name: 'echo', arguments: '{}' } as ContentBlock,
+      { type: 'image', data: 'x' } as unknown as ContentBlock,
+    ]
+    expect(toAssistantBlocks(blocks)).toEqual([
+      { kind: 'text', text: '正文' },
+      { kind: 'reasoning', text: '思考' },
+      { kind: 'tool-call', callId: 'c1', name: 'echo', argsRaw: '{}' },
+      { kind: 'other', block: blocks[3] },
+    ])
+    expect(toAssistantBlock(blocks[0] as ContentBlock)).toEqual({ kind: 'text', text: '正文' })
+  })
+})

packages/client/runtime/tests/event-script.ts

@@ -0,0 +1,50 @@
+// Minimal SessionEvent builders for orchestration tests (shape mirrors what the
+// host emits; only the fields the object layer reads).
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+
+/** One text content block (local helper). */
+const text = (t: string): ContentBlock[] => [{ type: 'text', text: t }]
+
+const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
+  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
+
+export const ev = {
+  turnStart: (seq: number, turn: number): SessionEvent =>
+    at(seq, { type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } }),
+  user: (seq: number, body: string): SessionEvent =>
+    at(seq, { type: 'user/message', surfaceOp: 'append', data: { content: text(body), source: { kind: 'user' } } }),
+  stepStart: (seq: number, turn: number, step = 0): SessionEvent =>
+    at(seq, { type: 'step/start', data: { turn, step } }),
+  chunkStart: (seq: number, turn: number, step = 0, index = 0): SessionEvent =>
+    at(seq, { type: 'assistant/chunk', data: { turn, step, chunk: { type: 'block-start', index, blockType: 'text' } } }),
+  chunkText: (seq: number, turn: number, piece: string, step = 0, index = 0): SessionEvent =>
+    at(seq, { type: 'assistant/chunk', data: { turn, step, chunk: { type: 'text-delta', index, text: piece } } }),
+  assistant: (seq: number, turn: number, body: string, step = 0): SessionEvent =>
+    at(seq, { type: 'assistant/message', surfaceOp: 'append', data: { turn, step, content: text(body), provenance: { provider: 'fake', model: 'fk-1' } } }),
+  toolCall: (seq: number, turn: number, callId: string, name: string, args: string, step = 0): SessionEvent =>
+    at(seq, { type: 'tool/call', data: { turn, step, callId, name, arguments: args } }),
+  toolResult: (seq: number, turn: number, callId: string, body: string, step = 0): SessionEvent =>
+    at(seq, { type: 'tool/result', surfaceOp: 'append', data: { turn, step, callId, content: text(body), isError: false } }),
+  stepEnd: (seq: number, turn: number, step = 0): SessionEvent =>
+    at(seq, { type: 'step/end', data: { turn, step } }),
+  turnEnd: (seq: number, turn: number, reason: 'completed' | 'cancelled' = 'completed'): SessionEvent =>
+    at(seq, { type: 'turn/end', data: { turn, reason: { kind: reason } } }),
+}
+
+/** One complete plain turn (turn/start → user → step → assistant → turn/end), 6 events from startSeq. */
+export function plainTurn(startSeq: number, turn: number, ask: string, answer: string): SessionEvent[] {
+  return [
+    ev.turnStart(startSeq, turn),
+    ev.user(startSeq + 1, ask),
+    ev.stepStart(startSeq + 2, turn),
+    ev.assistant(startSeq + 3, turn, answer),
+    ev.stepEnd(startSeq + 4, turn),
+    ev.turnEnd(startSeq + 5, turn),
+  ]
+}
+
+/** Wrap raw events as view-less history entries (the wire shape history now returns). */
+export function entries(events: readonly SessionEvent[]): { event: SessionEvent }[] {
+  return events.map(event => ({ event }))
+}

packages/client/runtime/tests/fake-api.ts

@@ -0,0 +1,157 @@
+// Test-local programmable IApiClient fake (NOT the fixture: fixture is a demo
+// data source on a real clock; behavior tests need per-case responses and
+// deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
+import type {
+  HostFrame, IApiClient, MuxFrame, RpcError, RpcRequest, RpcResponse, SessionId,
+} from '@deepseek-ai/dsh-client-connection/client'
+import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
+
+export interface Deferred<T> {
+  promise: Promise<T>
+  resolve(value: T): void
+  reject(error: unknown): void
+}
+
+/** Test-held settlement: the case decides when an RPC lands (history-pending injections etc.). */
+export function deferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void
+  let reject!: (error: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+let nextRpc = 0
+
+export function ok<T>(value: T): RpcResponse<T> {
+  return { rpcId: RpcId(`fake-${nextRpc++}`), result: { ok: true, value } }
+}
+
+export function err<T>(error: RpcError): RpcResponse<T> {
+  return { rpcId: RpcId(`fake-${nextRpc++}`), result: { ok: false, error } }
+}
+
+type StreamItem<F> = { kind: 'frame'; envelope: RpcRequest<F> } | { kind: 'end' } | { kind: 'fail'; error: unknown }
+
+interface StreamConn<F> {
+  feed(item: StreamItem<F>): void
+}
+
+export class FakeApiClient implements IApiClient {
+  /** Chronological call record: [method, payload]. */
+  readonly calls: { method: string; payload: unknown }[] = []
+
+  // Programmable slots (defaults answer OK-empty); reassign per case.
+  onList: (payload: unknown) => Promise<RpcResponse<{ items: never[] }>> = () => Promise.resolve(ok({ items: [] }))
+  onCreate: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId }))
+  onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
+  => Promise<RpcResponse<{ events: never[]; hasMore: boolean }>> =
+    () => Promise.resolve(ok({ events: [], hasMore: false }))
+
+  onPrompt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
+  onCancel: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
+  onDescribe: (payload: unknown) => Promise<RpcResponse<{ version: string; cwd: string; attachedSessions: number }>> =
+    () => Promise.resolve(ok({ version: '0-fake', cwd: '/f', attachedSessions: 0 }))
+
+  private readonly muxConns: StreamConn<MuxFrame>[] = []
+  private readonly hostConns: StreamConn<HostFrame>[] = []
+
+  readonly sessions: IApiClient['sessions'] = {
+    list: payload => this.record('session.list', payload, this.onList(payload)),
+    create: payload => this.record('session.create', payload, this.onCreate(payload)),
+    history: payload => this.record('session.history', payload, this.onHistory(payload)),
+    prompt: payload => this.record('session.prompt', payload, this.onPrompt(payload)),
+    cancel: payload => this.record('session.cancel', payload, this.onCancel(payload)),
+  }
+
+  readonly host: IApiClient['host'] = {
+    describe: payload => this.record('host.describe', payload, this.onDescribe(payload)),
+  }
+
+  /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */
+  suppressStreamOpen = false
+
+  /** When true, onOpen callbacks are parked instead of fired; releaseStreamOpens() fires them.
+   *  Lets a case hold the readiness handshake open (describe done, streams not yet "established"). */
+  holdStreamOpen = false
+  private heldOpens: (() => void)[] = []
+
+  releaseStreamOpens(): void {
+    const held = this.heldOpens
+    this.heldOpens = []
+    for (const fire of held) fire()
+  }
+
+  readonly events: IApiClient['events'] = {
+    mux: (_payload, signal, onOpen) => this.openStream(this.muxConns, signal, onOpen),
+    host: (_payload, signal, onOpen) => this.openStream(this.hostConns, signal, onOpen),
+  }
+
+  respond(): Promise<{ accepted: false; reason: 'not-pending' }> {
+    return Promise.resolve({ accepted: false, reason: 'not-pending' })
+  }
+
+  /** Push one mux frame to every open mux stream (rpcId minted unless pinned by the case). */
+  pushMux(frame: MuxFrame, rpcId?: string): void {
+    for (const conn of [...this.muxConns]) conn.feed({ kind: 'frame', envelope: { rpcId: RpcId(rpcId ?? `push-${nextRpc++}`), payload: frame } })
+  }
+
+  pushHost(frame: HostFrame, rpcId?: string): void {
+    for (const conn of [...this.hostConns]) conn.feed({ kind: 'frame', envelope: { rpcId: RpcId(rpcId ?? `push-${nextRpc++}`), payload: frame } })
+  }
+
+  /** End (clean close) or fail (throw) every open stream — reconnect-path material. */
+  endStreams(): void {
+    for (const conn of [...this.muxConns, ...this.hostConns]) conn.feed({ kind: 'end' })
+  }
+
+  failStreams(error: unknown): void {
+    for (const conn of [...this.muxConns, ...this.hostConns]) conn.feed({ kind: 'fail', error })
+  }
+
+  get openMuxCount(): number {
+    return this.muxConns.length
+  }
+
+  callsOf(method: string): unknown[] {
+    return this.calls.filter(c => c.method === method).map(c => c.payload)
+  }
+
+  private record<T>(method: string, payload: unknown, response: Promise<T>): Promise<T> {
+    this.calls.push({ method, payload })
+    return response
+  }
+
+  private async *openStream<F>(registry: StreamConn<F>[], signal: AbortSignal, onOpen?: () => void): AsyncGenerator<RpcRequest<F>> {
+    const inbox: StreamItem<F>[] = []
+    let wake: (() => void) | null = null
+    const conn: StreamConn<F> = {
+      feed: (item) => {
+        inbox.push(item)
+        wake?.()
+      },
+    }
+    registry.push(conn)
+    if (this.holdStreamOpen && onOpen !== undefined) this.heldOpens.push(onOpen)
+    else if (!this.suppressStreamOpen) onOpen?.()
+    try {
+      while (!signal.aborted) {
+        while (inbox.length > 0) {
+          const item = inbox.shift() as StreamItem<F>
+          if (item.kind === 'end') return
+          if (item.kind === 'fail') throw item.error
+          yield item.envelope
+        }
+        await new Promise<void>((resolve) => {
+          wake = resolve
+          signal.addEventListener('abort', () => { resolve() }, { once: true })
+        })
+        wake = null
+      }
+    } finally {
+      registry.splice(registry.indexOf(conn), 1)
+    }
+  }
+}

packages/client/runtime/tests/fold-adapter.spec.ts

@@ -0,0 +1,145 @@
+/**
+ * FoldAdapter over the real core SurfaceManager: padding sentinels for paged
+ * windows, incremental append with node-cache identity, six-variant
+ * materialization, call-index backfill, and the degraded linear-scan branch.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import { FoldAdapter } from '../src/client/sessions/fold-adapter.ts'
+import { ev, plainTurn } from './event-script.ts'
+
+const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
+  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
+
+describe('FoldAdapter', () => {
+  it('folds a baseSeq>0 window through padding sentinels with correct seqs', () => {
+    const adapter = new FoldAdapter()
+    const window = plainTurn(100, 5, '偏移问', '偏移答')
+    adapter.reset(window, 100)
+    const { nodes, degraded } = adapter.nodes()
+    expect(degraded).toBe(false)
+    expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 101], ['assistant', 103]])
+  })
+
+  it('appends incrementally keeping old node references (cache identity)', () => {
+    const adapter = new FoldAdapter()
+    adapter.reset(plainTurn(0, 0, 'a', 'b'), 0)
+    const first = adapter.nodes()
+    adapter.append(ev.user(6, '追加'))
+    const second = adapter.nodes()
+    expect(second.nodes).toHaveLength(3)
+    expect(second.nodes[0]).toBe(first.nodes[0])
+    expect(second.nodes[1]).toBe(first.nodes[1])
+    expect(second.nodes).not.toBe(first.nodes) // array itself fresh per call
+  })
+
+  it('materializes all six node variants with field mapping', () => {
+    const adapter = new FoldAdapter()
+    const events = [
+      ev.user(0, '用户'),
+      ev.assistant(1, 0, '助手'),
+      at(2, { type: 'steering/message', surfaceOp: 'append', data: { turn: 0, content: [{ type: 'text', text: '插话' }], source: { kind: 'user' } } }),
+      at(3, { type: 'context/message', surfaceOp: 'append', data: { content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' } } }),
+      ev.toolCall(4, 0, 'c1', 'echo', '{"x":1}'),
+      ev.toolResult(5, 0, 'c1', '结果'),
+    ]
+    adapter.reset(events, 0)
+    const { nodes } = adapter.nodes()
+    const kinds = nodes.map(n => n.kind)
+    expect(kinds).toContain('user')
+    expect(kinds).toContain('assistant')
+    expect(kinds).toContain('steering')
+    expect(kinds).toContain('context')
+    const result = nodes.find(n => n.kind === 'tool-result')
+    expect(result).toMatchObject({ callId: 'c1', call: { name: 'echo', argsRaw: '{"x":1}' }, isError: false })
+  })
+
+  it('returns call:null for a tool-result whose call fell outside the window', () => {
+    const adapter = new FoldAdapter()
+    adapter.reset([ev.toolResult(50, 3, 'outside-call', '孤儿结果')], 50)
+    const { nodes } = adapter.nodes()
+    expect(nodes[0]).toMatchObject({ kind: 'tool-result', callId: 'outside-call', call: null })
+  })
+
+  it('materializes surface-eligible types it does not know as unknown nodes', () => {
+    const adapter = new FoldAdapter()
+    adapter.reset([at(0, { type: 'notice/message', surfaceOp: 'append', data: { note: 1 } })], 0)
+    const { nodes } = adapter.nodes()
+    // Either the fold surfaces it (unknown node) or skips it as non-eligible — both are valid
+    // shapes; what matters is no throw and no misclassification into a known kind.
+    for (const node of nodes) expect(node.kind).toBe('unknown')
+  })
+
+  it('degrades to the lenient linear scan when the fold throws, and stays degraded', () => {
+    const adapter = new FoldAdapter()
+    // An invalid surfaceOp on a surface-eligible event deterministically throws in the core fold.
+    const window = [
+      ev.user(10, '正常'),
+      at(11, { type: 'assistant/message', surfaceOp: 'bogus-op', data: { turn: 0, step: 0, content: [{ type: 'text', text: '坏 op' }], provenance: { provider: 'x', model: 'y' } } }),
+    ]
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      adapter.reset(window, 10)
+      const first = adapter.nodes()
+      expect(first.degraded).toBe(true)
+      expect(errorSpy).toHaveBeenCalled()
+      expect(first.nodes.map(n => n.seq)).toEqual([10, 11]) // linear scan: append order, bad op ignored
+      adapter.append(ev.user(12, '降级后追加')) // bump rev so the cached result is not reused
+      const second = adapter.nodes()
+      expect(second.degraded).toBe(true) // sticky: no re-throw loop, straight to the linear scan
+      expect(second.nodes[0]).toBe(first.nodes[0]) // cache still serves node identity
+      expect(second.nodes.map(n => n.seq)).toEqual([10, 11, 12])
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('materializes a tool-result error field when present', () => {
+    const adapter = new FoldAdapter()
+    adapter.reset([
+      at(0, { type: 'tool/result', surfaceOp: 'append', data: { turn: 0, step: 0, callId: 'c1', content: [], isError: true, error: { name: 'Boom', code: 'boom' } } }),
+    ], 0)
+    expect(adapter.nodes().nodes[0]).toMatchObject({ kind: 'tool-result', isError: true, error: { code: 'boom' } })
+  })
+
+  it('exposes the in-window call index for runningCalls material', () => {
+    const adapter = new FoldAdapter()
+    adapter.reset([ev.toolCall(0, 1, 'c9', 'slow', '{}')], 0)
+    expect(adapter.callIndex.get('c9')).toMatchObject({ name: 'slow', turn: 1 })
+    adapter.append(ev.toolCall(1, 1, 'c10', 'fast', '{}'))
+    expect(adapter.callIndex.size).toBe(2)
+  })
+
+  it('attaches wire views: callView into the call index, resultView onto the node by seq', () => {
+    const adapter = new FoldAdapter()
+    const events = [
+      ev.toolCall(0, 1, 'c1', 'bash', '{"cmd":"ls"}'),
+      ev.toolResult(1, 1, 'c1', 'listing'),
+    ]
+    const callView = { for: 'call' as const, view: { card: 'terminal' as const, command: 'ls' } }
+    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '完成' } }
+    adapter.reset(events, 0, [callView, resultView] as never)
+    expect(adapter.callIndex.get('c1')).toMatchObject({ callView: { card: 'terminal' } })
+    const node = adapter.nodes().nodes.find(n => n.kind === 'tool-result')
+    expect(node).toMatchObject({ callView: { card: 'terminal' }, resultView: { card: 'generic', title: '完成' } })
+  })
+
+  it('attaches views on the live append path and defaults to null without views', () => {
+    const adapter = new FoldAdapter()
+    adapter.reset(plainTurn(0, 0, 'a', 'b'), 0) // no views argument: legacy-shaped call
+    adapter.append(ev.toolCall(6, 1, 'c2', 'echo', '{}'), { for: 'call', view: { card: 'generic', title: '回声' } } as never)
+    adapter.append(ev.toolResult(7, 1, 'c2', 'ok')) // no view on the result
+    expect(adapter.callIndex.get('c2')).toMatchObject({ callView: { title: '回声' } })
+    const node = adapter.nodes().nodes.find(n => n.kind === 'tool-result')
+    expect(node).toMatchObject({ callView: { title: '回声' }, resultView: null })
+  })
+
+  it('leaves callView null when the paired call fell outside the window (cross-page break)', () => {
+    const adapter = new FoldAdapter()
+    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '孤儿' } }
+    adapter.reset([ev.toolResult(50, 3, 'outside', '窗外配对')], 50, [resultView] as never)
+    const node = adapter.nodes().nodes[0]
+    expect(node).toMatchObject({ kind: 'tool-result', call: null, callView: null, resultView: { title: '孤儿' } })
+  })
+})

packages/client/runtime/tests/lineage.spec.ts

@@ -0,0 +1,55 @@
+/**
+ * flattenLineage: root ordering, DFS child expansion, orphan degradation, and
+ * cycle fail-soft (every entry always emitted, no infinite walk).
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionId, SessionSummary } from '@deepseek-ai/dsh-client-connection/client'
+import { flattenLineage } from '../src/client/sessions/lineage.ts'
+
+const s = (id: string, updatedAt: number, parent?: string): SessionSummary => ({
+  sessionId: id as SessionId, updatedAt, running: false,
+  ...(parent !== undefined ? { parentSessionId: parent as SessionId } : {}),
+})
+
+describe('flattenLineage', () => {
+  it('sorts roots by updatedAt desc and expands children DFS with depth, children sorted too', () => {
+    const out = flattenLineage([
+      s('old-root', 10),
+      s('new-root', 30),
+      s('kid-old', 11, 'new-root'),
+      s('kid-new', 12, 'new-root'),
+      s('grandkid', 5, 'kid-new'),
+    ])
+    expect(out.map(e => [e.sessionId, e.depth])).toEqual([
+      ['new-root', 0], ['kid-new', 1], ['grandkid', 2], ['kid-old', 1], ['old-root', 0],
+    ])
+  })
+
+  it('degrades an orphan (absent parent) to root level without dropping it', () => {
+    const out = flattenLineage([s('orphan', 20, 'ghost-parent'), s('root', 10)])
+    expect(out.map(e => [e.sessionId, e.depth])).toEqual([['orphan', 0], ['root', 0]])
+  })
+
+  it('fails soft on a two-node cycle: all entries emitted, warn fired, no hang', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    try {
+      const out = flattenLineage([s('a', 20, 'b'), s('b', 10, 'a'), s('root', 30)])
+      expect(out.map(e => e.sessionId).sort()).toEqual(['a', 'b', 'root'])
+      expect(warnSpy).toHaveBeenCalled()
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('handles a self-referencing entry as a cycle member', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    try {
+      const out = flattenLineage([s('self', 10, 'self')])
+      expect(out.map(e => e.sessionId)).toEqual(['self'])
+      expect(out[0]?.depth).toBe(0)
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+})

packages/client/runtime/tests/manager.spec.ts

@@ -0,0 +1,223 @@
+/**
+ * SessionManager orchestration: lazy resident instances, list lifecycle, host
+ * frame routing, and the pending-frame buffer for uninstantiated sessions.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import { SessionManager } from '../src/client/sessions/manager.ts'
+import { FakeApiClient, deferred, err, ok } from './fake-api.ts'
+import { entries, plainTurn } from './event-script.ts'
+
+const S1 = 'fk-m1' as SessionId
+const S2 = 'fk-m2' as SessionId
+
+function summary(sessionId: SessionId, over: Partial<{ updatedAt: number; running: boolean; parentSessionId: SessionId }> = {}) {
+  return { sessionId, updatedAt: 100, running: false, ...over }
+}
+
+describe('instances', () => {
+  it('lazily builds one resident instance per id and syncs the running bit from the list', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1, { running: true })] as never[] }))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    const session = manager.get(S1)
+    expect(manager.get(S1)).toBe(session) // resident: same instance forever
+    expect(session.getSnapshot().running).toBe(true) // list preceded instantiation
+  })
+
+  it('replays buffered approval frames on instantiation and drops ordinary frames for uninstantiated sessions', () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    // Uninstantiated: approval buffers, plain session/event drops.
+    manager.handleMuxEnvelope({ rpcId: 'ra' as never, payload: { type: 'approval/requested', sessionId: S1, approvalId: 'ap1' as never, toolName: 'rm' } })
+    manager.handleMuxEnvelope({ rpcId: 're' as never, payload: { type: 'session/event', sessionId: S1, event: plainTurn(0, 0, 'x', 'y')[0] as never } })
+    const session = manager.get(S1)
+    expect(session.getSnapshot().pending).toMatchObject([{ kind: 'approval', approvalId: 'ap1' }])
+    // Buffer cleared: a second instantiation of another id gets nothing.
+    expect(manager.get(S2).getSnapshot().pending).toEqual([])
+  })
+
+  it('caps the pending buffer at 32 keeping the newest, and drops it on session-removed', () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    // 40 distinct question frames for an uninstantiated session: only the newest 32 survive.
+    for (let i = 0; i < 40; i++) {
+      manager.handleMuxEnvelope({ rpcId: `q${i}` as never, payload: { type: 'question/requested', sessionId: S1, questions: [] } })
+    }
+    const pending = manager.get(S1).getSnapshot().pending
+    expect(pending).toHaveLength(32)
+    expect(pending.map(p => p.rpcId)).toEqual(Array.from({ length: 32 }, (_, i) => `q${i + 8}`)) // oldest 8 dropped
+    // Removed session: buffered frames must not replay on a future instantiation.
+    manager.handleMuxEnvelope({ rpcId: 'qz' as never, payload: { type: 'question/requested', sessionId: S2, questions: [] } })
+    manager.handleHostEnvelope({ rpcId: 'hz' as never, payload: { type: 'host/session-removed', sessionId: S2 } })
+    expect(manager.get(S2).getSnapshot().pending).toEqual([])
+  })
+})
+
+describe('list lifecycle', () => {
+  it('single-flights refreshList and lands items sorted through lineage flattening', async () => {
+    const api = new FakeApiClient()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onList']>>>()
+    api.onList = () => gate.promise
+    const manager = new SessionManager(api)
+    const first = manager.refreshList()
+    const second = manager.refreshList()
+    expect(manager.getListSnapshot().state).toBe('loading')
+    gate.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200 })] as never[] }))
+    await Promise.all([first, second])
+    expect(api.callsOf('session.list')).toHaveLength(1)
+    const snapshot = manager.getListSnapshot()
+    expect(snapshot.state).toBe('idle')
+    expect(snapshot.items.map(i => i.sessionId)).toEqual([S2, S1]) // updatedAt desc
+  })
+
+  it('keeps the error in the list snapshot on failure', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.resolve(err({ code: 'internal', message: 'boom', details: {} }))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    expect(manager.getListSnapshot()).toMatchObject({ state: 'error', error: { code: 'internal' } })
+  })
+
+  it('merges create into the list immediately without waiting for a refresh', async () => {
+    const api = new FakeApiClient()
+    api.onCreate = () => Promise.resolve(ok({ sessionId: S2 }))
+    const manager = new SessionManager(api)
+    const result = await manager.create()
+    expect(result).toMatchObject({ ok: true, value: { sessionId: S2 } })
+    expect(manager.getListSnapshot().items.map(i => i.sessionId)).toEqual([S2])
+  })
+})
+
+describe('host frame routing', () => {
+  it('adds/removes/flips sessions from host frames and keeps removed instances resident', async () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    manager.handleHostEnvelope({ rpcId: 'h1' as never, payload: { type: 'host/session-added', sessionId: S1 } })
+    manager.handleHostEnvelope({ rpcId: 'h2' as never, payload: { type: 'host/session-added', sessionId: S1 } }) // dup: ignored
+    expect(manager.getListSnapshot().items).toHaveLength(1)
+
+    const session = manager.get(S1)
+    manager.handleHostEnvelope({ rpcId: 'h3' as never, payload: { type: 'host/session-status', sessionId: S1, running: true } })
+    expect(session.getSnapshot().running).toBe(true)
+    expect(manager.getListSnapshot().items[0]?.running).toBe(true)
+
+    manager.handleHostEnvelope({ rpcId: 'h4' as never, payload: { type: 'host/agent-error', sessionId: S1, message: '炸了' } })
+    expect(session.getSnapshot().lastAgentError).toBe('炸了')
+
+    manager.handleHostEnvelope({ rpcId: 'h5' as never, payload: { type: 'host/session-removed', sessionId: S1 } })
+    expect(manager.getListSnapshot().items).toHaveLength(0)
+    expect(session.getSnapshot().removed).toBe(true)
+    expect(manager.get(S1)).toBe(session) // resident-instance rule survives removal
+  })
+})
+
+describe('remaining branches', () => {
+  it('refreshList folds a transport throw into the error state', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.reject(new Error('list wire down'))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    expect(manager.getListSnapshot()).toMatchObject({ state: 'error', error: { code: 'internal', message: 'list wire down' } })
+  })
+
+  it('refreshList pushes running bits down to already-instantiated sessions', async () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    const session = manager.get(S1)
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1, { running: true })] as never[] }))
+    await manager.refreshList()
+    expect(session.getSnapshot().running).toBe(true)
+  })
+
+  it('create passes cwd through, folds transport throws, and skips the merge when already listed', async () => {
+    const api = new FakeApiClient()
+    api.onCreate = () => Promise.resolve(ok({ sessionId: S1 }))
+    const manager = new SessionManager(api)
+    await manager.create('/tmp/w')
+    expect(api.callsOf('session.create')).toEqual([{ cwd: '/tmp/w' }])
+    expect(manager.getListSnapshot().items[0]).toMatchObject({ sessionId: S1, cwd: '/tmp/w' })
+    await manager.create('/tmp/w') // same id returned: no duplicate row
+    expect(manager.getListSnapshot().items).toHaveLength(1)
+    api.onCreate = () => Promise.reject(new Error('create wire down'))
+    expect(await manager.create()).toMatchObject({ ok: false, error: { code: 'internal' } })
+    // Business error passes through untouched.
+    api.onCreate = () => Promise.resolve(err({ code: 'internal', message: 'no', details: {} }))
+    expect(await manager.create()).toMatchObject({ ok: false })
+  })
+
+  it('subscribe notifies on list changes and stops after unsubscribe', async () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    let notified = 0
+    const unsubscribe = manager.subscribe(() => { notified++ })
+    await manager.refreshList()
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(notified).toBeGreaterThan(0)
+    const seen = notified
+    unsubscribe()
+    manager.handleHostEnvelope({ rpcId: 'h' as never, payload: { type: 'host/session-added', sessionId: S1 } })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(notified).toBe(seen)
+  })
+
+  it('routes stream/error and unknown frames to the documented drops, and dispatches to instantiated sessions', () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    manager.handleMuxEnvelope({ rpcId: 'e' as never, payload: { type: 'stream/error', error: { code: 'internal', message: 'x', details: {} } } })
+    manager.handleHostEnvelope({ rpcId: 'e2' as never, payload: { type: 'stream/error', error: { code: 'internal', message: 'x', details: {} } } })
+    manager.handleHostEnvelope({ rpcId: 'e3' as never, payload: { type: 'future/host-frame' } as never })
+    const session = manager.get(S1)
+    manager.handleMuxEnvelope({ rpcId: 'q1' as never, payload: { type: 'question/requested', sessionId: S1, questions: [] } })
+    expect(session.getSnapshot().pending).toMatchObject([{ kind: 'question' }])
+    // status flip for an unknown session only touches summaries (no crash).
+    manager.handleHostEnvelope({ rpcId: 'h9' as never, payload: { type: 'host/session-status', sessionId: S2, running: true } })
+    manager.handleHostEnvelope({ rpcId: 'ha' as never, payload: { type: 'host/agent-error', sessionId: S2, message: '无实例' } })
+  })
+
+  it('keeps list-entry identity for unchanged rows across an unrelated list change', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200 })] as never[] }))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    const before = manager.getListSnapshot()
+    manager.handleHostEnvelope({ rpcId: 'h' as never, payload: { type: 'host/session-status', sessionId: S2, running: true } })
+    const after = manager.getListSnapshot()
+    expect(after.items).not.toBe(before.items)
+    const beforeS1 = before.items.find(e => e.sessionId === S1)
+    const afterS1 = after.items.find(e => e.sessionId === S1)
+    expect(afterS1).toBe(beforeS1) // untouched entry keeps identity (entryCache)
+    // Same-order same-entries snapshot reuses the items array.
+    manager.handleHostEnvelope({ rpcId: 'h2' as never, payload: { type: 'host/agent-error', sessionId: S1, message: 'x' } })
+    expect(manager.getListSnapshot().items).toBe(after.items)
+  })
+
+  it('carries parentSessionId from host/session-added into the lineage row', () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    manager.handleHostEnvelope({ rpcId: 'h1' as never, payload: { type: 'host/session-added', sessionId: S1 } })
+    manager.handleHostEnvelope({ rpcId: 'h2' as never, payload: { type: 'host/session-added', sessionId: S2, parentSessionId: S1 } })
+    const items = manager.getListSnapshot().items
+    expect(items.find(e => e.sessionId === S2)).toMatchObject({ parentSessionId: S1, depth: 1 })
+  })
+})
+
+describe('connected generation', () => {
+  it('refreshes the list and resyncs only opened instances', async () => {
+    const api = new FakeApiClient()
+    api.onHistory = () => Promise.resolve(ok({ events: entries(plainTurn(0, 0, 'a', 'b')) as never[], hasMore: false }))
+    const manager = new SessionManager(api)
+    const openedSession = manager.get(S1)
+    await openedSession.open()
+    manager.get(S2) // instantiated but never opened
+    const historyCallsBefore = api.callsOf('session.history').length
+    manager.handleConnected()
+    await vi.waitFor(() => {
+      expect(api.callsOf('session.list').length).toBe(1)
+      // Only the opened instance repulls history; the cold one stays silent.
+      expect(api.callsOf('session.history').length).toBe(historyCallsBefore + 1)
+    })
+  })
+})

packages/client/runtime/tests/node-half.spec.ts

@@ -0,0 +1,10 @@
+/** Node half: the empty host apply (Loader governance + dshClient discovery placeholder). */
+import { describe, expect, it } from 'vitest'
+import { apply } from '../src/index.ts'
+
+describe('node half', () => {
+  it('apply is a no-op host placeholder', () => {
+    apply(undefined)
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+})

packages/client/runtime/tests/notifier.spec.ts

@@ -0,0 +1,75 @@
+/**
+ * Notifier: microtask batching, rebuild-before-notify ordering, no-listener
+ * laziness, synchronous notifyNow, and unsubscribe.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Notifier } from '../src/client/sessions/notifier.ts'
+
+const microtask = (): Promise<void> => new Promise((resolve) => { queueMicrotask(resolve) })
+
+describe('Notifier', () => {
+  it('collapses N markDirty calls into one flush, rebuilding before notifying', async () => {
+    const order: string[] = []
+    const notifier = new Notifier(() => order.push('rebuild'))
+    notifier.subscribe(() => order.push('notify'))
+    notifier.markDirty()
+    notifier.markDirty()
+    notifier.markDirty()
+    expect(order).toEqual([]) // nothing until the microtask boundary
+    await microtask()
+    expect(order).toEqual(['rebuild', 'notify'])
+  })
+
+  it('skips rebuild with zero listeners and ensureFresh rebuilds lazily exactly once', async () => {
+    let rebuilds = 0
+    const notifier = new Notifier(() => { rebuilds++ })
+    notifier.markDirty()
+    await microtask()
+    expect(rebuilds).toBe(0) // lazy: kept dirty
+    notifier.ensureFresh()
+    expect(rebuilds).toBe(1)
+    notifier.ensureFresh()
+    expect(rebuilds).toBe(1) // clean: no second rebuild
+  })
+
+  it('notifyNow runs listeners synchronously (controlled-input contract)', () => {
+    const order: string[] = []
+    const notifier = new Notifier(() => order.push('rebuild'))
+    notifier.subscribe(() => order.push('notify'))
+    notifier.notifyNow()
+    expect(order).toEqual(['rebuild', 'notify']) // before returning, no microtask needed
+  })
+
+  it('notifyNow with zero listeners stays lazy like markDirty', () => {
+    let rebuilds = 0
+    const notifier = new Notifier(() => { rebuilds++ })
+    notifier.notifyNow()
+    expect(rebuilds).toBe(0)
+    notifier.ensureFresh()
+    expect(rebuilds).toBe(1)
+  })
+
+  it('a scheduled flush after notifyNow already flushed is a no-op', async () => {
+    let rebuilds = 0
+    const notifier = new Notifier(() => { rebuilds++ })
+    notifier.subscribe(() => undefined)
+    notifier.markDirty() // schedules the microtask flush
+    notifier.notifyNow() // flushes synchronously, clears dirty
+    await microtask() // the scheduled flush finds dirty=false
+    expect(rebuilds).toBe(1)
+  })
+
+  it('unsubscribed listeners stop receiving notifications', async () => {
+    let calls = 0
+    const notifier = new Notifier(() => undefined)
+    const unsubscribe = notifier.subscribe(() => { calls++ })
+    notifier.notifyNow()
+    expect(calls).toBe(1)
+    unsubscribe()
+    notifier.markDirty()
+    await microtask()
+    notifier.notifyNow()
+    expect(calls).toBe(1)
+  })
+})

packages/client/runtime/tests/partial.spec.ts

@@ -0,0 +1,91 @@
+/**
+ * PartialAccumulator: six-variant chunk folding, sparse-index compaction, and
+ * the block/snapshot reference discipline (a delta swaps only that block).
+ */
+
+import { describe, expect, it } from 'vitest'
+import type { StreamChunk } from '@deepseek-ai/dsh-client-connection/client'
+import { PartialAccumulator } from '../src/client/sessions/partial.ts'
+
+const chunk = (c: Record<string, unknown>): StreamChunk => c as unknown as StreamChunk
+
+describe('PartialAccumulator', () => {
+  it('builds empty blocks per block-start type, unknown type falls to other', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'block-start', index: 0, blockType: 'text' }))
+    acc.push(chunk({ type: 'block-start', index: 1, blockType: 'reasoning' }))
+    acc.push(chunk({ type: 'block-start', index: 2, blockType: 'tool-call' }))
+    acc.push(chunk({ type: 'block-start', index: 3, blockType: 'no-such' }))
+    expect(acc.toPartial().blocks).toEqual([
+      { kind: 'text', text: '' },
+      { kind: 'reasoning', text: '' },
+      { kind: 'tool-call', callId: '', name: '', argsRaw: '' },
+      { kind: 'other', block: null },
+    ])
+  })
+
+  it('accumulates text deltas, starting from empty when prev is missing or another kind', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'text-delta', index: 0, text: '无 start ' })) // prev missing
+    acc.push(chunk({ type: 'text-delta', index: 0, text: '也累积' }))
+    expect(acc.toPartial().blocks).toEqual([{ kind: 'text', text: '无 start 也累积' }])
+    acc.push(chunk({ type: 'reasoning-delta', index: 0, text: '换型重起' })) // prev is text → restart
+    expect(acc.toPartial().blocks).toEqual([{ kind: 'reasoning', text: '换型重起' }])
+  })
+
+  it('accumulates reasoning deltas on the reasoning lane', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'block-start', index: 0, blockType: 'reasoning' }))
+    acc.push(chunk({ type: 'reasoning-delta', index: 0, text: '思' }))
+    acc.push(chunk({ type: 'reasoning-delta', index: 0, text: '考' }))
+    expect(acc.toPartial().blocks).toEqual([{ kind: 'reasoning', text: '思考' }])
+  })
+
+  it('folds tool-call deltas: first id pins callId, late name overrides, argsRaw concatenates', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'tool-call-delta', index: 0, id: 'c1', argumentsDelta: '{"a"' }))
+    acc.push(chunk({ type: 'tool-call-delta', index: 0, id: 'c2-late', name: 'echo', argumentsDelta: ':1}' }))
+    expect(acc.toPartial().blocks).toEqual([
+      { kind: 'tool-call', callId: 'c1', name: 'echo', argsRaw: '{"a":1}' },
+    ])
+  })
+
+  it('replaces the accumulated block wholesale on block-end', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'text-delta', index: 0, text: '中间态' }))
+    acc.push(chunk({ type: 'block-end', index: 0, block: { type: 'text', text: '定稿全文' } }))
+    expect(acc.toPartial().blocks).toEqual([{ kind: 'text', text: '定稿全文' }])
+  })
+
+  it('returns false (no notification) for usage/finish/unknown variants and keeps blocks', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'text-delta', index: 0, text: 'x' }))
+    const before = acc.toPartial()
+    expect(acc.push(chunk({ type: 'usage', usage: {} }))).toBe(false)
+    expect(acc.push(chunk({ type: 'finish', reason: 'stop' }))).toBe(false)
+    expect(acc.push(chunk({ type: 'future-variant' }))).toBe(false)
+    expect(acc.toPartial()).toBe(before) // unchanged: same snapshot reference
+  })
+
+  it('compacts sparse indexes into a dense render-order array', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'block-start', index: 2, blockType: 'text' }))
+    acc.push(chunk({ type: 'text-delta', index: 2, text: '先到的高位' }))
+    acc.push(chunk({ type: 'block-start', index: 0, blockType: 'reasoning' }))
+    const { blocks } = acc.toPartial()
+    expect(blocks).toHaveLength(2) // no undefined holes
+    expect(blocks[0]).toEqual({ kind: 'reasoning', text: '' })
+    expect(blocks[1]).toEqual({ kind: 'text', text: '先到的高位' })
+  })
+
+  it('keeps the snapshot reference stable without changes and swaps it once per mutation', () => {
+    const acc = new PartialAccumulator(3, 1)
+    const first = acc.toPartial()
+    expect(first).toMatchObject({ turn: 3, step: 1, blocks: [] })
+    expect(acc.toPartial()).toBe(first)
+    acc.push(chunk({ type: 'text-delta', index: 0, text: 'a' }))
+    const second = acc.toPartial()
+    expect(second).not.toBe(first)
+    expect(acc.toPartial()).toBe(second)
+  })
+})

packages/client/runtime/tests/session.spec.ts

@@ -0,0 +1,625 @@
+/**
+ * Session orchestration: drive the object through contract calls and injected
+ * frames (open → prompt → stream → finalize → cancel → resync) and assert the
+ * ConversationSnapshot it settles into. Reference stability is asserted with
+ * toBe/not.toBe — it is the React.memo/uSES contract, equal-value output is not
+ * enough.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import { Session } from '../src/client/sessions/session.ts'
+import { FakeApiClient, deferred, err, ok } from './fake-api.ts'
+import { entries, ev, plainTurn } from './event-script.ts'
+
+const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
+  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
+
+const SID = 'fk-s1' as SessionId
+
+function makeSession(api = new FakeApiClient()): { api: FakeApiClient; session: Session } {
+  return { api, session: new Session(SID, api) }
+}
+
+function histResponse(events: SessionEvent[], hasMore = false) {
+  // history now returns HistoryEntry[] ({event, view?}); these tests are view-less.
+  return Promise.resolve(ok({ events: entries(events) as never[], hasMore }))
+}
+
+describe('open', () => {
+  it('installs the tail page: cold → loading → open with window and nodes in place', async () => {
+    const { api, session } = makeSession()
+    const page = plainTurn(10, 3, '问', '答')
+    api.onHistory = () => histResponse(page, true)
+    expect(session.getSnapshot().openState).toBe('cold')
+    const opening = session.open()
+    expect(session.getSnapshot().openState).toBe('loading')
+    await opening
+    const snapshot = session.getSnapshot()
+    expect(snapshot.openState).toBe('open')
+    expect(snapshot.hasMore).toBe(true)
+    expect(snapshot.nodes.map(n => n.kind)).toEqual(['user', 'assistant'])
+  })
+
+  it('is idempotent: concurrent opens share one history call, reopening when open is a no-op', async () => {
+    const { api, session } = makeSession()
+    await Promise.all([session.open(), session.open()])
+    await session.open()
+    expect(api.callsOf('session.history')).toHaveLength(1)
+  })
+
+  it('lands an error result in openState=error with the RpcError kept', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => Promise.resolve(err({ code: 'session-not-found', message: 'gone', details: { sessionId: SID } }))
+    await session.open()
+    const snapshot = session.getSnapshot()
+    expect(snapshot.openState).toBe('error')
+    expect(snapshot.openError?.code).toBe('session-not-found')
+  })
+
+  it('folds a transport throw into openState=error / internal', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => Promise.reject(new Error('socket died'))
+    await session.open()
+    expect(session.getSnapshot().openState).toBe('error')
+    expect(session.getSnapshot().openError).toMatchObject({ code: 'internal', message: 'socket died' })
+  })
+
+  it('stitches live frames arriving while history is pending, dropping the page overlap', async () => {
+    const { api, session } = makeSession()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    api.onHistory = () => gate.promise
+    const opening = session.open()
+    // Three live frames land mid-open; seq 15 overlaps the page tail (page covers 10..15).
+    const page = plainTurn(10, 0, '早', '安')
+    session.handleMuxEnvelope('r1' as never, { type: 'session/event', sessionId: SID, event: ev.turnStart(15, 1) })
+    session.handleMuxEnvelope('r2' as never, { type: 'session/event', sessionId: SID, event: ev.user(16, '插进来的') })
+    gate.resolve(ok({ events: entries(page) as never[], hasMore: false }))
+    await opening
+    const seqs = session.getSnapshot().nodes.map(n => n.seq)
+    // Overlapping seq-15 frame (== page tail turn/end) was dropped; 16 appended once.
+    expect(seqs).toEqual([11, 13, 16])
+  })
+})
+
+describe('live event path', () => {
+  async function opened(events: SessionEvent[] = plainTurn(0, 0, 'a', 'b')) {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(events)
+    await session.open()
+    return { api, session }
+  }
+
+  it('drops replayed frames at or below the window tail', async () => {
+    const { session } = await opened()
+    const before = session.getSnapshot()
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.user(3, '重放') })
+    await Promise.resolve()
+    expect(session.getSnapshot().nodes).toEqual(before.nodes)
+  })
+
+  it('accumulates chunks into partial, then finalize swaps partial out as the node lands', async () => {
+    const { session } = await opened()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.user(7, '流式问'))
+    feed(ev.chunkStart(8, 1))
+    feed(ev.chunkText(9, 1, '半截'))
+    let snapshot = session.getSnapshot()
+    expect(snapshot.partial).toMatchObject({ turn: 1, blocks: [{ kind: 'text', text: '半截' }] })
+    feed(ev.chunkText(10, 1, '回复'))
+    expect(session.getSnapshot().partial?.blocks).toEqual([{ kind: 'text', text: '半截回复' }])
+    feed(ev.assistant(11, 1, '半截回复'))
+    feed(ev.turnEnd(12, 1))
+    snapshot = session.getSnapshot()
+    expect(snapshot.partial).toBeNull()
+    const last = snapshot.nodes.at(-1)
+    expect(last).toMatchObject({ kind: 'assistant', blocks: [{ kind: 'text', text: '半截回复' }] })
+    expect((last as { interrupted?: true }).interrupted).toBeUndefined()
+  })
+
+  it('freezes an unfinalized partial into an interrupted node on turn/end (cancel path)', async () => {
+    const { session } = await opened()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.user(7, '要被打断的'))
+    feed(ev.chunkStart(8, 1))
+    feed(ev.chunkText(9, 1, '说到一半'))
+    feed(ev.turnEnd(10, 1, 'cancelled')) // no assistant/message ever arrives
+    const snapshot = session.getSnapshot()
+    expect(snapshot.partial).toBeNull()
+    const frozen = snapshot.nodes.at(-1)
+    expect(frozen).toMatchObject({ kind: 'assistant', interrupted: true, blocks: [{ kind: 'text', text: '说到一半' }] })
+    // Ordered inside the flow: after the user message (seq 7), before any later turn.
+    expect((frozen as { seq: number }).seq).toBeGreaterThan(7)
+  })
+
+  it('tracks tool calls in runningCalls and converts orphans to interrupted tool-result cards on turn/end', async () => {
+    const { session } = await opened()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.toolCall(7, 1, 'c1', 'echo', '{"a":1}'))
+    expect(session.getSnapshot().runningCalls).toMatchObject([{ callId: 'c1', name: 'echo' }])
+    feed(ev.toolResult(8, 1, 'c1', 'ECHO'))
+    expect(session.getSnapshot().runningCalls).toEqual([])
+    // Second call never resolves: turn/end freezes it as an error card.
+    feed(ev.toolCall(9, 1, 'c2', 'slow_tool', '{}'))
+    feed(ev.turnEnd(10, 1, 'cancelled'))
+    const snapshot = session.getSnapshot()
+    expect(snapshot.runningCalls).toEqual([])
+    expect(snapshot.nodes.at(-1)).toMatchObject({
+      kind: 'tool-result', callId: 'c2', isError: true, error: { code: 'interrupted' },
+    })
+  })
+
+  it('repairs a seq gap by repulling the tail page instead of appending a hole', async () => {
+    const { api, session } = await opened(plainTurn(0, 0, 'a', 'b')) // tail seq = 5
+    const repaired = [...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]
+    api.onHistory = () => histResponse(repaired)
+    // seq 9 with tail 5 → gap; the event detours to the buffer and one history refetch fires.
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.assistant(9, 1, 'd') })
+    await vi.waitFor(() => {
+      expect(api.callsOf('session.history').length).toBe(2)
+    })
+    await Promise.resolve()
+    const seqs = session.getSnapshot().nodes.map(n => n.seq)
+    expect(seqs).toEqual([1, 3, 7, 9]) // both turns' user/assistant, no hole, no duplicate 9
+  })
+})
+
+describe('paging', () => {
+  it('prepends an older page and keeps seq continuity', async () => {
+    const older = plainTurn(0, 0, '旧问', '旧答')
+    const newer = plainTurn(6, 1, '新问', '新答')
+    const { api, session } = makeSession()
+    api.onHistory = payload => payload.beforeSeq === undefined
+      ? histResponse(newer, true)
+      : histResponse(older, false)
+    await session.open()
+    await session.loadOlder()
+    const snapshot = session.getSnapshot()
+    expect(api.callsOf('session.history')).toMatchObject([{}, { beforeSeq: 6 }].map(p => ({ sessionId: SID, ...p })))
+    expect(snapshot.hasMore).toBe(false)
+    expect(snapshot.nodes.map(n => n.seq)).toEqual([1, 3, 7, 9])
+  })
+
+  it('drops a discontinuous older page fail-soft (window unchanged, hasMore cleared)', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = payload => payload.beforeSeq === undefined
+      ? histResponse(plainTurn(10, 1, '新', '页'), true)
+      : histResponse(plainTurn(0, 0, '断', '层'), true) // tail seq 5, but baseSeq is 10 → hole
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      await session.open()
+      const nodesBefore = session.getSnapshot().nodes
+      await session.loadOlder()
+      const snapshot = session.getSnapshot()
+      expect(snapshot.nodes).toEqual(nodesBefore)
+      expect(snapshot.hasMore).toBe(false)
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('ignores loadOlder while one is in flight (single request)', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(6, 1, 'x', 'y'), true)
+    await session.open()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    api.onHistory = () => gate.promise
+    const first = session.loadOlder()
+    const second = session.loadOlder()
+    gate.resolve(ok({ events: entries(plainTurn(0, 0, 'a', 'b')) as never[], hasMore: false }))
+    await Promise.all([first, second])
+    expect(api.callsOf('session.history')).toHaveLength(2) // open + one page, not two
+  })
+})
+
+describe('prompt and cancel errors', () => {
+  it('sends content through session.prompt with the mode passed through', async () => {
+    const { api, session } = makeSession()
+    const result = await session.prompt([{ type: 'text', text: '要发的' }], 'queue')
+    expect(result.ok).toBe(true)
+    expect(api.callsOf('session.prompt')).toMatchObject([{ sessionId: SID, mode: 'queue', content: [{ type: 'text', text: '要发的' }] }])
+  })
+
+  it('business failure lands in promptError with op=send', async () => {
+    const { api, session } = makeSession()
+    api.onPrompt = () => Promise.resolve(err({ code: 'agent-busy', message: 'busy', details: { reason: 'x' } }))
+    const result = await session.prompt([{ type: 'text', text: '失败的' }], 'queue')
+    expect(result.ok).toBe(false)
+    expect(session.getSnapshot().promptError).toMatchObject({ op: 'send', error: { code: 'agent-busy' } })
+  })
+
+  it('lands cancel failures in promptError with op=stop', async () => {
+    const { api, session } = makeSession()
+    api.onCancel = () => Promise.reject(new Error('cancel transport down'))
+    const result = await session.cancel()
+    expect(result.ok).toBe(false)
+    expect(session.getSnapshot().promptError).toMatchObject({ op: 'stop', error: { code: 'internal' } })
+  })
+})
+
+describe('pending interactions', () => {
+  it('adds approval/question on requested and removes them on resolved', async () => {
+    const { session } = makeSession()
+    session.handleMuxEnvelope('ra' as never, { type: 'approval/requested', sessionId: SID, approvalId: 'ap1' as never, toolName: 'rm' })
+    session.handleMuxEnvelope('rq' as never, { type: 'question/requested', sessionId: SID, questions: [] })
+    expect(session.getSnapshot().pending.map(p => p.kind).sort()).toEqual(['approval', 'question'])
+    session.handleMuxEnvelope('rx' as never, { type: 'approval/resolved', sessionId: SID, approvalId: 'ap1' as never, outcome: 'approved' as never })
+    session.handleMuxEnvelope('ry' as never, { type: 'question/resolved', sessionId: SID, questionRpcId: 'rq' as never, outcome: 'answered' })
+    expect(session.getSnapshot().pending).toEqual([])
+  })
+})
+
+describe('remaining branches', () => {
+  it('prompt transport throw folds to internal promptError', async () => {
+    const { api, session } = makeSession()
+    api.onPrompt = () => Promise.reject(new Error('prompt wire down'))
+    const result = await session.prompt([{ type: 'text', text: 'x' }], 'queue')
+    expect(result.ok).toBe(false)
+    expect(session.getSnapshot().promptError).toMatchObject({ op: 'send', error: { code: 'internal', message: 'prompt wire down' } })
+  })
+
+  it('cancel business error also lands op=stop promptError', async () => {
+    const { api, session } = makeSession()
+    api.onCancel = () => Promise.resolve(err({ code: 'agent-busy', message: 'nope', details: { reason: 'r' } }))
+    await session.cancel()
+    expect(session.getSnapshot().promptError).toMatchObject({ op: 'stop', error: { code: 'agent-busy' } })
+  })
+
+  it('loadOlder guards: not-open/no-hasMore no-op, err result kept window, empty page updates hasMore, throw fail-soft', async () => {
+    const { api, session } = makeSession()
+    await session.loadOlder() // cold: no-op, zero calls
+    expect(api.calls).toEqual([])
+    api.onHistory = () => histResponse(plainTurn(6, 1, 'x', 'y'), true)
+    await session.open()
+    // err result: window unchanged
+    api.onHistory = () => Promise.resolve(err({ code: 'internal', message: 'x', details: {} }))
+    await session.loadOlder()
+    expect(session.getSnapshot().nodes).toHaveLength(2)
+    expect(session.getSnapshot().hasMore).toBe(true)
+    // empty page: hasMore adopts the response
+    api.onHistory = () => histResponse([], false)
+    await session.loadOlder()
+    expect(session.getSnapshot().hasMore).toBe(false)
+    // hasMore false now: further loadOlder is a guard no-op
+    const calls = api.calls.length
+    await session.loadOlder()
+    expect(api.calls.length).toBe(calls)
+    // throw path: fail-soft with console.error
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      await session.resync()
+      api.onHistory = () => histResponse(plainTurn(6, 1, 'x', 'y'), true)
+      await session.resync()
+      api.onHistory = () => Promise.reject(new Error('page wire down'))
+      await session.loadOlder()
+      expect(errorSpy).toHaveBeenCalled()
+      expect(session.getSnapshot().loadingOlder).toBe(false)
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('subscribe delivers snapshot-change notifications and unsubscribes', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    let notified = 0
+    const unsubscribe = session.subscribe(() => { notified++ })
+    await session.open()
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(notified).toBeGreaterThan(0)
+    const seen = notified
+    unsubscribe()
+    session.handleRunning(true) // any snapshot mutation; the listener must stay silent
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(notified).toBe(seen)
+  })
+
+  it('subscribed baseline past the window tail triggers the second stitch pull in doOpen', async () => {
+    const { api, session } = makeSession()
+    const full = [...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]
+    let call = 0
+    api.onHistory = () => {
+      call++
+      return histResponse(call === 1 ? plainTurn(0, 0, 'a', 'b') : full)
+    }
+    // Baseline arrives before open: lastSeq 11 > first page tail 5 → doOpen repulls once.
+    session.handleMuxEnvelope('rs' as never, { type: 'session/subscribed', sessionId: SID, lastSeq: 11 })
+    await session.open()
+    expect(call).toBe(2)
+    expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([1, 3, 7, 9])
+  })
+
+  it('a failed second stitch pull keeps the first window and still opens', async () => {
+    const { api, session } = makeSession()
+    let call = 0
+    api.onHistory = () => {
+      call++
+      return call === 1
+        ? histResponse(plainTurn(0, 0, 'a', 'b'))
+        : Promise.resolve(err({ code: 'internal', message: 'stitch pull down', details: {} }))
+    }
+    session.handleMuxEnvelope('rs' as never, { type: 'session/subscribed', sessionId: SID, lastSeq: 11 })
+    await session.open()
+    expect(call).toBe(2)
+    const snapshot = session.getSnapshot()
+    expect(snapshot.openState).toBe('open') // stitch-pull failure is not an open failure
+    expect(snapshot.nodes.map(n => n.seq)).toEqual([1, 3]) // first window kept
+  })
+
+  it('approval frame with callId/reason keeps the optional fields; duplicate resolved is a no-op', () => {
+    const { session } = makeSession()
+    session.handleMuxEnvelope('ra' as never, {
+      type: 'approval/requested', sessionId: SID, approvalId: 'ap2' as never, toolName: 'rm', callId: 'c1' as never, reason: '危险',
+    })
+    expect(session.getSnapshot().pending[0]).toMatchObject({ kind: 'approval', callId: 'c1', reason: '危险' })
+    session.handleMuxEnvelope('rx' as never, { type: 'approval/resolved', sessionId: SID, approvalId: 'ap2' as never, outcome: 'approved' as never })
+    session.handleMuxEnvelope('rx2' as never, { type: 'approval/resolved', sessionId: SID, approvalId: 'ap2' as never, outcome: 'approved' as never })
+    session.handleMuxEnvelope('ry2' as never, { type: 'question/resolved', sessionId: SID, questionRpcId: 'never-was' as never, outcome: 'cancelled' })
+    expect(session.getSnapshot().pending).toEqual([])
+  })
+
+  it('ignores unknown mux frame types and repeated running flips (documented defaults)', () => {
+    const { session } = makeSession()
+    const before = session.getSnapshot()
+    session.handleMuxEnvelope('rz' as never, { type: 'future/frame' } as never)
+    session.handleRunning(false) // already false: dedup branch
+    expect(session.getSnapshot()).toBe(before)
+    session.handleRemoved()
+    expect(session.getSnapshot().removed).toBe(true)
+  })
+
+  it('drops live events while cold/error (no window upkeep)', async () => {
+    const { api, session } = makeSession()
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.user(0, '冷态帧') })
+    expect(session.getSnapshot().nodes).toEqual([])
+    api.onHistory = () => Promise.resolve(err({ code: 'internal', message: 'x', details: {} }))
+    await session.open()
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.user(0, '错态帧') })
+    expect(session.getSnapshot().nodes).toEqual([])
+  })
+
+  it('repairGap failure logs and clears stitching; concurrent gaps coalesce into one repair', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    let repairs = 0
+    api.onHistory = () => {
+      repairs++
+      return gate.promise
+    }
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      session.handleMuxEnvelope('r1' as never, { type: 'session/event', sessionId: SID, event: ev.user(9, '洞一') })
+      session.handleMuxEnvelope('r2' as never, { type: 'session/event', sessionId: SID, event: ev.user(10, '洞二') }) // stitching: detours, no second repair
+      expect(repairs).toBe(1)
+      gate.reject(new Error('repair wire down'))
+      await vi.waitFor(() => { expect(errorSpy).toHaveBeenCalled() })
+      // Window unchanged; a later successful repull still lands the buffered frames.
+      expect(session.getSnapshot().nodes).toHaveLength(2)
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('freezes only content-bearing partials; a content-free partial is dropped outright', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.chunkStart(7, 1)) // empty text block only, no delta
+    feed(ev.turnEnd(8, 1, 'cancelled'))
+    const snapshot = session.getSnapshot()
+    expect(snapshot.partial).toBeNull()
+    expect(snapshot.nodes.filter(n => n.kind === 'assistant' && (n as { interrupted?: true }).interrupted)).toEqual([])
+  })
+
+  it('turn/end sweeps only same-turn open calls; other turns keep running', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.toolCall(7, 1, 'turn1-call', 'echo', '{}'))
+    feed(ev.toolCall(8, 2, 'turn2-call', 'echo', '{}')) // stray call attributed to a later turn
+    feed(ev.turnEnd(9, 1, 'cancelled'))
+    const snapshot = session.getSnapshot()
+    expect(snapshot.runningCalls.map(c => c.callId)).toEqual(['turn2-call'])
+    expect(snapshot.nodes.at(-1)).toMatchObject({ kind: 'tool-result', callId: 'turn1-call', isError: true })
+  })
+
+  it('doOpen transport throw of a stale generation is swallowed (generation guard in catch)', async () => {
+    const { api, session } = makeSession()
+    const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    api.onHistory = () => stale.promise
+    const opening = session.open()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    const resynced = session.resync()
+    stale.reject(new Error('stale wire'))
+    await Promise.all([opening, resynced])
+    expect(session.getSnapshot().openState).toBe('open') // stale catch did not write error
+  })
+
+  it('drops a stale doOpen whose history resolved successfully after resync superseded it', async () => {
+    const { api, session } = makeSession()
+    const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    api.onHistory = () => stale.promise
+    const opening = session.open()
+    api.onHistory = () => histResponse(plainTurn(6, 1, '新', '代'))
+    const resynced = session.resync()
+    stale.resolve(ok({ events: entries(plainTurn(0, 0, '旧', '代')) as never[], hasMore: false })) // success, but its generation is gone
+    await Promise.all([opening, resynced])
+    expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9]) // only the fresh generation's window
+  })
+
+  it('drops a stale stitch pull (second doOpen fetch) superseded mid-flight by resync', async () => {
+    const { api, session } = makeSession()
+    const secondPull = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    let call = 0
+    api.onHistory = () => {
+      call++
+      if (call === 1) return histResponse(plainTurn(0, 0, 'a', 'b')) // first page: tail 5
+      if (call === 2) return secondPull.promise // gap-stitch pull: held
+      return histResponse(plainTurn(6, 1, 'c', 'd'))
+    }
+    session.handleMuxEnvelope('rs' as never, { type: 'session/subscribed', sessionId: SID, lastSeq: 11 })
+    const opening = session.open() // triggers the second pull, which parks
+    await vi.waitFor(() => { expect(call).toBe(2) })
+    const resynced = session.resync()
+    secondPull.resolve(ok({ events: entries([...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]) as never[], hasMore: false }))
+    await Promise.all([opening, resynced])
+    expect(session.getSnapshot().openState).toBe('open')
+  })
+
+  it('drops a gap repair superseded by a full resync while its pull was in flight', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    const repairPull = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    api.onHistory = () => repairPull.promise
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.user(9, '洞') }) // starts repairGap
+    api.onHistory = () => histResponse(plainTurn(6, 1, 'c', 'd'))
+    const resynced = session.resync() // bumps the generation
+    repairPull.resolve(ok({ events: entries(plainTurn(0, 0, '旧', '页')) as never[], hasMore: false })) // repair result: stale, dropped
+    await resynced
+    expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9])
+  })
+
+  it('successful cancel leaves no promptError; tool/result for an unknown callId is a no-op', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    const result = await session.cancel()
+    expect(result.ok).toBe(true)
+    expect(session.getSnapshot().promptError).toBeNull()
+    const callsBefore = session.getSnapshot().runningCalls
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.toolResult(6, 0, 'never-called', 'x') })
+    expect(session.getSnapshot().runningCalls).toBe(callsBefore) // callsRev untouched: same reference
+  })
+
+  it('freezes a tool-call-only partial (visible through the non-text arm)', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(at(7, { type: 'assistant/chunk', data: { turn: 1, step: 0, chunk: { type: 'tool-call-delta', index: 0, id: 'c1', name: 'echo', argumentsDelta: '{' } } }))
+    feed(ev.turnEnd(8, 1, 'cancelled'))
+    const frozen = session.getSnapshot().nodes.at(-1)
+    expect(frozen).toMatchObject({ kind: 'assistant', interrupted: true, blocks: [{ kind: 'tool-call', callId: 'c1' }] })
+  })
+
+  it('dispose is a reserved no-op on resident instances', () => {
+    const { session } = makeSession()
+    expect(() => { session.dispose() }).not.toThrow()
+  })
+
+  it('carries mux-frame views into runningCalls and tool-result nodes, and history-entry views through open', async () => {
+    const { api, session } = makeSession()
+    const callView = { for: 'call', view: { card: 'generic', title: '历史卡' } }
+    api.onHistory = () => Promise.resolve(ok({
+      events: [
+        ...entries(plainTurn(0, 0, 'a', 'b')),
+        { event: ev.toolCall(6, 1, 'h1', 'bash', '{}'), view: callView },
+        { event: ev.toolResult(7, 1, 'h1', 'done'), view: { for: 'result', view: { card: 'generic', title: '历史果' } } },
+      ] as never[],
+      hasMore: false,
+    }))
+    await session.open()
+    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
+      kind: 'tool-result', callView: { title: '历史卡' }, resultView: { title: '历史果' },
+    })
+    // Live path: the frame's view slot reaches runningCalls, then the result node.
+    session.handleMuxEnvelope('rv1' as never, {
+      type: 'session/event', sessionId: SID, event: ev.toolCall(8, 2, 'l1', 'write', '{}'),
+      view: { for: 'call', view: { card: 'generic', title: '直播卡' } },
+    } as never)
+    expect(session.getSnapshot().runningCalls).toMatchObject([{ callId: 'l1', callView: { title: '直播卡' } }])
+    session.handleMuxEnvelope('rv2' as never, {
+      type: 'session/event', sessionId: SID, event: ev.toolResult(9, 2, 'l1', 'ok'),
+      view: { for: 'result', view: { card: 'generic', title: '直播果' } },
+    } as never)
+    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
+      kind: 'tool-result', callView: { title: '直播卡' }, resultView: { title: '直播果' },
+    })
+  })
+})
+
+describe('resync', () => {
+  it('rebuilds the window and clears pending; cold instances no-op', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    session.handleMuxEnvelope('ra' as never, { type: 'approval/requested', sessionId: SID, approvalId: 'ap1' as never, toolName: 'rm' })
+    api.onHistory = () => histResponse([...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')])
+    await session.resync()
+    const snapshot = session.getSnapshot()
+    expect(snapshot.openState).toBe('open')
+    expect(snapshot.pending).toEqual([]) // baseline replay re-sends still-pending frames
+    expect(snapshot.nodes).toHaveLength(4)
+
+    const cold = makeSession()
+    await cold.session.resync()
+    expect(cold.api.calls).toEqual([]) // never opened: no traffic
+  })
+
+  it('drops a stale in-flight open superseded by resync (generation guard)', async () => {
+    const { api, session } = makeSession()
+    const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    api.onHistory = () => stale.promise
+    const firstOpen = session.open()
+    api.onHistory = () => histResponse(plainTurn(6, 1, '新', '代'))
+    const resynced = session.resync()
+    stale.reject(new Error('dead connection')) // the doomed pre-disconnect request fails late
+    await firstOpen
+    await resynced
+    const snapshot = session.getSnapshot()
+    expect(snapshot.openState).toBe('open') // stale failure did not settle the fresh generation into error
+    expect(snapshot.nodes.map(n => n.seq)).toEqual([7, 9])
+  })
+})
+
+describe('reference stability (the memo contract)', () => {
+  it('keeps unchanged node references across an append and swaps the snapshot object', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, '稳', '定'))
+    await session.open()
+    const before = session.getSnapshot()
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.user(6, '追加') })
+    const after = session.getSnapshot()
+    expect(after).not.toBe(before) // top-level swap on change
+    expect(after.nodes[0]).toBe(before.nodes[0]) // untouched nodes keep identity
+    expect(after.nodes[1]).toBe(before.nodes[1])
+    expect(after.nodes).toHaveLength(3)
+    // No change → same snapshot reference.
+    expect(session.getSnapshot()).toBe(after)
+  })
+
+  it('keeps untouched substructure arrays identical across unrelated changes (revision counters)', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, '底', '座'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.toolCall(7, 1, 'c1', 'echo', '{}'))
+    session.handleMuxEnvelope('ra' as never, { type: 'approval/requested', sessionId: SID, approvalId: 'ap1' as never, toolName: 'rm' })
+    const before = session.getSnapshot()
+    // A chunk storm touches partial/nodes only: runningCalls and pending must keep identity.
+    feed(ev.chunkStart(8, 1))
+    feed(ev.chunkText(9, 1, '与工具无关的流式'))
+    const after = session.getSnapshot()
+    expect(after).not.toBe(before)
+    expect(after.runningCalls).toBe(before.runningCalls)
+    expect(after.pending).toBe(before.pending)
+    // And a mutation on the tracked domain swaps that array.
+    feed(ev.toolResult(10, 1, 'c1', 'ECHO'))
+    const resolved = session.getSnapshot()
+    expect(resolved.runningCalls).not.toBe(after.runningCalls)
+    expect(resolved.pending).toBe(after.pending)
+  })
+})

packages/client/runtime/tests/sessions-service.spec.ts

@@ -0,0 +1,141 @@
+/**
+ * SessionsService: list store projection (manager → {ids, byId} with derived
+ * titles), scope-tree lifecycle (lazy mint / frozen survival / removed
+ * teardown with watch deferral), binding identity, ancestry walk, create.
+ */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import { SessionsService, scopeOf } from '../src/client/sessions/service.ts'
+import { FakeApiClient, ok } from './fake-api.ts'
+
+const sid = (s: string): SessionId => s as SessionId
+
+interface Bench {
+  ctx: Context
+  api: FakeApiClient
+  svc: SessionsService
+}
+
+function bench(): Bench {
+  const ctx = new Context()
+  const api = new FakeApiClient()
+  const svc = new SessionsService(ctx, api)
+  return { ctx, api, svc }
+}
+
+/** Refresh the manager list from programmable rows and flush the microtask batch. */
+async function feedList(b: Bench, rows: { id: string; cwd?: string; parentId?: string; running?: boolean }[]): Promise<void> {
+  b.api.onList = () => Promise.resolve(ok({
+    items: rows.map(r => ({
+      sessionId: sid(r.id), updatedAt: 1, running: r.running ?? false,
+      ...(r.cwd !== undefined ? { cwd: r.cwd } : {}),
+      ...(r.parentId !== undefined ? { parentSessionId: sid(r.parentId) } : {}),
+    })),
+  }) as never)
+  await b.svc.manager.refreshList()
+  await Promise.resolve() // manager notifier flush
+}
+
+describe('list store projection', () => {
+  it('projects ids/byId with cwd-basename titles (id fallback) and parent links', async () => {
+    const b = bench()
+    await feedList(b, [
+      { id: 's1', cwd: '/home/u/proj-a/' },
+      { id: 's2', parentId: 's1', running: true },
+    ])
+    const state = b.svc.list.getSnapshot()
+    expect(state.ids).toEqual(['s1', 's2'])
+    expect(state.byId[sid('s1')]).toMatchObject({ title: 'proj-a', cwd: '/home/u/proj-a/' })
+    expect(state.byId[sid('s2')]).toMatchObject({ title: 's2', parentId: 's1', running: true })
+  })
+
+  it('reflects live increments (host stream via manager) into the store', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1' }])
+    b.svc.manager.handleHostEnvelope({ rpcId: 'r1' as never, payload: { type: 'host/session-added', sessionId: sid('s2') } as never })
+    await Promise.resolve()
+    expect(b.svc.list.getSnapshot().ids).toContain('s2')
+  })
+})
+
+describe('scope tree', () => {
+  it('mints lazily on first resolution, tags the ctx, and keeps binding identity stable', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1' }])
+    expect(b.svc.scope(sid('unknown'))).toBeUndefined()
+    const scoped = b.svc.scope(sid('s1'))
+    expect(scoped).toBeDefined()
+    expect(scopeOf(scoped as Context)).toBe('s1')
+    expect(scopeOf(b.ctx)).toBeUndefined()
+    const binding = b.svc.binding(sid('s1'))
+    expect(binding?.session).toBe(b.svc.manager.get(sid('s1')))
+    expect(b.svc.binding(sid('s1'))).toBe(binding)
+    expect(binding?.ctx).toBe(scoped)
+  })
+
+  it('tears down an unwatched removed session but defers the watched one until the watch moves', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1' }, { id: 's2' }])
+    const ctx1 = b.svc.scope(sid('s1'))
+    b.svc.binding(sid('s1')) // s1 is watched
+    b.svc.scope(sid('s2')) // s2 scoped but not watched
+
+    await feedList(b, [{ id: 's1' }]) // s2 removed, unwatched: torn down
+    expect(b.svc.scope(sid('s2'))).toBeUndefined()
+
+    await feedList(b, []) // s1 removed while watched: deferred, scope survives
+    expect(b.svc.scope(sid('s1'))).toBe(ctx1)
+
+    await feedList(b, [{ id: 's3' }])
+    b.svc.binding(sid('s3')) // watch moves: deferred teardown sweeps s1
+    expect(b.svc.scope(sid('s1'))).toBeUndefined()
+  })
+
+  it('keeps the scope when the session merely stops running (frozen ≠ removed)', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1', running: true }])
+    const scoped = b.svc.scope(sid('s1'))
+    await feedList(b, [{ id: 's1', running: false }])
+    expect(b.svc.scope(sid('s1'))).toBe(scoped)
+  })
+
+  it('cancels a deferred teardown when the id reappears in the list', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1' }])
+    const scoped = b.svc.scope(sid('s1'))
+    b.svc.binding(sid('s1'))
+    await feedList(b, []) // removed while watched → deferred
+    await feedList(b, [{ id: 's1' }, { id: 's2' }]) // reappears
+    b.svc.binding(sid('s2')) // watch moves; sweep must NOT tear down the re-listed s1
+    expect(b.svc.scope(sid('s1'))).toBe(scoped)
+  })
+})
+
+describe('ancestry', () => {
+  it('walks parentId links root-first including self; broken links stop the walk', async () => {
+    const b = bench()
+    await feedList(b, [
+      { id: 'root', cwd: '/w/app' },
+      { id: 'mid', parentId: 'root' },
+      { id: 'leaf', parentId: 'mid' },
+      { id: 'orphan', parentId: 'ghost' },
+    ])
+    expect(b.svc.ancestry(sid('leaf')).map(s => s.id)).toEqual(['root', 'mid', 'leaf'])
+    expect(b.svc.ancestry(sid('orphan')).map(s => s.id)).toEqual(['orphan'])
+    expect(b.svc.ancestry(sid('ghost'))).toEqual([])
+  })
+})
+
+describe('create', () => {
+  it('returns the new id on ok and throws a coded error on failure', async () => {
+    const b = bench()
+    b.api.onCreate = () => Promise.resolve(ok({ sessionId: sid('fresh') }))
+    await expect(b.svc.create({ cwd: '/w' })).resolves.toBe('fresh')
+    b.api.onCreate = () => Promise.resolve({
+      rpcId: 'e' as never,
+      result: { ok: false as const, error: { code: 'internal' as const, message: '爆了', details: {} } },
+    } as never)
+    await expect(b.svc.create()).rejects.toThrow(/internal: 爆了/)
+  })
+})

packages/client/runtime/tests/slots-service.spec.ts

@@ -0,0 +1,65 @@
+/**
+ * SlotsService: cordis Service wrapper semantics — core delegation, the
+ * 'slots/changed' event bridge, and fiber-scoped registration disposal.
+ */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import type { FC } from 'react'
+import { SlotsService } from '../src/client/slots.ts'
+
+// Test-only slot keys (SlotMap is empty in this package; the service is generic over it).
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    't-single': { kind: 'single'; scope: 'root'; props: object }
+    't-list': { kind: 'list'; scope: 'root'; props: object }
+  }
+}
+
+const C: FC<object> = () => null
+
+async function boot(): Promise<Context> {
+  const ctx = new Context()
+  ctx.plugin(SlotsService)
+  await ctx.fiber.await()
+  return ctx
+}
+
+describe('SlotsService', () => {
+  it('proxies define/register/entries/spec/getVersion to the core', async () => {
+    const ctx = await boot()
+    ctx.slots.define('t-single', { kind: 'single', scope: 'root' })
+    expect(ctx.slots.spec('t-single')).toEqual({ kind: 'single', scope: 'root' })
+    const v0 = ctx.slots.getVersion('t-single')
+    ctx.slots.register('t-single', C)
+    expect(ctx.slots.entries('t-single')).toHaveLength(1)
+    expect(ctx.slots.getVersion('t-single')).toBeGreaterThan(v0)
+    expect(ctx.slots.core.spec('t-single')).toBeDefined()
+  })
+
+  it("re-emits every mutation as 'slots/changed' with the key", async () => {
+    const ctx = await boot()
+    const seen: string[] = []
+    ctx.on('slots/changed', (key) => { seen.push(key) })
+    ctx.slots.define('t-list', { kind: 'list', scope: 'root' })
+    ctx.slots.register('t-list', C, { id: 'a' })
+    expect(seen).toEqual(['t-list', 't-list'])
+  })
+
+  it('collects a plugin fiber\'s registrations when the fiber unloads (cascade)', async () => {
+    const ctx = await boot()
+    ctx.slots.define('t-single', { kind: 'single', scope: 'root' })
+    const fiber = ctx.plugin({
+      name: 'occupant',
+      inject: ['slots'],
+      apply: (pluginCtx: Context) => {
+        pluginCtx.slots.register('t-single', C)
+      },
+    })
+    await fiber.await()
+    expect(ctx.slots.entries('t-single')).toHaveLength(1)
+    await fiber.dispose()
+    expect(ctx.slots.entries('t-single')).toHaveLength(0)
+    // The slot definition (registered from root) survives; a new occupant may register.
+    expect(() => ctx.slots.register('t-single', C)).not.toThrow()
+  })
+})

packages/client/runtime/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../web-react"
+    },
+    {
+      "path": "../connection"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ],
+  "exclude": [
+    "**/*.legacy.*"
+  ]
+}

packages/client/runtime/tsdown.config.ts

@@ -0,0 +1,23 @@
+import type { UserConfig } from 'tsdown'
+import { clientBundle } from '../tsdown.client.ts'
+
+/**
+ * Standard dual-entry shape plus the loader lib half: exports["./loader"]
+ * promises lib/loader.js (the web shell statically imports the machinery —
+ * a loader cannot load itself), and the shared preset only emits
+ * lib/{index,invariant}.js, so the extra config supplies it.
+ */
+const configs = clientBundle('@deepseek-ai/dsh-client-runtime', ['lib/types/index.js', 'lib/types/invariant.js'])
+
+const loaderLib: UserConfig = {
+  entry: { loader: 'lib/types/client/loader/index.js' },
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'neutral',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+}
+
+export default [...configs, loaderLib]