# Archived Sessions · archive-manager

> A real "archive center" for **DeepSeek Harness (DSH)**: see every archived session grouped by workspace, restore one back to its exact place, or wipe its local storage for good — no ghost rows, no unopenable sessions, no reload required.

**English** · [简体中文](README.md)

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Platform: DSH Web](https://img.shields.io/badge/platform-DSH%20Web-4f46e5.svg)](#compatibility)
[![Version](https://img.shields.io/badge/version-1.2.0-success.svg)](https://github.com/jiulanyanyue-boop/dsh-archive-manager)
[![No build step](https://img.shields.io/badge/bundled%20JS-no%20build%20step-orange.svg)](#architecture)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)

**English** · [简体中文](README.md)

![Archived sessions](screenshots/e2e-01-section.png)

---

## What this is

DSH's built-in "archive" is nothing more than a **hide switch**: it makes a session disappear from the sidebar. That's it.

- You **cannot see** how many sessions you archived, how much space they take, or which workspace they belong to.
- To find a session from three months ago, you have to scroll the entire sidebar.
- To reclaim space by permanently clearing archived sessions, DSH **has no such feature**.
- Worse: after deleting storage files by hand, the sidebar keeps listing **ghost sessions that fail with `ENOENT`** the moment you click them.

`archive-manager` fills that gap. It adds a full page under **Settings → Archived Sessions** and turns archiving from a one-way hide into a complete lifecycle: inspect, restore, permanently delete.

**Plain client JS + host routes. No build step, no npm dependencies, no external service.** Restart DSH once after installing and you're done.

---

## The real problems it solves

This page is not a thin wrapper over existing APIs. Each row below is a long-standing trap that this plugin closes:

| Problem | What it looks like | What this plugin does |
| --- | --- | --- |
| **Archived content is invisible** | Archiving means "gone from the sidebar"; you have no idea what's left | Groups everything by workspace: title / archived-at / last activity / size on disk / whether files still exist |
| **No archive timestamp anywhere** | DSH only persists the *set of archived ids* — **it never stores when** | The plugin keeps its own index `archive-times.json`, records the first observation of archiving, writes atomically, and prunes on restore/delete |
| **Restore can't find "where it was"** | Guess by scrolling the sidebar | Restore goes through `unarchiveSession`; the workspace record is **left untouched**, so the session returns to its exact workspace and position |
| **Ghost rows survive deletion** | Files deleted, but the sidebar still lists it, it still opens, and sending a message throws `ENOENT` | Delete stops activity via `workspace/session-stop` → detaches the live session via `detachEntered` → then removes disk → clears records → drops the archive entry |
| **Deletion only half happened** | Files gone but the workspace record remains, leaving a permanently unopenable entry | Delete semantics changed to "erase **every** local trace of this session": disk / records / archive set / time index |
| **UI leftovers need a manual refresh** | You must close and reopen the settings page after deleting | Remove the row locally + `ctx.sessions.refresh()` + sequenced reconciliation — **effective within the same page** |
| **Refresh races resurrect deleted rows** | Concurrent `/state` responses arrive out of order and stale data overwrites fresh state | `/state` reads are sequenced and single-flight; stale responses are discarded |
| **Historical leftovers never get cleaned** | No file on disk, still recorded in a workspace — accumulating forever | `POST /repair` plus a silent, idempotent self-check 3 s after startup; the page also offers a one-click banner when it detects leftovers |

---

## Features

| Capability | Details |
| --- | --- |
| **Dedicated settings page** | `Settings → Archived Sessions`, using the host-reserved `settings.section` (id `archived-sessions`, order 25, right after "Agent presets"; icon is the archive box rather than the default gear) |
| **Grouped by workspace** | Each group shows workspace title + directory name + count; sessions no longer owned by any workspace go into a separate "Ungrouped sessions" group |
| **Complete row metadata** | Full title (never truncated; long titles wrap), archived-at (absolute + relative), last activity, created-at, size on disk; a red hint when storage is missing |
| **Restore** | Unarchives immediately and puts the session back to its original workspace and position; visible in the sidebar **without a page reload** |
| **Permanent delete** | Confirmation (shows how many entries and roughly how much space) → stop activity → detach live session → remove disk → clear records → drop archive entry → clear index |
| **Stale-reference cleanup** | Automatic + manual; cleanup only touches workspace records and never removes an existing session's files |
| **Actions on hover** | "Restore / Delete" are hidden by default and fade in on hover or keyboard focus; always visible on touch devices — a clean list without sacrificing discoverability |
| **Theme-faithful** | Colors, fonts, spacing and radii all reference host variables (`--dsw-alias-*` / `--dsw-radius-*`); looks native in light, dark, and any skin |
| **Bilingual** | Dictionaries switch through the host `locale` service — not hard-coded strings |
| **Accessible** | `role="dialog"` / `aria-labelledby` / Escape to close / focus handling / keyboard reachable |
| **A warmer empty state** | A whale illustration instead of a cold "no data" |

---

## Screenshots

**List: grouped by workspace, just the right density**

![Actions on hover](screenshots/e2e-02-hover.png)

**Permanent delete: explicit confirmation with counts and size**

![Delete confirmation](screenshots/e2e-03-confirm.png)

**Empty state**

![Empty state with whale](screenshots/empty-03-section.png)

---

## Installation

### Prerequisites

| Item | Requirement |
| --- | --- |
| DSH | Web / desktop, **verified on 0.2.1-rc.2** (depends on `webServer`, `workspaceRegistry`, `sessions`) |
| Node | `>= 22.19.0` (the DSH bundled runtime is enough; nothing to install) |
| Build | **Not needed.** The repository already contains runnable artifacts |

### ⚠️ Read this first: do not install by bare package name

This package is named `archive-manager`, but **both `archive-manager` and `dsh-archive-manager` are already taken on npm by other people**. DSH's "Add plugin" treats a bare package name as an npm package, so:

| You type | What actually gets installed | Result |
| --- | --- | --- |
| `archive-manager` | Someone else's npm package | ❌ Different plugin, most likely incompatible with your DSH |
| `dsh-archive-manager` | Someone else's npm package (peer `0.1.0-rc.6`) | ❌ `Plugin ... is incompatible with dsh 0.2.1-rc.2` |
| **`https://github.com/jiulanyanyue-boop/dsh-archive-manager`** | **This repository** | ✅ Correct |

**Bottom line: use the full GitHub URL, not a bare package name.**

### Option 1: GitHub URL (recommended)

Open **Settings → Plugins → Add plugin** and paste:

```
https://github.com/jiulanyanyue-boop/dsh-archive-manager
```

Equivalent forms (all resolved by the DSH installer, all clone this repository):

| Form | Notes |
| --- | --- |
| `https://github.com/jiulanyanyue-boop/dsh-archive-manager` | Simplest — paste the browser URL |
| `github:jiulanyanyue-boop/dsh-archive-manager` | pnpm's GitHub shorthand |
| `https://github.com/jiulanyanyue-boop/dsh-archive-manager#v1.2.0` | Pin to a tag / branch / commit (**the tag must be pushed** — see "Development & publishing") |
| `git+https://github.com/jiulanyanyue-boop/dsh-archive-manager.git` | Explicit git protocol |

The installer first runs a `git ls-remote` reachability check (5 s timeout by default) and then hands the clone to pnpm.

> **Restart the DSH desktop app once after installing.** The profile composition is built once at startup (no HMR for profiles), so a new plugin entry only takes effect after a restart. After that, every operation (restore/delete) takes effect inside the page — no restart and no manual refresh.

### Option 2: Local directory / tarball (offline)

```powershell
# Build a tarball inside the repository
npm pack --pack-destination "$env:USERPROFILE\Downloads"
```

Then paste the **absolute path** of the tarball (or of the unpacked directory) into "Add plugin".
The "Install source" dropdown only applies to npm package names; a local path stays offline.

> Before packing, check that the `files` whitelist in `package.json` contains what you need.
> GitHub installation clones the whole repository and is not limited by `files`; only `npm pack` is.

### Option 3: Manual profile mount

1. Put the repository at `<DSH_HOME>/plugins/archive-manager`
2. Edit `<DSH_HOME>/profiles/<your-profile>/package.json`:
   - add `"archive-manager": "link:<DSH_HOME>/plugins/archive-manager"` to `dependencies`
   - append `"archive-manager"` to `dsh.profile.bundles`
3. Restart DSH

> **Install the package exactly once.** `archive-manager` is both the package name and the Loader entry id, so installing it twice creates duplicate entries. When switching sources, remove the old dependency and bundle entry first.

---

## Usage

### Archiving a session

The archive action itself is DSH's own (the "Archive" item in the session list); this plugin does not change it.
An archived session disappears from the sidebar **and shows up under Settings → Archived Sessions**.

### Restore

Hover the target row in the list → click **Restore**.

- The session is unarchived immediately and returns to its **original workspace and position**;
- It shows up in the sidebar without any reload;
- A notice appears at the top: *Restored "{title}"; the session list has been refreshed.*

### Permanent delete

Hover → click **Delete** → confirm → **Delete permanently**.

The confirmation tells you **how many storage entries and roughly how much space** will be removed. After confirming, the steps run in a fixed order:

1. `workspace/session-stop` — stop the session's turns, subagents, background jobs and reminders in parallel;
2. `detachEntered` — remove the live session from `SessionStore` and let `session/disposed` cleanup land;
3. Remove the session directory + projection cache files (if this fails, the whole operation fails and **no record is touched**);
4. `workspace.detachSession` — clear the workspace record;
5. `unarchiveSession` — drop the archive entry;
6. Clear the archive-time index.

**Nothing goes to the recycle bin. It cannot be undone.**

### Cleaning stale references

If the plugin finds leftovers ("recorded in a workspace, but no file on disk"), a banner appears at the top:

> N stale session references found … **Clean up**

Cleanup only calls `detachSession` and **never removes files of an existing session**. The plugin also runs the same idempotent self-check silently 3 seconds after startup.

---

## Compatibility

| Item | Status |
| --- | --- |
| DSH `0.2.1-rc.2` | ✅ Verified (development and test baseline) |
| DSH `0.1.0-rc.x` | ⚠️ Untested and very likely unusable (the client/host service shape differed) |
| Host services missing | The plugin **does not activate** rather than rendering a fake list |
| Localization | Chinese / English, following the host `locale` |

> Note: this `package.json` declares **no** `peerDependencies` and no `engines.dsh` —
> DSH's compatibility preflight lets plugins with no declared requirements through, and actual compatibility is decided at runtime by service probing (missing services means no activation).

---

## Architecture

The plugin is a **host half + browser half** pair, structurally identical to existing DSH plugins such as `boot-splash` and `dsh-purge`.

### Files

| File | Role |
| --- | --- |
| `host.js` | Host side: registers `/plugins/archive-manager/*` routes, reads/writes the index, performs restore/delete |
| `client.js` | Browser side: `window.__ModuleLoader__.load()` form, registers the settings `settings.section` |
| `cordis.patch.yml` | Bundle patch layer: declares one enabled Loader entry to the host |
| `package.json` | Package manifest: `dsh.bundle.patch` points at the patch, `dsh.client.platform = web` |

### Host half (`host.js`)

`inject = ['webServer', 'workspaceRegistry', 'sessions']`

Registers **five `exact` routes** (deliberately not a prefix — a prefix would swallow the static materialization path of `client.js`):

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/plugins/archive-manager/ping` | Self-check (`{ ok, plugin }`) |
| `GET` | `/plugins/archive-manager/state` | The whole archive tree (groups + `orphanCount`, newest archived first within each group) |
| `POST` | `/plugins/archive-manager/restore` | `{ sessionId }` restore |
| `POST` | `/plugins/archive-manager/delete` | `{ sessionId }` permanent delete |
| `POST` | `/plugins/archive-manager/repair` | Clean stale records (idempotent) |

Data sources:

- Archive set and workspace records: `ctx.workspaceRegistry` (`archivedSessionIds` / `list()`)
- Title, created-at, last activity: `<DSH_HOME>/storages/session_projcache/sessions/<id>.json`
- Size on disk and existence: `<DSH_HOME>/sessions/<workspace-slug>/<session-id>/`
- Archived-at: `<DSH_HOME>/archive-manager/archive-times.json` (own index, atomic writes, 20000-session scan cap)

**Concurrency control**: restore / delete / cleanup share a single Promise serial queue, so only one mutation runs at a time.

### Browser half (`client.js`)

- No build step; `require('react')` comes from the host module table; **no JSX** (built directly with `React.createElement`);
- Registers `settings.section`: `{ id: 'archived-sessions', order: 25, label, locale, inject }`;
- Data flow: `createStore` (immutable snapshot + subscription) → `useStore` (`useState` + `useEffect`) → re-render;
- Styles are injected as `<style data-plugin-css>` and reference host CSS variables exclusively; dot/pill controls set `corner-shape: round` explicitly to avoid the host's global superellipse affecting circles;
- Refresh chain: remove the row locally → `ctx.sessions.refresh()` → sequenced `/state` reconciliation; it also subscribes to the `ctx.workspaces` archive-set changes, so other tabs or external operations re-reconcile this page;
- Lifecycle: every `setInterval` / `addEventListener` / store subscription / slot registration is released in a `useEffect` cleanup or `ctx.effect`.

### API examples

```bash
BASE=http://127.0.0.1:<port>/plugins/archive-manager

curl $BASE/state
curl -X POST $BASE/restore -H 'content-type: application/json' -d '{"sessionId":"session-xxxx"}'
curl -X POST $BASE/delete  -H 'content-type: application/json' -d '{"sessionId":"session-xxxx"}'
curl -X POST $BASE/repair
```

Status codes:

| Code | `error` field | Meaning |
| --- | --- | --- |
| `200` | — | Success |
| `400` | `invalid-session-id` / body parse reason | Invalid request body |
| `403` | `host-not-allowed` (`/ping`) | Host is not loopback |
| `403` | `untrusted-request` (`/state`) / `foreign-origin` (others) | Origin check failed |
| `404` | `not-archived` | Restore: the session is not in the archive set |
| `404` | `session-not-found` | Delete: no local trace left (safe to call again) |
| `405` | `method-not-allowed` | Wrong method (e.g. GET on `/delete`) |
| `409` | `session-active` | Turns / subagents / background jobs still running — delete refused |
| `500` | `delete-failed` / `internal` | Disk removal failed (records untouched) / unexpected error |
| `503` | `registry-unavailable` | Workspace registry not ready |
| `503` | `activity-probe-failed` / `session-stop-failed` | Activity state unknown / cannot stop it → **delete cancelled** |

---

## Security design

This plugin **can recursively delete session storage**, so the delete entry point follows "rather refuse than mis-delete":

| Surface | Measure |
| --- | --- |
| **Request origin** | Routes are served by `webServer` directly (bypassing the `/api` browser trust fence), so two extra gates are added: **Host must be loopback** (blocks DNS rebinding / LAN calls; desktop IPC bridging without a Host header is allowed) + **Origin must be same-origin** (blocks cross-site requests) |
| **`sessionId` validation** | Whitelist regex `^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$` — **`.` is deliberately disallowed**, so `..`, `../../x`, `a/b` and `C:\x` are all rejected at the boundary; a redundant character check sits on top |
| **Path boundary** | Every path to be removed must resolve **inside** `sessions/` or the projection cache root (`path.relative` check); anything outside is never touched |
| **Preconditions** | A session must still be attached to at least one of disk / workspace record / archive set; a failed activity probe → **503, delete cancelled**; activity that cannot be stopped → **503, delete cancelled** (never blind-delete something that might still be running) |
| **Response content** | `/state` and `/ping` never return an absolute home path, a full workspace path (only the directory name `pathLabel`), or the raw id list; `/delete` never returns deleted absolute paths — only `removedCount` and the `basename` of failed entries |
| **Request body** | Capped at 16 KiB; larger bodies are rejected outright |
| **Permission model** | The plugin runs inside the host process with the host's own file permissions; it can only delete session storage under the current `DSH_HOME`, and the route port listens on loopback only. **Never bind DSH's web server to a LAN address.** |

---

## Known limitations

- **Archive time is approximate**: for sessions archived before the plugin ever ran, the timestamp can only be the first observation — DSH simply does not persist it.
- **Attachments are not deleted with a session**: `<DSH_HOME>/attachments` is a content-addressed store possibly shared across sessions and carrying no session id, so it is not cleaned per session.
- **Active sessions are refused**: a session with running turns / subagents / background jobs is rejected (409) and must be stopped first — consistent with DSH's own archive admission.
- **Requires two host services**: without `workspaceRegistry` or `webServer`, the plugin does not activate.
- **Network-drive risk**: the startup self-check treats "no session directory on disk" as a stale reference. If a session directory is on a temporarily unavailable network drive, its workspace record may be cleaned — this **only affects sidebar ownership, deletes no files**, and reopening the session re-attaches it.
- **Web only**: `dsh.client.platform = web`; no other client form is provided.

---

## FAQ / Troubleshooting

**Q: There's no "Archived Sessions" entry in Settings after installing.**
Restart DSH. The profile composition is built at startup and plugin entries are not hot-reloaded.

**Q: Installation fails with `Plugin ... is incompatible with dsh 0.2.1-rc.2`.**
You typed a bare package name (`dsh-archive-manager`) and installed someone else's npm package. Use the full GitHub URL instead.

**Q: The sidebar still shows the session after deleting it.**
Prefer a recent DSH build (`SessionStore.detachEntered` is a relatively new public primitive; older hosts may lack it). Then check the diagnostic fields in the `/delete` response:
`probe.sessionStore` (can the host reach the SessionStore), `probe.liveAtDelete` (was the session live at delete time), `detachedLive` (did the detach succeed).
If `sessionStore: false`, the host does not expose that service — restart DSH so the session list is refetched.

**Q: Delete says "the session still has running work".**
Stop the running turn/subagent in that session first, then delete. This is an intentional guard, not a bug.

**Q: Can archive state be synced across machines?**
No. The archive set is persisted locally by DSH's `WorkspaceRegistry`; this plugin only reads it and adds no extra sync.

**Q: Could it delete the wrong data?**
Removal is restricted three times over: the `sessionId` shape whitelist → the path must stay inside `sessions/` or the projection cache root → on failure the whole operation rolls back with records untouched. Paths outside those boundaries are never touched.

---

## Development & publishing (maintainers)

The repository root **is** the package root (`package.json`, `cordis.patch.yml`, `host.js`, `client.js` all live at the root), so pushing it makes it directly installable — do not nest it under `packages/xxx`.

```powershell
# One command: whitelist check → commit → tag → push main and the current tag
./publish-github.ps1 -RepositoryUrl https://github.com/<your-name>/dsh-archive-manager
```

Safety constraints enforced by `publish-github.ps1`:

- Only `git add`s files from an **explicit whitelist** — never `git add -A`;
- Stops immediately when the working tree contains changes outside the whitelist (pass `-AllowUnexpectedFiles` to continue);
- Never overwrites an existing `origin` (use `-ForceOrigin`);
- Pushes only the one tag for the current version — never `push --tags`;
- Publishes only from `main`.

### Three things to know about GitHub installation

1. **Repository root = package root.** The installer treats the link as the package address and will not look for a subdirectory.
2. **No build step.** `host.js` and `client.js` are ready-to-run artifacts; there are no `prepare` / `build` scripts, so pnpm runs no compilation after cloning (avoiding install failures caused by missing devDependencies).
3. **`files` whitelist**: currently `host.js`, `client.js`, `cordis.patch.yml`, `README.md`, `screenshots/*.png`
   (`LICENSE` and `README.md` are included by npm automatically). `.git`, `.backup` and `node_modules` never ship.
   > When you swap in new promo screenshots, update the whitelist in `files` as well (or keep the `screenshots/*.png` wildcard).

### Local development

There is no build chain. Edit `host.js` / `client.js` and restart DSH (both the host half and the browser half reload).

For debugging, hit `/plugins/archive-manager/ping` to confirm the routes are mounted, then `/state` to inspect the grouping data.

---

## Contributing

Issues and PRs are welcome. When a change touches the delete path, please also include:

- The DSH version you tested on;
- The `/state` output before and after deleting;
- Whether the sidebar kept a leftover row (and the diagnostic fields from `/delete`).

---

## License

[MIT](LICENSE) © archive-manager contributors

---

<sub>Not affiliated with DeepSeek. This is a community plugin. The whale just happened to swim by 🐳</sub>