dsh-orchestrator: Move Your AI from Solo Worker to Team Lead
Who this is for: Developers already using DeepSeek Harness (DSH) on real projects who are finding themselves turning into "human schedulers" — watching the AI write code while tracking priorities, remembering who is stuck, and nudging tasks forward in their heads.
What you'll get: An understanding of the "coordinator / sub-session / ledger" structure; a way to install it and dispatch your first task; a checklist of how to write goals, lay out dependencies, and when not to use it.
1. Why You Need This (WHY)
One Session Doing All the Work Hits Three Walls
Have you ever had this happen? At nine in the morning you open an AI coding session, confident: "Help me finish this feature — change the API, add the page, write tests, and update the docs along the way." The AI cooperates, works all afternoon. Your chat window has gotten so long it needs compression, mixed in with three logs, two error reports, one requirement change. Then it starts forgetting: the field name you settled on in the morning gets misspelled next round; the original plan quietly morphs into something else by afternoon. 😭
This isn't because the model is dumb — it's because one session is playing too many roles at once: product manager, executor, and its own verifier. Three walls stand in the way:
- The context wall: Requirements, logs, code, and errors all pile into one context; after compression, the most important constraint is often the first thing lost.
- The serial wall: Only one thing can progress at a time. While you wait on A, B and C queue up — even if they're completely unrelated.
- The amnesia wall: Open a new session and yesterday's pitfalls and decisions are all reset to zero.
The Real Bottleneck Isn't "Writing" — It's Scheduling
We passed the "AI can't write code" stage long ago. The more common difficulty now is: too much work, only one session, and you have to be the scheduler yourself. You maintain a mental table: which task is running, which is stuck, which has to wait for that API change, which output lives in which directory. As the table grows, people start making mistakes — forgetting to follow up, forgetting to check, forgetting to collect artifacts. That table should be machine work.
The dsh-orchestrator Solution
dsh-orchestrator is a plugin for DeepSeek Harness (npm: @wjj865-code/dsh-orchestrator, current 0.11.0, MIT). It does something plain: it turns the table in your head into a real ledger; it splits "break down tasks, assign tasks, watch tasks, collect artifacts" and hands those tasks to individual sub-sessions.
In one sentence: it doesn't make you write faster — it lets you have more things running in parallel without having to remember them yourself.
2. What It Is (WHAT)
One-Sentence Definition
An orchestration layer of "one main session + multiple sub-sessions": the main session only breaks down tasks and collects reports; each sub-session works in its own target directory; all intermediate state (who's running, who depends on whom, where the artifacts are, who's waiting on your decision) lives in a SQLite ledger.
Three Roles, Each With Its Own Turf
| Role | Who | What it can do | What it cannot do |
|---|---|---|---|
| Coordinator | The fixed "main session" | Break down tasks, dispatch sub-sessions, review reports, use present to declare delivered artifacts |
Read/write files, run commands — execution layer hard-blocks tools like read/write/bash |
| Sub-task | An independent DSH sub-session running in a specified target directory | Full file / shell / search / web / todo / skill tools; can be read-only, re-dispatched, stopped, re-dispatched | Cannot speak for other tasks (task_report only affects its own task) |
| Ledger | $DSH_HOME/state/orchestrator/tasks.sqlite |
Records status, dependencies, groups, write scopes, messages, artifacts, goal snapshots; survives restarts | Does not auto-recover corrupted snapshots (only gives path hints) |
This division's key point is that the coordinator is deliberately weakened: it has no filesystem permission, so the "main session accidentally changes your code" problem can't happen structurally. It only talks, dispatches, and reads docs. The real hands are on the sub-session side.
One Dispatch Walks This Pipeline
You state a requirement
→ coordinator task_create(): goal / acceptance / constraints saved, task ID t-xxxxxxxx generated
→ has dependsOn but prerequisites not done? Status waiting_dep, no dispatch, no concurrency slot used
→ all prerequisites done? Auto-promotes to pending, queued by priority
→ Dispatch: sub-session gets [task ID] + two-line instruction "call task_detail to read details"
→ Sub-session task_detail reads: full goal, acceptance, constraints, background, user's verbatim,
working directory and permissions, prerequisite summaries, experience files, existing artifacts
→ During work: task_report progress / blocked / needs_auth (optional question + options)
→ Ending: done → settled as completed; interrupted → cancelled; exception → failed;
only reported progress then ended → orphaned (waiting for you in inbox to decide)
→ Collect artifacts: on done, auto-collect files from workspace changes, dedup merge with explicitly declared artifacts by path
→ Archive: completion summary goes to log layer only; distilled atomic facts (experience/decisions/preferences) are injected into next dispatch
Note that line: the brief is only two lines. That's a deliberate design in 0.11.0 — the full goal body isn't repeated in the prompt; the sub-session uses task_detail to read the stored snapshot. Why this change? We'll cover it in the Evolution section; in short, the fuller the prompt, the more expensive the sub-session's opening attention.
12 Tools: 10 for Coordinator, 2 for Sub-sessions
| Owner | Tool | Purpose |
|---|---|---|
| Coordinator | task_create |
Create and dispatch a task; supports dependsOn / group / writeScopes / priority / readOnly |
| Coordinator | task_list |
Active / historical tasks; view group progress by group |
| Coordinator | task_status |
Single-task details: dependencies, write scopes, group, priority, issues, recent messages; include: 'full' shows sub-session's last reply |
| Coordinator | task_message |
Send follow-up message (use this to change goal) |
| Coordinator | task_stop |
Stop running / queued / waiting-for-prerequisite tasks |
| Coordinator | task_retry |
Rebuild failed / orphaned tasks, preserving orchestration fields |
| Coordinator | task_inbox |
Inbox: waiting for your decision, failed/lost, long-inactive |
| Coordinator | history_search |
Search plugin memory, historical tasks, platform history |
| Coordinator | project_context |
Read-only project whitelist files, top-level structure, recent tasks, relevant memories |
| Coordinator | memory_note |
Record a cross-task decision / preference / experience (written as distilled atomic fact) |
| Sub-task | task_report |
progress / done / blocked / needs_auth, can include question / options / artifacts |
| Sub-task | task_detail |
Read-only access to own task creation details; unauthorized access rejected |
All 12 tools globally registered, but permissions cleanly separated: task_retry / task_inbox / history_search / project_context / memory_note only callable by main session; task_detail / task_report only open to the task's own sub-session.
Difference From "Opening Multiple Windows and Copy-Pasting Manually"
| Dimension | Manual multiple windows | dsh-orchestrator |
|---|---|---|
| Context | You carry background between windows, gets messier | Each sub-task has isolated context, background read on demand |
| State | Relies on brain memory and tabs | Ledger stored in DB, view via task_list / panel |
| Dependencies | You watch A finish then start B | dependsOn declares, auto-promotes on completion, failure propagates |
| Failure | You notice it's quiet and start over | Settlement auto-closes + startup reconciliation catches, directly task_retry |
| Artifacts | You find and copy yourself | done auto-collects, artifact library grouped by project/date |
| Experience | Stumble through again next time | Distilled into atomic facts, injected into future tasks |
3. How to Use (HOW)
3.1 Install: One Package Name + One Full Restart
DSH → Plugins → Add plugin, paste:
@wjj865-code/[email protected]Completely exit DSH and start again (closing window alone won't apply).
In the pure DSH sidebar, below "Plugins", a "◈ Main session" appears; Bot mode uses the session header "Tasks" button to open the panel.
Remember the two entry points: the sidebar "Main session" is always visible (guides creation if none exists); the session header "☰ Tasks" only shows in the main session — hidden when you switch to a sub-session or other sessions.
Installed an old version? Probably the mirror hasn't synced.
npm publishwrites only toregistry.npmjs.org, while domestic default usesregistry.npmmirror.com(different registry) which takes minutes to hours to backfill. Maintainer side hasnpm run mirror:check(read-only) andnpm run mirror:sync(trigger sync and poll).Another subtle pit:
npm view --registry=https://registry.npmmirror.comhits local npm cache, showing oldlatestor even404. When in doubt, add--prefer-onlineor check HTTP response directly.
3.2 Dispatch Your First Task: Write in Acceptance Criteria
Talk to the main session in natural language; the coordinator translates it to task_create:
task_create({
title: 'Fix empty data copy',
goal: 'Empty window should show a clear message instead of empty table',
constraints: ['Only modify src/report.js'],
acceptance: ['Empty window outputs "No call records for this window"', 'npm test all green'],
user_verbatim: 'Look at this empty data, it shows nothing',
})
These four fields deserve individual explanation because task quality depends 90% on them:
goal: the result to achieve, not steps. Write "empty window should have a message" not "open file, find line 42, add an if".acceptance: how to determine completion, as testable sentences. "Tests all green" is a hundred times more useful than "good code quality".constraints: what not to touch. Boundaries like "only modify src/report.js" are cheaper than ten rework cycles.user_verbatim: user's original words. It's the last safety net for the sub-session to understand context, and this line is not written to logs.
3.3 Dependencies, Groups, Write Scope, Priority: Turn "Queueing" Into Declarative
// Create A first, then B depending on A
task_create({ title: 'Change API', goal: '...', acceptance: ['...'], group: 'Login rework' })
task_create({
title: 'Integrate login',
goal: '...',
acceptance: ['...'],
dependsOn: ['t-xxxxxxxx'],
group: 'Login rework',
writeScopes: ['src/auth'],
priority: 5,
})
Four rules are enough:
- If prerequisites incomplete: B is
waiting_dep, not dispatched, doesn't occupy a concurrency slot — won't waste a sub-session spot. - All prerequisites
done: B auto-pending; viatask_detailyou can see prerequisite summaries and artifacts (read from current ledger, not creation snapshot). - Prerequisite fails: B automatically
failed, error states cause. writeScopesonly provides conflict hints, not file locks; higherprioritydispatches first.
3.4 You Don't Watch It, It Doesn't Play Dead
New users most underestimate this layer:
| Mechanism | Default | Purpose |
|---|---|---|
Inbox task_inbox / panel "Awaiting your decision" |
On | Centrally show tasks needing confirmation, authorization, failed, long-inactive |
blocked / needs_auth with question + options |
On demand | When sub-session stuck, present problem + multiple-choice to you |
| Settlement (S1) | On | Sub-session interrupted → cancelled, exception → failed, only reported progress then ended → orphaned, no longer silently stuck in running |
| Startup reconciliation (S2) | On | On plugin start, scan ledger; mark tasks running but sub-session no longer exists as orphaned, covers process crashes |
| Idle watchdog | On | Every 5 minutes, if running task has no heartbeat/message/state change for 15 minutes, alert once — alert only, no state change, no kill, no re-dispatch |
Daily digest digestAt |
Off | At scheduled time summarize completed / running / awaiting decision / failed / artifacts, e.g., '09:00' + Asia/Shanghai |
Worth emphasizing about the watch-dog's "alert only": it's an observer, not an executor. You wake up, it tells you "these three tasks haven't moved", but it won't kill them — judgment stays with you.
3.5 Task Panel: DeepSeek-Style Three-Part Layout
Click "☰ Tasks" in the session header to open a panel. It's not a table; it's a three-part layout:
| Section | Content |
|---|---|
| Top command bar | Title + main session status dot, task search box, refresh, open main session; below 4 metric cards (In Progress / Awaiting Decision / Completed / Failed, click to filter) |
| Middle workspace | Left filter rail (with count badges) + task card list; switch to "Artifacts" becomes artifact library (grouped by project/date) |
| Right detail drawer | Click task card or "Details" slides in from right, mask, Esc, close button all dismiss |
Drawer has 7 collapsible blocks: Overview, Latest Reply (sub-session's last assistant message), Brief (acceptance / constraints / background / user verbatim), Goal Status (read-only), Messages (unsent / delivered / failed), Dependencies (upstream/downstream), Artifacts (copy path); bottom action bar has stop (inline double-confirm) / re-dispatch / add message / open sub-session.
Color details worth noting: colors, radius, shadows, effects all take host design tokens (--dsw-* set), so dark/light theme auto-follows, panel hard-codes no colors. Also fixed an old bug — old code used --dsw-alias-color-* which doesn't exist in host token table, always fell back, messy in dark mode.
3.6 Several Advanced Switches Worth Enabling
| Switch | Default | When to turn on |
|---|---|---|
readOnly: true |
No | "Recon first, don't act" tasks: read code, understand structure, give conclusions. Only explicit true recognized |
keepAlive: true |
Off | Want sub-session to keep running across round boundaries instead of idling then settling; keepAliveMode optional steer (one more step same round) / followup (new round), keepAliveMaxRounds default 8 (1–50) |
memoryInject / memoryLimit |
On / 3 items | New tasks inject matched fact-layer memories (lesson/decision/preference/note); log layer not injected |
workerPreset: orch-debug |
dsh-orchestrator-worker |
When you want sub-tasks on "creative mode" capability stack (cordis_* read-only insight tools + dsh-doc skill + plugin_manager) for debugging plugins |
staleMinutes / stallRounds |
30 / 3 | Adjust "how long counts as stale" and "consecutive rounds of progress later remind may be stuck" |
keepAlive's boundary must be clear or it's misunderstood: it only applies to tasks that are ledger running + platform goal not complete; stop conditions include rounds exhausted, goal closed, task leaves running, round interrupted, read-only tasks, next round already queued in inbox. It's the host starting the sub-session (one full model call per round), not a cost control, and can't block explicit stop or model errors.
4. How It Grew (0.0.0 → 0.11.0)
The plugin wasn't designed in one go; real usage forced it out. Looking at CHANGELOG version themes, the main line is clear:
| Version | Theme | One-liner |
|---|---|---|
| 0.0.0-stage | npm placeholder (deprecated) | Reserve name first |
| 0.2.x | Direct entry to main session, read-only sub-tasks | Minimal "usable" |
| 0.3.x | Release pipeline (provenance + duplicate release protection), MIT LICENSE | Confident to publish |
| 0.4.0 | Dependency orchestration: dependsOn / group / writeScopes / priority |
From "can dispatch tasks" to "can orchestrate" |
| 0.5.0 | Inbox / question options / stallRounds / daily digest |
Let blockers surface actively |
| 0.6.x | Artifact library and panel actions; split ARCHITECTURE / LIMITATIONS docs | Panel becomes main entry |
| 0.7.0 | Panel action error codes and idempotency, detail drawer, done auto-collect artifacts | Actions explainable, replayable |
| 0.8.0 | Settlement S1 + startup reconciliation S2 + debug preset | Don't let tasks silently die in running |
| 0.9.0 | Memory layering M1 + idle watchdog W1 + sub-session goal G1 | Context is the most expensive resource |
| 0.10.0 | Sub-session reads goal G2, latest reply B1, brief slimming L1, coordinator delivers artifacts P1 | Prompt slimming, capability completion |
| 0.11.0 | Cross-round keep-alive K2 + task_detail T1 + main-session-only entry U1 + panel UI redo U2 |
From "stuff prompt" to "let sub-session look up itself" |
Several turning points worth separate mention, because they explain why it looks this way today.
Turning Point 1: From "Can Dispatch Tasks" to "Can Orchestrate"
Earliest version could only dispatch independent tasks, essentially "batch kickoff". With 0.4.0 adding dependsOn, there was finally a dependency graph: tasks with unmet prerequisites stay in waiting_dep and don't occupy concurrency slots; on completion auto-promote; failure propagates along the chain. That's when the word "orchestrate" became true.
Turning Point 2: The Biggest Pit Isn't Failure — It's Silence
Long-term use reveals what really drives people mad isn't a sub-session erroring — an error is at least a clear signal. What's truly annoying is it says nothing, just sits in running. You sleep, come back next day: status still running, session long gone.
0.8.0's S1 (settlement reason closure) and S2 (startup reconciliation) targeted exactly this: consume sub-session's end stopReason, move running to terminal state (normal done → done, interrupted → cancelled, exception → failed, only reported progress → orphaned); on plugin restart scan ledger again, mark running but sub-session no longer active as orphaned.
One line: Better give you an "session lost" task awaiting decision than let it pretend it's still running.
Turning Point 3: Memory Isn't More the Better
0.9.0 did something counterintuitive: downgraded done summaries from memory. Completion summaries no longer go into task-done (memory-injected layer), but into log layer task-log — archive only, don't inject into brief. Also added distillation on write: drop code fences, shell/test outputs, quoted original words, pure path lists entirely; fact-layer single-entry max 160 chars. Only clauses with markers like "conclusion / experience / note / avoid" get distilled into lesson atomic facts, alongside decision / preference / note injected into future tasks (default 3). Because context is the most expensive resource. A "this change is done" log entry has zero value to the next task, but it eats prompt budget.
Turning Point 4: Brief Gets Shorter, Sub-sessions Get More Autonomous
0.10.0 moved goal to platform goal (sub-session reads via get_goal, brief only has one-line instruction + 160-char fallback), moved experience into lessons/ memory files (brief only has count, summary, path). 0.11.0 goes further: brief is just two lines —
【Task ID】t-xxxxxxxx
【Task Details】First call task_detail to read full task details……
Full goal, acceptance, constraints, background, user verbatim, working directory, prerequisites, experience, artifacts — all read by the sub-session itself via task_detail. Direct benefit: prompt length fully decoupled from task complexity and memory count, dispatch no longer expensive because "too much background stuffed". Prerequisite progress is also no longer a snapshot at creation, but real-time ledger at dispatch. Cost: task_detail must be read-only and must check authorization (exec.agent.id or exec.agent.session.id must equal ledger's session_id for that task, otherwise returns "read denied"; main session checking tasks uses task_status).
Turning Point 5: Stronger Capability, Default Off
0.11.0's keepAlive best shows "design restraint": it lets sub-sessions continue across round boundaries, theoretically a strong automation ability. But author default is off, and:
- Only injects for tasks
running+ platform goal not complete; - Round budget in ledger (default 8), resets each entry to
running, duplicate/concurrent events use conditionalUPDATEto atomically increment rounds, no over-issue; - Dedup with settlement: doesn't change status, doesn't write
progress_count, doesn't writefollowupmessages, doesn't trigger settlement; - Listeners fully wrapped in
try/catch, never throw exceptions back to dispatch chain.
Similarly restrained is goal state: when dispatched, goal synced to platform goal then immediately disarmed — goal is just persistent target state, doesn't drive sub-session auto-continuation. Fun fact: 0.8.0, 0.9.0, 0.10.0, 0.11.0 all released 2026-11-15, four minors same day; 0.11.0's npm test ran 602 all green.
5. Best Practices
✅ 1. Write "Acceptance" Not "Steps"
goal describes result, acceptance holds testable statements. Leave steps to the sub-session — it knows its own path better than you.
✅ 2. One Task, One Write Scope
writeScopes is only a hint, but it forces you to think before dispatch: "these two tasks might clash." True conflict avoidance comes from splitting, not declaring.
✅ 3. Organize with group, Not Numbers
"Login rework" is far more useful than "third batch": group progress can be viewed directly, and human memory holds onto names better.
✅ 4. Don't Restate Background in Goal
Experience, prerequisites, existing artifacts are all read via task_detail. Restating in goal wastes prompt and risks drifting from actual state.
✅ 5. Turn Decision Points into Multiple Choice
When stuck, use blocked with question + options to surface in notifications, details, and panel — far more effective than hiding "should we change this?" in a long message.
✅ 6. Recon Tasks Get readOnly First
"Don't touch anything, tell me how this code is organized" tasks get readOnly: true, sub-session in read-only sandbox, physically impossible to accidentally break.
✅ 7. Artifacts Use Absolute Paths
Sub-session's working directory isn't yours. When delivering with present, write absolute path to be clickable.
✅ 8. Scan Inbox Once a Day Especially with daily digest: completed / running / awaiting / failed / artifacts all on one screen, much faster than clicking each task card.
6. Common Misconceptions & Pitfalls
❌ Misconception 1: It's a "Faster AI"
It doesn't speed up single inference. It saves your scheduling cost and single-session context pressure. Each sub-session is a full model call; keepAlive is the host continuously starting sub-sessions — capability feels great, bill needs discipline.
❌ Misconception 2: Goal Written as a Requirements Document
Longer goal means less attention for "understanding task structure" at sub-session start. Good goal is usually one or two sentences: what you want, what you don't. Put background in constraints and refs, not all in goal.
❌ Misconception 3: writeScopes Is a File Lock
It only hints conflicts, not a lock. Two tasks targeting src/auth won't block each other; for serialization use dependsOn.
❌ Misconception 4: Dependencies Can Be Edited After Creation
dependsOn cannot be edited after creation, nor can it point to future IDs. So think during breakdown: if unsure, start small, string into chain, don't rely on later adjustment.
❌ Misconception 5: "Plugin Broken" When Not Fully Restarted
Closing window alone doesn't work; must fully exit DSH and start. Also "installed old version" is 90% mirror sync issue — check mirror:check first, then suspect plugin.
❌ Misconception 6: Looking for Task Panel in Sub-session
Entry only shows in main session, and hidden by default when signal not available (fail-closed). Not a bug; it's deliberate — better missing entry than misleading panel in sub-session.
❌ Misconception 7: Expect It to Control Cost for You
keepAlive default off, has round limit, comment openly says: it's host starting sub-session, not cost control. To save money, turn it off, shorten goals, reduce concurrency — more direct than tuning parameters.
❌ Misconception 8: Logs Will Remember Everything
goal / summary only 80 chars in log, user_verbatim not logged. Want a decision remembered? Use memory_note to explicitly record an atomic fact — logging and memory are two different things.
7. What It's Not For (Honest Take)
- Small changes finishable in one sentence: breakdown, ledger, brief overhead outweighs benefit; just say it directly.
- Edits needing strong real-time collaboration: two people (or two sub-sessions) editing same files,
writeScopescan't help. - Want infinite auto-continuation:
keepAlivedefault off, has round budget, platform goal disarmed on creation. Design choice, not a bug to fix. - Cross-machine or multi-person shared state: ledger is a local SQLite under
$DSH_HOME/state/orchestrator/, plugin doesn't sync across machines — it's your personal record book. - Fully unattended pipeline: it explicitly keeps judgment with a human —
blocked/needs_auth/orphanedall wait for you to look. Want "it runs itself end-to-end"? That's not this tool.
8. Final Thoughts
This article itself is a dispatch. The main session created a sub-task in "public account promotion" group (ID t-5a95ac12), gave only three things: goal (write an article introducing and promoting this plugin), five acceptance criteria, and paths to background materials. A sub-session then read materials in its designated working directory, distilled style from previous 17 articles, wrote, self-checked, and finally used task_report done to hand over artifacts. Nobody nudged, nobody moved context — because everything that needed remembering was in the ledger.
Back to the three walls: context wall solved by "task-level isolation + on-demand read"; serial wall bypassed by "multiple sub-sessions in parallel"; amnesia wall patched by "distilled atomic fact injection". There's no magic; its value lies in moving a thing that should be process responsibility from your brain into a database. Installing it doesn't change your working style — you still speak natural language; just from today, you can safely say three things at once and go get a coffee. ☕
Reference Links
- npm:
@wjj865-code/dsh-orchestrator - Repository: github.com/wjj865-code/dsh-orchestrator
- Changelog:
CHANGELOG.mdin repo root (0.0.0-stage → 0.11.0) - Architecture & boundaries: repo
docs/ARCHITECTURE.md,docs/LIMITATIONS.md,docs/UI.md,docs/DEBUG-PRESET.md - License: MIT
Top 1 from juejin.cn, machine-translated. The original thread is authoritative.
The 'memory wall' is even more obvious in a team: the ledger sits on your own machine, so a colleague's pitfalls from yesterday's session are still unknown to your session. We later put everyone's task records and project rules on the same machine, so before an agent starts, it can look up similar tasks others have done, and when someone else takes over, they don't have to re-explain everything from scratch.