dsh-reaper
DeepSeek Harness 的孤儿进程和端口清理工具：查找智能体遗留的开发服务器、监视器和后台进程，将其归属到工作区，预览影响范围并回收端口。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:11111353535/dsh-reaper#b0412244e623d54fbf0bded66cba5203de8c85c4Reaper 以 dsh-reaper 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Reclaim the ports your agent forgot to give back.
An agent starts vite, next dev, a watcher, a tunnel. The turn ends. The session ends. The process does not — it keeps holding 5173, and the next run dies with EADDRINUSE while you go hunting through Task Manager for a node.exe you cannot identify.
dsh-reaper inventories every listening endpoint on the machine, attributes each holder to this session, shows you exactly what it would kill, and only then — when you say confirm: true — reclaims the ports.
$ /reap
dsh-reaper · win32 · 2026-10-16T10:57:26.626Z
workspace: E:\work\shop-frontend
51 listening endpoint(s) · 432 process(es) · 3 reclaimable
5173 tcp agent-spawned pid 8899 18m node.exe
node E:\work\shop-frontend\node_modules\.bin\vite --host
3001 tcp workspace pid 9120 42m node.exe
node E:\work\shop-frontend\server.js
3306 tcp system pid 9168 9h29m mysqld.exe
↳ port 3306 is a well-known service port
19387 tcp protected pid 11664 2h9m DeepSeek Harness.exe
↳ holds the harness process tree
Port tools tell you what holds a port. The hard part is deciding whether you are allowed to kill it, and that answer depends on facts a port number does not carry:
mysqld on 3306, nginx on 80?dsh-reaper answers that per endpoint and grades the result, so a --all sweep can be safe:
| verdict | meaning | auto-selected by all: true |
|---|---|---|
agent-spawned | descends from the harness host process | ✅ |
workspace | command line names the current workspace | ✅ |
dev-server | looks like a dev server, watcher or tunnel | ❌ |
unattributed | listening, but nothing ties it to this session | ❌ |
system | OS process, or holds a well-known service port | ❌ |
protected | matched neverKill / protectPorts, or holds the harness tree | ❌ |
Two rules make that table trustworthy:
system — the same hands-off grade as an OS process — so all: true never reaches it, and its note says left alone rather than hinting at an override.Reaping is destructive, so the defaults are conservative and the refusals are absolute:
confirm: true. The default call computes the plan and returns it.npm run dev shim without its child leaves the port held — the exact failure this plugin exists to prevent. Descendants are ordered deepest-first so children die before their parents.neverKill matches and protectPorts holders are refused even when passed explicitly, with the reason reported.SIGTERM first, SIGKILL only if you ask. force: true escalates, and even then survivors are reported rather than hidden.ports confirmed free or ports still held.dsh plugin add https://github.com/11111353535/dsh-reaper
From a checkout instead of a git host, pass the absolute path:
dsh plugin add /absolute/path/to/dsh-reaper
The package declares no dsh-* peer dependency on purpose: it imports only node:* plus @deepseek-ai/dsh-tools, which the harness resolves from its own installation. Nothing is bundled that could shadow the host's copy.
To tune it per profile, add a config block to the row the installer inserted in ~/.dsh/profiles/<profile>/cordis.patch.yml:
- insert:
- id: reaper
name: 'dsh-reaper'
config:
neverKill: ['my-precious-daemon']
protectPorts: [80, 443, 19387]
includeUdp: false
graceMs: 3000
scanTimeoutMs: 20000
| key | default | meaning |
|---|---|---|
neverKill | [] | Process-name or command-line substrings that must never be signalled. |
protectPorts | [] | Ports whose holder is refused even when named explicitly. The harness's own web port is added automatically. |
includeUdp | false | Also enumerate UDP endpoints. Off by default: dev servers are TCP. |
graceMs | 3000 | How long SIGTERM gets before the process is reported as surviving. |
scanTimeoutMs | 20000 | Wall-clock ceiling for one system enumeration. |
reaper_scanRead-only inventory. Signals nothing. Grades every listening endpoint and returns the full scan.
| argument | type | meaning |
|---|---|---|
includeUdp | boolean | Also enumerate UDP endpoints. |
workspace | string | Workspace root used for attribution. Defaults to the session workspace. |
reaper_reapCompute a plan and, only with confirm: true, execute it.
| argument | type | meaning |
|---|---|---|
pids | integer[] | Explicit root pids. Their descendants are included automatically. |
ports | integer[] | Reap whatever holds these ports. |
all | boolean | Also select every endpoint confidently attributable to this session (agent-spawned and workspace only). |
force | boolean | Escalate to SIGKILL for processes that ignore SIGTERM. |
confirm | boolean | Actually signal the plan. Defaults to false. |
reaper_free_portReclaim one specific port. If the port is already free it says so and does nothing; if the holder cannot be attributed or is protected, it reports why instead of guessing.
| argument | type | meaning |
|---|---|---|
port | integer (required) | The TCP port to reclaim. |
force | boolean | Escalate to SIGKILL if SIGTERM is ignored. |
confirm | boolean | Actually signal the holder. Defaults to false. |
/reap # inventory
/reap --all # preview everything confidently attributable to this session
/reap --all --confirm # and actually do it
/reap 5173 # preview reclaiming one port
/reap 5173 3001 --confirm --force
| platform | endpoints | process table |
|---|---|---|
| Windows | Get-NetTCPConnection -State Listen (+ Get-NetUDPEndpoint) | Get-CimInstance Win32_Process |
| Windows (fallback) | netstat -ano | tasklist /FO CSV /NH |
| Linux | ss -H -ltnp | ps -eo pid=,ppid=,comm=,etimes=,args= |
| macOS | lsof -nP -iTCP -sTCP:LISTEN -Fpcn | ps |
Every probe is best-effort: a missing binary or a failed command degrades that one source and is reported in degraded: ... at the end of the scan. A scan that falls back to netstat still works — it just loses command lines, and therefore attribution gets weaker, which the report tells you.
One process listening on both :: and 0.0.0.0 is one problem, not two: dual-stack bindings are collapsed into a single row per protocol/port/pid, with every address kept in addresses.
npm test # 42 unit tests, no harness needed
npm run test:live # a real read-only scan of this machine
npm run setup:deps
lib/ is plain ESM JavaScript with no build step, and the unit tests cover the parsers against recorded fixtures — Windows and BSD netstat tables, ss, lsof, ps, tasklist, the classifier, the plan builder, and the renderers. test:live covers what fixtures cannot: that the real enumeration works on the host you are on. It signals nothing.
setup:deps links the three host packages lib/ imports (cordis, dsh-tools, schemastery) into a local node_modules so a bare checkout can run the tests. Set DSH_HOST_NODE_MODULES if the harness is not in a standard location.
MIT