Back to directory

dsh-session-surgeon

In a curated listMaintenance: Active

xiaoshenming/dsh-session-surgeon

Scan sessions, inspect integrity issues, and dry-run or apply repairs with backups.

View on GitHubHomepage
$ dsh plugin --profile desktop add "github:xiaoshenming/dsh-session-surgeon#main"

16

stars

3

forks

JavaScript

Language

MIT

License

2026-08-18

Created

2026-11-08

Last push

MIT JavaScript DSH plugin that copies session IDs for continued chats and repairs DeepSeek Harness session logs that refuse to load — dry-run by default, `.bak.<utc>` before any write, no invented seqs, tool results or turn boundaries.

DSH integration

Native runtime

Author-claimed

Safety audit

Unaudited

Last verified

2026-11-16

License

MIT

01What can it help you accomplish?

  • Keep working from an earlier conversation: copy its session ID out of the session ⋯ menu and paste it into a fresh chat so the new session can read the old log

    The session ID on the clipboard and a pasted reference such as `Continue from session session-1e66cda9-a046-4893-8f4b-b817080acbea.` — or `session_inspect id=…` when the receiving agent has tools

    People who pass a thread id around the way Codex users do, and anyone who wants a new DSH session to build on an old one without forking a duplicate file

  • Get a session that refuses to open back into the harness — seq gap, torn zstd frame, a zero-filled tail after the last committed frame, `llm/retry` chains that do not sequence, lone surrogates, events missing their message id, `assistant/message` / `assistant/attempt` rows with settlement fields the seed/restore gate rejects

    A dry-run report naming each culprit row and field, or — with `--apply` — a rewritten log that was backed up to `.bak.<utc>` first, with `llm/retry` chains renumbered from 1 and their `retryId` unified

    Anyone whose `session.vN.jsonl.zstd` is already broken: the README states that a later loader fix from the maintainers cannot recover an already-damaged file

  • Sweep a sessions root and see which conversations are healthy before opening them or handing the machine to someone else

    `scan` lists sessions with header health and orphan `.tmp` files, `index` prints a session / parent / goal / health table, `--format text` renders a human table, and the exit code separates success (0), usage error (2) and not-found / refuse (1)

    Operators with more than one DSH home — the panel's session-root picker lists every home it finds — and anyone checking a machine after a crash

  • Shrink a long session down to its last few turns, or hand the log to someone else as JSONL instead of a binary zstd file

    A compacted session with seqs renumbered from 0, turns and steps renumbered from 1 and the seq references that stay inside the slice shifted — or a JSONL dump whose secrets are redacted by default

    People moving a session between machines or attaching a log to a bug report, where raw files from `~/.dsh/sessions` are a liability

02How to install into DeepSeek Harness

Prerequisites

  • DSH Desktop, or a DSH CLI profile — the profile this plugin is installed into lives in `~/.dsh/profiles/desktop`
  • The upstream git package added as `github:xiaoshenming/dsh-session-surgeon#main`; pnpm resolves `#main` to a commit tarball inside that profile
  • For local development the README pins the dsh version and the pnpm lockfile and asks for Node.js 24
  • Do not reinstall this checkout with npm — duplicate physical copies of `@deepseek-ai/dsh-tools` can make tool calls fail with `reading 'prepare'`

Installation steps

  1. 01

    In DSH Desktop open the **Plugins** page and add the upstream git package `github:xiaoshenming/dsh-session-surgeon#main`

  2. 02

    Or from a CLI profile: `dsh plugin --profile desktop add "github:xiaoshenming/dsh-session-surgeon#main"`

    $ dsh plugin --profile desktop add "github:xiaoshenming/dsh-session-surgeon#main"

  3. 03

    Update with the Plugins page's update action for this plugin, or `cd ~/.dsh/profiles/desktop && pnpm update dsh-session-surgeon` — no `dsh web` restart and no re-`add`

    $ dsh web

  4. 04

    Optional: make the bundled update skill visible to the DSH skill catalog with `mkdir -p ~/.dsh/skills` and `ln -sfn ~/.dsh/profiles/desktop/node_modules/dsh-session-surgeon/skills/dsh-session-surgeon-update ~/.dsh/skills/dsh-session-surgeon-update`

  5. 05

    For local development: `pnpm install --frozen-lockfile`, `export DSH_HOME="$HOME/.dsh-surgeon-dev"`, `./node_modules/.bin/dsh plugin --profile web add "link:$(pwd)"`, `./node_modules/.bin/dsh web`

  6. 06

    Without the plugin at all the CLI runs straight from git: `npx --yes github:xiaoshenming/dsh-session-surgeon scan`

    $ npx --yes github:xiaoshenming/dsh-session-surgeon scan

Verify the integration

  • Open a session's ⋯ menu in the left sidebar: it now offers 复制会话 ID, inspect and dry-run repair
  • The sidebar gains **会话医生 / Session surgeon**, a real center-column page for browsing conversations, copying an id, dry-running and applying a repair, previewing a compaction and exporting JSONL
  • In an agent chat, `session_scan` / `session_inspect` / `session_repair` are available and `apply` defaults to false, so the first repair call is a dry run
  • From a shell, `npx --yes github:xiaoshenming/dsh-session-surgeon scan` lists sessions with header health and orphan `.tmp` files

Rollback

  • If the desktop reports the plugin incompatible, remove it and add it again in the profile: `pnpm remove dsh-session-surgeon` then `pnpm add "github:xiaoshenming/dsh-session-surgeon#main"`
  • If that still resolves an old version, pin the commit: `pnpm add "github:xiaoshenming/dsh-session-surgeon#<sha>"`
  • A repaired session can be reverted from the `.bak.<utc>` file `--apply` writes before rewriting the log

03DSH integration and capability boundaries

DSH integrationNative runtime

DSH plugin — registers the 会话医生 / Session surgeon sidebar row and center-column page into the Desktop `sidebar.panellist` / `main` seats, adds the `session_scan` / `session_inspect` / `session_repair` agent tools, and installs with `dsh plugin --profile desktop add "github:xiaoshenming/dsh-session-surgeon#main"`

  • Copy session ID from the session menu

    nothing is duplicated on disk — the ID is pasted into a new chat by hand, unlike Fork, which duplicates a file
  • Repair a log the official reader refuses

    `--apply` rewrites the session log only after writing `.bak.<utc>` next to itwhen a crash-recovery closer collided with a still-live writer, the synthetic closers are dropped and the live tail kept instead of truncating at the first gap
  • Warn instead of inventing

  • Same operations from the CLI and as agent tools

    `session_repair` takes an `apply` flag that defaults to false, so the tool is a dry run unless it is turned on

04Who is it for? When not to use it?

Good for

  • People who pass a thread id around the way Codex users do, and anyone who wants a new DSH session to build on an old one without forking a duplicate file
  • Anyone whose `session.vN.jsonl.zstd` is already broken: the README states that a later loader fix from the maintainers cannot recover an already-damaged file
  • Operators with more than one DSH home — the panel's session-root picker lists every home it finds — and anyone checking a machine after a crash
  • People moving a session between machines or attaching a log to a bug report, where raw files from `~/.dsh/sessions` are a liability

Not for

  • Compatibility is a `peerDependencies` gate validated before loading: a range that excludes your harness leaves the plugin installed but never activated, `pnpm update` does not fix it and the plugin cannot report the failure itself because `apply()` never runs — remove and re-add it. The README's own check was against `@deepseek-ai/dsh@0.1.7-rc.2` and the 0.2.x line, most recently `0.2.2-rc.1`.
  • The tool stops where the log stops: unknown event types are reported but never deleted, and `compact` refuses an unloadable file and writes nothing until repair has run with all writers stopped.
  • Session logs carry user text and secrets: never commit raw files from `~/.dsh/sessions`, and `export` redacts `sk-*`, PEM blocks and home paths unless you pass `--no-redact`.

05Compatibility, maintenance and safety notes

  • Write paths are opt-in: the default is read-only, `--apply` writes `.bak.<utc>` first, and on Windows an `EPERM` from fsync on the read-only backup handle is now treated as best-effort instead of aborting after the copy already succeeded.
  • Compatibility is a `peerDependencies` gate validated before loading: a range that excludes your harness leaves the plugin installed but never activated, `pnpm update` does not fix it and the plugin cannot report the failure itself because `apply()` never runs — remove and re-add it. The README's own check was against `@deepseek-ai/dsh@0.1.7-rc.2` and the 0.2.x line, most recently `0.2.2-rc.1`.
  • The tool stops where the log stops: unknown event types are reported but never deleted, and `compact` refuses an unloadable file and writes nothing until repair has run with all writers stopped.
  • Session logs carry user text and secrets: never commit raw files from `~/.dsh/sessions`, and `export` redacts `sk-*`, PEM blocks and home paths unless you pass `--no-redact`.
2026-08-182026-11-08v0.1.0

MIT · latest release v0.1.0 (2026-08-18T06:41:58Z) · repairs DSH session logs that refuse to load

06Frequently asked questions

How do I install dsh-session-surgeon into DeepSeek Harness?

In DSH Desktop open the **Plugins** page and add the upstream git package `github:xiaoshenming/dsh-session-surgeon#main`, or run `dsh plugin --profile desktop add "github:xiaoshenming/dsh-session-surgeon#main"` from a CLI profile — the profile lives in `~/.dsh/profiles/desktop` and pnpm resolves `#main` to a commit tarball there.

Does repair touch my session file by default?

No. The default is read-only and repair is a dry run; `--apply` writes `.bak.<utc>` first, never invents missing seqs and fills missing message ids without dropping events. The agent tool behaves the same way — `session_repair` takes an `apply` flag that defaults to false.

How does it show up inside a DSH session?

As real Desktop UI, not an overlay: the session ⋯ menu gains 复制会话 ID / inspect / dry-run repair, and the sidebar gains **会话医生 / Session surgeon** as a center-column page for browsing conversations, copying an id, dry-running or applying a repair, previewing a compaction and exporting JSONL. In an agent chat the same work is available as `session_scan` / `session_inspect` / `session_repair`.

Which DSH versions does it work with?

The README verified it against `@deepseek-ai/dsh@0.1.7-rc.2` and the 0.2.x line DSH Desktop ships, most recently `0.2.2-rc.1`, with `SESSION_FORMAT_VERSION` still 4. If the desktop reports it incompatible, remove and re-add it in the profile (`pnpm remove dsh-session-surgeon`, then `pnpm add "github:xiaoshenming/dsh-session-surgeon#main"`) — a `peerDependencies` mismatch is validated before loading, so `pnpm update` will not fix it.

What will it refuse to repair?

Anything the log does not say. Missing seqs, a dangling `tool/call` with no `tool/result`, steps continuing a turn the log already closed, and an empty `tool_calls[].id` are reported and left alone; unknown event types are reported but never deleted; and `compact` refuses an unloadable file until repair has run with all writers stopped.

08Data and sources

  • Author-claimedgithub.com44d7b3b3f870…

    dsh plugin --profile desktop add "github:xiaoshenming/dsh-session-surgeon#main"

  • Author-claimedgithub.com44d7b3b3f870…

    The Desktop shell (bundled `@deepseek-ai/dsh-web-frontend@0.2.0-rc.2`) is what serves the `sidebar.panellist` / `main` s…

  • Author-claimedgithub.com44d7b3b3f870…

    Agent tools after install: `session_scan` / `session_inspect` / `session_repair` (`apply` defaults to false).

This page is generated from the project’s public documentation, repository metadata and a structured parse of DSH Plugins; last verified on 2026-11-16. Found an error? Submit a correction.

🏆

Best DeepSeek Harness Plugins

Twelve plugins worth installing first — picked from the whole catalog, across every category.

DSH Plugins is an independent community directory of DeepSeek Harness plugins. Not affiliated with or endorsed by DeepSeek. Third-party plugins are not security-audited — review the source before installing.

New DeepSeek Harness plugins, weekly. No spam.