- docs/plans/2026-09-10-dsh-0.1.5-rc.2-adaptation.md: the adaptation plan —
the upstream rc.1 -> rc.2 delta per affected area, why there is no
plugin-side code change, and the CI failure taxonomy (A real Windows
timeouts, B the two silent worker deaths, C the mount lane's npm
ETARGET/OOM) with the evidence and the fix for each.
- AGENTS.md §2/§3: CI pins rc.2, the mount lane's npm flags and their reason
(floating transitives + staged prerelease publishing), the Windows lane's
bounded pool and why, and the primitives-dependencies note extended to rc.2.
- README.md / README_EN.md: support badge (v0.19.1, verified on rc.2), the
install section's stable-release note (rc.1 hosts need no upgrade — the peer
floor is unchanged) and a v0.19.1 changelog entry covering the two CI fixes.
- docs/external-plugin-guide.md: baseline line -> v0.19.1 / DSH 0.1.5-rc.1+,
verified on rc.2.
- Comment-only: `DSH 0.1.5-rc.1` -> `0.1.5-rc.1+` where the note describes a
behaviour that arrived in rc.1 and is unchanged in rc.2 (native guide
description rendering, in src/client/native/index.ts, src/client/service.ts
and the three specs that assert it).
Two independent, evidence-backed defects in the 2026-09-09/10 CI window
(60 completed runs: 26 success / 17 failure; ci-windows|Test red 8 times,
plugin-mount|Install dsh CLI red 4 times).
1. Windows: six of the eight red ci-windows runs were genuine 5000 ms
vitest timeouts in specs that really start a process —
`tests/agent-pty.spec.ts` (`:71` / `:106`; a PowerShell + ConPTY pair per
terminal) and `tests/install-powershell.spec.ts` (`:105`; a cold
`powershell.exe` start measured 12.1 s). vitest.config.ts sets no
testTimeout, so both suites ran on the 5000 ms default, and
`waitForTranscript`'s own poll budget was *also* 5000 ms — the inner wait
consumed the whole outer budget, which is a structurally guaranteed
timeout, not a flake. Both suites now declare a 30 s budget (describe-level
options, verified working on vitest 4) and the inner poll drops to 15 s so
it stays strictly below the outer bound.
2. Windows: `ci-windows`'s Test step runs `pnpm test:windows`
(`vitest run --maxWorkers=2`, the script added with the baseline commit)
instead of `pnpm test`. Five specs spawn real processes, node-pty's ConPTY
helper and a cold powershell.exe are both console-bound, and an unbounded
fork pool on a 2-core runner is the amplifier behind both the timeouts
above and the two silent worker deaths (`Worker exited unexpectedly` with
0 FAIL and every file reported passing — one of them on a commit whose
sibling run was green). Local `pnpm test` semantics are unchanged; only the
Windows lane is bounded.
The worker-death mode itself is NOT proven fixed here: it does not
reproduce on macOS and the two occurrences have no same-commit rerun. This
is the evidence-backed part; the real Windows result decides whether more
is needed, and retries are deliberately not used to paper over it.
3. plugin-mount: `npm install -g @deepseek-ai/dsh@<ver>` never really pinned
anything — the pin's transitives are floating `^` ranges, so while upstream
publishes a prerelease in stages (rc.2 went out package by package between
14:43 and 14:57 UTC on 09-10) npm resolved a mixed rc.1/rc.2 peer graph:
3062 ERESOLVE lines then `Ineffective mark-compacts near heap limit`
(exit 134), or a hard ETARGET on a sibling that appeared 5.5 minutes (resp.
25 seconds) later. The same mechanism hit the alpha line on 09-09. The lane
now pins an already-complete rc.2 and passes `--legacy-peer-deps` plus
`NODE_OPTIONS=--max-old-space-size=4096` to decouple the install from the
upstream publish window; a mismatch would not be silent because the mount
smoke in the same lane boots the real shell.
The stale comment claiming rc.1 is both `latest` and `next` is corrected —
it documented a reality that had already changed.
The pinned baseline moves to DSH 0.1.5-rc.2 (npm `next`; `latest` is still
rc.1) while the plugin's peer floor stays ^0.1.5-rc.1, so rc.1 hosts need no
DSH upgrade to run this version. Nothing in the rc.1 -> rc.2 delta touches
this plugin: of 300 changed upstream files, the overwhelming majority are
single-line `version` bumps in per-package package.json files, and the only
real code edits are the message-feedback dialog, deliverables card CSS and
the CodeFileIcon SVG artwork split (`code-file-icon-artwork.ts`). There are
zero changes under packages/api|host|session|agent and zero type-surface
changes beyond one line in message-feedback/types.ts, so the adaptation is
the pin itself — devDependencies, the CI mount lane and
SIDEBAR_SERVICE_VERSION — with no plugin-side code change and no runtime
compatibility layer.
- package.json: devDependency pins 0.1.5-rc.1 -> 0.1.5-rc.2 (including
dsh-client-locale, which is still published on the DSH tuple); peers keep
the ^0.1.5-rc.1 floor; version -> 0.19.1
- dsh.plugin.json: version -> 0.19.1; engines.dsh keeps >=0.1.5-rc.1 (same
supported range as the peer floor — the two must not fork)
- pnpm-lock.yaml: lockfile realigned to rc.2
- src/client/service.ts: SIDEBAR_SERVICE_VERSION -> 0.19.1 (tests/service.spec.ts
asserts it equals package.json's version)
Verified locally on macOS arm64 against the rc.2 tree: pnpm install clean,
`pnpm peers check` reports no peer dependency issues, typecheck / lint /
check:consumer-types green, `pnpm test` 126 files / 1312 passed / 9 skipped.
The real-mount smoke (scripts/e2e-mount.sh with DSH_CMD pinned to rc.2) and
the aggregate double-mount lane both pass — evidence recorded in
docs/plans/2026-09-10-dsh-0.1.5-rc.2-adaptation.md.
Conflict: src/client/sidebar/use-host-feeds.ts
- ours: import { mirrorAgentWaits, ... } from '../state.ts'
- theirs: same line + new import { isNarrowWidth } from '../breakpoints.ts'
Resolution keeps both imports; the two sides' semantic changes are in
disjoint regions (ours: tab-disabled wait mirroring; theirs:
activateTasksPage native-landing) and both survive intact.
The v0.19.0 regression, its root cause in 223b254, the four decisions
(native landing, narrow-viewport park, jump-back always expands, bottom
workbench keeps its own flows), the change list, and the evidence — including
the environment trap that the PATH `dsh` on this machine is 0.1.2-rc.1 and
cannot register the `file:` tarball into a scratch profile.
The two auto-open switches (a new subagent, a new background job) and the
topology jump-back opened the Tasks page with `target: 'bottom'` — the
plugin's own bottom workbench, i.e. the bottom bar. The right column IS DSH's
native Sidebar since v0.19.0 and every other open in this plugin already lands
there, so `service.ts`'s native branch was bypassed and the switches did NOT
do what their copy promises (README feature table + `settingsSubagentDesc` /
`settingsJobsDesc` in all 20 dictionaries: "wide viewports also expand the
sidebar, while narrow full-screen drawers are not forced open").
- use-host-feeds: one `activateTasksPage(ctx, sessionId, { background })`
carries all three triggers and opens the Tasks page at the default (native)
landing, so the host expands the column in the same step.
- Narrow viewports keep that promise: below 768px the host draws the column
FULLSCREEN (`autoFullscreen = viewportWidth < 768`, `position: fixed;
inset: 0`) and expands it on every open with no way to suppress it, so a
BACKGROUND activation parks the tab — reads `ctx.sidebarRight.isExpanded()`
first and puts the column back to collapsed in the same React batch (only
for the mounted session, which is what that face acts on, and only when the
user had it collapsed). The explicit jump-back is a user gesture and always
takes the host's expansion.
- The bottom workbench keeps its own flows on `target: 'bottom'` (its `+`
menu, the first-expansion auto-terminal); `OpenTabSeed.target` is unchanged.
- tests/sidebar-auto-activation.spec.tsx: asserts the native surface receives
`openTab { kind: 'subagent', revealIfOpened: true }`, that the workbench
stays closed and gains no tab, the park counts per width, the resize-before
-fire read, and the jump-back's no-park. All 10 cases fail against the
unfixed module.
Root cause: 223b254 (retire the plugin's own right panel, v0.19.0-alpha.0)
rewrote these three landings from the plugin's right pane to the bottom one.
A GFM IMPORTANT alert under the title states that the right column is
DSH's own sidebar since v0.19.0 (tab types/bodies via ctx.sidebarRightTabs
/ ctx.sidebarRight, file opens via ctx.sidebarRight.openResource, no
self-drawn right panel), and that the bottom workbench plus the
ctx.betterSidebar service are unchanged.
Baseline moves to DSH 0.1.5-rc.1 — the 0.1.5 line's first release
candidate, and the npm `latest` dist-tag now: peer floor ^0.1.5-rc.1,
devDependency pins, the CI mount-lane pin and dsh.plugin.json engines
all follow. 0.1.5-alpha.2 users stay on v0.19.0-alpha.1.
The upstream delta from alpha.2 is small: 373 changed files, mostly
version bumps, sidebar preview polish and test snapshots. Exactly two
changes touch this plugin, and only one needs work:
- `SidebarRightGuideEntry.description` is back (optional). The native
guide renders it only while it lists at most 4 entries; a longer list
drops every description. The plugin restores `TabDescriptor.description`
and the six built-in `guideDesc*` lines (20 dictionaries) verbatim from
0b6ac5d^, but deliberately does NOT restore the old generic
`nativeGuideDesc` fallback: the host has no fallback of its own, so a
descriptor that declares none now ships no `description` field at all
and renders as a clean title-only capsule.
Consequence worth knowing: the plugin contributes six guide entries, so
the default composition is over the 4-entry limit and shows titles only.
The mount lane proves the restored field end to end by shrinking the
enabled set to three types through the plugin's own settings route
(scratch profile only) and requiring the Files capsule to grow its line.
- The built-in `files` type declares a guide description again and uses a
coloured folder glyph; the plugin owns that kind, so nothing to do.
Verified unchanged from alpha.2 (so nobody re-checks them): the global
main-panel model, the file address grammar (util/workspace-path changed
only its package.json), the native tab-body host contract (.paneBody is
still a block scroller with a definite height), the core/agent/session/
subagent host APIs and the ui-primitives export surface.
Restore caveat fixed in the lane: the settings route merges patches
key-wise, so undoing a temporary `tabsEnabled` change by posting the
original (empty) map leaves the disabled keys behind — the e2e restores
every key it touched explicitly.
Baseline moves to DSH 0.1.5-alpha.2 only (peer floor ^0.1.5-alpha.2,
CI pin, manifest engines); alpha.1 users stay on v0.19.0-alpha.0.
Host-contract changes handled:
- the native guide entry lost its `description` field (entries are
icon+title capsules now): `TabDescriptor.description` and the six
`guideDesc*` keys plus the `nativeGuideDesc` fallback are removed.
- the file address grammar changed: `fileAddressFor` always returns a
session-scoped address (absolute paths keep their leading `/`),
`parseFileAddress` is prefix-based and strips `?`/`#`. The plugin's
purity-gated mirror follows.
- global main panels replaced the `conversation` root slot with the
keyed `main` slot (`main.conversation`): the bottom workbench's
center-column locator now accepts both keys and skips
`display: contents` slot hosts.
Fixes a pre-existing fill bug the alpha.2 probe made obvious: the native
tab body host is a block scroller with a definite height, so tab roots
that only declared `flex: 1` collapsed to content height and the side
chat composer drifted off the pane bottom. The native adapter now wraps
every tab body in a `height: 100%` column flex host.
Also promotes the dependencies `dsh-client-ui-primitives@0.1.5-alpha.2`
dropped from its manifest (anser / shiki / mdast-util-* / micromark-* /
katex / @shikijs/langs) and the newly unmet `dsh-session-persistence`
peer into devDependencies.
The native new-tab list rendered one generic line ("opens in the DSH
sidebar") under every plugin entry, so six plugin rows read identically.
`TabDescriptor.description` now carries the real purpose (string or
locale-following thunk; absent falls back to the generic line), and the
six visible builtins declare theirs across all 20 dictionaries.
- service.ts: `TabDescriptor.description` + docs (guide §4.1, §0 row).
- native/: the guide entry's description follows the descriptor; the
`files` takeover reuses the editor's line.
- builtins: files / changes / tasks / side chat / terminal / browser.
- tests: builtins assert every visible type declares a distinct line;
the lifecycle test asserts descriptor lines (and the takeover reuse).
DSH 0.1.5 owns the right column (its native Sidebar hosts every tab type
this plugin registers), so the plugin's own right panel, its width drag /
new-session seed prefs, and the free-window feature are gone. The bottom
workbench is the only plugin-owned surface left, and its expand/collapse
control is registered into DSH's session-header utilities list slot (the
header's corner seat belongs to the native sidebar's own control).
- state: one `bottomSplits` tree; `makeDefaultState()` takes no arguments;
`toggleBottomPanel` / `openTabInBottomPane` are the only landing
reducers; `setBottomHeight` and `sanitizeState` share the
`CONVERSATION_MIN` cap (a persisted tall height no longer snaps on the
first drag).
- service: every landing in the workbench (creation or focus) expands it;
`SIDEBAR_FEATURES` drops `'floatWindows'`; the open/close/activate tab
pools cover the single tree.
- shell: `Sidebar.tsx` renders only the bottom workbench; the toggle lives
in `sidebar/bottom-toggle.tsx`; layout-push pushes height only (no width,
no `--dsh-sidebar-width`).
- prefs: `openByDefault` / `defaultWidthPercent` / `changesDiffFloat`
removed from the schema, defaults, client parser, settings page, and all
20 dictionaries; the retired keys in stored documents are ignored.
- tests: free-window specs deleted, panel/float assertions dropped,
remaining suites adapted (124 files / 1287 tests); the mount lane asserts
the header toggle and sweeps the native sidebar's guide page.
- docs: README / README_EN / guide §0,§11 / AGENTS test map.
The guide renders `entry.icon`, and the `files` kind takeover registered
without one — so after the editor type stopped contributing its own
duplicate row (b56ceec), the single "Files" row was the only entry in the
new-tab list with a blank icon slot. The takeover now carries the editor
descriptor's icon (the takeover IS that descriptor's page).
Extracted `guideIconOf` so both registration sites build the icon field
the same way; the lifecycle test asserts the takeover's guide entry has
an icon.
The editor type's page identity IS the `files` kind takeover (same
explorer, same title), so the guide/new-tab list showed two identical
"Files" entries — observed on a real profile after the takeover landed.
The editor type now contributes no guide entry of its own; it stays
registered as the file RESOURCE viewer. Covered by the registration
lifecycle test (editor: no guide, files takeover: guide).
The editor type serves both the files PAGE and every file RESOURCE; its
native `title` callback ignored the address, so every opened file showed
up in the strip as "Files" — indistinguishable tabs. Verified on a real
profile: after opening `AGENTS.md` from the tree and a chat file link,
the strip read ["文件", "文件", "文件"].
`title(address)` now returns the file name for a file address and keeps
the descriptor title for a page address (`sidebar://editor`). Covered by
the registration-lifecycle test in tests/native-surface.spec.ts.
The native seat declares `sidebar.right.pane.tab` BEFORE it provides
`sidebarRightTabs`, so driving the registration off the slot declaration
read the service as missing and registered nothing — permanently, since a
declaration never collapses. Observed on a real DSH profile (0.1.5-alpha.1,
`dsh web` on the web profile): the plugin host and its other slot
registrations mounted, the native guide page stayed empty, and a probe
printed `sidebarRightTabs= undefined` at declaration time with the registry
present three seconds later. The scratch mount lane never saw it because
there the plugin activates after the native package finished providing.
`registerNativeSurface` now waits on the SERVICE (`ctx.inject`), which
re-runs whenever the registry appears/reappears, and keeps the per-body
slot registrations on `slots.inject` (they only need the declaration).
Regression test: `tests/native-surface.spec.ts` models the real order
(slot callback fires first, registry arrives later) and fails on the old
implementation. Verified on the real web profile: all guide entries
(files / editor / git / subagent / sidechat / terminal / browser) appear
and the terminal tab renders.
TabDescriptor requires `component`; the fixture omitted it, so CI's
typecheck step failed on the phase-2 branch (vitest never compiled the
file's props strictly, so the local run stayed green).
Phase 2 of the 0.1.5 adaptation: the plugin stops drawing its own right
panel and contributes tab TYPES to DSH's native right Sidebar, which owns
the right column. The bottom workbench (terminal dock) stays plugin-owned.
Registrations (src/client/native/):
- every TabDescriptor becomes a native tab type (kind = descriptor.id, the
default `extension` band) plus a keyed body in `sidebar.right.pane.tab`
and a live chip title in `sidebar.right.pane.tab.title`
- the `editor` type also claims `dsh-resource://file/**`, so it outranks
the built-in `text` preview (fallback) and every file the product opens
lands in the plugin's editor
- the built-in `files` page kind is TAKEN OVER by an extension
registration of the same kind: `openTab('files')` draws the plugin's
explorer, and the built-in resumes when the plugin unregisters
- registrations follow the plugin registry + the side-card settings: a
type registered later (external plugin) gets its native type too, a
disabled type is unregistered (absent from the guide, refuses opens)
Adapter (src/client/native/tab-adapter.tsx):
- one synthetic plugin `SidebarTab` per native tab id, minted from the
native record + navigation params (or the descriptor's own createTab,
which a native guide open bypasses), kept live across navigations and
updateTab writes
- the explorer's per-tab expansion/reveal sets and the per-kind instance
counter, which the plugin's own layout used to hold
Service routing (src/client/service.ts):
- `setSurface` installs the native write face; openTab/openFile land
natively (a path becomes a resource address, a path-less editor open
becomes the `files` page, the rest carry the seed as navigation params),
closeTab/updateTab/activateTab recognise native tab ids
- new optional `OpenTabSeed.target` ('right' default, 'bottom' keeps the
bottom workbench); the bottom panel's own + menu and auto-terminal pass
'bottom'
- src/client/native/surface.ts probes the controller's per-session writes
(`openTabIn`/`openResourceIn`/`closeIn`, not in `ISidebarRight`) and
queues opens for a session whose surface is not mounted yet
Right panel retired behaviourally (Phase 3 deletes the code): Sidebar
renders its bottom workbench only, keeps the panel collapsed, and hides
the right-panel toggle. The panel-specific e2e specs are removed; the
mount lane now drives the native guide (tab sweep), the plugin explorer
inside the native pane (editor/mermaid/README chunks) and the sidechat
host routes.
Verified: pnpm typecheck / lint / build / test (126 files, 1349 tests) /
check:consumer-types, plus pnpm test:mount against a real
@deepseek-ai/dsh@0.1.5-alpha.1 host (7/7).
Move the plugin onto the DSH 0.1.5-alpha.1 baseline (peer floor
^0.1.5-alpha.1, CI pinned to the alpha dist-tag) and fix the two host
contract changes that alpha line introduced.
Baseline:
- all @deepseek-ai/dsh-* peer/dev deps -> 0.1.5-alpha.1; optional peer
@deepseek-ai/dsh-client-ui-sidebar-right (declared, unused until the
native-surface phase); devDep @deepseek-ai/dsh-agent-loop (inbox fold)
- dsh.plugin.json engines >=0.1.5-alpha.1; version 0.19.0-alpha.0;
SIDEBAR_SERVICE_VERSION follows
Live assistant stream (assistant/chunk is gone):
- 0.1.5 publishes in-flight model deltas as process-local
agent/assistant-stream frames instead of durable assistant/chunk events
and embeds the settled stream in assistant/message / assistant/attempt.
src/assistant-live.ts folds the frames into a bounded per-session buffer;
sidechat.events serves the current attempt as `live` rows (replaced every
poll, never a delta) and the transcript renders them; the inherited
in-progress snapshot reads message content / attempt stream / live frames.
Cold session reads (persistence.inspect is gone):
- 0.1.5 reads a stored session through an explicit read handle
(open(id,'read') -> handle.read() -> close()). src/session-store.ts owns
that protocol; every cold read (sidechat transcript, cold-resume preset,
session.cwd, changes replay) goes through it.
Dead code and docs:
- drop the remote.session.openWorkspacePath interception: 0.1.5's chat opens
files through ctx.sidebarRight.openResource instead, so the wrapper had no
caller and would hijack the host's "open in app" gesture; the
interceptOpenPath pref, its settings row and its locale keys go with it
- AGENTS.md §3 + external-plugin-guide.md describe the new baseline
- vitest setup bridges Node's localStorage accessor to jsdom's store (the
pre-existing 26 failures on Node >= 22)
- desktop-layout e2e seeds through host RPC and types into the Lexical
composer (0.1.5 replaced the textarea) instead of driving the directory
picker
Verified: pnpm typecheck / lint / build / test (124 files, 1327 tests) /
check:consumer-types, plus pnpm test:mount against a real
@deepseek-ai/dsh@0.1.5-alpha.1 host (18/18).
Menghuan1918