dsh-job-watch
A long-running job you did not start, pinned to the conversation that cares about it.
The sidebar row of that conversation turns pink while the job runs, green once it has
finished (come back and analyse the result), and amber when the job id cannot be found.
English | 中文速览
Not affiliated with DeepSeek. This is an independent community plugin for
DeepSeek Harness (DSH). "DeepSeek Harness" is named
only to describe compatibility.
The problem
An agent submits a job that takes six hours — to a cluster scheduler, to a bare-metal box over SSH, to
tmux somewhere — and then the session goes quiet. The job's state lives in a completely different program
(squeue, bjobs, tmux list-sessions), so the only ways to find out are:
- open a terminal and poll it by hand, or
- keep a monitoring tab open, or
- notice four hours later that it finished and you never looked.
The GUI already knows which conversation you were working in. dsh-job-watch attaches the job id to that
conversation, queries the provider for you, and paints the conversation's row — so "which conversation still
has something running, and which one finished while I was away" is answered by the sidebar you are already
looking at.
□ conv A · (no mark) nothing to do
▌ conv B · ● pink, pulsing a tracked job is running
▌ conv C · ● green finished — come back and analyse
▌ conv D · ● amber the id cannot be found by its provider
Green is deliberately sticky: it does not expire, because it exists to make you come back. It clears the
moment you actually say something in that conversation — and injected context (workspace instructions, skill
catalogs, runtime snapshots) does not count as "saying something", because that would clear it silently and
defeat the whole feature.
Screenshot
Three tracked conversations, each carrying the running colour on its sidebar row
A real screenshot of the sidebar: three tracked conversations, each with the running bar
(#ec4899, the exact colour the plugin paints) on the left edge of its row. The conversation titles are
covered by a solid block — they are the author's private session names, and the crop is verified pixel by
pixel to contain no text at all. No green example appears here simply because no tracked job had finished
when the shot was taken; green means "finished, come back and analyse".
How it works
| Half | Runs in | Does |
|---|
host (lib/index.js) | the dsh process | the job ledger, the provider poller, the job_watch agent tool, /api/job-watch/* |
browser (lib/client.js) | the Web GUI | reads the state endpoint and paints the sidebar rows |
The plugin owns no job logic. A provider is a shell command plus one regex applied per output line —
so an HPC scheduler, tmux on a bare-metal box, or your own status CLI are all the same thing to it.
Nothing about a cluster, queue or path is hard-coded.
Queries happen on four triggers, all of them cheap and skipping each other:
| Trigger | Why it exists |
|---|
every pollMinutes (default 30) | the normal rhythm |
| a 60 s heartbeat that compares the wall clock against the monotonic clock | a suspended machine freezes timers, so a timer firing "on time" proves nothing; clock drift > 90 s is the evidence of a sleep, and the poll catches up right away |
| opening / refocusing the GUI | you are here, so the state you are shown should be current (the host only re-queries if the ledger is older than requestStaleSeconds) |
right after register | the colour must be correct immediately, not in 30 minutes |
Install
dsh plugin --profile web add dsh-job-watch
Restart dsh web afterwards (--profile must come after plugin — the other order is rejected).
Then configure at least one provider in your profile patch, ~/.dsh/profiles/<profile>/cordis.patch.yml:
- id: job-watch
config:
pollMinutes: 30
providers:
# 1) a scheduler that prints one job per line (Slurm here: id, state, name)
- id: cluster
label: Cluster
command: 'ssh login01 "squeue -u $USER -h -o ''%i %T %j''"'
linePattern: '^(?<id>\S+)\s+(?<stat>\S+)\s+(?<name>\S+)$'
# 2) a bare-metal box where "a job" is a tmux session name
- id: lab
label: Lab box
command: 'ssh lab "tmux list-sessions -F ''#{session_name}''"'
linePattern: '^(?<id>[A-Za-z0-9_.-]+)$'
linePattern is applied per line; it needs a named group id, and may add stat and name. Lines that
match nothing are ignored, so headers, banners and warnings cost nothing. ANSI colour codes are stripped
first, which matters as soon as your command runs through a shell that thinks it is talking to a terminal.
Provider reference
| Key | Required | Meaning |
|---|
id | ✅ | the name used by job_watch(provider=…) and shown in the tooltip |
label | | human-readable name for messages |
command | ✅ | run through the platform shell; write the SSH call yourself, so no remote details live in the plugin |
linePattern | ✅ | regex per line, named group id (required), stat, name (optional) |
runningStates | | overrides the default list (RUN, PEND, QUEUE, WAIT, …) |
doneStates | | overrides the default list (DONE, EXIT, FAIL, ABORT, KILL, …) |
Other config: pollMinutes, heartbeatSeconds, commandTimeoutSeconds, minPollGapSeconds,
requestStaleSeconds, unknownAfterSeconds, pruneDays (finished + acknowledged rows are dropped after
this long), missingMeans (done = a job vanishing from its provider's listing has finished; unknown =
paint it amber instead), statePath (default $DSH_HOME/job-watch.json).
A non-zero exit from a provider command is not fatal: tmux list-sessions exits 1 when there are no
sessions, and several schedulers print the listing while warning on stderr. stdout is parsed either way and
the failure is reported alongside the state.
Agent integration
The host injects a short rule into every agent's system prompt, and exposes one tool:
job_watch(action='register', jobIds=['40217'], provider='cluster', etaMinutes=540, note='sweep A')
job_watch(action='list')
job_watch(action='refresh')
job_watch(action='clear')
register without jobIds auto-claims: every job the providers currently list as running and that no
conversation tracks yet. Useful after the fact ("what did I forget to register?").- Registering is not optional. No colour can be inferred from a job that nobody told the plugin about —
a job submitted in
tmux or on a cluster leaves no trace in the ledger. This is why the rule lives in the
system prompt rather than in a doc nobody reads.
- Every report ends each job with a recommended finish time. It is arithmetic (registration time + the
ETA you registered) or an explicit "cannot be estimated, here is how to measure it" — the plugin never
invents a time. An ETA that has already elapsed while the provider still reports the job as running is
called out as overdue rather than assumed finished.
SKILL.md is the same contract written for an agent that loads skills.
Limitations (measured, not guessed)
- The sidebar has no decoration API. The browser half finds a row's session id through the React fiber
chain hanging off the row DOM node and injects the marker into the row. This is inherently tied to the
current sidebar implementation; when it breaks, the console and
window.__dshJobWatch.stats() say so
instead of failing silently.
register is a manual step — see above. There is no way around it for jobs DSH did not spawn.- Only rows the sidebar renders get a colour. A conversation that is not in the visible list is not
painted (the rollup is still computed, so it paints as soon as the row appears).
linePattern is yours to get right. A pattern that matches the header row as a job will track a fake
job; a pattern that matches nothing silently tracks nothing (which is why refresh reports how many ids
each provider listed).- No test of the GUI itself.
node --test test/kernel.test.mjs covers the kernel — listing parsing, STAT
folding, the real-prompt discriminator, and the finish-time contract.
Prior art, and what is actually new here
Job listing is not new, and none of it is claimed as an idea of this plugin. In the DSH ecosystem:
| Project | What it covers | Why this is different |
|---|
official @deepseek-ai/dsh-client-ui-jobs (the ui-jobs entry) | background jobs DSH itself spawned, in the session header | this is for jobs DSH did not start: a scheduler, a tmux session, another machine |
lql341/dsh-scnet | SCNet HPC as tools + a skill (submit, status, logs, cancel) | on-demand tool calls for one specific platform; no conversation-level colour, no ETA contract |
Gczmy/dsh-node-sched | a dashboard for their own sched daemon | requires that daemon; a main-panel view rather than the conversation list |
Luaphes/dsh-web-attention-badge | session attention state in the browser tab bar (amber = waiting on you, green = done) | a session has finished, not a job; painted in the tab strip, not on the conversation row |
catsenior507/dsh-command-center | a panel for running background jobs | a panel you open, not a colour on the row you are already reading |
The increment claimed here is narrow: an external job id → a colour on that conversation's sidebar row,
plus the finish-time contract (arithmetic or an explicit refusal to guess) and the sleep/wake-safe poller.
Everything else — the job tools, the dashboards, the attention badges — belongs to the projects above.
License
MIT. See LICENSE.
中文速览
问题：作业交出去要跑几小时，状态却在另一个程序里（squeue / bjobs / tmux list-sessions），于是
要么手动开终端轮询，要么四小时后才发现早跑完了。
做法：把作业号绑到当前对话上，插件自己按配置的 provider 去查，侧边栏那一行直接变色 ——
🩷 粉 = 在跑 ｜ 🟢 绿 = 已结束，回来分析 ｜ 🟠 橙 = 查不到。绿色不会自己过期（它就是要喊你回来），
你在那个对话里真的说话之后才消失（注入的上下文不算说话）。
provider 就是「一条命令 + 一行一条的正则」，所以调度器、裸机 tmux、你自己的状态 CLI 都是同一种东西：
插件里不写死任何集群、队列、路径。查询有四条触发（定时 / 心跳发现休眠唤醒 / 打开页面 / 注册后立刻）。
必做：dsh plugin --profile web add dsh-job-watch，重启 dsh web，然后在
~/.dsh/profiles/<profile>/cordis.patch.yml 里配 providers（见上文）。每次提交作业后必须登记
——没人登记的作业不会有任何颜色，这是设计约束，不是 bug：
job_watch(action="register", jobIds=["40217"], provider="cluster", etaMinutes=540)
每条报告都会给出推荐结束时间：要么是「登记时刻 + 你给的 ETA」算出来的，要么明确说无法可靠推算
并告诉你从哪取数（作业自身的 elapsed 列 / 日志里的进度行）——不编时间。
与既有项目的关系：官方 ui-jobs 管的是 DSH 自己起的后台任务；dsh-scnet 是 SCNet 的工具+技能；
dsh-node-sched 是自家 sched 守护进程的看板；dsh-web-attention-badge 是标签页里的会话注意力状态；
dsh-command-center 是要打开的作业面板。本插件只占一格：外部作业 → 对话列表那一行的颜色 +
结束时间口径 + 抗休眠的轮询。
