DSH plugin workspaces: ownership, pinning, and archival
"Archiving was refused" is not a permission problem; the workspace refuses to hide something still running. DSH plugin's archival admission asks composed providers what a session still has in flight before writing. Understand that rule, then read pinning and ownership.
Ownership truth is the ordered sessionIds
cwd validates membership; it never derives ownership.(source)
WorkspaceId is a branded identifier; consumers see only the Workspace interface while the implementation stays package-private.
The source of truth for ownership is the record's ordered sessionIds, never derived from a session's cwd. Membership validates the recorded header cwd against the workspace path; an existing candidate whose fully qualified cwd returns ENOENT during path resolution or directory stat still keeps its attribution — preserving bookkeeping when a directory is missing or a symlink broke, while admitting no new sessions.
Failure semantics are restrained: a failed write rejects (insertSessionBefore ledger errors reject with WorkspaceMoveInvalidError, storage failures with ordinary errors); every accepted change gets an updatedAt timestamp and persistently prunes candidates that no longer pass the membership check.
create is idempotent; delete removes records only
Deleting a workspace touches neither files nor sessions.(source)
WorkspaceRegistry owns registration and resolution:
create(path, title?)requires a fully qualified path, normalizes it, rejects nonexistent paths (passingENOENTthrough) and non-directories; it returns an existing entity verbatim when the canonical path is already owned; otherwise it creates a record titledtitle ?? defaultWorkspaceTitle(path)and prepends it to the persistent registry order;get(id)and orderedlist()are synchronous cache reads;resolveByPath(path)applies the same fully qualified realpath normalization without creating;delete(id)removes only the registry record, the order entry, and the session ledger — directories, user files, live sessions, and persisted logs stay untouched, so those sessions become Ungrouped; an unknown id returnsfalse.
create and delete first persist a pending mutation marker before their two writes (record and order) can diverge. Startup resolves exactly the marked mutation by deleting the marked table row: that completes an interrupted delete and rolls back an interrupted create (registration can be recreated, so rollback is the safe direction). An order table inconsistent without a marker fails loudly as corruption.
The creator assigns cwd
The registry assigns no cwd; it revalidates on attach.(source)
A session's cwd is assigned by its creator at creation, not by the registry. The API gateway resolves a new session's cwd from the selected workspace's path (falling back to an explicit or default cwd), creates the session first so the cwd lands in its immutable SessionHeader, then calls attachSession, which revalidates the stored header cwd against the workspace path.
On the first successful start, the registry bootstraps history from persisted headers alone (id, cwd, createdAt — never reading event bodies): it groups sessions with a valid canonical cwd into workspaces by directory, newest first, and writes the "initialized" mark last so an interrupted bootstrap can safely resume.
Bootstrap happens only once: legacy sessions without a cwd stay Ungrouped, and sessions created afterward can join only through attachSession.
The default workspace is a fixed directory
Automatic titles come from the directory name; display language lives in the browser only.(source)
The controller's initializeDefault accepts no request parameters: it owns the fixed directory name default-workspace, resolves the Documents location, and asks the registry to initialize once.
The registry receives a directory resolver, uses the last segment of the requested directory (not the canonical path) as the initial title, and commits registration together with the persisted identity.
Language never reaches the host — browser consumers label a workspace still carrying that automatic title through the controller's workspaceDisplayTitle, so only the on-screen name follows the reader's language. That split means switching languages needs no host data change.
Pinning: full arrays, newest first
Archiving removes pins along the way; unarchiving restores nothing.(source)
The controller's transport types define WorkspacePinSessionRequest and WorkspaceUnpinSessionRequest, each carrying one sessionId.
Both operations return WorkspacePinValue: the complete pinnedSessionIds array with the most recent pin first. So clients should not maintain their own increment — replace with the returned value.
Three rules: pinning requires a known, unarchived session; unpinning an id that is not pinned succeeds and changes nothing; archiving removes that session's pin in the same persisted write, and unarchiving does not restore it.
Archival admission: ask what is still running
Activity means rejection unless you explicitly ask to stop it first.(source)
Archiving is a registry-global persisted set, and the registry refuses to hide running work behind it. That rule is a capability seam over two host events this package declares and dispatches:
workspace/session-activity(waterfall) asks composed providers what a session still has running;workspace/session-stop(parallel) asks them to stop that work.
Each provider registers at the root like any listener, so this package knows nothing of agent, job, or schedule vocabulary; each family is a key in a merge-extensible map. The shipped providers merge turn (agent registry), job (jobs seam), subagent (subagent runtime), and schedule (the schedule plugin).
SessionActivityKindMap is empty in this package, so a program compiling no providers sees no keys. Providers answer the waterfall by prepending their SessionActivity entries to the next() result; the registry's innermost callback returns an empty list, so a composition without providers can archive freely.
archiveSession(sessionId) asks the waterfall once after the existence check and, on any non-empty answer, rejects with WorkspaceActiveSessionError (sessionId, activity) without writing; the controller maps it to a workspace/session-active error whose details carry the same two fields.
archiveSession(sessionId, { stopActivity: true }) skips the check, writes the archive first, then dispatches workspace/session-stop; provider throws are only logged, the archive stands, and stopped work is never awaited to converge. An already archived id is neither queried nor stopped.
Verification: pin two workspaces, then archive
Check ordering, the rejection path, and the no-restore rule together.(source)
- Pin session A then B and assert B precedes A in
pinnedSessionIds. - Unpin an unpinned C and assert success with an unchanged array.
- Give a session running work, call
archiveSession, and assertWorkspaceActiveSessionErrorwith a non-emptyactivity. - Retry with
{ stopActivity: true }and assert the archive succeeded and the pin was removed in the same write. - Unarchive and assert the session returns while pins stay unrestored.
deletethe workspace and assert the session becomes Ungrouped with disk files and session logs intact.
If step 3 rejects without activity, some provider returned empty entries instead of real activity detail; inspect the merged results of each family's providers first.
For workspace concepts and selection, see workspace explained and workspace configuration; for persistence-side recovery boundaries, see the persistence seam.
One line to close: ownership rides ordered sessionIds, create is idempotent while delete drops records only, the creator supplies cwd, pinning returns full arrays, archiving asks about activity first, and unarchiving restores no pins.
FAQ
No. DSH plugin treats the ordered sessionIds in the record as the source of truth. DSH plugin states ownership is never derived from session cwd, which only validates membership.
No. DSH plugin removes only the registry record, the order entry, and the session ledger. DSH plugin leaves directories, user files, live sessions, and persisted logs alone, so those sessions become Ungrouped.
No. DSH plugin removes pins in the same write as the archive. DSH plugin's unarchive restores accessibility only, never the pinned set.
DSH plugin rejects with activity details. DSH plugin throws WorkspaceActiveSessionError carrying sessionId and activity, which the controller maps to a workspace/session-active error.
Related Terms
- WorkspaceId
- WorkspaceId is the branded identifier of a workspace record; consumers see only the Workspace interface while the implementation stays package-private.— packages/workspace/workspace/src/types.ts
- WorkspaceRegistry
- WorkspaceRegistry owns workspace registration and resolution, providing create, get, list, resolveByPath, and delete.— packages/workspace/workspace/src/types.ts
- WorkspacePinValue
- WorkspacePinValue is the pin operation result with the complete pinnedSessionIds array, newest pin first.— packages/workspace/workspace/src/types.ts
- SessionActivity
- SessionActivity is one archival admission reason with a family kind and optional per-item items.— packages/workspace/workspace/src/types.ts
Sources
- DeepSeek Harness reference - Workspace· deepseek-ai
- packages/workspace/workspace/src/types.ts· deepseek-ai