# DSH Desktop 0.2.1-rc.2 Vault compatibility

This adapter is pinned to the four macOS Desktop client artifacts shipped with
DSH 0.2.1-rc.2 (`/Applications/DeepSeek Harness.app`, Electron 44.7.0, Node
24.21.0). Unlike the 0.2.0-rc.2 adapter it does **not** replay a 0.2.0 snapshot:
`patch-client.mjs` reads the *installed* 0.2.1-rc.2 bundles, refuses any other
input SHA-256, and re-applies the Vault seams in place. Everything else in those
bundles stays exactly as 0.2.1-rc.2 shipped it, so the `uiConversation` service
and the slot contracts that `ui-skill`, `ui-reference`, `ui-secret-mask` and
`ui-goal` inject keep their new-version semantics.

Pinned inputs (SHA-256 of `lib/client.js`):

| package | sha256 |
| --- | --- |
| `@deepseek-ai/dsh-api-session-controller` | `82f2301c18f0e51340c1eedf8ecdfb939e873b3770a80632e438b86e82887d0e` |
| `@deepseek-ai/dsh-client-ui-workspace` | `977c75d31c356b1ffd11a0419997c4426dad48a852c80be01819d01902254050` |
| `@deepseek-ai/dsh-client-ui-conversation` | `48d308ca86c9350986982e113bb775696719a958415f436ce7b977de1eace0b6` |
| `@deepseek-ai/dsh-client-ui-layout` | `355628eb82b799fb19b7f85b7ca49c538eee309f399733d719257643286c3c56` |

## Why the 0.2.0 adapter broke on 0.2.1

The bundle hashes changed, so `patch-client.mjs` refused the new input; and the profile kept serving the *old* client bundles as the conversation /
workspace / layout / session-controller rows. Those snapshots no longer matched
the 0.2.1 client runtime (the slot chain election and the session-controller
event protocol both moved), which surfaced as a blank conversation area and
`definition.match is not a function`, and made the four plugins above fail to
activate because the old convo bundle did not expose `uiConversation`.

The unpatched 0.2.1 bundles also still lack `sessions.openingAccess`, which
Vault's client calls during `apply()`; without it the client entry fails and the
Desktop reports `web boot: 1 entry did not activate / dsh-vault-plugin: failed`.

## What the adapter restores

* `sessions.openingAccess.register` plus the abort-aware opening wait
  (`openingGates`), so a locked session is gated before history is fetched.
* Sidebar workspace row `action` / `accessory` / `title` and session row `title`
  chain seats.
* `conversation.session.guard` and `conversation.session.header.title`.
* `shell.document.title`.

All four bundles still contain the 0.2.0 anchor strings, so the seam edits are
byte-for-byte the same shapes as before; only the hash pins are new.

## Install / repair

Stop Desktop before changing the profile or the overlay output.

```sh
python3 compat/dsh-v0.2.1-rc.2/extract-fixture.py \
  '/Applications/DeepSeek Harness.app/Contents/Resources/app.asar' \
  .cache/dsh-v0.2.1-fixture
DSH_CLIENT_FIXTURE="$PWD/.cache/dsh-v0.2.1-fixture" \
  node --test compat/dsh-v0.2.1-rc.2/compat.test.mjs
node compat/dsh-v0.2.1-rc.2/prepare-overlay.mjs \
  "$PWD/.cache/dsh-v0.2.1-fixture" \
  "$HOME/.dsh/plugin-packages/vault-desktop-021rc2" \
  '/Applications/DeepSeek Harness.app/Contents/Resources/app.asar/dsh/node_modules'
```

Then in the Desktop profile:

1. add `dsh-vault-plugin` to `dsh.profile.bundles` in
   `~/.dsh/profiles/desktop/package.json`;
2. add the Vault `config` row;
3. disable `session-controller`, `ui-workspace`, `ui-conversation`, `ui-layout`
   and insert the four replacement rows pointing at the overlay
   `lib/index.js` files:

```yaml
- id: session-controller
  disabled: true
- id: ui-workspace
  disabled: true
- id: ui-conversation
  disabled: true
- id: ui-layout
  disabled: true
- insert:
    - id: vault-compat-session-controller
      name: "/Users/<you>/.dsh/plugin-packages/vault-desktop-021rc2/@deepseek-ai/dsh-api-session-controller/lib/index.js"
    - id: vault-compat-ui-workspace
      name: "/Users/<you>/.dsh/plugin-packages/vault-desktop-021rc2/@deepseek-ai/dsh-client-ui-workspace/lib/index.js"
    - id: vault-compat-ui-conversation
      name: "/Users/<you>/.dsh/plugin-packages/vault-desktop-021rc2/@deepseek-ai/dsh-client-ui-conversation/lib/index.js"
    - id: vault-compat-ui-layout
      name: "/Users/<you>/.dsh/plugin-packages/vault-desktop-021rc2/@deepseek-ai/dsh-client-ui-layout/lib/index.js"
```

Desktop's HTTP proxy strips `Origin` and supplies its authenticated host cookie;
Vault's originless path still requires loopback transport, loopback authority and
the host's `connection.requestRejection` to pass.

## Rollback

Stop Desktop, remove the four `disabled` rows, the `insert` block and the
`dsh-vault` config row, drop `dsh-vault-plugin` from `bundles`, and restart. No
Vault state (`~/.dsh/vault-lock`) is touched by installing or removing the
adapter.

## Upgrading to a new DSH release

The adapter is version-bound on purpose, but the work a new release needs is
measurable. Run the probe **before** touching the profile: it reads the installed
bundles from `app.asar`, compares them with the pinned baseline, replays every
seam edit with the hash gate off, and prints which tier you are in.

```sh
node compat/probe-dsh.mjs                 # 已安装的 /Applications 桌面端
node compat/probe-dsh.mjs <app.asar> <adapter-dir>
```

| verdict (exit) | meaning | work |
| --- | --- | --- |
| exact (0) | bundles byte-identical to the pins | nothing |
| L1 (1) | bytes changed, all anchors still in place | replace `baseline` only |
| L2 (2) | an anchor moved | edit the failing `replace`/`section` call |

L1 is the common case. `0.2.0-rc.2 → 0.2.1-rc.2` changed all four hashes while
every anchor still matched, so not a single seam edit changed — only the pins.
The probe prints a ready-to-paste `baseline` block for that case.

For L2 the probe stops at the first miss and quotes the exact string it expected,
so fix one anchor, re-run, and repeat. `patch-client.mjs` validates anchors in
order, which is what makes that loop safe.

### Before starting the new build

1. `cp -R compat/<old> compat/dsh-v<new>`, then update the pins. Keep the old
   directory — it documents the previous seam shapes.
2. Regenerate the overlay into a **version-named** directory
   (`~/.dsh/plugin-packages/vault-desktop-<new>`), then update the four `insert`
   paths in `cordis.patch.yml`; they are absolute and will silently rot
   otherwise.
3. Restart Desktop and confirm `web boot` reports zero failed entries.

### If Desktop will not start after an upgrade

Do not reinstall Vault. Take the adapter out of the path first so Desktop boots
on its native bundles again:

- comment out the four `disabled` rows, the `insert` block and the `dsh-vault`
  config row in `~/.dsh/profiles/desktop/cordis.patch.yml`;
- remove `dsh-vault-plugin` from `dsh.profile.bundles` in
  `~/.dsh/profiles/desktop/package.json`;
- restart, then build the new adapter from a working Desktop.

That isolates the failure to the adapter instead of the plugin, and Vault state in
`~/.dsh/vault-lock` is not touched by any of it.

This is not a compatibility promise for later DSH versions: re-probe, re-pin and
re-verify before every upgrade (`patch-client.mjs` throws on a hash mismatch).