refactor(process): split the process manager out of the bash executor

New process/ capability family: @deepseek-ai/dsh-process owns ctx.processes —
abstract ProcessManager.spawn(spec) over a fully-explicit ProcessSpawnSpec —
plus the shared DSH_* managed-environment and CollectedOutput vocabulary;
@deepseek-ai/dsh-process-local carries the former bash-local run.ts plumbing
(detached groups, tail-keep spill-backed output, credential scrub, kill
escalation, kill-and-join disposal) with no config of its own.

dsh-bash-local becomes a consumer: it keeps command defaulting, the fused
deadline timedOut/aborted classification, the model-friendly terminal env
(now merged through the ordinary env channel), and the [stderr]-marked
background read merge, and spawns through ctx.processes. Background-process
lifetime moves to the manager, so an executor reload no longer kills live
background work; a background spawn failure is injected once into the read
path instead of being buffered as fake stderr. dsh-bash re-exports the moved
vocabulary so bash consumers keep one import root; dsh-bash-sandbox only
redeclares the inherited inject.

Every composition loading a bash executor now loads dsh-process-local (CLI,
examples, python bundled runtime, create-sdk bash feature, inline test
configs).

examples/acp-agent/composition.md

@@ -14,6 +14,8 @@ flowchart LR
   cfg --> plugin_acp_sandbox
   plugin_acp_sandbox_policy["sandbox-policy<br/>@deepseek-ai/dsh-sandbox-policy"]
   cfg --> plugin_acp_sandbox_policy
+  plugin_acp_processes["processes<br/>@deepseek-ai/dsh-process-local"]
+  cfg --> plugin_acp_processes
   plugin_acp_bash["bash<br/>@deepseek-ai/dsh-bash-sandbox"]
   cfg --> plugin_acp_bash
   plugin_acp_approval["approval<br/>@deepseek-ai/dsh-user-approval"]
@@ -68,6 +70,7 @@ flowchart LR
 | `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
 | `sandbox` | `@deepseek-ai/dsh-sandbox-local` |
 | `sandbox-policy` | `@deepseek-ai/dsh-sandbox-policy` |
+| `processes` | `@deepseek-ai/dsh-process-local` |
 | `bash` | `@deepseek-ai/dsh-bash-sandbox` |
 | `approval` | `@deepseek-ai/dsh-user-approval` |
 | `acp-agent` | `@deepseek-ai/dsh-acp-demo` |

examples/acp-agent/cordis.yml

@@ -33,6 +33,10 @@
     mode: !!js "process.env.DSH_PERMISSION_MODE ?? (process.env.DSH_SNAPSHOT === undefined ? 'workspace-write' : 'danger-full-access')"
     workspaceRoot: !!js process.cwd()
 
+# Managed child-process groups for the bash executor (spawn/kill/output plumbing).
+- id: processes
+  name: '@deepseek-ai/dsh-process-local'
+
 - id: bash
   name: '@deepseek-ai/dsh-bash-sandbox'
   config:

examples/cordis-agent/composition.md

@@ -12,6 +12,8 @@ flowchart LR
   cfg --> plugin_cordis_hmr
   plugin_cordis_llm_deepseek["llm-deepseek<br/>@deepseek-ai/dsh-llm-deepseek"]
   cfg --> plugin_cordis_llm_deepseek
+  plugin_cordis_processes["processes<br/>@deepseek-ai/dsh-process-local"]
+  cfg --> plugin_cordis_processes
   plugin_cordis_bash["bash<br/>@deepseek-ai/dsh-bash-local"]
   cfg --> plugin_cordis_bash
   plugin_cordis_fs_local["fs-local<br/>@deepseek-ai/dsh-fs-local"]
@@ -39,6 +41,7 @@ flowchart LR
 | --- | --- |
 | `hmr` | `@cordisjs/plugin-hmr` |
 | `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
+| `processes` | `@deepseek-ai/dsh-process-local` |
 | `bash` | `@deepseek-ai/dsh-bash-local` |
 | `fs-local` | `@deepseek-ai/dsh-fs-local` |
 | `web` | `@deepseek-ai/dsh-web` |

examples/cordis-agent/cordis.yml

@@ -25,6 +25,10 @@
 
 # Local bash executor for agent-spine-demo's tool-bash schema — gives the agent an
 # ordinary tool whose calls make the mounted listeners observably fire.
+# Managed child-process groups for the bash executor (spawn/kill/output plumbing).
+- id: processes
+  name: '@deepseek-ai/dsh-process-local'
+
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
   config:

examples/headless-agent/composition.md

@@ -10,6 +10,8 @@ flowchart LR
   cfg["examples/headless-agent<br/>cordis.yml"]
   plugin_headless_llm_deepseek["llm-deepseek<br/>@deepseek-ai/dsh-llm-deepseek"]
   cfg --> plugin_headless_llm_deepseek
+  plugin_headless_processes["processes<br/>@deepseek-ai/dsh-process-local"]
+  cfg --> plugin_headless_processes
   plugin_headless_bash["bash<br/>@deepseek-ai/dsh-bash-local"]
   cfg --> plugin_headless_bash
   plugin_headless_cli_agent["cli-agent<br/>@deepseek-ai/dsh-cli-demo"]
@@ -54,6 +56,7 @@ flowchart LR
 | Plugin id | Package / module |
 | --- | --- |
 | `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
+| `processes` | `@deepseek-ai/dsh-process-local` |
 | `bash` | `@deepseek-ai/dsh-bash-local` |
 | `cli-agent` | `@deepseek-ai/dsh-cli-demo` |
 | `token-meter` | `@deepseek-ai/dsh-token-meter` |

examples/headless-agent/cordis.yml

@@ -19,6 +19,10 @@
       - id: deepseek-v4-flash
         contextWindow: 128000
 
+# Managed child-process groups for the bash executor (spawn/kill/output plumbing).
+- id: processes
+  name: '@deepseek-ai/dsh-process-local'
+
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
   config:

examples/headless-agent/semantic-checkpoint.cordis.snapshot.yml

@@ -17,6 +17,10 @@
     file: !!js process.env.DSH_SNAPSHOT_FILE
     overrideFile: !!js process.env.DSH_SNAPSHOT_OVERRIDE
 
+# Managed child-process groups for the bash executor (spawn/kill/output plumbing).
+- id: processes
+  name: '@deepseek-ai/dsh-process-local'
+
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
   config:

examples/headless-agent/tests/code-mode.e2e.ts

@@ -13,6 +13,7 @@ import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import LocalProcessManager from '@deepseek-ai/dsh-process-local'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 import { WorkerCodeRuntime } from '@deepseek-ai/dsh-code-runtime-worker'
@@ -55,6 +56,7 @@ async function codeModeHarness(cwd: string): Promise<Context> {
   await harness.plugin(AgentRegistry)
   await harness.plugin(AgentLoop, { agents: [] })
   await harness.plugin(LlmDeepSeek)
+  await harness.plugin(LocalProcessManager)
   await harness.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 })
   await harness.plugin(ToolBash)
   await harness.plugin(WorkerCodeRuntime, {})
@@ -114,6 +116,7 @@ async function backgroundCodeModeHarness(cwd: string): Promise<Context> {
   const harness = await typedCodeModeHarness()
   await harness.plugin(LocalTaskService)
   await harness.plugin(ToolTasks, {})
+  await harness.plugin(LocalProcessManager)
   await harness.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 })
   await harness.plugin(ToolBash)
   return harness

examples/headless-agent/tests/fixtures/goal-domain/cordis.yml

@@ -2,6 +2,10 @@
 - id: cli-mock-llm
   name: '../cli-mock-llm.ts'
 
+# Managed child-process groups for the bash executor (spawn/kill/output plumbing).
+- id: processes
+  name: '@deepseek-ai/dsh-process-local'
+
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
 

examples/headless-agent/tests/fixtures/time-context.cordis.yml

@@ -2,6 +2,10 @@
 - id: time-context-mock-llm
   name: './time-context-mock-llm.ts'
 
+# Managed child-process groups for the bash executor (spawn/kill/output plumbing).
+- id: processes
+  name: '@deepseek-ai/dsh-process-local'
+
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
 

examples/headless-agent/tests/harness.ts

@@ -4,6 +4,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import LocalProcessManager from '@deepseek-ai/dsh-process-local'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
@@ -59,6 +60,7 @@ export async function codingHarness(workdir: string, options: CodingHarnessOptio
   await ctx.plugin(LlmDeepSeek, options.modelContextWindow === undefined ? {} : {
     models: [{ id: 'deepseek-v4-flash', contextWindow: options.modelContextWindow }],
   })
+  await ctx.plugin(LocalProcessManager)
   await ctx.plugin(LocalBashExecutor, { cwd: workdir, timeoutMs: 30_000 })
   await ctx.plugin(ToolBash)
   await ctx.plugin(ToolTodo)

examples/jsonrpc-agent/cordis.yml

@@ -17,6 +17,10 @@
     thinking: enabled
     reasoningEffort: max
 
+# Managed child-process groups for the bash executor (spawn/kill/output plumbing).
+- id: processes
+  name: '@deepseek-ai/dsh-process-local'
+
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
   config:

examples/package.json

@@ -31,6 +31,7 @@
     "@deepseek-ai/dsh-lsp": "workspace:*",
     "@deepseek-ai/dsh-lsp-local": "workspace:*",
     "@deepseek-ai/dsh-plan-mode": "workspace:*",
+    "@deepseek-ai/dsh-process-local": "workspace:*",
     "@deepseek-ai/dsh-permission": "workspace:*",
     "@deepseek-ai/dsh-pty": "workspace:*",
     "@deepseek-ai/dsh-pty-local": "workspace:*",

examples/tui-agent/composition.md

@@ -12,6 +12,8 @@ flowchart LR
   cfg --> plugin_tui_hmr
   plugin_tui_llm_deepseek["llm-deepseek<br/>@deepseek-ai/dsh-llm-deepseek"]
   cfg --> plugin_tui_llm_deepseek
+  plugin_tui_processes["processes<br/>@deepseek-ai/dsh-process-local"]
+  cfg --> plugin_tui_processes
   plugin_tui_bash["bash<br/>@deepseek-ai/dsh-bash-local"]
   cfg --> plugin_tui_bash
   plugin_tui_tui_agent["tui-agent<br/>@deepseek-ai/dsh-tui-demo"]
@@ -69,6 +71,7 @@ flowchart LR
 | --- | --- |
 | `hmr` | `@cordisjs/plugin-hmr` |
 | `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
+| `processes` | `@deepseek-ai/dsh-process-local` |
 | `bash` | `@deepseek-ai/dsh-bash-local` |
 | `tui-agent` | `@deepseek-ai/dsh-tui-demo` |
 | `session-title-llm` | `@deepseek-ai/dsh-session-title-first-message-llm` |

examples/tui-agent/cordis.yml

@@ -21,6 +21,10 @@
     reasoningEffort: max
 
 # Local executor for the app bundle's bash tool.
+# Managed child-process groups for the bash executor (spawn/kill/output plumbing).
+- id: processes
+  name: '@deepseek-ai/dsh-process-local'
+
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
   config:

examples/tui-agent/tests/fixtures/tui-scripted.cordis.yml

@@ -4,6 +4,10 @@
 - id: scripted-llm
   name: './tui-scripted-llm.ts'
 
+# Managed child-process groups for the bash executor (spawn/kill/output plumbing).
+- id: processes
+  name: '@deepseek-ai/dsh-process-local'
+
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
 

examples/tui-agent/tests/tui.snapshot.ts

@@ -8,6 +8,7 @@ import { scrubRequestHeaders } from '@deepseek-ai/dsh-acp-snapshot'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import * as AgentCore from '@deepseek-ai/dsh-agent-spine-demo'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import LocalProcessManager from '@deepseek-ai/dsh-process-local'
 import WorkerCodeRuntime from '@deepseek-ai/dsh-code-runtime-worker'
 import CommandService from '@deepseek-ai/dsh-commands'
 import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
@@ -204,6 +205,7 @@ async function mountScenarioContext(
     skills: { local: { agentsHome: join(cwd, '.agents') } },
   })
   await ctx.plugin(TokenMeterService)
+  await ctx.plugin(LocalProcessManager)
   await ctx.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 })
   await ctx.plugin(SnapshotLocalFileSystem, { cwd: '/' })
   await ctx.plugin(FsPolicy)