dsh-session-pin

📌 dsh-session-pin

• 1024 store channel: npm i -g dsh1024 once, then dsh1024 plugin --profile web add dsh-session-pin (counts toward the deepseek1024.com install ranking).

Pin sessions and workspaces to the top of the DeepSeek Harness sidebar with per-pin row colors.

*A dual-face (host + browser) plugin: two pin levels, an 8-color swatch per pin, and a navigation organizer — boards, tags, saved views, health summaries, and /goto.*

Official repository. This is the only official repository of dsh-session-pin, maintained by PerryLink. Same-name repositories under other accounts are not affiliated.

English · 简体中文 · Español · Português · हिन्दी

Compatibility

What you get

dsh-session-pin keeps the conversations that matter at the top of the sidebar and colors them so you can find them at a glance:

• Two pin levels — pin whole workspaces and individual sessions; a pinned workspace moves to the front of the workspace list and a pinned session to the front of its account.
• Per-pin row colors — a swatch after each pin cycles an 8-color preset palette (Shift+click clears); the row gets a left accent bar plus a translucent tint.
• Four pin surfaces — a hover [pin][swatch] pair on every row, a pin toggle in the session header, a sidebar foot action with a pinned panel, and per-browser durable pinning that keeps pins and colors across restarts.
• Zero core changes — a standalone plugin for the stock DSH Web GUI; every surface degrades gracefully on older baselines.

┌─ Workspaces ────────────────────────────┐
│ 🎨 Workbench            ███             │  ← pinned workspace, tinted red
│   📌 Implement login flow         3h    │  ← pinned session, tinted teal
│     Fix the auth bug              1h    │  ← hover shows a gray pin + swatch
│   Refactor the DB layer           2d    │
└─────────────────────────────────────────┘

Navigation organizer

Four browser-local capabilities organize multi-session work on top of pinning. All state rides the same session-pin store (per-browser; nothing is uploaded), and each has a Config switch.

• Boards — pins join named groups; the board chip row creates, renames, and deletes boards and drag-reorders them (order persists per-browser), while the pinned panel groups each board's pins under a collapsible header.
• Tags & views — entities carry up to 8 tags (≤24 chars each), set per row from the panel's manage button (which also assigns the pin's board); the filter bar matches text and tags, and any filter state saves as a named view (up to 20) for one-click switching.
• Health summary — each pinned session row appends a read-only, sanitized line (N msgs · you|ai · relative time) derived from the public session snapshot — counts and directions only, never content.
• /goto <keyword> — a composer line starting with /goto plus Enter jumps: a unique title/tag match opens it, several matches list in a prompt, none explains. The command line never reaches the model.

How it works

• Host half (src/index.ts) — registers the durable session-pin settings namespace (the two pinned id lists, the two color maps, and the organizer state, plus the host policy maxPins/reorderOnLoad/pruneStale); no session events, no model traffic.
• Browser half (src/client.ts) — assembles a framework-free PinStore (settings transport, degrading to a versioned localStorage document with cross-tab sync), a PinController (two-level toggle / color cycle / prune / reorder state machine), and the UI: the row overlay, the optional row-slot registration, the header toggle, the sidebar foot action, and the pinned panel. Ordering goes through ctx.workspaces.
• Log-backed write channel — on builds mounting the built-in dsh-session-pin service, every session toggle commits through the session.setPinned RPC first (the session/pin event log is the canonical residence) and mirrors the commit into the settings store; a failed or slow RPC degrades to a direct settings write.
• Log-backed projection read — enableLogBacking (host Config, fail-closed default off) mounts a projection reader that folds live session/pin events into the canonical pin set and mirrors the folded pinned/colors into the settings namespace, which becomes the idempotent cache for the log-backed state. The event schema, the pure fold (foldPinEvents), and the pre-flight-gated append seam (PinLogAppender) live in src/pin-log.ts: the host's known event vocabulary plus its ignorable append marker are probed BEFORE the first write (probe cached per process), so hosts that cannot safely carry the event — 0.1.2-rc.1 fails closed on unknown types at read — never receive one; the settings/localStorage store remains the compat + degradation path.
• Client seam — the browser half reads SessionId/WorkspaceId brands from @deepseek-ai/dsh-client-connection (the removed dsh-client-runtime package no longer exists on current hosts); the session-header slot's standard-kit seats are typed as a local structural contract. On 0.1.2-rc.1 hosts the sessions.row.action row slot is not declared, so session rows fall back to the DOM overlay and the row-slot registration stays deferred.
• Build — esbuild emits the host ESM half and the client CJS half wrapped in the web boot factory (window.__ModuleLoader__.load({ id, factory })); react is externalized onto the shell's own React, and a purity gate fails the build if any @deepseek-ai/* value import leaks into the browser bundle.

Extension points used: settings (host); sessions, workspaces, settingsScope, connection, remote, slots (client); locale (client, optional); conversation.session.header.actions, sidebar.footer.action, shell.overlay, and the upstream sessions.row.action row slot when declared (0.1.2-rc.1 hosts do not declare it — the DOM overlay covers session rows there). Model-visible effects: none — this is a UI-only plugin: it adds no session events and no tokens to any model request.

Quick start

# 1. install the bundle into your profile
dsh plugin --profile web add "github:PerryLink/dsh-session-pin#main"

# or from npm (published releases)
dsh plugin --profile web add dsh-session-pin

# 2. restart and verify the row
dsh --profile web --dump-config | grep -A3 'id: session-pin'

Loader entry id. On harness builds whose dsh-base bundle mounts the built-in host service @deepseek-ai/dsh-session-pin (entry id session-pin), give this plugin a distinct entry id such as id: session-pin-ui in the profile patch row — a duplicate session-pin id fails the boot with "duplicate loader entry id".

Install & uninstall

• git channel (latest main): dsh plugin --profile web add "github:PerryLink/dsh-session-pin#main" — pnpm run build emits the host half (lib/index.js) and the browser half (lib/client.js).
• npm channel (published releases): dsh plugin --profile web add dsh-session-pin.
• tarball channel: pnpm pack in this repo, then dsh plugin --profile web add ./dsh-session-pin-<version>.tgz.
• uninstall: dsh plugin --profile web remove dsh-session-pin (or remove the row from the profile patch; the session-pin section of settings.yaml can also be removed).

Configuration

All tunables are Schemastery Config fields (changeable from cordis.yml). cordis.patch.yml mounts the bundle with the defaults below.

Tools & surfaces

Permissions & data

• Permissions: the dshWorkshop manifest declares browser:local-storage, settings:read, and settings:write.
• Data: pins, colors, and organizer state live per browser in the session-pin settings namespace, degrading to a versioned localStorage document (v1 documents migrate) where the web proxy does not serve the namespace. Nothing is uploaded. With enableLogBacking, the settings namespace becomes the idempotent cache for the log-backed session/pin projection.
• Session log: none by default — this plugin adds no session events and no tokens to any model request. When enableLogBacking is on, the host folds the log-only session/pin event (written by the upstream session.setPinned RPC) into the canonical pin projection; PinLogAppender pre-flight-gates its own writes so hosts that cannot carry the event (0.1.2-rc.1) never receive one. Model-visible effects remain none.

Security boundaries

• UI-only. No model-visible effects, no network, no subprocesses; every surface degrades gracefully on older baselines.
• Durable, bounded state. Pins and colors are pruned with deleted entities (pruneStale); maxPins caps the pinned count per level.
• Read-only health. The health summary derives counts and directions from the public session snapshot and writes nothing back.

Known limitations

• Persistence scope — the log-backed canonical residence is opt-in (enableLogBacking, fail-closed default off) and its live read loop requires builds that emit the session/pin event (the upstream session.setPinned RPC); on baselines without it, pins and colors fall back to the session-pin settings namespace, then to browser-local localStorage. On 0.1.2-rc.1 hosts the pre-flight gate disables log appends entirely (the fail-closed event vocabulary would reject such logs), so the projection degrades to the settings cache there.
• Ordering scope — the pinned position is stable only under Manual order; under Updated order the core's activity promotion re-fronts active sessions, and reorderOnLoad re-asserts the prefixes on load.
• Remote browsers — settings RPCs are loopback-only on the baseline; remote browsers fall back to browser-local localStorage.
• Row badge fallback — where the upstream row slot is unavailable, session rows are matched by title text; with duplicate titles the badge shows on every matching row and toggles the first match (cosmetic).
• Row DOM dependency — the overlay relies on the core rows' role="treeitem" structure and must follow upstream UI changes.

Roadmap

• Canonical residence: a log-backed session/pin event + pin projection + write RPC (upstream) — the settings namespace then retires as the durable store and the plugin consumes useProjection('pin'). Landed (P0): the plugin ships the session/pin event schema, the pure projection fold (foldPinEvents), the pre-flight-gated append seam (PinLogAppender), and a host projection reader (enableLogBacking) that folds live session/pin events back into the settings cache. The settings/localStorage store remains the compat + degradation path; the log is canonical when enabled.
• Self-build write fallback: wire PinLogAppender to append session/pin events on builds without the upstream session.setPinned RPC, so no-upstream baselines also log canonically.
• Consume the upstream pin projection (useProjection('pin')) on the client once @deepseek-ai/dsh-session-pin ships in the npm baseline; today the host mirror covers the read path on master builds.
• Right-click / row-menu "Pin" entry (needs a core row-level menu slot; the row badge slot is upstream now).
• A full color-picker popover (custom colors) once the canonical residence exists; today's cycle swatch covers the preset palette.

Development

pnpm install                    # install dependencies
pnpm run typecheck              # tsc --noEmit
pnpm test                       # vitest unit tests
pnpm run build                  # dual-half build + client-bundle purity check
node scripts/verify-live.mjs    # live check against a running `dsh web` (DSH_CHECKOUT env)

Topics

deepseek-harness, dsh, dsh-plugin, session-pin, pin, workspace

Contributors

• @PerryLink — creator and maintainer: pin UX, durable persistence, workspace ordering, per-pin row colors, the navigation organizer, and the five-language docs.

PerryLink DSH Plugin Family

This project is one of the 37 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:

Install from the DSH Desktop Market

All PerryLink plugins are browsable in the built-in DSH Desktop Market: Market → Sources → add source → paste https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → select it. Installation still goes through the Market's npm-identity verification and your confirmation.

License

Apache License 2.0 © 2026 dsh-session-pin contributors