DSH Session Pins

简体中文

@dsh-external/dsh-session-pins adds a persistent pinned-session menu to the
DeepSeek Harness web sidebar.

The plugin answers
DeepSeek Harness Discussion #63,
which asks to keep valuable sessions easy to reach. Harness does not expose a
public session-row action slot, and replacing the stock session browser would
couple a plugin to private UI source. Session Pins therefore contributes one
root-scoped action through the public sidebar.footer.action slot. It does not
patch or replace the host.

Compatibility status

The source, automated contracts, and package artifacts target
@deepseek-ai/dsh@0.1.0-rc.6. DeepSeek Harness is in developer preview, so a
new release candidate may break this plugin until compatibility is reviewed.

The automated suite includes an isolated, keyless rc.6 profile smoke: it
installs this repository through the published CLI, composes the plugin row,
boots on an ephemeral loopback port, reads the root boot manifest, and fetches
the package-name browser module route. Task 7's manual wide/rail visual
acceptance remains pending and is not claimed here.

User experience

• Wide sidebar: the footer action shows a pin icon, Pinned sessions, and
  the current pin count.
• Rail sidebar: the same action is icon-only, with an accessible name and a
  delayed tooltip.
• Activating the action opens a menu above the footer. Selecting a root row
  opens a same-menu drill-down with Open, Unpin, and Back as
  applicable. An empty list has an explicit empty state.
• An ordinary current session can be pinned when it is non-blank and not from
  a subagent. The newest pin appears first; pinning an existing id moves it to
  the front without duplicating it. A pinned current session offers Unpin
  current session.
• A blank current session cannot be newly pinned. If a blank id is already
  stored, it remains removable and can be opened only while its non-subagent
  summary still resolves and workspace availability is actionable.
• A subagent current session cannot be newly pinned or opened by this plugin.
  A previously stored subagent id remains removable; a rejected open is
  contained and leaves the recovery actions usable.
• Workspace archive state is actionable only when baselinesReady === true,
  phase === 'ready', and state === 'idle'. Until then, every resolvable pin
  detail omits Open, explains that session availability is not ready, and
  keeps Unpin and Back.
• DeepSeek Harness 0.1.0-rc.6 immediately clears an archived id selected
  through sessions.open() and exposes no public unarchive operation. An
  actionable archived pin therefore keeps its live title, omits Open,
  explains this version limitation, and remains removable.
• Session Pins does not call sessions.open() for an archived pin or report a
  false success. It does not use a delayed-selection workaround, private API,
  host patch, or timer.
• A stale id that no longer resolves is shown as Unavailable: id. Its
  drill-down omits Open but keeps Unpin and Back.
• If an open fails because the session disappears or Harness rejects it, the
  menu stays usable, announces a localized error, and preserves the unpin
  recovery path.

Browser-local persistence

Pins are stored in localStorage under dsh.session-pins.v1 as a versioned,
ordered id list. Input is validated: malformed records fall back to empty,
non-string and blank ids are removed, duplicate ids keep their first
occurrence, and at most 100 pins are retained.

Persistence is browser-local. It does not sync across devices, browser
profiles, browsers, or different origins. Same-origin tabs reconcile
through browser storage events while the plugin is active; the tab that
writes a change updates itself directly because browsers do not send that
storage event back to the writing document. If localStorage is blocked or
throws, pins remain usable in memory for the current page but do not survive a
reload.

Install after release

The GitHub repository and tag are created during the release step. Run these
commands only after the referenced release exists.

Install the v0.1.0 Git tag into the stock web profile:

dsh plugin --profile web add github:alooshxl/dsh-session-pins#v0.1.0

To upgrade to another Git tag, repeat add with that tag; do not use update
to select a Git ref. For example:

dsh plugin --profile web add github:alooshxl/dsh-session-pins#v0.1.1

For an immutable installation, replace the placeholder with the full
40-character commit SHA:

dsh plugin --profile web add github:alooshxl/dsh-session-pins#<40-character-commit-sha>

Remove the plugin:

dsh plugin --profile web remove @dsh-external/dsh-session-pins

Launch the stock web profile:

dsh web

The equivalent explicit launch is:

dsh --profile web

The package tracks reviewed lib/ output. A Git installation therefore needs
neither an install build allowlist nor an install-time prepare, install, or
postinstall lifecycle.

Security and host boundaries

• No API key or other credential is required to pin, unpin, persist, or open a
  session.
• The package does not read credential files, ship temporary browser profiles,
  or include private Harness source.
• Product behavior stays in the browser client entry. The Node entry only
  enables package registration and browser-module discovery.
• Integration uses published Harness client services and the public
  sidebar.footer.action slot. There is no host patch, monkey patch, or
  compatibility layer.

Local development

Use Node 22 and pnpm 11.7.0:

git clone https://github.com/alooshxl/dsh-session-pins.git
cd dsh-session-pins
pnpm install --frozen-lockfile

The frozen development graph allows lifecycle scripts only for the exact
@deepseek-ai/dsh-subprocess-local@0.1.0-rc.6 and node-pty@1.1.0 transitive
host dependencies required to boot the published rc.6 Web profile on Linux.
Every other discovered script is denied. These development-only host packages
are not part of the packed plugin or its installation contract.

The GNU Make checkpoint is:

make fmt && make test && make lint

On systems without GNU Make, run its exact commands:

pnpm run format && pnpm run test && pnpm run lint
pnpm run typecheck

Run the complete release-oriented verification:

pnpm run build
pnpm run format:check
pnpm run typecheck
pnpm run verify:self-contained
pnpm run verify:package
git diff --check
git status --short --untracked-files=all -- lib

pnpm run verify:package performs the local dry-run package inventory
validation through a compatible package-manager invocation.

The final git status command must print nothing: tracked and untracked
generated-artifact drift is blocking.

Contributing, discussion, and license

Please report defects or compatibility findings through
GitHub issues, and send
focused changes through
pull requests. Feature
context remains available in
Discussion #63.

This project is available under the MIT License.