dsh-devlead: Orchestration in Ordinary Sessions

dsh-devlead is an ordinary DSH Session with a switch only a human can flip. Once it is on, the lead dispatches work to real Sessions you can open and take over, and does not implement anything itself. This is why it is built that way, how notifications wake the lead, what v0.2.3 added, and what still does not work.

When three repositories have to move at once, my old routine was three sessions and a lot of switching. Watch the CI on one, answer a question on the second, go back and see whether the third had finished what it was doing. The switching was not the exhausting part. The exhausting part was holding the state of all three in my head: which failure was waiting on a decision, which README edit was still missing a verdict.

Subagents helped for a while. They finish the job and hand back a summary, but the worker itself is not something I can open. If I want to know why it changed a particular file, I have to ask the parent to relay the question, and the parent compresses the answer again. Two rounds later, the thread is gone.

dsh-devlead came out of that annoyance. It does not make child agents smarter. It changes what they are: the dispatching happens in an ordinary Session, and the workers are ordinary Sessions too. What follows describes v0.2.3 — why the lead dispatches instead of implementing, how a finished turn wakes it up, and the parts that still do not work well.

Parallelism was never the problem

A subagent assumes a bounded job inside one turn. Most of the time that assumption holds, which is why it is fast. But the job's lifecycle belongs to the parent turn: when the parent finishes, the worker is gone. It usually does not appear in the sidebar as a conversation you can open, so you see the final report and not the work.

Work that crosses repositories does not fit that shape. It runs for many turns. It fails, waits for a decision, or turns around because an interface upstream changed. At those moments I rarely want another dispatch. I want to open the session, add a sentence of context, or take over myself. The missing piece was not more parallelism. It was a door into the parallelism I already had.

So the plugin changes the work product instead of wrapping it. A child is a real Session: it is in the sidebar, and it can be opened, continued, archived. A Workspace is registered through ctx.workspaceRegistry, not kept in a private table inside the plugin. I can walk in at any point, and the model can pick up the same Session in a later turn.

That choice fixes the lead's job too: dispatch by default. It reads the metadata of registered Workspaces to decide who owns a request, then writes a brief that carries its own context — background, target outcome, open questions, deliverables, and how to verify the result — and hands it to a Session in that repository. It may do read-only checks to judge feasibility or confirm a claim, but it does not read every repository first. Writes, builds, and commits happen in the owning Workspace unless I explicitly tell the lead to do them here.

A switch only a human can flip

DevLead is not a different kind of Session. It is an ordinary Session with one durable switch. I run /devlead on in the session that should coordinate several repositories, or click the small icon in the composer toolbar, and that session gains the devlead_* tools, a DevLead system prompt, and a status strip above the input with the watched count, the running count, and the latest notification.

I kept the switch out of the model's reach on purpose. Whether a conversation gets to drive other conversations is a decision for the person sitting in front of it, not for a model that has just concluded it would be more efficient. While the mode is off there is only a small icon; no banner on every conversation. Once it is on it survives a restart or a resume, and turning it off is my job too: /devlead off.

What I like is that the extension does not invent a second kind of container. The DevLead is still the conversation I was already reading, now with a dispatching responsibility.

Dispatch, then end the turn

There is one convention here that runs against instinct: after dispatching, the lead should end its turn. Not sleep inside the same turn, not poll devlead_list_sessions every few seconds, and not sit on wait_agent until the child replies. The child runs independently. A lead that holds the turn open gains nothing and makes the conversation look stuck.

The wake-up comes from notifications. Every turn/end of a watched Session — completed, failed, blocked, cancelled — writes a notice into the lead's log. The runtime coalesces notices over a short window (400 ms by default) and delivers one message that starts a new turn. Then the lead checks the real state with devlead_get_session or devlead_notifications and decides: follow up, dispatch the next step, or report to me.

That the notice goes to the log first matters more than it looks. It is not a toast that dies with the window; mode, watch set, notices, and reset are all plugin:devlead/* events. After a restart or a plugin reload the watch index is rebuilt from those records by strict replay, and a cold lead is resumed by default to collect whatever queued up. If a record is corrupt the projection freezes and reports the error; /devlead reset takes it back to the default off state. The old records stay in the log and are simply no longer folded.

One boundary worth stating plainly: a notification is a runtime notice, not a human instruction. Text inside a child's output does not gain authority by arriving through this path. That rule is written into the prompt, and I would rather have it there than rely on a review afterwards.

v0.2.3: twelve tools, one of them reads the catalog

There are twelve tools now, and their names say what they do. devlead_list_workspaces, devlead_use_workspace, and devlead_remove_workspace handle Workspaces. devlead_list_sessions, devlead_create_session, devlead_get_session, devlead_prompt_session, devlead_watch_session, devlead_archive_session, and devlead_unarchive_session handle Sessions. devlead_notifications returns the retained notices, and devlead_list_models reads the Host catalog.

A creation call looks roughly like this:

{
  "workspace": "/Users/me/Workspace/src/api",
  "title": "Fix the CI failure",
  "prompt": "Reproduce the CI failure, fix it, run the relevant checks, and report the result. Do not commit or push.",
  "watch": true
}

The child cannot see the lead's conversation, so the prompt has to stand alone. watch already defaults to true; spelling it out here is only to make the relationship visible. If the owning Workspace already has a live Session on the same request, continue that one instead of creating a twin.

Version 0.2.3 is a patch release. The tool surface went from 11 to 12, and the new one, devlead_list_models, returns a trimmed Host model catalog — display fields like descriptions are dropped to keep it cheap. With that, creation can pin a paired provider and model, plus an optional reasoning_effort. The default is still to inherit the Host model. Pinning is for the cases where someone asked for it, or where the work genuinely needs cost or capability routing or has to be reproducible; and if you are going to pin, look it up first rather than guess.

The selection is recorded on that child Session, applies at creation only, and never rewrites the profile default. I care about that last part. A dispatch quietly changing the global default model is the kind of debt you find months later.

agent_teams is creation-time only as well. For work that is complex, multi-step, parallel, and actually helped by subagents, the lead can judge and pass true. Simple linear work usually leaves it out, and an explicit instruction from me wins. Leaving it out means leaving the Host default alone, which is not the same as forcing it off; that distinction gets misread a lot.

When the Host composes the experimental worktree service, isolation: "worktree" gives a new Session its own branch and checkout before the first prompt. It is optional and best-effort. If the capability is missing or creation fails, the Session is still created and prompted in the shared checkout, and the result says unavailable or failed. Do not pretend the isolation happened; writes that share that checkout have to be serialized.

Wrap-up is also a judgment call, with conservative edges. The lead may archive finished temporary Sessions it created or dispatched, and remove Workspace registrations that are clearly stale, duplicate, empty, or its own. It must not close something I am using, hide a failure behind an archive, or start a broad cleanup nobody asked for. Archive keeps the log and can be reversed; removing a Workspace only unregisters it and does not delete the directory. Every self-directed close comes with a reason and an impact statement.

Install, and the compatibility details

Install the bundle into the desktop profile and you get the service, the tools, the command, and the interface:

dsh plugin --profile desktop add @yankeguo/dsh-devlead-bundle

The project is yankeguo/dsh-devlead on GitHub, and the npm package is @yankeguo/dsh-devlead-bundle. This article covers v0.2.3, released under the MIT license.

The plugins declare DSH >=0.2.2-rc.1 <0.3.0, and the release notes cover 0.2.2-rc.1, rc.2, and rc.3. The base tools, the model catalog, and model selection work on all three. Agent Teams is the one exception: rc.1 has no such service, so agent_teams: true returns DEVLEAD_TEAM_UNAVAILABLE and no Session is created. Omit it, or pass false, and dispatch proceeds as usual. From rc.2 the Host has to compose the service. This is a capability error, not the quiet degradation worktree isolation does.

What it still does not do

Durable state is not the same as never missing an event. A turn that ends while the plugin is unloaded is not replayed for watchers when it loads again. The projection keeps the latest 64 notices and watches at most 64 Sessions by default.

Resuming a cold lead for a notice is the default, but this is not a background scheduler. The plugin does not create schedules, does not start a long-running autonomous goal, and does not orchestrate across processes or DSH instances.

Worktree isolation is not a complete Git workflow either. A new checkout starts at the source checkout's HEAD, and uncommitted, staged, untracked, and ignored files are not copied. An existing Session cannot be moved into a worktree. Reviewing, merging, or cherry-picking the branch is still separate work; the plugin never merges on its own. And an ordinary child Session appears in the sidebar and spends quota like any other conversation. It is not a free shadow copy.

Finally, the switch is not a security sandbox. Child Sessions keep DSH's existing sandbox and permission mode, and installing a third-party plugin still means trusting its code inside the Host process. Visibility makes the operating boundary clearer. It does not replace the permission boundary.

When I switch it on

For one change in one repository, an ordinary Session is enough. For one-off parallel subtasks, subagents or Agent Teams are more direct. DevLead does not make those cases better; it adds a layer that has to be explained and reviewed.

I switch it on for a narrower shape: work that spans a few repositories, runs for several turns, needs follow-ups, has to survive a failure, and where I want to open any worker and take over. The value there is not "more agents." It is that the orchestration rides on Sessions I could already see, resume, and take over.