# dsh-workspace-status-badge · Workspace Status Badge

<div align="center">
  <a href="README.md">中文</a> · <b>English</b>
</div>

> **Collapse a workspace and still see, at a glance, what is going on inside.**
> Session rows in the sidebar carry their own status dots, but once a workspace
> folder is collapsed those dots disappear — this plugin aggregates the
> workspace's session states into **one badge between the folder icon and title**.

[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.3.0-blue.svg)](https://github.com/AFAP/dsh-workspace-status-badge/releases)

No configuration needed.

## 1. What problem it solves

The DeepSeek Harness sidebar groups sessions under workspaces; each session row
shows a status dot:

| State | Color | Meaning |
|:---:|:---:|---|
| Waiting for you | Amber | Approve / review plan / answer a question |
| Running | Blue | The session or one of its subagents is active |
| Completed | Green | Finished but not opened yet |

But the dot lives **on the session row only**: collapse a workspace and every
session row disappears — the folder row itself is just an icon plus a label,
with no hint of what is running or waiting inside.

This plugin aggregates the state up to the workspace level, with the same
priority as the per-session dots: **waiting > running > completed**.

## 2. Features

- ✅ Aggregate status badge between the folder icon and title of **collapsed**
  workspaces, styled like the official `StateDot` (same colors, same pulsing "ongoing" animation)
- ✅ While a workspace has running work, its **folder glyph tints light blue**
  (visible expanded and collapsed)
- ✅ Hover tooltip with the breakdown: "2 waiting for you · 1 running …"
- ✅ **Clicking the badge = clicking the folder row** (expands / collapses)
- ✅ Fully reactive client-side: states update live as sessions start, stop or
  wait for you
- ✅ Subagents count: a running subagent chain marks the workspace "running"
- ✅ The Ungrouped bucket is supported too
- ✅ UI language follows the app (Simplified Chinese / English)

## 3. Directory layout

```
dsh-workspace-status-badge/      # repo root = npm package root
├── package.json                 # dsh.bundle.patch + dsh.client declarations
├── cordis.patch.yml             # composition row: registers into the web roster
├── LICENSE                      # MIT
├── README.md / README.en.md     # bilingual docs
└── lib/
    ├── index.js                 # host half: deliberately inert (no backend needed)
    └── client.js                # browser bundle: aggregation + shell.overlay layer
```

## 4. Quick start (GitHub)

```powershell
dsh plugin --profile web add github:AFAP/dsh-workspace-status-badge
```

Then **restart `dsh web`** to load it.

> After install the plugin lives at `$DSH_HOME\profiles\web\node_modules\dsh-workspace-status-badge`.
>
> Upgrade: `dsh plugin --profile web update dsh-workspace-status-badge`
>
> Uninstall: `dsh plugin --profile web remove dsh-workspace-status-badge`

### Manual install from a source directory (equivalent check)

```powershell
dsh plugin --profile web add "D:\path\to\dsh-workspace-status-badge"
```

### Verify it loaded

Collapse any workspace in the left sidebar — if it contains sessions, a badge
appears between the folder icon and title (amber / blue / green); hover for
details, click to expand.

## 5. Usage and state semantics

Badge colors match the official session dots:

| Display | Meaning (aggregated over all sessions in the workspace) |
|---|---|
| <span style="color:#E6A23C">●</span> Amber (waiting) | At least one session waits for you: approval / plan review / question |
| <span style="color:#3B82F6">▦</span> Blue pulse (running) | At least one session is running, or a subagent chain is active |
| <span style="color:#22C55E">●</span> Green (completed) | At least one session finished and is not opened yet |
| Hidden | All sessions in the workspace are idle (same as per-row idle hiding) |

- Priority: waiting > running > completed, exactly like the per-session rows.
- Badges show **only when collapsed**; expanded groups show per-session dots and
  do not duplicate the folder badge.
- Subagent sessions do not get their own row, but keep a parent workspace marked
  "running" while they are active.

## 6. Known boundaries

| Situation | Behavior |
|---|---|
| Flat "In one list" view | No folder rows; no badges (expected) |
| Sidebar collapsed to the rail | The tree is hidden; no badges (expected) |
| Search mode | The tree is replaced by results; no badges (expected) |
| Very narrow viewport | Badges track the folded folder positions inside the viewport |

How it works: the plugin mounts in the frame-wide `shell.overlay` slot, locates
folder rows through the semantic anchor `[role="treeitem"][aria-expanded]`
(session rows use `aria-selected`, so they never match), maps rows 1:1 onto the
derived group order, and keeps positions in sync with a MutationObserver plus
scroll/resize listeners. If a future DSH release changes the row structure or
order, the counts stop matching and the plugin **hides itself** instead of
painting badges in the wrong place.

## 7. Safety & compliance

- **Zero backend**: the host half is an empty module; no HTTP route is exposed;
- **Read-only snapshots**: all data comes from the browser's `useSessions` /
  `useWorkspaces` framework hooks (Harness's own runtime stores); the plugin
  never reads, writes or touches session logs or files;
- **No credentials, no network**: no external calls, no data leaves the machine;
- **No configuration**: nothing to set up.

## 8. FAQ

**Q: Will the badge be confused with the per-session dots?**
A: Colors, shape and animation are identical to the official `StateDot` (the
"ongoing" state uses the same 3×3 chasing-square animation). The only difference
is placement — between the folder icon and title of a collapsed row, meaning
"the most urgent state among this group's sessions".

**Q: Why not show it when expanded?**
A: Expanded groups already show per-session dots; a folder badge would be
redundant. It is intentionally collapsed-only.

**Q: Do subagents affect the state?**
A: Yes. Subagent sessions do not occupy a workspace row, but while one is
running the workspace is marked "running" — matching how official session rows
count subagent activity.

**Q: The badge disappeared after a DSH upgrade?**
A: On a major row-structure change the plugin hides itself (count mismatch) and
never misplaces badges. Usually no action is needed; if it stays broken, file an issue.

## 9. License

MIT © AFAP