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/ui-sidebar/README.md

@@ -0,0 +1,19 @@
+# @deepseek-ai/dsh-client-ui-sidebar
+
+Sidebar plugin: session multi-level tree (cwd grouping + parentId nesting), search, by-workspace grouping, state dots, three creation entries. Contract: api-contracts v3 §6.
+
+`src/client/contract/slots.ts` is the single-domain contract file: `SidebarRootInjected` (the registrant's own injected share — tree hook, current-session hook, actions) and `SidebarRootComponentProps = OwnerOf<'sidebar'> & SidebarRootInjected` (the owner share referenced from ui-layout's slot declaration, never re-stated). `apply` registers SidebarRoot cast-free against that composition; the inject factory binds layout/sessions off `RootBinding<ClientContext>`.
+
+## Model Experience
+
+None, as the sidebar renders the browser session list; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **State dots have two live data states (running/none)** — the done/error/amber sources arrive with P-II approvals and notifications; the four-color primitive is already wired.
+- **Group-by menu ships by-workspace only** — Update/Status grouping strategies are drawn without specs and deferred.
+- **"New task completed" unread marking is local viewing state** — completion-time > last-seen never reaches the host.

packages/client/ui-sidebar/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-sidebar",
+  "description": "Sidebar plugin: session multi-level tree, search, grouping, state dots",
+  "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"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-ui-layout"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
+    "clsx": "^2.0.0",
+    "react": "^18.2.0"
+  },
+  "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/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}

packages/client/ui-sidebar/src/client/Rows.module.css

@@ -0,0 +1,158 @@
+/* Tree rows (figma Cell set 14:3080): project 54px two-line, session 34px
+   single-line, radius 8, indent step 22px (16px slot + 6px gap). Hover swaps
+   are pure CSS: project folder -> chevron + action buttons; session time ->
+   ellipsis button. */
+
+.projectRow,
+.sessionRow {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  border-radius: 8px;
+  padding: 0 8px;
+  cursor: pointer;
+  user-select: none;
+  color: var(--dsw-alias-label-primary);
+}
+
+.projectRow:hover,
+.sessionRow:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.sessionRow.selected {
+  background: var(--dsw-alias-interactive-bg-active);
+}
+
+.projectRow {
+  height: 54px;
+}
+
+.sessionRow {
+  height: 34px;
+}
+
+.slot {
+  flex: none;
+  width: 16px;
+  height: 20px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+
+.folderActive {
+  color: var(--dsw-alias-state-business-primary);
+}
+
+/* Project leading slot: folder by default, chevron on row hover. */
+.projectRow .chevron { display: none; }
+.projectRow:hover .chevron { display: inline-flex; }
+.projectRow:hover .folder { display: none; }
+
+.projectText {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.title {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 14px;
+  line-height: 20px;
+}
+
+.sessionRow .title {
+  flex: 1;
+}
+
+.meta {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 12px;
+  line-height: 20px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.time {
+  flex: none;
+  font-size: 12px;
+  line-height: 20px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.dot {
+  flex: none;
+}
+
+/* Trailing action buttons surface on hover only (figma 27:4668 / 27:4656):
+   bare 16px glyphs, gap 12, tertiary grey. */
+.rowActions {
+  flex: none;
+  display: none;
+  align-items: center;
+  gap: 12px;
+}
+
+.projectRow:hover .rowActions,
+.sessionRow:hover .rowActions {
+  display: inline-flex;
+}
+
+.sessionRow:hover .time {
+  display: none;
+}
+
+.iconButton {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  border: none;
+  border-radius: 4px;
+  padding: 0;
+  background: transparent;
+  cursor: pointer;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.iconButton:hover {
+  color: var(--dsw-alias-label-primary);
+}
+
+/* Session expand twist occupies the leading 16px slot; keep a spacer when absent
+   so titles align across sibling rows. */
+.twist {
+  composes: iconButton;
+  width: 16px;
+  height: 20px;
+}
+
+/* "L" connector slot (figma arrow 14:3071): 16x16, glyph right-aligned. */
+.cornerSlot {
+  flex: none;
+  width: 16px;
+  height: 16px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: flex-end;
+  color: var(--dsw-alias-label-caption);
+}
+
+/* Chevrons and tree twists ride the caption grey (#ADB2B8); the folder glyph
+   stays one step darker (tertiary, #81858C) per the cell spec. Declared last
+   to win over the composed .iconButton color. */
+.chevron,
+.twist {
+  color: var(--dsw-alias-label-caption);
+}

packages/client/ui-sidebar/src/client/Rows.tsx

@@ -0,0 +1,122 @@
+/**
+ * Sidebar tree row components (figma Cell set 14:3080): pure presentational —
+ * all data and callbacks arrive via props. Hover swaps (folder->chevron,
+ * time->ellipsis, action buttons) are CSS-only.
+ */
+import clsx from 'clsx'
+import {
+  IconChevronDownOutline14, IconChevronRightOutline14,
+  IconEllipsisOutline16, IconFolderClose16, IconFolderOpen16, IconPlusOutline16,
+  IconTreeCorner8x10, StateDot,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ProjectRow, SessionRow } from './tree.ts'
+import { formatRelativeTime } from './tree.ts'
+import css from './Rows.module.css'
+
+/** Indent step per tree level: 16px slot + 6px gap (figma). */
+const INDENT_STEP = 22
+
+/**
+ * Project (workspace) row: 54px, folder + title + session count; hover
+ * reveals the chevron and the more/create buttons.
+ * @param props.row - derived project row.
+ * @param props.active - group contains the selected session (blue open folder).
+ * @param props.onToggle - expand/collapse the group.
+ * @param props.onCreate - create a session inside this group.
+ * @returns the row element.
+ */
+export function ProjectRowItem({ row, active, onToggle, onCreate }: {
+  row: ProjectRow
+  active: boolean
+  onToggle: () => void
+  onCreate: () => void
+}) {
+  const count = `${row.sessionCount} ${row.sessionCount === 1 ? 'session' : 'sessions'}`
+  return (
+    <div className={css.projectRow} role="treeitem" aria-expanded={row.expanded} onClick={onToggle}>
+      <span className={clsx(css.slot, css.folder, active && css.folderActive)}>
+        {row.expanded ? <IconFolderOpen16 /> : <IconFolderClose16 />}
+      </span>
+      <span className={clsx(css.slot, css.chevron)}>
+        {row.expanded ? <IconChevronDownOutline14 /> : <IconChevronRightOutline14 />}
+      </span>
+      <span className={css.projectText}>
+        <span className={css.title}>{row.label}</span>
+        <span className={css.meta}>{count}</span>
+      </span>
+      <span className={css.rowActions}>
+        {/* Row menu contents are not designed yet (figma draft notes); the button is the reserved anchor. */}
+        <button type="button" className={css.iconButton} aria-label="More" onClick={(e) => { e.stopPropagation() }}>
+          <IconEllipsisOutline16 />
+        </button>
+        <button
+          type="button"
+          className={css.iconButton}
+          aria-label="New session here"
+          onClick={(e) => { e.stopPropagation(); onCreate() }}
+        >
+          <IconPlusOutline16 />
+        </button>
+      </span>
+    </div>
+  )
+}
+
+/**
+ * Session row: 34px, indent by depth, expand twist when it has children,
+ * running state dot, relative time swapping to the more button on hover.
+ * @param props.row - derived session row.
+ * @param props.selected - row is the current session.
+ * @param props.now - epoch ms for relative-time formatting.
+ * @param props.onOpen - open this session.
+ * @param props.onToggle - unfold/fold the subtree.
+ * @returns the row element.
+ */
+export function SessionRowItem({ row, selected, now, onOpen, onToggle }: {
+  row: SessionRow
+  selected: boolean
+  now: number
+  onOpen: () => void
+  onToggle: () => void
+}) {
+  // Rail (figma sub-cell slot sequence): twist slot, always-reserved state
+  // slot (opacity-0 slots keep their 22px in figma, so titles align whether
+  // or not the dot is lit), then the L connector on child rows. Extra depth
+  // rides the left padding: indent spacers = depth - 1.
+  return (
+    <div
+      className={clsx(css.sessionRow, selected && css.selected)}
+      role="treeitem"
+      aria-selected={selected}
+      {...(row.hasChildren ? { 'aria-expanded': row.expanded } : {})}
+      style={{ paddingLeft: 8 + Math.max(0, row.depth - 1) * INDENT_STEP }}
+      onClick={onOpen}
+    >
+      {row.hasChildren
+        ? (
+            <button
+              type="button"
+              className={css.twist}
+              aria-label={row.expanded ? 'Collapse' : 'Expand'}
+              onClick={(e) => { e.stopPropagation(); onToggle() }}
+            >
+              {row.expanded ? <IconChevronDownOutline14 /> : <IconChevronRightOutline14 />}
+            </button>
+          )
+        : <span className={css.slot} />}
+      <span className={css.slot}>{row.running && <StateDot state="ongoing" />}</span>
+      {row.depth > 0 && (
+        <span className={css.cornerSlot} data-tree-corner="">
+          <IconTreeCorner8x10 />
+        </span>
+      )}
+      <span className={css.title}>{row.title}</span>
+      <span className={css.time}>{formatRelativeTime(row.updatedAt, now)}</span>
+      <span className={css.rowActions}>
+        <button type="button" className={css.iconButton} aria-label="More" onClick={(e) => { e.stopPropagation() }}>
+          <IconEllipsisOutline16 />
+        </button>
+      </span>
+    </div>
+  )
+}

packages/client/ui-sidebar/src/client/SidebarRoot.module.css

@@ -0,0 +1,248 @@
+/* Sidebar column (figma 133:7629): vertical stack, gap 8, padding 16/6,
+   sidebar fill + 1px right border painted by the layout column. Header block
+   (logo + New Session) and list area (section header + search + cells) carry
+   their own inner gaps per the style spec (1.2 / 1.3). */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  height: 100%;
+  padding: 6px 16px;
+  box-sizing: border-box;
+  background: var(--dsw-specific-sidebar-fill);
+  color: var(--dsw-alias-label-primary);
+  font-size: 14px;
+}
+
+/* Header block (figma 133:7630): logo row + New Session, gap 16, padBottom 12. */
+.headerBlock {
+  flex: none;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding-bottom: 12px;
+}
+
+/* Logo row: 60px, brand mark left, collapse button right.
+   figma pad is (l,t,r,b)=(4,8,4,8) — horizontal 4, vertical 8. */
+.logoRow {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 60px;
+  padding: 8px 4px;
+  box-sizing: border-box;
+}
+
+/* Brand group (figma I133:7632): fish + wordmark ride the text ink
+   (figma-flows ruling: main-screen instance is black; blue is brand
+   emphasis only). */
+.brand {
+  flex: 1;
+  min-width: 0;
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  overflow: hidden;
+}
+
+.wordmark {
+  font-weight: 600;
+  white-space: nowrap;
+}
+
+/* HARNESS badge (figma 34:10358): 14px tall, mono 11/500 on primary fill. */
+.badge {
+  flex: none;
+  padding: 0 3px;
+  border-radius: 2px;
+  background: var(--dsw-alias-label-primary);
+  color: var(--dsw-alias-label-primary-inverted);
+  font-family: var(--ds-font-family-code);
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 14px;
+}
+
+.iconButton {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border: none;
+  border-radius: 50%;
+  padding: 0;
+  background: transparent;
+  cursor: pointer;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.iconButton:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+/* New Session: 38px capsule (figma 133:7634). */
+.newSession {
+  flex: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  height: 38px;
+  padding: 8px 16px;
+  box-sizing: border-box;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 24px;
+  background: var(--dsw-alias-button-elevated-fill);
+  color: var(--dsw-alias-label-primary);
+  font-size: 14px;
+  font-weight: 510;
+  line-height: 22px;
+  cursor: pointer;
+}
+
+.newSession:hover {
+  background: var(--dsw-alias-button-floating-hover);
+}
+
+/* List area (figma 133:7640): section header + search + cells, gap 4.
+   Relative for the bottom fade overlay. */
+.listArea {
+  position: relative;
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+/* Bottom fade (figma 133:7666): 72px overlay pinned to the visible bottom,
+   transparent -> sidebar fill so it tracks the theme. */
+.fade {
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  height: 72px;
+  background: linear-gradient(to bottom, transparent, var(--dsw-specific-sidebar-fill));
+  pointer-events: none;
+}
+
+/* Batch separator (figma 133:7661): 20px spacer after an expanded project's
+   session run, before the next project row. */
+.batchGap {
+  flex: none;
+  height: 20px;
+}
+
+/* Section header: 36px, "WorkSpace" label + group-by / new-workspace buttons. */
+.sectionHeader {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  height: 36px;
+  padding-left: 12px;
+  box-sizing: border-box;
+  border-radius: 12px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.sectionLabel {
+  flex: 1;
+  min-width: 0;
+  line-height: 20px;
+}
+
+/* Search input: 38px capsule (figma 133:7649). Upstream binds a dedicated
+   design-system variable (light #F1F3F5 / dark #1B1B1C) matching no shipped
+   alias — a component token pinned to the static scale mirrors it (ruled
+   compliant: indirect via custom property, upstream-variable equivalent). */
+.search {
+  --dsh-search-input-fill: var(--dsw-static-neutral-bluish-75);
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 38px;
+  margin-bottom: 8px; /* + 4px area gap = 12px to the first cell (spec padB12) */
+  padding: 0 14px;
+  box-sizing: border-box;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 24px;
+  background: var(--dsh-search-input-fill);
+  color: var(--dsw-alias-label-caption);
+}
+
+:global(body[data-ds-dark-theme]) .search {
+  --dsh-search-input-fill: var(--dsw-static-neutral-bluish-900);
+}
+
+.searchInput {
+  flex: 1;
+  min-width: 0;
+  border: none;
+  outline: none;
+  background: transparent;
+  font-size: 14px;
+  line-height: 20px;
+  color: var(--dsw-alias-label-primary);
+}
+
+.searchInput::placeholder {
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.clearButton {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border: none;
+  border-radius: 50%;
+  padding: 0;
+  background: transparent;
+  cursor: pointer;
+  color: var(--dsw-alias-label-secondary);
+}
+
+/* Tree list: the only scrolling region. */
+.list {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding-bottom: 12px;
+}
+
+.empty {
+  padding: 16px 12px;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 13px;
+}
+
+/* Foot: settings entry (figma 133:7668). */
+.foot {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 29px;
+  margin: 10px 0;
+  padding: 0 2px 0 6px;
+  border-radius: 12px;
+  cursor: pointer;
+  color: var(--dsw-alias-label-primary);
+}
+
+.foot:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}

packages/client/ui-sidebar/src/client/SidebarRoot.tsx

@@ -0,0 +1,164 @@
+/**
+ * SidebarRoot (figma 133:7629): logo row + collapse, New Session, search,
+ * WorkSpace section header with the group-by menu, session tree list,
+ * Settings foot. Pure presentational — data and actions arrive through the
+ * inject surface; the tree store is subscribed via useTree, never derived in
+ * render.
+ */
+import { Fragment, useState } from 'react'
+import clsx from 'clsx'
+import {
+  FishLogo,
+  IconCloseFill14, IconNewChatOutline16, IconPanelLeftOutline16, IconPersonalizationOutline16,
+  IconProjectAddOutline16, IconSearchOutline16, IconSettingsOutline14,
+  Menu,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { SidebarRootComponentProps } from './contract/slots.ts'
+import { ProjectRowItem, SessionRowItem } from './Rows.tsx'
+import css from './SidebarRoot.module.css'
+
+const GROUP_BY_ITEMS = [
+  { id: 'workspace', label: 'WorkSpace' },
+  // Update/Status grouping has no design yet (figma §3) — visible, disabled.
+  { id: 'update', label: 'Update', disabled: true },
+  { id: 'status', label: 'Status', disabled: true },
+]
+
+/**
+ * Render the sidebar column.
+ * @param props - composed slot props (owner share + injected surface, contract/slots.ts).
+ * @returns the sidebar element tree.
+ */
+export function SidebarRoot({ useTree, useCurrent, actions, tree }: SidebarRootComponentProps) {
+  const rows = useTree((s) => s.rows)
+  const query = useTree((s) => s.query)
+  const groupBy = useTree((s) => s.groupBy)
+  const current = useCurrent()
+  const [menuOpen, setMenuOpen] = useState(false)
+  const now = Date.now()
+
+  // Presentational lookup (not tree derivation): the group holding the
+  // selected session gets the active folder; only expanded groups can show it.
+  let activeGroup: string | undefined
+  if (current !== undefined) {
+    for (const row of rows) {
+      if (row.type === 'session' && row.id === current) { activeGroup = row.groupKey; break }
+    }
+  }
+
+  return (
+    <div className={css.root}>
+      <div className={css.headerBlock}>
+        <div className={css.logoRow}>
+          <span className={css.brand}>
+            {/* Wordmark svg not extracted yet (figma 88:8932) — text stands in at the same ink. */}
+            <FishLogo size={23} />
+            <span className={css.wordmark}>deepseek</span>
+            <span className={css.badge}>HARNESS</span>
+          </span>
+          <button
+            type="button"
+            className={css.iconButton}
+            aria-label="Collapse sidebar"
+            onClick={() => { actions.toggleSidebar() }}
+          >
+            <IconPanelLeftOutline16 />
+          </button>
+        </div>
+
+        <button type="button" className={css.newSession} onClick={() => { actions.create() }}>
+          <IconNewChatOutline16 size={14} />
+          New Session
+        </button>
+      </div>
+
+      <div className={css.listArea}>
+      <div className={css.sectionHeader}>
+        <span className={css.sectionLabel}>WorkSpace</span>
+        <Menu
+          open={menuOpen}
+          onClose={() => { setMenuOpen(false) }}
+          items={GROUP_BY_ITEMS}
+          selectedId={groupBy}
+          onSelect={() => { setMenuOpen(false) }}
+          align="end"
+          anchor={(
+            <button
+              type="button"
+              className={css.iconButton}
+              aria-label="Group by"
+              onClick={() => { setMenuOpen((v) => !v) }}
+            >
+              <IconPersonalizationOutline16 />
+            </button>
+          )}
+        />
+        <button
+          type="button"
+          className={css.iconButton}
+          aria-label="New workspace"
+          onClick={() => { actions.create() }}
+        >
+          <IconProjectAddOutline16 />
+        </button>
+      </div>
+
+      <label className={css.search}>
+        <IconSearchOutline16 size={14} />
+        <input
+          className={css.searchInput}
+          type="text"
+          placeholder="Search name, keywords..."
+          value={query}
+          onChange={(e) => { tree.setQuery(e.target.value) }}
+        />
+        {query !== '' && (
+          <button
+            type="button"
+            className={css.clearButton}
+            aria-label="Clear search"
+            onClick={() => { tree.setQuery('') }}
+          >
+            <IconCloseFill14 />
+          </button>
+        )}
+      </label>
+
+      <div className={css.list} role="tree" aria-label="Sessions">
+        {rows.length === 0 && (
+          <div className={css.empty}>{query === '' ? 'No sessions yet' : 'No matches'}</div>
+        )}
+        {rows.map((row, i) => row.type === 'project'
+          ? (
+              <Fragment key={`p:${row.key}`}>
+                {/* Batch separator: a project row closing an expanded session run (figma 133:7661). */}
+                {i > 0 && rows[i - 1]!.type === 'session' && <span className={css.batchGap} />}
+                <ProjectRowItem
+                  row={row}
+                  active={row.key === activeGroup}
+                  onToggle={() => { tree.toggleProject(row.key) }}
+                  onCreate={() => { actions.create(row.cwd) }}
+                />
+              </Fragment>
+            )
+          : (
+              <SessionRowItem
+                key={row.id}
+                row={row}
+                selected={row.id === current}
+                now={now}
+                onOpen={() => { actions.open(row.id) }}
+                onToggle={() => { tree.toggleSession(row.id) }}
+              />
+            ))}
+      </div>
+      <span className={css.fade} />
+      </div>
+
+      <div className={clsx(css.foot)} role="button" tabIndex={0} aria-label="Settings">
+        <IconSettingsOutline14 />
+        Settings
+      </div>
+    </div>
+  )
+}

packages/client/ui-sidebar/src/client/contract/slots.ts

@@ -0,0 +1,49 @@
+/**
+ * Sidebar slot contract: the registrant-side props composition for the
+ * layout-owned `sidebar` slot. The own injected share is declared here (a
+ * share's type lives with whoever wires it); the owner share is referenced
+ * off ui-layout's slot declaration through OwnerOf, never re-stated. Single
+ * domain — this is the package's whole contract surface.
+ */
+import type { OwnerOf } from '@deepseek-ai/dsh-client-ui-slots'
+// Type-only: pulls ui-layout's SlotMap merge (the 'sidebar' entry) into every
+// program that sees this contract, so OwnerOf<'sidebar'> resolves.
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SidebarTreeState } from '../store.ts'
+
+/** Cross-plugin actions bound in apply (layout / sessions services). */
+export interface SidebarActions {
+  open(id: SessionId): void
+  create(cwd?: string): void
+  toggleSidebar(): void
+}
+
+/** Plugin-owned tree viewing-state actions (tree store mutators). */
+export interface SidebarTreeActions {
+  toggleProject(key: string): void
+  toggleSession(id: SessionId): void
+  setQuery(query: string): void
+}
+
+/**
+ * Registrant-private injected share (arrives via the register inject
+ * factory). A type alias, not an interface: the alias carries an implicit
+ * index signature, so the factory's return crosses the registry's
+ * `Record<string, unknown>` boundary uncast.
+ */
+export type SidebarRootInjected = {
+  useTree: SnapshotSelectorHook<SidebarTreeState>
+  /** Current session selector (row highlight); undefined selects nothing. */
+  useCurrent: () => SessionId | undefined
+  actions: SidebarActions
+  tree: SidebarTreeActions
+}
+
+/**
+ * Full component props: owner share referenced from ui-layout's declaration
+ * plus the own injected share. Root scope has no standard injection
+ * (useSession is session-scope only), so no standard term appears.
+ */
+export type SidebarRootComponentProps = OwnerOf<'sidebar'> & SidebarRootInjected

packages/client/ui-sidebar/src/client/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Sidebar plugin, browser half: SidebarRoot registered into the layout-owned
+ * sidebar slot; tree derivation materialized in a plugin-owned snapshot
+ * store (pure consumer — no ctx service). Contract: api-contracts v3
+ * section 6; props composition in contract/slots.ts.
+ */
+import type { RootBinding } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ClientContext, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SidebarRootInjected } from './contract/slots.ts'
+import { createSidebarTreeStore } from './store.ts'
+import { SidebarRoot } from './SidebarRoot.tsx'
+
+export {
+  deriveRows, formatRelativeTime, projectLabel,
+  UNGROUPED_KEY, UNGROUPED_LABEL,
+  type ProjectRow, type SessionRow, type SidebarRow, type TreeView,
+} from './tree.ts'
+export {
+  createSidebarTreeStore,
+  type GroupBy, type SidebarTreeState, type SidebarTreeStore,
+} from './store.ts'
+export { ProjectRowItem, SessionRowItem } from './Rows.tsx'
+export { SidebarRoot } from './SidebarRoot.tsx'
+export type {
+  SidebarActions, SidebarRootComponentProps, SidebarRootInjected, SidebarTreeActions,
+} from './contract/slots.ts'
+
+/** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
+export const inject = ['slots', 'layout', 'sessions']
+
+/**
+ * Client plugin body: build the tree store and register SidebarRoot into the
+ * sidebar slot with the inject surface bound off the root binding's ctx.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  const sessions = ctx.sessions
+
+  ctx.effect(() => {
+    const tree = createSidebarTreeStore(sessions)
+    // Called once per registration (root slots cache per entry); services are
+    // bound off the binding ctx per the contract's inject-surface wording.
+    const injectProps = (b: RootBinding<ClientContext>): SidebarRootInjected => {
+      const { sessions: boundSessions, layout } = b.ctx
+      return {
+        useTree: tree.store.useSelector,
+        useCurrent: () => layout.current.useSelector(s => s.sessionId),
+        actions: {
+          open: (id) => { layout.open(id) },
+          create: (cwd) => {
+            // Create-then-open: the sidebar's three creation entries all land
+            // in the new session (empty-state first-send stays with ui-conversation).
+            void boundSessions.create(cwd === undefined ? {} : { cwd })
+              .then((id: SessionId) => { layout.open(id) })
+          },
+          toggleSidebar: () => { layout.toggleSidebar() },
+        },
+        tree: {
+          toggleProject: (key) => { tree.toggleProject(key) },
+          toggleSession: (id) => { tree.toggleSession(id) },
+          setQuery: (query) => { tree.setQuery(query) },
+        },
+      }
+    }
+    const disposeRegistration = ctx.slots.register('sidebar', SidebarRoot, { inject: injectProps })
+    return () => {
+      disposeRegistration()
+      tree.dispose()
+    }
+  }, 'ui-sidebar: tree store + slot registration')
+}

packages/client/ui-sidebar/src/client/store.ts

@@ -0,0 +1,94 @@
+/**
+ * Sidebar tree store: plugin-owned snapshot store materializing the derived
+ * row list. Subscribes to sessions.list and re-derives on list changes and
+ * on viewing-state actions (expansion, search, group-by) — components
+ * subscribe to `rows` and never derive in render. Contract: api-contracts
+ * v3 section 6.
+ */
+import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { deriveRows, type SidebarRow } from './tree.ts'
+
+/** Grouping strategy. Only by-workspace is designed (figma); the menu shows the rest disabled. */
+export type GroupBy = 'workspace'
+
+/** Sidebar tree state: materialized rows plus the viewing state that shaped them. */
+export interface SidebarTreeState {
+  rows: SidebarRow[]
+  /** Expanded project group keys (cwd or the ungrouped key). */
+  expandedProjects: string[]
+  /** Expanded session ids (subtree unfold). */
+  expandedSessions: string[]
+  query: string
+  groupBy: GroupBy
+}
+
+/** Store handle: snapshot store plus mutation actions and the list unsubscribe. */
+export interface SidebarTreeStore {
+  readonly store: SnapshotStore<SidebarTreeState>
+  toggleProject(key: string): void
+  toggleSession(id: SessionId): void
+  setQuery(query: string): void
+  setGroupBy(groupBy: GroupBy): void
+  dispose(): void
+}
+
+/**
+ * Create the sidebar tree store bound to a sessions service.
+ * @param sessions - root sessions service (only the list store is consumed).
+ * @returns store handle; call dispose on plugin teardown.
+ */
+export function createSidebarTreeStore(sessions: Pick<SessionsService, 'list'>): SidebarTreeStore {
+  const store = createSnapshotStore<SidebarTreeState>({
+    rows: [],
+    expandedProjects: [],
+    expandedSessions: [],
+    query: '',
+    groupBy: 'workspace',
+  })
+
+  const rederive = (draft: SidebarTreeState): void => {
+    draft.rows = deriveRows(sessions.list.getSnapshot(), {
+      expandedProjects: new Set(draft.expandedProjects),
+      expandedSessions: new Set(draft.expandedSessions),
+      query: draft.query,
+    })
+  }
+  store.update(rederive)
+  const unsubscribe = sessions.list.subscribe(() => { store.update(rederive) })
+
+  const toggle = (list: string[], key: string): void => {
+    const at = list.indexOf(key)
+    if (at >= 0) list.splice(at, 1)
+    else list.push(key)
+  }
+
+  return {
+    store,
+    toggleProject(key) {
+      store.update((draft) => {
+        toggle(draft.expandedProjects, key)
+        rederive(draft)
+      })
+    },
+    toggleSession(id) {
+      store.update((draft) => {
+        toggle(draft.expandedSessions, id)
+        rederive(draft)
+      })
+    },
+    setQuery(query) {
+      store.update((draft) => {
+        draft.query = query
+        rederive(draft)
+      })
+    },
+    setGroupBy(groupBy) {
+      store.update((draft) => {
+        draft.groupBy = groupBy
+        rederive(draft)
+      })
+    },
+    dispose: unsubscribe,
+  }
+}

packages/client/ui-sidebar/src/client/tree.ts

@@ -0,0 +1,265 @@
+/**
+ * Pure sidebar tree derivation: session list snapshot -> flat render rows.
+ * Groups sessions by project directory (cwd), builds the per-group session
+ * tree from parentId links, sorts by recency, and applies search filtering
+ * with forced ancestor visibility. Components subscribe to the materialized
+ * rows and never derive in render. Contract: api-contracts v3 section 6.
+ */
+import type { SessionId, SessionListState, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** Group key for sessions without a project directory. */
+export const UNGROUPED_KEY = ''
+
+/** Display label for the ungrouped project row. */
+export const UNGROUPED_LABEL = 'Ungrouped'
+
+/** Project (workspace) row: 54px, two lines (label + session count). */
+export interface ProjectRow {
+  type: 'project'
+  /** Group key: the cwd, or {@link UNGROUPED_KEY}. */
+  key: string
+  cwd: string | undefined
+  label: string
+  /** Total sessions in the group, including hidden ones. */
+  sessionCount: number
+  expanded: boolean
+}
+
+/** Session row: 34px single line; depth drives the 22px indent steps. */
+export interface SessionRow {
+  type: 'session'
+  id: SessionId
+  /** Owning project group key (selection -> active-folder lookup). */
+  groupKey: string
+  title: string
+  /** 0 = directly under the project row. */
+  depth: number
+  hasChildren: boolean
+  expanded: boolean
+  running: boolean
+  updatedAt: number
+}
+
+/** One flat sidebar list row. */
+export type SidebarRow = ProjectRow | SessionRow
+
+/** Viewing state consumed by the derivation. */
+export interface TreeView {
+  expandedProjects: ReadonlySet<string>
+  expandedSessions: ReadonlySet<string>
+  query: string
+}
+
+interface Group {
+  key: string
+  cwd: string | undefined
+  label: string
+  summaries: Map<SessionId, SessionSummary>
+  roots: SessionId[]
+  children: Map<SessionId, SessionId[]>
+  latest: number
+}
+
+/**
+ * Project display label: basename of the group directory.
+ * @param cwd - project directory, or undefined for the ungrouped bucket.
+ * @returns basename, the raw cwd when it has no basename, or the ungrouped label.
+ */
+export function projectLabel(cwd: string | undefined): string {
+  if (cwd === undefined || cwd === '') return UNGROUPED_LABEL
+  const base = cwd.replace(/[/\\]+$/, '').split(/[/\\]/).pop()
+  return base !== undefined && base !== '' ? base : cwd
+}
+
+/** Recency comparator: newest first, id as the deterministic tiebreak (ids are unique per group). */
+function byRecency(a: SessionSummary, b: SessionSummary): number {
+  if (b.updatedAt !== a.updatedAt) return b.updatedAt - a.updatedAt
+  return a.id < b.id ? -1 : 1
+}
+
+function groupByCwd(list: SessionListState): Group[] {
+  const byKey = new Map<string, SessionSummary[]>()
+  for (const id of list.ids) {
+    const s = list.byId[id]
+    if (s === undefined) continue
+    const key = s.cwd ?? UNGROUPED_KEY
+    const members = byKey.get(key)
+    if (members === undefined) byKey.set(key, [s])
+    else members.push(s)
+  }
+  const groups: Group[] = []
+  for (const [key, members] of byKey) {
+    const summaries = new Map(members.map(m => [m.id, m]))
+    const children = new Map<SessionId, SessionId[]>()
+    const roots: SessionSummary[] = []
+    for (const m of members) {
+      // A session is a tree child only when its parent lives in the same
+      // group; cross-group or unknown parents degrade to group roots.
+      if (m.parentId !== undefined && m.parentId !== m.id && summaries.has(m.parentId)) {
+        const kids = children.get(m.parentId)
+        if (kids === undefined) children.set(m.parentId, [m.id])
+        else kids.push(m.id)
+      } else {
+        roots.push(m)
+      }
+    }
+    roots.sort(byRecency)
+    for (const kids of children.values()) {
+      kids.sort((a, b) => {
+        const sa = summaries.get(a)
+        const sb = summaries.get(b)
+        /* v8 ignore next -- unreachable: kid ids are inserted alongside their summaries. */
+        if (sa === undefined || sb === undefined) return 0
+        return byRecency(sa, sb)
+      })
+    }
+    const rootIds = roots.map(r => r.id)
+    // parentId cycles (host bug) leave members unreachable from any root;
+    // surface them as extra roots — the flatten walk's visited set stops
+    // loops. Each node sits in at most one kids list and roots have no
+    // in-group parent, so the scan pushes every reachable node exactly once.
+    const reachable = new Set<SessionId>(rootIds)
+    const stack = [...rootIds]
+    while (stack.length > 0) {
+      const top = stack.pop()
+      /* v8 ignore next -- unreachable: the loop condition guarantees a non-empty stack. */
+      if (top === undefined) break
+      for (const kid of children.get(top) ?? []) {
+        reachable.add(kid)
+        stack.push(kid)
+      }
+    }
+    for (const m of [...members].sort(byRecency)) {
+      if (!reachable.has(m.id)) rootIds.push(m.id)
+    }
+    let latest = 0
+    for (const m of members) latest = Math.max(latest, m.updatedAt)
+    groups.push({
+      key,
+      cwd: key === UNGROUPED_KEY ? undefined : key,
+      label: projectLabel(key === UNGROUPED_KEY ? undefined : key),
+      summaries,
+      roots: rootIds,
+      children,
+      latest,
+    })
+  }
+  groups.sort((a, b) => b.latest - a.latest || (a.label < b.label ? -1 : a.label > b.label ? 1 : 0))
+  return groups
+}
+
+function sessionRow(g: Group, s: SessionSummary, depth: number, hasChildren: boolean, expanded: boolean): SessionRow {
+  return {
+    type: 'session',
+    id: s.id,
+    groupKey: g.key,
+    title: s.title,
+    depth,
+    hasChildren,
+    expanded,
+    running: s.running,
+    updatedAt: s.updatedAt,
+  }
+}
+
+function flattenVisible(g: Group, expandedSessions: ReadonlySet<string>, rows: SidebarRow[]): void {
+  const visited = new Set<SessionId>()
+  const walk = (id: SessionId, depth: number): void => {
+    if (visited.has(id)) return
+    visited.add(id)
+    const s = g.summaries.get(id)
+    /* v8 ignore next -- unreachable: walked ids come from the grouped summaries. */
+    if (s === undefined) return
+    const kids = g.children.get(id) ?? []
+    const expanded = expandedSessions.has(id)
+    rows.push(sessionRow(g, s, depth, kids.length > 0, expanded))
+    if (expanded) for (const kid of kids) walk(kid, depth + 1)
+  }
+  for (const root of g.roots) walk(root, 0)
+}
+
+/** Matched sessions plus their ancestor chains (forced visible under search). */
+function searchVisible(g: Group, q: string): Set<SessionId> {
+  const visible = new Set<SessionId>()
+  for (const m of g.summaries.values()) {
+    if (!m.title.toLowerCase().includes(q)) continue
+    let cur: SessionSummary | undefined = m
+    while (cur !== undefined && !visible.has(cur.id)) {
+      visible.add(cur.id)
+      cur = cur.parentId !== undefined && cur.parentId !== cur.id ? g.summaries.get(cur.parentId) : undefined
+    }
+  }
+  return visible
+}
+
+function flattenSearch(g: Group, visible: ReadonlySet<SessionId>, rows: SidebarRow[]): void {
+  const visited = new Set<SessionId>()
+  const walk = (id: SessionId, depth: number): void => {
+    if (visited.has(id) || !visible.has(id)) return
+    visited.add(id)
+    const s = g.summaries.get(id)
+    /* v8 ignore next -- unreachable: walked ids come from the grouped summaries. */
+    if (s === undefined) return
+    const kids = (g.children.get(id) ?? []).filter(kid => visible.has(kid))
+    rows.push(sessionRow(g, s, depth, kids.length > 0, kids.length > 0))
+    for (const kid of kids) walk(kid, depth + 1)
+  }
+  for (const root of g.roots) walk(root, 0)
+}
+
+/**
+ * Derive the flat sidebar row list.
+ *
+ * Normal mode: every project row shows; sessions show under expanded
+ * projects, descending only into expanded sessions. Search mode (non-blank
+ * query, case-insensitive title substring): expansion state is ignored —
+ * matched sessions and their ancestor chains are forced visible, groups
+ * without a title or label hit are dropped, and a label-only hit keeps the
+ * bare project row.
+ * @param list - sessions list snapshot.
+ * @param view - expansion sets and search query.
+ * @returns rows in render order.
+ */
+export function deriveRows(list: SessionListState, view: TreeView): SidebarRow[] {
+  const q = view.query.trim().toLowerCase()
+  const rows: SidebarRow[] = []
+  for (const g of groupByCwd(list)) {
+    if (q === '') {
+      const expanded = view.expandedProjects.has(g.key)
+      rows.push({ type: 'project', key: g.key, cwd: g.cwd, label: g.label, sessionCount: g.summaries.size, expanded })
+      if (expanded) flattenVisible(g, view.expandedSessions, rows)
+    } else {
+      const visible = searchVisible(g, q)
+      if (visible.size === 0 && !g.label.toLowerCase().includes(q)) continue
+      rows.push({
+        type: 'project',
+        key: g.key,
+        cwd: g.cwd,
+        label: g.label,
+        sessionCount: g.summaries.size,
+        expanded: visible.size > 0,
+      })
+      flattenSearch(g, visible, rows)
+    }
+  }
+  return rows
+}
+
+/**
+ * Relative time label for session rows (figma samples: now / 2min / 1h / 2d / 18d / 2mo).
+ * @param updatedAt - epoch ms of the last update.
+ * @param now - current epoch ms.
+ * @returns compact age label.
+ */
+export function formatRelativeTime(updatedAt: number, now: number): string {
+  const MIN = 60_000
+  const HOUR = 3_600_000
+  const DAY = 86_400_000
+  const diff = Math.max(0, now - updatedAt)
+  if (diff < MIN) return 'now'
+  if (diff < HOUR) return `${Math.floor(diff / MIN)}min`
+  if (diff < DAY) return `${Math.floor(diff / HOUR)}h`
+  if (diff < 30 * DAY) return `${Math.floor(diff / DAY)}d`
+  if (diff < 365 * DAY) return `${Math.floor(diff / (30 * DAY))}mo`
+  return `${Math.floor(diff / (365 * DAY))}y`
+}

packages/client/ui-sidebar/src/css-modules.d.ts

@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'

packages/client/ui-sidebar/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Sidebar plugin, node half. Pure UI plugin: the empty apply exists so the
+ * plugin appears in the host cordis.yml / Loader (load and lifecycle follow
+ * the host; the browser half ships via exports["./client"], discovered
+ * through the package.json dshClient declaration). Contract: api-contracts
+ * v3 sections 0.3 and 6.
+ */
+
+/** Host plugin body — no host-side behavior for the sidebar plugin. */
+export function apply(): void {}

packages/client/ui-sidebar/src/invariant.ts

@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-sidebar`.
+ * @module @deepseek-ai/dsh-client-ui-sidebar/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-sidebar'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-sidebar-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a pure-consumer plugin deriving its tree store from
+ * sessions.list — it emits no cordis events and owns no cross-plugin mutable
+ * state; derivation and interaction behavior are asserted directly by this
+ * package's tree/store/component specs.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * 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/ui-sidebar/tests/apply.spec.tsx

@@ -0,0 +1,158 @@
+// @vitest-environment jsdom
+/**
+ * apply wiring on a real cordis Context + SlotsService: tree store built and
+ * subscribed, SidebarRoot registered into the layout-owned sidebar slot with
+ * the inject surface bound off the root binding ctx, effect teardown
+ * unregisters and drops the list subscription. Behavior-level assertions
+ * only — the inject factory's cast shape is due to change with the slot
+ * type-chain redesign.
+ */
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { act } from 'react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import { scopedSlots, RootBindingProvider } from '@deepseek-ai/dsh-client-web-react'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { apply, inject } from '@deepseek-ai/dsh-client-ui-sidebar/client'
+// Type-only: ui-layout's SlotMap merge so the sidebar slot key typechecks.
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+
+const sid = (s: string) => s as SessionId
+
+afterEach(cleanup)
+
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  const list = createSnapshotStore<SessionListState>({
+    ids: [sid('a')],
+    byId: { [sid('a')]: { id: sid('a'), title: 'alpha', cwd: '/proj', running: false, updatedAt: 1 } },
+  })
+  const sessions = { list, create: vi.fn(async () => sid('minted')) }
+  const layout = {
+    current: createSnapshotStore<{ sessionId?: SessionId }>({}),
+    open: vi.fn(),
+    toggleSidebar: vi.fn(),
+  }
+  ctx.provide('sessions', sessions)
+  ctx.provide('layout', layout)
+  const slots = ctx.get('slots') as SlotsService
+  slots.define('sidebar', { kind: 'single', scope: 'root' })
+  return { ctx, slots, sessions, layout }
+}
+
+function mountSlot(ctx: Context, slots: SlotsService) {
+  const surface = scopedSlots(slots.core, 'sidebar')
+  return render(
+    <RootBindingProvider value={{ ctx }}>
+      {surface.renderSlot('sidebar', {})}
+    </RootBindingProvider>,
+  )
+}
+
+describe('apply', () => {
+  it('declares the services it binds', () => {
+    expect(inject).toEqual(['slots', 'layout', 'sessions'])
+  })
+
+  it('fails loud when mounted without the inject declaration', async () => {
+    // ctx.sessions rides the cordis property proxy: reading it from a plugin
+    // that never declared the dependency throws instead of yielding undefined.
+    // Await the fiber thenable itself, not a second .await() chain: the test
+    // invariant host wraps plugin() with an eager readiness promise, and only
+    // the thenable settles it (a parallel .await() leaves it unhandled).
+    const ctx = new Context()
+    await ctx.plugin(SlotsService).await()
+    await expect(ctx.plugin({ apply })).rejects.toThrow(/without inject/)
+  })
+
+  it('registers SidebarRoot which renders from the live list', async () => {
+    const { ctx, slots } = await bench()
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    mountSlot(ctx, slots)
+    expect(screen.getByText('proj')).toBeTruthy()
+    expect(screen.getByText('1 session')).toBeTruthy()
+  })
+
+  it('binds actions to layout/sessions off the root binding', async () => {
+    const { ctx, slots, sessions, layout } = await bench()
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    mountSlot(ctx, slots)
+
+    act(() => { fireEvent.click(screen.getByLabelText('Collapse sidebar')) })
+    expect(layout.toggleSidebar).toHaveBeenCalledOnce()
+
+    act(() => { fireEvent.click(screen.getByText('proj')) })
+    act(() => { fireEvent.click(screen.getByText('alpha')) })
+    expect(layout.open).toHaveBeenCalledWith('a')
+
+    act(() => { fireEvent.click(screen.getByText('New Session')) })
+    expect(sessions.create).toHaveBeenCalledWith({})
+    // create-then-open lands after the create promise resolves.
+    await act(async () => { await Promise.resolve() })
+    expect(layout.open).toHaveBeenCalledWith('minted')
+
+    act(() => { fireEvent.click(screen.getAllByLabelText('New session here')[0]!) })
+    expect(sessions.create).toHaveBeenCalledWith({ cwd: '/proj' })
+  })
+
+  it('throws from the inject factory when binding ctx lacks the services', async () => {
+    const { ctx, slots } = await bench()
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    const bare = new Context()
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    try {
+      const surface = scopedSlots(slots.core, 'sidebar')
+      render(
+        <RootBindingProvider value={{ ctx: bare }}>
+          {surface.renderSlot('sidebar', {})}
+        </RootBindingProvider>,
+      )
+      // The slot error boundary absorbs the throw and logs it.
+      expect(document.querySelector('[data-slot-error="sidebar"]')).toBeTruthy()
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
+  it('search input drives the plugin-owned tree store', async () => {
+    const { ctx, slots } = await bench()
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    mountSlot(ctx, slots)
+    act(() => {
+      fireEvent.change(screen.getByPlaceholderText('Search name, keywords...'), { target: { value: 'zzz' } })
+    })
+    expect(screen.getByText('No matches')).toBeTruthy()
+  })
+
+  it('expansion toggles route through the injected tree actions', async () => {
+    const { ctx, slots, sessions } = await bench()
+    sessions.list.update((draft) => {
+      draft.ids.push(sid('kid'))
+      draft.byId[sid('kid')] = {
+        id: sid('kid'), title: 'child', cwd: '/proj', parentId: sid('a'), running: false, updatedAt: 2,
+      }
+    })
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    mountSlot(ctx, slots)
+    act(() => { fireEvent.click(screen.getByText('proj')) })
+    expect(screen.getByText('alpha')).toBeTruthy()
+    act(() => { fireEvent.click(screen.getByLabelText('Expand')) })
+    expect(screen.getByText('child')).toBeTruthy()
+  })
+
+  it('teardown unregisters the slot and drops the list subscription', async () => {
+    const { ctx, slots, sessions } = await bench()
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(slots.entries('sidebar')).toHaveLength(1)
+    await fiber.dispose()
+    expect(slots.entries('sidebar')).toHaveLength(0)
+    // A post-teardown list change must not reach a disposed store.
+    expect(() => {
+      sessions.list.update((draft) => { draft.ids = [] })
+    }).not.toThrow()
+  })
+})

packages/client/ui-sidebar/tests/invariant.spec.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import * as SidebarInvariant from '@deepseek-ai/dsh-client-ui-sidebar/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(SidebarInvariant).await()).resolves.toBeDefined()
+  })
+
+  it('node-half apply is a no-op host placeholder', async () => {
+    const { apply } = await import('@deepseek-ai/dsh-client-ui-sidebar')
+    apply()
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+})

packages/client/ui-sidebar/tests/sidebar-root.spec.tsx

@@ -0,0 +1,195 @@
+// @vitest-environment jsdom
+/**
+ * SidebarRoot interaction spec on the real framework stack: real tree store
+ * (web-react SnapshotStore) feeding the component through the same selector
+ * hook the inject surface hands out. Covers expand/collapse, subtree unfold,
+ * search filtering, row activation, and the creation entries.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { act } from 'react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId, SessionListState, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  createSidebarTreeStore, SidebarRoot,
+  type SidebarActions, type SidebarTreeStore,
+} from '@deepseek-ai/dsh-client-ui-sidebar/client'
+
+const sid = (s: string) => s as SessionId
+
+/** Bare-string init; brands ids and omits absent optional keys (exactOptionalPropertyTypes). */
+interface SummaryInit {
+  id: string
+  title?: string
+  cwd?: string
+  parentId?: string
+  running?: boolean
+  updatedAt?: number
+}
+
+function summary(init: SummaryInit): SessionSummary {
+  const s: SessionSummary = {
+    id: sid(init.id),
+    title: init.title ?? init.id,
+    running: init.running ?? false,
+    updatedAt: init.updatedAt ?? 0,
+  }
+  if (init.cwd !== undefined) s.cwd = init.cwd
+  if (init.parentId !== undefined) s.parentId = sid(init.parentId)
+  return s
+}
+
+function listStateOf(...summaries: SessionSummary[]): SessionListState {
+  const byId: Record<SessionId, SessionSummary> = {}
+  for (const s of summaries) byId[s.id] = s
+  return { ids: summaries.map((s) => s.id), byId }
+}
+
+afterEach(cleanup)
+
+function mount(...summaries: SessionSummary[]) {
+  const list = createSnapshotStore<SessionListState>(listStateOf(...summaries))
+  const tree: SidebarTreeStore = createSidebarTreeStore({ list })
+  const current = createSnapshotStore<{ id: SessionId | undefined }>({ id: undefined })
+  const actions: SidebarActions = {
+    open: vi.fn((id: SessionId) => { current.update((d) => { d.id = id }) }),
+    create: vi.fn(),
+    toggleSidebar: vi.fn(),
+  }
+  const utils = render(
+    <SidebarRoot
+      useTree={tree.store.useSelector}
+      useCurrent={() => current.useSelector((s) => s.id)}
+      actions={actions}
+      tree={tree}
+    />,
+  )
+  return { list, tree, current, actions, ...utils }
+}
+
+const projectData = () => [
+  summary({ id: 'root', title: 'root work', cwd: '/proj', updatedAt: 5 }),
+  summary({ id: 'kid', title: 'forked child', cwd: '/proj', parentId: sid('root'), updatedAt: 4 }),
+  summary({ id: 'lone', title: 'elsewhere', cwd: '/other', updatedAt: 3 }),
+]
+
+describe('SidebarRoot', () => {
+  it('renders chrome and collapsed project rows', () => {
+    mount(...projectData())
+    expect(screen.getByText('HARNESS')).toBeTruthy()
+    expect(screen.getByText('New Session')).toBeTruthy()
+    expect(screen.getByText('proj')).toBeTruthy()
+    expect(screen.getByText('2 sessions')).toBeTruthy()
+    expect(screen.getByText('1 session')).toBeTruthy()
+    expect(screen.queryByText('root work')).toBeNull()
+  })
+
+  it('expands a project on click and unfolds a subtree via the twist', () => {
+    mount(...projectData())
+    act(() => { fireEvent.click(screen.getByText('proj')) })
+    expect(screen.getByText('root work')).toBeTruthy()
+    expect(screen.queryByText('forked child')).toBeNull()
+    act(() => { fireEvent.click(screen.getByLabelText('Expand')) })
+    expect(screen.getByText('forked child')).toBeTruthy()
+    act(() => { fireEvent.click(screen.getByLabelText('Collapse')) })
+    expect(screen.queryByText('forked child')).toBeNull()
+  })
+
+  it('opens a session on row click and marks it selected', () => {
+    const { actions } = mount(...projectData())
+    act(() => { fireEvent.click(screen.getByText('proj')) })
+    act(() => { fireEvent.click(screen.getByText('root work')) })
+    expect(actions.open).toHaveBeenCalledWith('root')
+    expect(screen.getByText('root work').closest('[role="treeitem"]')!.getAttribute('aria-selected')).toBe('true')
+  })
+
+  it('search filters across groups and forces ancestor chains visible', () => {
+    mount(...projectData())
+    const input = screen.getByPlaceholderText('Search name, keywords...')
+    act(() => { fireEvent.change(input, { target: { value: 'forked' } }) })
+    expect(screen.getByText('forked child')).toBeTruthy()
+    expect(screen.getByText('root work')).toBeTruthy()
+    expect(screen.queryByText('elsewhere')).toBeNull()
+    expect(screen.queryByText(/^other$/)).toBeNull()
+    act(() => { fireEvent.click(screen.getByLabelText('Clear search')) })
+    expect(screen.queryByText('root work')).toBeNull()
+    expect(screen.getByText('proj')).toBeTruthy()
+  })
+
+  it('shows the blank-list empty state without a query', () => {
+    mount()
+    expect(screen.getByText('No sessions yet')).toBeTruthy()
+  })
+
+  it('shows the no-match empty state', () => {
+    mount(...projectData())
+    const input = screen.getByPlaceholderText('Search name, keywords...')
+    act(() => { fireEvent.change(input, { target: { value: 'zzz-none' } }) })
+    expect(screen.getByText('No matches')).toBeTruthy()
+  })
+
+  it('routes the three creation entries with the right cwd', () => {
+    const { actions } = mount(...projectData())
+    act(() => { fireEvent.click(screen.getByText('New Session')) })
+    expect(actions.create).toHaveBeenLastCalledWith()
+    act(() => { fireEvent.click(screen.getByLabelText('New workspace')) })
+    expect(actions.create).toHaveBeenLastCalledWith()
+    // Per-project "+" is hover-revealed by CSS; still clickable in jsdom.
+    act(() => { fireEvent.click(screen.getAllByLabelText('New session here')[0]!) })
+    expect(actions.create).toHaveBeenLastCalledWith('/proj')
+  })
+
+  it('collapse button and group-by menu behave', () => {
+    const { actions } = mount(...projectData())
+    act(() => { fireEvent.click(screen.getByLabelText('Collapse sidebar')) })
+    expect(actions.toggleSidebar).toHaveBeenCalledOnce()
+    expect(screen.queryByText('Update')).toBeNull()
+    act(() => { fireEvent.click(screen.getByLabelText('Group by')) })
+    expect(screen.getByText('Update')).toBeTruthy()
+    expect(screen.getByText('Status')).toBeTruthy()
+    // Selecting the active strategy closes the list (only workspace is enabled).
+    act(() => { fireEvent.click(screen.getByText('WorkSpace', { selector: 'button *' })) })
+    expect(screen.queryByText('Update')).toBeNull()
+    // Reopen and dismiss via Escape (Menu onClose channel).
+    act(() => { fireEvent.click(screen.getByLabelText('Group by')) })
+    act(() => { fireEvent.keyDown(document, { key: 'Escape' }) })
+    expect(screen.queryByText('Update')).toBeNull()
+  })
+
+  it('re-renders when the sessions list gains a session', async () => {
+    const { list } = mount(...projectData())
+    act(() => {
+      list.update((draft) => {
+        draft.ids.push(sid('fresh'))
+        draft.byId[sid('fresh')] = summary({ id: 'fresh', title: 'brand new', cwd: '/fresh', updatedAt: 99 })
+      })
+    })
+    // Store notifications are microtask-batched.
+    await act(async () => { await Promise.resolve() })
+    expect(screen.getByText('fresh')).toBeTruthy()
+  })
+
+  it('row "More" anchors swallow the click without opening or toggling', () => {
+    const { actions, tree } = mount(...projectData())
+    act(() => { fireEvent.click(screen.getByText('proj')) })
+    const before = tree.store.getSnapshot().expandedProjects.length
+    // Project-row anchor: must not collapse the project.
+    act(() => { fireEvent.click(screen.getAllByLabelText('More')[0]!) })
+    expect(tree.store.getSnapshot().expandedProjects).toHaveLength(before)
+    // Session-row anchor: must not open the session.
+    act(() => { fireEvent.click(screen.getAllByLabelText('More')[1]!) })
+    expect(actions.open).not.toHaveBeenCalled()
+  })
+
+  it('shows the running state dot only for running sessions', () => {
+    mount(
+      summary({ id: 'busy', title: 'busy one', cwd: '/p', running: true, updatedAt: 2 }),
+      summary({ id: 'idle', title: 'idle one', cwd: '/p', updatedAt: 1 }),
+    )
+    act(() => { fireEvent.click(screen.getByText('p')) })
+    const busyRow = screen.getByText('busy one').closest('[role="treeitem"]')!
+    const idleRow = screen.getByText('idle one').closest('[role="treeitem"]')!
+    expect(busyRow.querySelector('[data-state="ongoing"]')).toBeTruthy()
+    expect(idleRow.querySelector('[data-state="ongoing"]')).toBeNull()
+  })
+})

packages/client/ui-sidebar/tests/store.spec.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId, SessionListState, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSidebarTreeStore } from '@deepseek-ai/dsh-client-ui-sidebar/client'
+
+const sid = (s: string) => s as SessionId
+
+/** Bare-string init; brands ids and omits absent optional keys (exactOptionalPropertyTypes). */
+interface SummaryInit {
+  id: string
+  title?: string
+  cwd?: string
+  parentId?: string
+  running?: boolean
+  updatedAt?: number
+}
+
+function summary(init: SummaryInit): SessionSummary {
+  const s: SessionSummary = {
+    id: sid(init.id),
+    title: init.title ?? init.id,
+    running: init.running ?? false,
+    updatedAt: init.updatedAt ?? 0,
+  }
+  if (init.cwd !== undefined) s.cwd = init.cwd
+  if (init.parentId !== undefined) s.parentId = sid(init.parentId)
+  return s
+}
+
+function listStateOf(...summaries: SessionSummary[]): SessionListState {
+  const byId: Record<SessionId, SessionSummary> = {}
+  for (const s of summaries) byId[s.id] = s
+  return { ids: summaries.map(s => s.id), byId }
+}
+
+function setup(...summaries: SessionSummary[]) {
+  const list = createSnapshotStore<SessionListState>(listStateOf(...summaries))
+  const tree = createSidebarTreeStore({ list })
+  return { list, tree }
+}
+
+const flushMicrotasks = () => new Promise<void>((resolve) => { queueMicrotask(resolve) })
+
+describe('createSidebarTreeStore', () => {
+  it('materializes rows from the initial list snapshot', () => {
+    const { tree } = setup(summary({ id: 'a', cwd: '/p' }))
+    expect(tree.store.getSnapshot().rows).toEqual([
+      expect.objectContaining({ type: 'project', key: '/p', sessionCount: 1 }),
+    ])
+  })
+
+  it('re-derives when the sessions list changes', async () => {
+    const { list, tree } = setup(summary({ id: 'a', cwd: '/p' }))
+    list.update((draft) => {
+      draft.ids.push(sid('b'))
+      draft.byId[sid('b')] = summary({ id: 'b', cwd: '/q', updatedAt: 99 })
+    })
+    // Snapshot-store notifications are microtask-batched.
+    await flushMicrotasks()
+    expect(tree.store.getSnapshot().rows.map(r => r.type === 'project' && r.key)).toEqual(['/q', '/p'])
+  })
+
+  it('toggleProject expands and collapses synchronously', () => {
+    const { tree } = setup(summary({ id: 'a', cwd: '/p' }))
+    tree.toggleProject('/p')
+    expect(tree.store.getSnapshot().rows).toHaveLength(2)
+    tree.toggleProject('/p')
+    expect(tree.store.getSnapshot().rows).toHaveLength(1)
+  })
+
+  it('toggleSession unfolds a subtree', () => {
+    const { tree } = setup(
+      summary({ id: 'root', cwd: '/p', updatedAt: 2 }),
+      summary({ id: 'kid', cwd: '/p', parentId: sid('root'), updatedAt: 1 }),
+    )
+    tree.toggleProject('/p')
+    expect(tree.store.getSnapshot().rows).toHaveLength(2)
+    tree.toggleSession(sid('root'))
+    expect(tree.store.getSnapshot().rows).toHaveLength(3)
+  })
+
+  it('setQuery switches into search mode and back', () => {
+    const { tree } = setup(
+      summary({ id: 'a', title: 'needle', cwd: '/p' }),
+      summary({ id: 'b', title: 'other', cwd: '/q' }),
+    )
+    tree.setQuery('needle')
+    const rows = tree.store.getSnapshot().rows
+    expect(rows.map(r => r.type)).toEqual(['project', 'session'])
+    tree.setQuery('')
+    expect(tree.store.getSnapshot().rows.every(r => r.type === 'project')).toBe(true)
+  })
+
+  it('setGroupBy records the strategy and re-derives', () => {
+    const { tree } = setup(summary({ id: 'a', cwd: '/p' }))
+    tree.setGroupBy('workspace')
+    expect(tree.store.getSnapshot().groupBy).toBe('workspace')
+    expect(tree.store.getSnapshot().rows).toHaveLength(1)
+  })
+
+  it('dispose stops re-derivation on list changes', async () => {
+    const { list, tree } = setup(summary({ id: 'a', cwd: '/p' }))
+    tree.dispose()
+    list.update((draft) => {
+      draft.ids.push(sid('b'))
+      draft.byId[sid('b')] = summary({ id: 'b', cwd: '/q' })
+    })
+    await flushMicrotasks()
+    expect(tree.store.getSnapshot().rows).toHaveLength(1)
+  })
+})

packages/client/ui-sidebar/tests/tree.spec.ts

@@ -0,0 +1,234 @@
+import { describe, expect, it } from 'vitest'
+import type { SessionId, SessionListState, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  deriveRows, formatRelativeTime, projectLabel, UNGROUPED_KEY, UNGROUPED_LABEL,
+  type SessionRow, type TreeView,
+} from '@deepseek-ai/dsh-client-ui-sidebar/client'
+
+const sid = (s: string) => s as SessionId
+
+/** Bare-string init; brands ids and omits absent optional keys (exactOptionalPropertyTypes). */
+interface SummaryInit {
+  id: string
+  title?: string
+  cwd?: string
+  parentId?: string
+  running?: boolean
+  updatedAt?: number
+}
+
+function summary(init: SummaryInit): SessionSummary {
+  const s: SessionSummary = {
+    id: sid(init.id),
+    title: init.title ?? init.id,
+    running: init.running ?? false,
+    updatedAt: init.updatedAt ?? 0,
+  }
+  if (init.cwd !== undefined) s.cwd = init.cwd
+  if (init.parentId !== undefined) s.parentId = sid(init.parentId)
+  return s
+}
+
+function listOf(...summaries: SessionSummary[]): SessionListState {
+  const byId: Record<SessionId, SessionSummary> = {}
+  for (const s of summaries) byId[s.id] = s
+  return { ids: summaries.map(s => s.id), byId }
+}
+
+const view = (partial: Partial<TreeView> = {}): TreeView => ({
+  expandedProjects: partial.expandedProjects ?? new Set(),
+  expandedSessions: partial.expandedSessions ?? new Set(),
+  query: partial.query ?? '',
+})
+
+describe('projectLabel', () => {
+  it('takes the basename and survives trailing separators', () => {
+    expect(projectLabel('/home/me/proj')).toBe('proj')
+    expect(projectLabel('/home/me/proj/')).toBe('proj')
+    expect(projectLabel('C:\\work\\thing')).toBe('thing')
+  })
+
+  it('falls back for empty and root-only paths', () => {
+    expect(projectLabel(undefined)).toBe(UNGROUPED_LABEL)
+    expect(projectLabel('')).toBe(UNGROUPED_LABEL)
+    expect(projectLabel('///')).toBe('///')
+  })
+})
+
+describe('deriveRows grouping', () => {
+  it('groups by cwd into project rows with counts, newest group first', () => {
+    const rows = deriveRows(listOf(
+      summary({ id: 'a', cwd: '/x/alpha', updatedAt: 10 }),
+      summary({ id: 'b', cwd: '/x/beta', updatedAt: 30 }),
+      summary({ id: 'c', cwd: '/x/alpha', updatedAt: 20 }),
+    ), view())
+    expect(rows).toEqual([
+      expect.objectContaining({ type: 'project', key: '/x/beta', label: 'beta', sessionCount: 1, expanded: false }),
+      expect.objectContaining({ type: 'project', key: '/x/alpha', label: 'alpha', sessionCount: 2 }),
+    ])
+  })
+
+  it('orders equally-recent groups by label and skips ids missing from byId', () => {
+    const list = listOf(
+      summary({ id: 'b1', cwd: '/x/beta', updatedAt: 5 }),
+      summary({ id: 'a1', cwd: '/x/alpha', updatedAt: 5 }),
+      // Same basename and same recency as beta: label comparator returns 0,
+      // insertion order breaks the tie.
+      summary({ id: 'b2', cwd: '/y/beta', updatedAt: 5 }),
+    )
+    list.ids.push(sid('ghost'))
+    const rows = deriveRows(list, view())
+    expect(rows.map(r => r.type === 'project' && r.key)).toEqual(['/x/alpha', '/x/beta', '/y/beta'])
+  })
+
+  it('buckets cwd-less sessions under the ungrouped project row', () => {
+    const rows = deriveRows(listOf(summary({ id: 'a' })), view())
+    expect(rows).toEqual([
+      expect.objectContaining({ type: 'project', key: UNGROUPED_KEY, cwd: undefined, label: UNGROUPED_LABEL }),
+    ])
+  })
+
+  it('hides sessions under collapsed projects and shows them when expanded', () => {
+    const list = listOf(
+      summary({ id: 'a', cwd: '/p', updatedAt: 1 }),
+      summary({ id: 'b', cwd: '/p', updatedAt: 2 }),
+    )
+    expect(deriveRows(list, view()).filter(r => r.type === 'session')).toHaveLength(0)
+    const rows = deriveRows(list, view({ expandedProjects: new Set(['/p']) }))
+    expect(rows.slice(1)).toEqual([
+      expect.objectContaining({ type: 'session', id: 'b', depth: 0 }),
+      expect.objectContaining({ type: 'session', id: 'a', depth: 0 }),
+    ])
+  })
+})
+
+describe('deriveRows session tree', () => {
+  const treeList = listOf(
+    summary({ id: 'root', cwd: '/p', updatedAt: 5 }),
+    summary({ id: 'kid', cwd: '/p', parentId: sid('root'), updatedAt: 4 }),
+    summary({ id: 'grandkid', cwd: '/p', parentId: sid('kid'), updatedAt: 3 }),
+    summary({ id: 'other', cwd: '/p', updatedAt: 9 }),
+  )
+
+  it('nests children under expanded parents with increasing depth', () => {
+    const rows = deriveRows(treeList, view({
+      expandedProjects: new Set(['/p']),
+      expandedSessions: new Set(['root', 'kid']),
+    }))
+    expect(rows.slice(1)).toEqual([
+      expect.objectContaining({ id: 'other', depth: 0, hasChildren: false }),
+      expect.objectContaining({ id: 'root', depth: 0, hasChildren: true, expanded: true }),
+      expect.objectContaining({ id: 'kid', depth: 1, hasChildren: true, expanded: true }),
+      expect.objectContaining({ id: 'grandkid', depth: 2, hasChildren: false }),
+    ])
+  })
+
+  it('collapses subtrees at unexpanded sessions', () => {
+    const rows = deriveRows(treeList, view({ expandedProjects: new Set(['/p']) }))
+    const ids = rows.filter((r): r is SessionRow => r.type === 'session').map(r => r.id)
+    expect(ids).toEqual(['other', 'root'])
+  })
+
+  it('degrades a cross-group parent link to a group root', () => {
+    const rows = deriveRows(listOf(
+      summary({ id: 'p1', cwd: '/a', updatedAt: 2 }),
+      summary({ id: 'stray', cwd: '/b', parentId: sid('p1'), updatedAt: 1 }),
+    ), view({ expandedProjects: new Set(['/a', '/b']) }))
+    expect(rows).toEqual([
+      expect.objectContaining({ type: 'project', key: '/a' }),
+      expect.objectContaining({ id: 'p1', depth: 0 }),
+      expect.objectContaining({ type: 'project', key: '/b' }),
+      expect.objectContaining({ id: 'stray', depth: 0 }),
+    ])
+  })
+
+  it('keeps cycle members visible as extra roots without looping', () => {
+    const rows = deriveRows(listOf(
+      summary({ id: 'x', cwd: '/p', parentId: sid('y'), updatedAt: 2 }),
+      summary({ id: 'y', cwd: '/p', parentId: sid('x'), updatedAt: 1 }),
+      summary({ id: 'self', cwd: '/p', parentId: sid('self'), updatedAt: 3 }),
+    ), view({ expandedProjects: new Set(['/p']), expandedSessions: new Set(['x', 'y', 'self']) }))
+    const ids = rows.filter((r): r is SessionRow => r.type === 'session').map(r => r.id)
+    expect(ids).toContain('self')
+    expect(ids).toContain('x')
+    expect(ids).toContain('y')
+    expect(ids).toHaveLength(3)
+  })
+
+  it('breaks updatedAt ties deterministically by id', () => {
+    const rows = deriveRows(listOf(
+      summary({ id: 'b', cwd: '/p', updatedAt: 7 }),
+      summary({ id: 'a', cwd: '/p', updatedAt: 7 }),
+      summary({ id: 'c', cwd: '/p', updatedAt: 7 }),
+    ), view({ expandedProjects: new Set(['/p']) }))
+    const ids = rows.filter((r): r is SessionRow => r.type === 'session').map(r => r.id)
+    expect(ids).toEqual(['a', 'b', 'c'])
+  })
+
+  it('collects multiple children under one parent in recency order', () => {
+    const rows = deriveRows(listOf(
+      summary({ id: 'p', cwd: '/p', updatedAt: 9 }),
+      summary({ id: 'old', cwd: '/p', parentId: sid('p'), updatedAt: 1 }),
+      summary({ id: 'new', cwd: '/p', parentId: sid('p'), updatedAt: 5 }),
+    ), view({ expandedProjects: new Set(['/p']), expandedSessions: new Set(['p']) }))
+    const ids = rows.filter((r): r is SessionRow => r.type === 'session').map(r => r.id)
+    expect(ids).toEqual(['p', 'new', 'old'])
+  })
+
+  it('carries the running flag onto rows', () => {
+    const rows = deriveRows(
+      listOf(summary({ id: 'a', cwd: '/p', running: true })),
+      view({ expandedProjects: new Set(['/p']) }))
+    expect(rows[1]).toEqual(expect.objectContaining({ id: 'a', running: true }))
+  })
+})
+
+describe('deriveRows search', () => {
+  const list = listOf(
+    summary({ id: 'root', title: 'alpha work', cwd: '/p', updatedAt: 5 }),
+    summary({ id: 'kid', title: 'deep needle here', cwd: '/p', parentId: sid('root'), updatedAt: 4 }),
+    summary({ id: 'noise', title: 'unrelated', cwd: '/p', updatedAt: 3 }),
+    summary({ id: 'q', title: 'quiet', cwd: '/other', updatedAt: 2 }),
+  )
+
+  it('forces matched sessions and their ancestor chains visible, ignoring expansion', () => {
+    const rows = deriveRows(list, view({ query: 'NEEDLE' }))
+    expect(rows).toEqual([
+      expect.objectContaining({ type: 'project', key: '/p', expanded: true }),
+      expect.objectContaining({ id: 'root', depth: 0, expanded: true }),
+      expect.objectContaining({ id: 'kid', depth: 1 }),
+    ])
+  })
+
+  it('drops groups without a hit and keeps a bare project row on label-only hits', () => {
+    const rows = deriveRows(list, view({ query: 'other' }))
+    expect(rows).toEqual([
+      expect.objectContaining({ type: 'project', key: '/other', expanded: false }),
+    ])
+  })
+
+  it('blank query means normal mode', () => {
+    const rows = deriveRows(list, view({ query: '   ' }))
+    expect(rows.every(r => r.type === 'project')).toBe(true)
+  })
+})
+
+describe('formatRelativeTime', () => {
+  const now = 1_000_000_000_000
+  it.each([
+    [now, 'now'],
+    [now - 30_000, 'now'],
+    [now - 2 * 60_000, '2min'],
+    [now - 3_600_000, '1h'],
+    [now - 2 * 86_400_000, '2d'],
+    [now - 18 * 86_400_000, '18d'],
+    [now - 65 * 86_400_000, '2mo'],
+    [now - 400 * 86_400_000, '1y'],
+  ])('%d -> %s', (at, label) => {
+    expect(formatRelativeTime(at, now)).toBe(label)
+  })
+
+  it('clamps future timestamps to now', () => {
+    expect(formatRelativeTime(now + 5_000, now)).toBe('now')
+  })
+})

packages/client/ui-sidebar/tsconfig.json

@@ -0,0 +1,40 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "jsx": "react-jsx",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../web-react"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../ui-layout"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/client/ui-sidebar/tsdown.config.ts

@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-sidebar', ['lib/types/index.js', 'lib/types/invariant.js'])