English | 中文

dsh-project-session-store

DSH (DeepSeek Harness) plugin: keep each project's session logs inside the project directory, instead of everything centralized under ~/.dsh/sessions.

By default DSH stores every session under ~/.dsh/sessions/<project-key>/<session-id>/session.jsonl.zstd. This plugin replaces the built-in JSONL persistence backend so session data lives with the project:

<project>/.dsh/sessions/<session-id>/session.jsonl.zstd

Clone a repo, archive it, or move it to another machine — the conversation history travels with the project.

What it does

Concern	Behavior
Storage layout	<cwd>/.dsh/sessions/<session-id>/session.jsonl.zstd (same file format, same zstd frames — fully compatible readers)
Built-in backend	@deepseek-ai/dsh-session-persistence-jsonl is disabled in the composition tree; this plugin provides ctx.sessionPersistence instead
Legacy data	On first startup, sessions already under ~/.dsh/sessions are migrated once into their project's .dsh/sessions/ (keyed by each log's header cwd)
Unmovable sessions	Sessions whose cwd is gone, sessions without a cwd, and log files whose project directory is not writable stay in place under ~/.dsh/sessions and remain readable/resumable
Lookup index	A small pointer file ~/.dsh/sessions/index.json maps session-id -> project dir so resume-by-id and the cross-project Web session list keep working; it contains pointers only, never session data
Web UI	Session list still shows all projects grouped by project directory (it merges project-local plus any unmigrated leftovers)
No cwd sessions	Stay under ~/.dsh/sessions/_no-cwd/, exactly like the stock backend

Installation

dsh plugin --profile web add @yangzhe1991/dsh-project-session-store

Then restart dsh web (restarting is required — the composition tree changes).

Dev-mode install (local checkout):

# in ~/.dsh/profiles/web
# package.json dependencies:
#   "@yangzhe1991/dsh-project-session-store": "link:/absolute/path/to/dsh-project-session-store"
pnpm install

Notes & caveats

• Restart to activate. The plugin swaps the persistence row of the composition tree (session-persistence-jsonl gets disabled: true), applied at boot.
• One-time migration is best-effort and idempotent. Failures are logged and the leftover stays in the old location. A later startup retries it.
• Uninstall / rollback: remove the plugin from the profile (or set session-persistence-project-local: disabled: true and re-enable session-persistence-jsonl in cordis.patch.yml). Project-local sessions are then not visible to the stock backend — they live in the project. Either migrate them back manually or keep using this plugin.
• Cross-machine copy: when the project directory (including .dsh/sessions/) is moved to another machine, copied sessions are discovered (listed) and remain fully readable/resumable — the plugin resolves them by where the files actually live, not by the header cwd (which points at the source machine's path, unresolvable here). After a resume, new events are written back into that same physical file, so the log never splits. The exposed cwd is normalized to the session's real project directory on this machine, and ungrouped sessions are automatically attached to the matching (or auto-created) web workspace via the stock WorkspaceRegistry API — zero configuration, no hard-coded path mappings; anyone copying a project to any machine gets sidebar grouping out of the box.
• The ~/.dsh/sessions/index.json pointer file is irreplaceable-by-scan only for cross-project discovery: if it is deleted, the next session.list rebuilds it by scanning the old root, but project-local dirs outside the index are then only discoverable per-project.
• Version coupling: the plugin locks the exact DSH package versions it extends (@deepseek-ai/dsh-session-persistence-jsonl etc.). After upgrading the DSH runtime, bump the plugin to match before using it.

Configuration

The plugin row accepts these options (all optional):

- id: session-persistence-project-local
  name: '@yangzhe1991/dsh-project-session-store'
  config:
    # Central root: legacy fallback + pointer index location. Default: $DSH_HOME/sessions
    # root: /your/custom/root
    # Directory inside each project. Default: .dsh/sessions
    # projectDirName: .dsh/sessions

How it works

• Subclasses the official JsonlSessionPersistence, reusing its coordinator, zstd encoding, crash repair (torn-tail), and durability guarantees — only path resolution, listing, and discovery are overridden.
• Write path: <cwd>/.dsh/sessions/<id>/session.jsonl.zstd (sessions without cwd fall back to the central _no-cwd/).
• Read path (findLog by id): pointer index first, then a legacy-root scan fallback; the physical location hit is remembered in-memory so follow-up appends never split the log.
• One-time migration: moves each legacy log into its project dir (same filesystem rename, EXDEV fallback copy+unlink), updates the index, and prunes emptied legacy directories.

License

MIT