dsh-codex-pin

Codex-style session pinning for the DeepSeek Harness Web sidebar — a pin is a flag, not a position.

Pinning a session lifts it into a single Pinned section above the whole workspace list. Toggling a pin never calls workspace.insertSessionBefore, never writes the workspace view store's order, and never switches the sidebar's sort mode: the durable session order in ~/.dsh/storages/workspace.json is not touched. That promise is guarded by a static check in this repo (npm test), not just by documentation.

Independent community plugin. Not an official DeepSeek product, and not affiliated with OpenAI — “Codex-style” describes the interaction model it copies, not any official connection.

What you get

• A pinned flag. Hover a session row and click the pin (📌). The session moves into 已置顶 / Pinned at the top of the sidebar, newest pin first.
• The pinned row leaves its group, so nothing is duplicated: click the row in the section to open the session, click the pin control there to unpin, and the row is back where the list order says it belongs.
• Host-durable state. The ordered list lives in the host settings namespace codex-pin (~/.dsh/settings.yaml), so it survives restarts and is shared by every browser whose settings transport reaches the host.
• Honest degradation. A browser that cannot reach the namespace keeps its own localStorage list and the section header says 仅本浏览器 / This browser only. That fallback is a fail-safe, not a one-way lock: a failed host write is retried once, and even after the page has fallen back every later pin keeps probing the host, so the note clears itself at the first write that lands.
• No model-visible effects. No session events, no tokens, no telemetry and no external network calls — the browser half reaches only same-origin host surfaces: the settings namespace, the row menu's workspaces.openSession / forkSession / archiveSession, and the session's own rename.

How it differs from the other pinning plugins

	dsh-codex-pin	dsh-pin	dsh-session-pin
Pin levels	one: a Pinned section above all workspaces	two: in-workspace + global tray	two: workspace + session
Durable session order	never written — no ordering API is called at all	in-workspace pins go through workspace.insertSessionBefore and switch the sort mode to manual; the global tray is display-level	pinned sessions move to the front of their account
Pin state	host settings namespace codex-pin.pinned, localStorage fallback	host order anchors + local records	host settings, per-browser durable
Extras	deliberately none	anchor-exact restore, sort-mode restore	8 colours, boards, tags, saved views, /goto
Footprint	one bundle entry; no HTTP routes	client-only	host + browser

Pick this one if you want pinning to be a purely visual, always-reversible annotation. Pick the others if you want pins to also drive ordering, colours or boards.

Requirements

• DeepSeek Harness with the web profile (the plugin is platform: web).
• Verified against dsh web 0.1.5-rc.1, and re-verified against 0.1.6-alpha.2 (that host rewrote the sidebar, so the browser half now probes host capability shapes instead of one build's API); the declared peer range is >=0.1.2-rc.1 <0.2.0 and other builds in it are untested (see Compatibility).
• Node >=22.19.0 (only for building from source).
• dsh plugin add prints a peer-dependency warning on every known DSH build — the ecosystem's peer declarations are optional overlays, so the warning is expected and harmless.

Install

# straight from GitHub — the path that works today
dsh plugin --profile web add github:jackovibe/dsh-codex-pin

# pin a release instead of tracking main (any tag works)
dsh plugin --profile web add github:jackovibe/dsh-codex-pin#v0.2.7

# from the tarball attached to a release (Releases → Assets)
dsh plugin --profile web add ./dsh-codex-pin-0.2.7.tgz

# from a checkout
npm run build && npm pack && dsh plugin --profile web add ./dsh-codex-pin-0.2.7.tgz

# from npm (once published)
dsh plugin --profile web add dsh-codex-pin

The github: spec is what this plugin's own development profile uses, so it is exercised on every local run; the npm name is reserved for a later publish and does not resolve yet.

Then restart dsh web (the loader composes bundle layers at boot) and hard-refresh the browser (Ctrl+Shift+R). Open the sidebar: session rows now carry the pin control on hover.

How it mounts

The package ships a bundle patch (cordis.patch.yml) that inserts exactly one loader entry:

- insert:
    - id: codex-pin
      name: dsh-codex-pin

dsh plugin add reconciles dsh.profile.bundles by itself, so do not also add this insert to your profile's own cordis.patch.yml: two layers inserting the same loader id fail the boot. Check the composition before restarting:

dsh --profile web --dump-config | grep -c 'id: codex-pin'   # must print 1

Upgrade / uninstall

# upgrade: re-run the same spec (adds the newest commit on main, then restart)
dsh plugin --profile web add github:jackovibe/dsh-codex-pin
# or move to a specific release
dsh plugin --profile web add github:jackovibe/dsh-codex-pin#v0.2.7

dsh plugin --profile web remove dsh-codex-pin       # uninstall, then restart

Session ids stay in settings.yaml under codex-pin after uninstalling; delete that block to clean up.

Usage

Action	How
Pin / unpin a session	hover the row, click the pin control (📌 toggles)
Open a pinned session	click its row in the 已置顶 / Pinned section
Unpin from the section	click the filled pin on the section row
Rename / fork / archive / delete / copy title or id	right-click any session row for the row menu
Pin / rename / archive the current session	Ctrl+Alt+P / Alt+Ctrl+R / Ctrl+Shift+A

Pinned and unpinned rows carry the same pair of controls — the pin (outlined when unpinned, filled when pinned) and archive — and the rows inside the Pinned section carry them too, so archiving stays available while a session is pinned. The menu's red Delete session entry calls the archive manager's workspaceRegistry.deleteSession behind a confirmation dialog; without that plugin the entry reports why instead of failing silently.

Menu copy and tooltips follow the GUI language: the plugin registers zh/en dictionaries through ctx.inject(['locale']), so a Chinese GUI shows 重命名 / 置顶聊天 / 归档会话 / 删除会话 and an English GUI shows Rename / Pin chat / Archive session / Delete session — switching the language re-labels a running page with no reload.

Ctrl+Shift+A asks for confirmation before archiving the current session (a single global keystroke should not archive silently); the row menu's archive entry is a deliberate click and archives directly. Right-clicking a session row opens this plugin's menu — a Codex-style overlay. It only intercepts rows it can act on; a row without a session identity keeps whatever context menu it had. The app's own surfaces (multi-select, search, the settings pages) are untouched.

Configuration

Key	Default	Meaning
maxPins	0	Cap on pinned sessions; 0 = unlimited. Set it on the loader entry:

# profile cordis.patch.yml
- id: codex-pin
  config:
    maxPins: 5

When the cap is reached, the oldest pin is dropped as a new one is added, and a lowered cap prunes the view on the next read. Changing the cap re-composes the host plugin: an already-open page picks the new value up when the host pushes it (observed to take tens of seconds, and writes in that window can race the re-registration) — so refresh the page after changing the cap. The browser-local fallback has no policy to read, so the cap applies to the host-backed list.

Where state lives

What	Where
Pinned ids (newest first)	~/.dsh/settings.yaml → codex-pin.pinned
Browser-local fallback	localStorage key dsh.codex-pin.pinned
Session order	untouched — ~/.dsh/storages/workspace.json is never written by this plugin

Compatibility

DSH Web	Status
0.1.5-rc.1	verified (2026-09-16) — see Verification
0.1.2-rc.1 … 0.1.5-rc.2	inside the declared peer range, not tested by hand
any 0.2.x	not claimed; the peer range stops at <0.2.0

Tested alongside @michengai/dsh-archive-manager, which takes over the sidebar slot (sidebar.workspaces, priority −0.5): the Pinned section still rendered above the tree with zero page errors. Sidebar-rewriting plugins are the most likely source of breakage, because this plugin finds rows by React fiber props (see Limits).

Verification

Static checks need nothing but Node:

npm run check   # lib/client.js is byte-identical to src/client-src.js
npm test        # invariants: no order API, one loader entry, live e2e selectors

The e2e suites drive a running dsh web GUI with Playwright's Chromium. Point them at your instance with DSH_E2E_URL (a full URL including ?token=…) or let them read the URL the launcher logged into ~/.dsh/dsh-web.log; DSH_E2E_CHROMIUM overrides the executable path (any chromium-* build in the ms-playwright cache is found automatically). They need playwright-core from the dev dependencies:

node e2e/pin-e2e.mjs 3080              # pin -> tray -> open -> unpin -> persist
node e2e/pin-e2e.mjs 3080 --leave-pinned
node e2e/state-check.mjs 3080          # read-only: what the section shows now

Result of the run recorded in verification/ (redacted: tokens, session/workspace ids and titles are stripped before the records are written) against dsh web 0.1.5-rc.1 on 2026-09-16 (Windows, 5 session rows, 2 workspace groups, plugin installed from the packed tarball). The e2e run asserts every row of this table and exits non-zero when one breaks:

Check	Result
Client bundle in the boot graph	…,dsh-codex-pin/client.js,…; served after client-HMR re-hash
Pin controls injected on session rows	4 of 5 rows — the provisional New Session row carries no row actions
Pinned section above the workspace list	aboveTree: true
Pinned session leaves its group	hiddenRows: 1, back to 0 after unpin
Section row opens the pinned session	the click goes through sessions.open (single-page app: there is no URL change to assert)
Unpin restores the row	tray gone, hiddenRows: 0
DOM order unchanged by pinning	identical title sequence before and after
Stored on the host	settings.yaml → codex-pin.pinned, id read out of the row's React fiber props
Host order untouched	workspace.json sessionIds arrays identical before/after
Rendered from the host, not the browser	fresh headless context, no local state: 已置顶 · 1, noteShown: false
Tray controls present	markers tray, tray-head, tray-row, tray-pin, tray-archive, wrap tray-ctl
maxPins: 1	two pins leave only the newest, on write and on read; see verification/maxpins-check.md
Console / page errors	none

Development

lib/index.js        host half: registers the codex-pin settings namespace
src/client-src.js   browser half (the authored source)
lib/client.js       served bundle — built by `npm run build`, checked by `npm run check`
e2e/                Playwright suites against a running dsh web (dev dependency)
test/               dependency-free invariant tests (`npm test`)
verification/       redacted results of the runs quoted above
shots/              e2e screenshots (local only — not shipped, they show real titles)

lib/client.js is a copy of src/client-src.js (the loader wants a classic script registering window.__ModuleLoader__.load), so edit src/ and run npm run build; CI fails if the two drift apart.

Limits

• Row controls are found through React fiber props and the row's own action button. A DSH UI rewrite — or another plugin replacing the sidebar slot — can strand the per-row controls; the Pinned section keeps working.
• Pinned ids are never pruned automatically: a deleted session's id stays in the stored list but stops rendering.
• Pinned rows are hidden with display: none, which also removes them from their group's “show more” count.
• Pinning is per session; pinned workspaces (the other half of Codex's model) are not implemented.
• The row menu is a plugin-rendered overlay, not DSH's native context menu.

License

MIT — see LICENSE. The DOM layer is adapted from dsh-pin (MIT) and the host-backed store pattern from dsh-session-pin (Apache-2.0); see NOTICE.md and THIRD_PARTY_LICENSES.md.