dsh-session-move

Readme

# dsh-session-move

A DeepSeek Harness feature bundle for moving an existing cold DSH session between two DSH workspaces while preserving its `SessionId` and event history. The interactive target is the existing session-title row in the DSH Web sidebar; this package does not import Claude Code or other external transcripts.

## Current iteration

The service exposes a read-only `ctx.sessionMove.inspect({ sessionId, targetWorkspaceId })` dry-run that reports:

- source and target workspace identity;
- source and target JSONL locations;
- immutable source/target headers;
- persistence revision;
- physical row and logical event counts;
- contiguous seq bounds;
- raw-artifact and logical-event SHA-256 values;
- stable blockers such as live, archived, missing, same-workspace, unsupported backend/core capability, or target collision.

It uses `SessionPersistence.readRaw()` rather than `inspect()`, so the dry-run does not populate a prepared-session cache. The inspection itself performs no mutation.

With all revision-fenced core patches applied, the service registers itself as the one `WorkspaceRegistry` cold-session mover. The official Web sidebar then executes `workspace.moveSession({ targetWorkspaceId, sessionId, beforeSessionId? })` through the typed Host RPC gateway, the registry validates the commit and emits the authoritative `workspace/session-moved` frame, and clients replace the session cwd plus both Workspace snapshots without optimistic membership edits. A private durable journal under configured `root` recovers or restores persistence cwd, lifecycle-bound message feedback, workspace accounting, and manual target/source order after interruption. It verifies the final header, unique effective workspace owner, event count, and logical-event SHA-256 before deleting the journal. The `./invariant` companion rejects publication if any startup move journal remains unresolved.

## Move semantics

A final move changes only the session header `cwd` and its workspace account. It preserves ID, creation time, lineage, preset, every logical event, and external `dsh-session:` references. Future tools and sandbox policy use the destination workspace. The first release is JSONL-only and cold-session-only.

See `docs/phase-2-design.md` for the core relocation seam, crash journal, rollback protocol, and UI integration plan, and `docs/distribution.md` for installation, support matrix, and rollback. Reproducible first-party changes are stored as a revision-fenced patch series under `patches/deepseek-harness/`; validate the current series with `node scripts/apply-core-patches.mjs <checkout> --check`.

## Installation

Full capability requires a DSH built from the exact public base with the bundled
first-party patch series applied. The npm package is the runtime plugin; the
patch bundle builds the runtime.

| Runtime | `ctx.sessionMove.inspect()` | Sidebar drag move |
| --- | --- | --- |
| Exact public base `47f943859bef60e4160492346772ded9b24f765a` + the bundled patches, built from source | Yes | Yes |
| Official installed rc.6, unpatched | Yes (read-only) | No — every move is refused with the `unsupported` blocker |

Quick install after the patched DSH build:

```sh
dsh plugin --profile <profile> add dsh-session-move
# or, from a packed tarball (also works with `pnpm dsh` in a source checkout):
DSH_HOME=<dsh-home> pnpm dsh plugin --profile <profile> add ./dsh-session-move-0.1.0.tgz
dsh --profile <profile> --dump-config
```

For the complete build-from-exact-base, installation, verification, provenance,
and rollback steps, see `docs/distribution.md`. Use an isolated profile for
first-time checks; a profile containing only `@deepseek-ai/dsh-base` fails
activation with "did not activate (waiting for workspaceRegistry,
messageFeedback)" until a host bundle is present.

## Model Experience

Inspection and journal orchestration add no prompt, message, tool schema, tool result, or model selection. A completed explicit move preserves historical events but changes future working-directory-derived instructions, skills, tools, and sandbox context to the destination.

#### KV Cache effect

Inspection consumes no model tokens and does not affect cache. A completed move retains the event stream but a resumed request may not reuse provider cache entries whose system context includes the old cwd.

## Known Limitations and Deferred Work

- Official installed DSH rc.6 has no relocation or mover capability, so an unpatched runtime only gets the read-only `inspect()` service. Drag-to-move requires the user-built patched DSH: exact public base `47f943859bef60e4160492346772ded9b24f765a` plus the bundled 8-patch series, which adds the cold lifecycle lease, coordinator seam, recoverable POSIX JSONL transaction, mover registration, typed `workspace.moveSession` RPC, authoritative `host/session-moved` frame, and official sidebar cross-group drag. This package never patches an installed DSH on its own.
- The service injects the workspace/feedback host layer: a `dsh-base`-only profile fails activation with an explicit "did not activate" error until a host bundle (`dsh-headless`/`dsh-web-app`) is present.
- SQLite and Windows relocation are deferred; the first Provider implementation is POSIX JSONL only.
- Cross-group drag is verified in official UI tests and the assembled Host integration; a real GUI profile drag has not yet been exercised.
- Filesystem locks stay defense-in-depth under DSH's one-live-writer-per-session/process model; they do not make concurrent live writers cross-process transactional.
- No active profile or real session is modified during development.
- Public source commit `47f943859bef60e4160492346772ded9b24f765a` labels itself rc.5, while the installed runtime is rc.6; exact build provenance is unavailable.