deepseek-harness/packages/subprocess/subprocess-local/README.md

@deepseek-ai/dsh-subprocess-local

English | 中文

Local Service Provider for the @deepseek-ai/dsh-subprocess seam. LocalSubprocessRuntime resolves local executables, gives ordinary Linux and Windows commands an OS-owned managed range when the host supports it, and implements terminal processes through node-pty plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling capability seams (dsh-bash-local, dsh-lsp-stdio, and dsh-terminal-bash).

Behavior

• One managed range for signal and wait — Linux uses a transient user-systemd scope when the manager supports literal argv and readable scope state. On Windows the parent creates private named-pipe endpoints for non-inherited streams; the runner opens only the target-side handles, creates the target suspended, assigns it to its kill-on-close Job, resumes it, and closes those pipe handles before publishing startup. The runner alone retains the original target process handle and Job, reports the direct result, and exits successfully only after ActiveProcesses reaches zero; the parent never opens either native object. Linux scopes and POSIX process-group fallbacks receive TERM and then KILL after graceMs; Windows Job and taskkill owners force-terminate on the first request. waitForExit() succeeds only after the selected owner proves the range empty and rejects when that proof is unavailable. .done remains the direct command result, and only collected pipes retain the existing bounded drain grace.
• Explicit weaker fallback — macOS, old or unavailable user-systemd, and unavailable Windows native support keep the existing detached PGID or taskkill /T path. The provider warns once before the first affected command. It never retries through fallback after a native runner may have started the user command.
• Per-stream dispositions — 'pipe' hands the raw stream to the caller untouched (protocol framing stays consumer-owned); 'inherit' passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting spill keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are 0600 with random names under a lazily-created 0700 per-process directory.
• Credential scrub + explicit merge — process.env minus credential-shaped vars (*KEY*/*PASSWORD*/*SECRET*/*TOKEN*) and all ambient DSH_* names; the spec's explicit env merges after that scrub with no namespace validation, so a deliberately supplied credential or current DSH_* fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is /dev/null. See the stdin/env Agent Note and managed environment Agent Note.
• Offset-based reads — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
• Executable lookup — resolveExecutable checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions; relative paths containing separators are rejected at the seam, and relative PATH entries resolve from the host process cwd.
• Terminal-process ownership — spawnTerminal allocates node-pty, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. On Windows the koffi-backed inspector enumerates the process table through Toolhelp32, combines GetProcessTimes start identities with zero-time process-handle waits for liveness, reports the shell pid as the pseudo foreground group (Windows has no POSIX groups), and teardown verifies the shell's termination because externally taskkilled shells may never fire node-pty's exit notification. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
• Terminate-and-join disposal — the service retains live handles so its own disposal can run each provider-owned termination procedure and await its exit; quiescent and spawn-failed handles leave the live set after managed-range or terminal-session cleanup finishes.
• Synchronous host-exit finalization — while the service effect is active, a Node exit listener synchronously signals every ordinary managed range and observable terminal session still in the live sets. Linux issues the scope KILL request; the Windows runner treats parent IPC disconnect as Job termination; fallback and terminal paths retain their PGID, taskkill, and captured-identity behavior. The listener creates no promise or timer, preserves the host exit code and diagnostic, contains each target failure, and does not claim quiescence. Normal disposal keeps the awaited managed-range path above. See the host-exit cleanup decision.

Model Experience

Indirectly, through Consumers (today the bash executor family behind dsh-tool-bash), which own all model-facing rendering of process output and lifecycle.

KV Cache effect

No direct invalidation; the named consumers own any request-prefix changes.

Known Limitations and Deferred Work

• Native ownership has explicit host requirements — Linux needs a readable user manager and systemd-run --expand-environment=no; older systemd versions use the warned PGID fallback. macOS always uses that fallback because no supported public persistent owner exists.
• Native launch has a synchronous setup cost — the first ordinary spawn probes host capability once for that provider instance, with a 5-second bound on each probe command. The local native path publishes a numeric target pid before returning, so each launch waits synchronously for its per-spawn runner to report target start or spawn failure. The built runner normally completes this handshake promptly; a runner that never publishes a result holds the caller for the fixed 10-second protocol bound. Each supported native command keeps one runner process alive until the OS-owned range is empty, and Windows additionally creates private per-spawn named-pipe endpoints. After publication, runner events are polled asynchronously every 100 ms and Linux scope state every 200 ms.
• Windows Job inheritance has defined exclusions — ordinary descendants inherit the Job by default, but breakaway processes are outside the guarantee. The target starts only after Job assignment; external termination of the runner in the narrow create-to-assignment interval can leave a suspended target behind.
• Windows terminal signalling is console-wide — SIGINT is delivered as a \x03 Ctrl-C input write that conhost turns into a console-wide CTRL_C event; SIGTSTP and SIGHUP are rejected as unavailable; a taskkill without /F does not terminate console processes, so the teardown TERM tier is a grace wait before the /F escalation. Windows readiness has no exact stdin-wait tier: the prompt-marker fast path compares the shell pid as the pseudo foreground group, and silence/timing tiers cover the rest.
• A daemonized terminal descendant can still escape the observable boundary — on macOS, a child that reparents before any foreground-inspection snapshot is no longer discoverable from the node-pty root; on Linux, a child that calls setsid leaves both the tree and owned terminal session. The local provider does not add a continuous process-table monitor.
• In-process cleanup requires a JavaScript-observable exit — direct process.exit(), default uncaught exceptions, and default unhandled rejections emit Node's synchronous exit event. The default OS disposition for an unhandled SIGTERM, SIGINT, or SIGHUP bypasses that event; an application covers those signals only by installing a handler that performs normal disposal or calls process.exit(). SIGKILL, fatal OOM, process.abort(), native crashes, power loss, and any failure that cannot run JavaScript require an external supervisor, container init, or equivalent OS owner.
• The credential scrub is a name heuristic — *KEY*/*PASSWORD*/*SECRET*/*TOKEN* only; differently-named secrets (e.g. *PASSPHRASE*) pass through, and a whitelist for over-scrubbed vars is noted future work.
• Completed spill files are not deleted — bounded full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them; oversize incomplete spills are discarded and deletion is attempted immediately, but a cleanup failure can leave a bounded file behind.

Common process handling lives in src/spawn.ts; Linux scopes, Windows Jobs, and the private runner live in their platform modules; src/index.ts owns selection and service wiring.