DSH plugin sameWorkspace: three states, one boolean
In DSH plugin, sameWorkspace is not "looks like the same project"; it is a strict compression of three states: true only when cwd is recorded and equal, false otherwise. Hosts may group by it, but reading "false" as "definitely another project" produces wrong labels.
DeepSeek Harness: The awkward "same project" badge
Some candidates carry cwd, some do not, and a frontend cannot compare uniformly. (source) Scene:
candidate 1 cwd=/repo/app sameWorkspace=true
candidate 2 cwd=/repo/docs sameWorkspace=false
candidate 3 cwd missing sameWorkspace=false
Write candidate.cwd === currentCwd yourself and candidate 3 evaluates undefined === '/repo/app', which is false — identical to candidate 2.
The meanings differ completely: candidate 2 really is in another directory, while candidate 3 is unknown. Collapsing unknown into different tells users that session lives in another project.
DeepSeek Harness: The truth table
Exactly one case is true; the other two are false. (source) Truth table:
| Source cwd | Relationship to requester cwd | sameWorkspace |
|---|---|---|
| Recorded | Equal | true |
| Recorded | Different | false |
| Missing | Not comparable | false |
The official comment adds a key sentence: hosts that only show whether the location differs should read this field instead of comparing paths they never received.
That sentence reveals the design motive: some hosts cannot obtain the other cwd at all and only want a yes/no answer.
DeepSeek Harness: Why hosts should not compare paths
Three reasons: absence, normalization, and permissions. (source) Breaking them down:
- Absence — the other cwd may be unrecorded, so comparison has no input;
- Normalization — trailing slashes, relative segments, and case are not equivalent across platforms;
- Overreach — equal paths do not imply equal permissions, and a comparison result invites misuse.
The first is a hard constraint: no value, no comparison. The second means even with a value, a frontend should not do string equality.
So the value of sameWorkspace is not saving a line of code; it moves "can this be compared at all" to the layer that knows both sides.
DeepSeek Harness: What a missing cwd means
It means the candidate remains usable, with an unknown location. (source) Missing does not mean a corrupted session or a remote one.
Possible causes include migration of old sessions, a session created without recording a directory, or a source that does not expose paths. The official field description says "when recorded", which makes absence an expected state.
Handling rules:
- Do not filter candidates out because cwd is missing;
- Do not render absence as "another project";
- Use neutral copy such as "location unknown" when display requires something.
These rules prevent users from deleting or selecting the wrong session.
DeepSeek Harness: Three grouping options
From least to most information; pick one. (source) Comparison:
| Approach | Basis | Fits |
|---|---|---|
| Two groups | sameWorkspace | Only "current project vs other" |
| Three groups | sameWorkspace plus cwd presence | Needs an "unknown" bucket |
| Full path groups | cwd | Organizing by directory tree |
Three groups is the balance most products settle on: same directory, other directory, unknown. It avoids exposing full paths and keeps unknown out of other.
If you choose full path groups, still handle a missing cwd, or you will render an empty "undefined" group.
DeepSeek Harness: Verifying the flag
Build one candidate per state and check the truth values. Steps:
- Create a session with the requester's cwd and confirm
sameWorkspaceis true; - Create a session with a different cwd and confirm false, with cwd present;
- Create a session without cwd and confirm false, with cwd absent;
- Put all three in one list and confirm grouping does not merge cases 2 and 3.
Step 4 is a UI-level assertion: if 2 and 3 land in one group, grouping used only the boolean and ignored whether cwd exists.
Document one more thing: sameWorkspace says directories match, not permissions. A same-named directory on another machine can also be true, so it is not an access-control signal.
Candidate cwd is for display and grouping only; do not log it verbatim in user-facing logs, since paths may contain user names.
With location settled, ordering is next. Read DSH plugin candidate ranking and self exclusion; for display names, read DSH plugin session candidate names; for the wider picture, read how DSH plugin implements session references.
Sources: DeepSeek Harness reference - Session references, session-reference/src/types.ts
FAQ
DSH plugin returns true only when the source session's cwd is recorded and equals the requesting agent's cwd. Every other case, including a missing cwd, is false.
Because DSH plugin allows cwd to be missing, and path strings can differ in trailing slashes, relative forms, or case. DSH plugin records the answer on the side that actually knows both values.
No, a false DSH plugin value does not mean another project. False covers both 'recorded and different' and 'not recorded'. Treating the second as another project misleads users, so check whether cwd exists before labeling.
No, DSH plugin still returns candidates with a missing cwd. A missing cwd is an expected state for migrated or untracked sessions. DSH plugin still returns the candidate; show it under an unknown-location group instead of dropping it.
Related Terms
- sameWorkspace
- sameWorkspace is true only when the source session's cwd is recorded and equals the requester's cwd; otherwise it is false.— DeepSeek Harness reference - Session references
- cwd
- cwd is the working directory recorded for a session; it is optional on candidates and may be absent.— session-reference/src/types.ts
- three-state grouping
- Three-state grouping separates same directory, other directory, and unknown directory instead of collapsing unknown into other.— DeepSeek Harness reference - Session references
- path normalization
- Path normalization reconciles trailing separators, relative segments, and case differences that make string comparison unreliable.— session-reference/src/types.ts
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/types.ts· deepseek-ai