dsh-workspace-promote

Readme

# dsh-workspace-promote

English | [中文](README.zh.md)

A DeepSeek Harness (DSH) host plugin that promotes the workspace you just submitted a task in to the top of the sidebar — **once per submission, and never while the task is running**.

One command, no patch editing — the package ships its own profile bundle patch:

```bash
dsh plugin --profile web add dsh-workspace-promote
```

Restart `dsh web` afterwards (host-plane plugins mount at boot).

## The gap it fills

DSH's sidebar handles the two layers very differently:

| Layer | Native behaviour | Enough? |
|---|---|---|
| Sessions inside a workspace group | View options default to `orderBy: "updated"`; a session with new activity is promoted to the top of its group | ✅ Native, no plugin needed |
| Workspaces themselves | Order comes from the durable `workspaceIds` array, i.e. **manual drag order**; it never reacts to what you are actually working on | ❌ This plugin |

So if you want "whatever project I am working on floats to the top", only the workspace layer is missing, and that is exactly what this plugin adds.

## Trigger semantics

The plugin reorders on exactly one condition: a `user/message` event whose `data.source.kind === "user"` — a prompt a **human actually submitted**.

The same `user/message` event also carries two other kinds of content, distinguished by `source.kind`. All of them are ignored:

| `source.kind` | What it is | This plugin |
|---|---|---|
| `user` | A direct human prompt | ✅ promotes |
| `plugin` | Synthetic `agent.inject()` context (file-change notices, AGENTS.md, skill content, cron notifications) and goal continuation rounds | ❌ ignored |
| `tool` | A tool result (`role` is `user` too) | ❌ ignored |

Execution-time events — `assistant/message`, `step/start`, `step/end`, `turn/start`, `turn/end` — are ignored as well.

**Net effect: one submission, one promotion.** The sidebar does not move while a task is being executed.

Hooking the raw `session/event` feed instead (the obvious first implementation) is what makes the sidebar jump continuously, because tool results are themselves `user`-role events.

## How it works

- On a qualifying event it calls `workspaceRegistry.insertBefore(id, currentFirst)`.
- If the workspace is already first, or there are fewer than two workspaces, it returns immediately and **writes nothing** — so bursts of events cannot cause a write storm.
- No state file: `insertBefore` mutates the durable `workspaceIds` order, so the result survives restarts for free, with no "insufficient activity samples after restart" problem.
- Ungrouped sessions and subagent child sessions do not participate.
- Any failure is logged only; it never affects the session itself.

## Audit log

`~/.dsh/workspace-promote.log` (honours `DSH_HOME`). Append-only, and useful for answering "which behaviour is this process actually running, and when exactly did it fire":

```
2026-09-15T09:31:44.809Z boot pid=49220 trigger=human-prompt-only
2026-09-15T09:33:11.770Z promote workspace=039cce9b-... session=session-1ee5c45f-... from=a6680e0c-...
```

`ctx.logger` output has no guaranteed destination; this file does.

## Trade-off

Real-time ordering competes with manual drag: if you drag workspace B to the top and then submit a task in A, A returns to the top. That is inherent to "dynamic ordering", not a bug.

## Difference from `dsh-workspace-sort`

[`dsh-workspace-sort`](https://www.npmjs.com/package/dsh-workspace-sort) also orders workspaces by activity, but its semantics are **"re-sort at most once per calendar day, then stay frozen"** — the order in the morning reflects activity up to yesterday. This plugin triggers on the **user's submission action** instead, and keeps no state file.

Pick `dsh-workspace-sort` if you want the sidebar to stay put all day; pick this one if you want the project you are actively working on to be on top.

## Verify

1. Submit a task in some other project → that project jumps to the top.
2. Watch the task execute (many tool calls, many steps) → the sidebar should **not** move again.
3. `~/.dsh/workspace-promote.log` should gain exactly **one** `promote` line per submission.

## Uninstall

```bash
dsh plugin --profile web rm dsh-workspace-promote
```

Then restart `dsh web`. If you instead wired it by hand into `cordis.patch.yml`, delete that `workspace-promote` row and restart.

> Note: do not run both install paths at once. If you added the row manually and later install the package as a bundle, the same row id would be inserted twice — remove one first.

## License

MIT