Spawn and drive DeepSeek Harness workers from the codeman agent skill

[Ark0N]

Codeman ships an agent skill (skills/codeman) that lets an agent running inside a Codeman session drive the server over HTTP: spawn worker sessions, hand them tasks, block until a worker's turn ends, read its answer, clean up. Until now that only worked properly for claude workers. Every other CLI backend has neither a real end-of-turn signal (Codeman infers "idle" from the pane going quiet, which flaps mid-turn) nor an answer Codeman can read, so the skill drives them the hard way: make the worker print a unique marker and poll the terminal for it.

DeepSeek Harness (dsh, the ninth run mode added in #337) is the one exception on both counts, and this PR turns that into a usable capability. A dsh worker is now spawned, tasked, waited on and read with exactly the same four verbs as a claude worker:

S=();whileread -r _ s;do S+=("$s");done<<(spawn_workers alpha beta:deepseek)# mixed fleet, concurrent
sendwait "${S[1]}"'Read calc.py and tell me in one sentence whether add() is correct.'
last_text "${S[1]}"
delete_session "${S[1]}"

Why dsh can do this and the other backends cannot

Two halves have to be true, and dsh is the only non-Claude CLI where both are:

• A real end-of-turn signal. The harness TUI reports idle/working/blocked to a supervising process over a generic env-gated contract, and Codeman is that supervisor (deepseek-status-shim.ts, from feat(deepseek): add DeepSeek Harness (dsh) as a ninth CLI run mode #337). So wait?until=stop on a dsh session is a definitive signal, not a guess.
• A real transcript. dsh writes structured JSONL per session. That half did not exist yet, and is the server-side work in this PR.

Server: last-response reads the dsh transcript

DeepSeek was falling through to the terminal-buffer segmenter used for the other external CLIs. For this mode that is not merely coarse, it is wrong: dsh-TUI paints a full-screen splash, so last-response on a fresh dsh session returned its ASCII-art logo, which anything polling for a worker's first reply reads as a reply.

src/deepseek-transcript.ts reads $DSH_HOME/sessions/<mangled-cwd>/<id>/session.jsonl.zstd instead. Four things in that file shaped it, all found against real transcripts on disk:

1. dsh appends one zstd FRAME per write, and Node's zlib zstd decoder (one-shot and streaming alike) stops at the first frame end. A real 56-line transcript decoded as 1 line / 158 bytes: the session header alone, a silent truncation that reads forever as "the worker never answered". The module walks zstd frame and block headers itself to find exact boundaries. Splitting on the 4-byte magic instead would corrupt everything after a magic sequence that happens to occur inside compressed data. zstd is resolved at runtime, because it landed in Node 22.15 while this project's floor is 22.0 and @types/node still does not declare it: an older Node keeps the previous pane behaviour rather than throwing.
2. Not every user/message is the user. Each turn also records a plugin-sourced runtime-context snapshot (sandbox policy, approval policy, cwd). Rendering those shows the agent its own boilerplate back as the user's words.
3. A failed turn is not an empty turn.turn/end carries the provider's error, surfaced as Turn error: … (and a non-error early stop such as max-tokens as Turn ended: …) instead of an empty string that reads as "still thinking" through fifteen polls.
4. Reply text is assembled per (turn, step). A finalized assistant/message wins; the streamed deltas fill in only for a step that never finalized, so a partial answer is readable mid-turn and never doubled. "Finalized" is tracked as a set of steps rather than as non-empty text: a step whose whole reply was reasoning strips to '' at the </think> boundary, and without that distinction the raw unstripped deltas were resurrected in its place, putting the model's monologue in front of the caller.

Session-to-transcript pairing is by the transcript's own header cwd plus a boot window against the Codeman session's createdAt — never by reproducing dsh's directory mangling (which already has two forms on disk), and never by newest-mtime alone. Mtime alone handed a freshly spawned worker its predecessor's answer from the same case directory, which is worse than saying nothing, because an agent cannot tell a stale answer from a fresh one.

Session.deepSeekHomeOverride is a deliberately narrow getter: envOverrides can hold provider credentials, and the reader needs the profile tree's location and nothing else.

Skill: dsh workers, driven like claude workers

Preamble 1.20.0 (SKILL.md's §0 heredoc is regenerated from preamble.sh, byte-identical as the existing test requires):

• spawn_worker grows a deepseek branch that gates on the harness composer. Readiness is not the stop signal: the harness reports idle at boot ~300 ms before its composer paints (measured 2.26 s vs 2.56 s after spawn, twice), so a send-and-wait fired straight after quick-start resolves on that boot edge, reports a turn that never ran, and strands the prompt in a pane that was not yet taking input. Waiting for the composer also spends that edge, since signals are edge-triggered with no history.
• spawn_workers accepts name[:mode], so a mixed fleet is one concurrent call. Case names still have to be unique — the mode never disambiguates two workers that would share a directory.
• sendwait asks for wait:"stop,exit" rather than the wait:true default set. That set also carries idle, which for an external CLI is inferred from output stabilization: on a dsh worker whose TUI repaints rarely, the re-wait resolved in 0 ms with signal:"idle" on a turn that had another three minutes to run. It also makes a wrong mode loud — the modes that cannot deliver stop answer 400 before writing anything, instead of resolving on a flap.
• The self-heal resend carries delivered:true forward. That resend is a tagged duplicate, so the server truthfully reports delivered:false about a write it skipped — but about the wrong send, and the fast path then read a completed turn as an undelivered one and kept a finished worker forever.
• dsh workers spawn with the permission posture the Run button already sends, because the harness default still asks and a worker parked on an approval row cannot finish a fan-out. The multi-user clamp still applies.

Docs: a worked dsh flow in recipes.md, readiness and signal rules in verbs.md, and the corrections this makes necessary — stop/blocked are no longer claude-only, and last-response is no longer permanently empty for deepseek. The integration guide gains a section on reading a session back and driving one as a worker; its web-UI section was also stale (that server moved out of a shell session in an earlier commit).

Measured against a live server

Verified end to end against a real dsh install (dsh 0.1.1-rc.2, @deepseek-harness-tui/dsh-tui 0.8.8) on an isolated Codeman instance:

• Mixed fleet (alpha claude + beta:deepseek) spawned and both ready in 6 s; both tasked concurrently, both resolved on a real stop (dsh 555 ms, claude 3894 ms), both answers read, 12 s total.
• Multi-turn on one dsh worker: ready in 2 s, two turns each ending on stop, each answer read back distinctly (the second read correctly refuses to return the first answer), full prompt/response/tool blocks via ?context=full, then a clean delete — 5 s total.
• Against a slow local model, a genuine tool-using turn: stop after 172 s, answer read from the transcript. Against a provider that rejected the request, the reader surfaced Turn error: 400: … does not support tools instead of an empty string.
• The frame walker was checked byte-for-byte against zstd -dc on all 13 real transcripts on the box, including one with 2470 frames.

Tests

test/deepseek-transcript.test.ts (21 tests) covers the frame walker (multi-frame, single-frame, uncompressed passthrough, torn tail, non-zstd), the parser (plugin-context filtering, reasoning strip, tool blocks, streamed-vs-finalized steps, last-turn semantics, turn errors) and the pairing rules (predecessor excluded, boot window vs a busier sibling, foreign workspace, /new mid-session, missing home).

test/agent-skill-mode-lists.test.ts — the static guard that stops the skill's prose from listing some external CLIs but not others — is extended rather than exempted: it now knows the three real classes inside that family (no transcript, no hook signals, and the positive twin: modes whose answers can be read), with the hook class derived from hooksAvailableForMode() so predicate and prose cannot drift. Any other partial list still fails, and a new backend belongs to none of the classes until someone says so.

Full suite green (npm test).

Note on the base

This is stacked on #337 (the DeepSeek Harness run mode), which it needs and which is not merged yet, so the diff here is only the new work. If #337 lands first, GitHub retargets this to master.