DSH plugin subprocess: spawn specs and stdio handling
"Output came back incomplete" and "the exit reason is unclear" usually share one root cause: assuming the seam fills in defaults. DSH plugin's subprocess seam applies none. Every stream disposition, every limit, and every directory must be explicit in the spec.
This seam applies no defaults
All dispositions and limits come from the caller; hidden defaults are treated as a design defect.(source)
The fields of SubprocessSpawnSpec are the entire input: argv, cwd, stdio, graceMs, optional signal, and optional env. The reference is blunt: this seam applies no defaults, because the caller's own configuration should decide those values rather than some hidden subprocess service default.
argv is never shell-interpreted — argv[0] is the program and the rest are arguments. This is the same thinking as the shell request/spec split: finish the explicit work at the boundary and let the execution layer stop guessing. For pipes or redirection, run a shell explicitly and pass the command as an argument.
graceMs is constrained too: a positive finite millisecond value no greater than MAX_TIMER_DELAY_MS. It is both the provider's grace period for termination and the drain allowance for collection pipes still open after exit — a survivor holding an inherited descriptor must not stall the result forever.
Executable resolution lives in the same world
Spawn's working directory, executable path, and filesystem provider share one path and process namespace.(source)
resolveExecutable(command, env?, signal?) does two things: validate an absolute executable path, or resolve a bare name through the provider's sanitized PATH plus intentional overrides.
One easily missed rejection rule: a relative path containing separators is rejected because its resolution base is undefined, and the provider prefers explicit failure to guessing. SubprocessExecutableNotFoundError means the executable does not exist; provider and transport faults remain ordinary errors, so do not fold both into one handler.
Managed DSH_* and env merge order
DSH_* is stripped before injection, so caller env cannot impersonate managed facts.(source)
DSH_* names are harness-owned subprocess facts. Implementations discard existing DSH_* names before merging the caller's explicit env, so current facts only arrive as intentionally provided string entries.
Two more merge details: env merges onto the provider-sanitized parent environment base and receives no namespace validation; a string is an intentional caller choice, so forwarded credential-shaped entries or current DSH_* facts survive the scrub. An explicit undefined is a tombstone that deletes an existing value from the child's normal environment.
That makes the scrub a default baseline rather than an absolute safety net: what you pass is what gets through.
stdio dispositions are all explicit
Three output dispositions mean three completely different consumption models.(source)
stdin has three forms: 'ignore' leaves fd 0 on /dev/null; 'pipe' exposes handle.stdin for continuous writes; { data } writes bytes and closes, the batch form.
stdout and stderr have three: 'pipe' exposes the raw Readable for protocol decoding; 'inherit' passes through to the parent descriptor, sending child diagnostics to the harness's own streams; a SubprocessCollect object buffers bounded memory and offers offset-based reads.
Collection has two caps: maxBytes is the memory limit, retaining the tail on overflow, and optional spill.maxBytes caps the whole stream, discarding an already incomplete spill file once the stream exceeds it. The reference's trade-off is clean: use raw pipes for framed protocols (LSP JSON-RPC, ACP ndjson), inherit for diagnostics, and collection for bounded batch output. Spill is optional, so a language server's stderr can keep just a tail in memory and write no file.
There is also control?: 'pipe': request an independent byte-mode duplex channel, created only when asked. Native launch failure can leave it missing, so null-check before reading.
To learn which shell an environment defaults to, call terminalEnvironment(signal?), returning the execution platform (posix or windows) and an optional defaultShell. These facts come from the provider, not from a web server or browser; executable resolution and terminal allocation remain separate operations.
Handle: readers never consume; terminate the managed range
Collection reads are offset-based, so multiple readers never steal bytes.(source)
spawn synchronously returns a live handle, while target and managed-range identity stay inside the provider. Collection readers accept whole-stream byte offsets and never consume, so independent readers keep their own increments; piped streams belong to the caller.
SubprocessOutputReader.readFrom(fromByte) returns text, nextOffset, lossy, and an optional spillPath. A read is lossy when the requested offset has slid out of the retained tail window — it returns the whole retained tail, and only the spill file can recover the gap. Calling readFrom(0) after settlement is the batch result, where lossy means the in-memory tail lost its head, matching the CollectedOutput.truncated fact.
Termination has two verbs: terminate() starts the provider-recorded termination, is idempotent, becomes a no-op once the range disappears, and also fires on the spec's abort signal; waitForExit(signal?) observes the same provider-managed range rather than just the spawned command ending, so surviving work stays observable. It returns true for an empty range, false when the signal aborts first, and throws when the provider can no longer observe the range.
The outcome carries exit facts only
done judges neither timeout nor cancellation and carries no output.(source)
SubprocessOutcome has two fields: exitCode (null when a signal killed it) and signal (null on a normal exit). It speaks Node's close event vocabulary and deliberately excludes timeout or cancellation classes and any output.
The division of responsibility explains why: the service terminates a process on abort but never judges the cause, leaving the caller to classify with the deadline signal it owns — the bash executor's timedOut/aborted split being the reference example. Collected output remains readable through handle.collected after settlement, so batch and streaming callers share one access path.
Looking for "did it time out" inside done means looking in the wrong layer. A timeout is your timer's fact, not the subprocess's.
Terminal primitives are not a spawn substitute
Use spawnTerminal when you need terminal semantics; plain spawn() cannot reconstruct them.(source)
spawnTerminal(spec) is the non-piped process primitive. The provider allocates a controlling terminal and handles UTF-8 text transport, foreground process group checks and signal delivery, plus an awaitable TERM→KILL operation that brings every still-observable session member fully to rest.
Its boundaries are clear: the PTY backend still owns prompt detection, readiness inference, scrollback, sandbox policy, and persistent session ownership. The terminal handle exposes pid, ordered output, done, write, resize, inspectForeground, inspectActivity, signalForeground, and an awaitable terminate. resize(cols, rows) updates a running PTY and rejects after exit; inspectActivity() reports state as only idle, busy, or unknown, with revision changing on observed activity or input.
Verification: large output and signal exit
Cover truncation, offset reading, and exit facts — skipping one hides a class of production bug.(source)
- Spawn a collect-mode command producing more than
maxBytesand assertreadFrom(0)reportslossywith aspillPath. - Repeat without spill and assert
lossyis still true, no path appears, and only the tail is returned. - Have two readers read the same stream at different offsets and assert neither disturbs the other's bytes.
- Send
SIGTERMand let the command exit itself, assertingdonereportssignalasSIGTERMandexitCodeasnull. - Call
spawnwith an already-abortedsignaland assert a synchronous throw with no handle published. - Call
terminate()thenwaitForExit()and assert the range is clear; callterminate()again on a finished handle and assert it is a no-op.
If step 1 shows no lossy, check whether you used pipe mode — pipes never buffer and never offer offset reads.
For how the shell layer resolves requests into specs, see shell resolve split; for encoding issues in large-output truncation, see subprocess byte truncation and UTF-8.
One line to close: specs carry no defaults, argv skips the shell, DSH_* is cleared before injection, each stdio path has its own contract, reads are offset-based and non-consuming, and done reports exit facts alone.
FAQ
No. DSH plugin's spawn spec applies no defaults. DSH plugin requires each stream disposition, limit, and directory explicitly, decided by the caller's own configuration rather than a hidden service default.
No. DSH plugin states argv is never shell-interpreted. DSH plugin treats argv[0] as the program and the rest as arguments, so invoke a shell explicitly when shell syntax is needed.
No. DSH plugin's readers take whole-stream byte offsets and never consume, so independent readers keep their own increments. Piped streams, by contrast, belong to the caller.
No. DSH plugin's done carries exit facts only. DSH plugin kills the process on abort without judging why, so the caller classifies timedOut and aborted from the deadline signal it owns.
Related Terms
- SubprocessSpawnSpec
- SubprocessSpawnSpec is a fully specified spawn request: argv, cwd, stdio, graceMs, optional signal, and optional env.— packages/subprocess/subprocess/src/types.ts
- SubprocessCollect
- SubprocessCollect is the bounded in-memory collection config for one stream, with maxBytes and an optional whole-stream spill cap.— packages/subprocess/subprocess/src/types.ts
- SubprocessHandle
- SubprocessHandle is a live child handle exposing streams, collection readers, done, terminate, and waitForExit.— packages/subprocess/subprocess/src/types.ts
- SubprocessOutcome
- SubprocessOutcome carries only Node close-event exit code and signal, with no timeout or cancellation class and no output.— packages/subprocess/subprocess/src/types.ts
Sources
- DeepSeek Harness reference - Subprocess· deepseek-ai
- packages/subprocess/subprocess/src/types.ts· deepseek-ai