# DSH Compatibility Notes

## Reference baseline

- Supported and installed package baseline: DeepSeek Harness `0.1.7-rc.2` (npm `latest` on 2026-09-29)
- S7R release line: `0.10.x`
- Latest compatibility audit: 2026-09-29
- Node target: 22.19+ or 24+
- Previous S7R/DSH pairing: S7R `0.9.4` with DSH `0.1.1-rc.2`

DSH `0.1.7-rc.2` is a structural client-API migration, not a peer-range-only update. The monolithic `@deepseek-ai/dsh-client-runtime` package used by S7R 0.9.x no longer exists. S7R 0.10 therefore targets the new controllers, UI projections, and typed Remote facade directly. Older DSH releases are no longer declared compatible with this release line.

The npm `next` tag was `0.2.0-rc.1` at audit time. It is useful as an early warning, but S7R does not claim production compatibility with that prerelease until the same package, build, and browser workflow below passes against it.

## Migration summary

| Area | DSH 0.1.7 seam used by S7R | S7R behavior |
| --- | --- | --- |
| Root composition | `ctx.slots.register` plus `PropsRuntime<'root'>` | S7R intentionally occupies the root slot to provide the complete desktop shell. Global Session and Workspace hooks still come from DSH. |
| Sessions | `ctx.sessions`, explicit `retain`/`release`, `SessionFace`, `useSessions`, `useSessionStatus` | Creation, live control, prompt/steer/cancel, rename, pagination, attachments, completion notices, and cold-session metadata remain DSH-owned. Retained references are released when the plugin unloads. |
| Conversation | `ctx.uiConversation.binding(binding).target('chat')` | The Agent window combines the current Session snapshot with the Chat target's conversation projection. S7R does not rebuild conversation state from transport frames. |
| Workspaces | `ctx.workspaces` and `ctx.uiWorkspace` | Folder picking, registration, connection, navigation, archive, and unarchive use the supported Workspace controller/navigation services. |
| Jobs | `ctx.jobs.state` and `ctx.jobs.watchRows` | Monitor's Background view follows the real per-Session job roster instead of reading a removed Session-list field. |
| Remote catalogs | `ctx.remote.session`, `agentPresets`, `skills`, `commands`, `pluginInventory`, and `credentials` | Model routes, Presets, Skills, commands, plugin inventory, and value-free API-key status use direct `{ok,value}` Remote results. Each child namespace is explicitly injected, as required by Cordis service ownership. |
| Connection | authenticated exact Fetch route `/api/knowledge-desk` | S7R's bounded Host operations use Connection's shared trust/authentication fence without depending on the retired dedicated-channel route ownership model. |
| Event ledger | live `Session.snapshotEvents()` | Timeline, Find, context inspection, metrics, and export read an immutable snapshot instead of a removed public `events` property. |
| Persistence | `sessionPersistence.open(id, 'read')`, `read()`, `close()` | Cold-session reads explicitly borrow and close a read handle instead of using the removed `inspect()` shortcut. |
| Filesystem | `ctx.fs` with inspected Session cwd | Finder, TextEdit, Preview, and Find re-resolve and contain every path under the Session Workspace on the Host. |
| Terminal | `ctx.terminals` with an exact live Agent owner | S7R starts `/bin/zsh -f -i` through the official terminal service/backend and keeps terminal ownership independent of an open Agent window. |

## Deliberately unused integration techniques

- No DOM selectors or mutation of DSH's own rendered tree.
- No iframe bridge, browser-native alert/confirm UI, or secret readback.
- No arbitrary filesystem or process access from the browser.
- No private Session maps, terminal backend maps, subprocess handles, or direct `node-pty` dependency.
- No invented plugin enable switches: the exposed loader inventory is read-only.

## Archive semantics

DSH 0.1.7 publishes supported archive and unarchive operations. S7R now uses those operations, and the DSH archive set remains authoritative. Pre-0.10 browser-local archive records remain visible as a migration layer and disappear when restored. Archiving preserves the durable Session history; restoring removes the Session from the native archive and makes it available to Knowledge Desk again.

S7R's desktop Trash is unrelated: it deletes only local desktop aliases and never archives a Session or deletes a project file.

## Known upstream limitation: terminal transport

The `0.1.7-rc.2` `TerminalSessionService` and backend contract provide spawn, interactive send, bounded retained reads, signals, status, and close. They still do not publish a PTY resize method or a raw browser byte stream. S7R therefore:

- reflows the Terminal window and scroll viewport but does not claim to resize backend rows/columns;
- reports `terminalResize: false` through its capability endpoint;
- returns `{ supported: false }` from the forward-compatible `terminal/resize` endpoint;
- presents a fast line console rather than pretending to be an xterm-style raw attachment.

## Runtime availability boundaries

Finder, TextEdit, Preview, Timeline, Find, and export can inspect a live or cold persisted Session. Monitor's Agent view intentionally reports live Agents; its Background view follows jobs for Sessions visible in the DSH catalog. Terminal requires an exact live Agent owner, so S7R creates a fresh Workspace-owned Session when a preferred cold Session cannot own a terminal. No visible Agent window is required.

## Validation gate

For every DSH baseline change:

1. install an exact DSH package graph and regenerate the lockfile;
2. run strict Host and Client typechecks;
3. run all deterministic tests;
4. produce the Host and lazy browser bundles;
5. install the packed plugin into a clean, isolated DSH Web profile;
6. verify folder choice, Agent creation, streaming/steering, context UI, native archive/restore, API-key status/write, DSH Control Center, Monitor jobs, Finder, and zsh Terminal;
7. check the browser console and Host log for errors;
8. repeat Fit Browser at 1× and 2× and at least one fixed resolution.

Do not widen compatibility based only on compilation. A new version is supported only after the clean-profile browser run succeeds.