@qilin-agent/subprocess 0.0.0-stage → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,73 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/subprocess/subprocess/README.md
+/:
+  en: 04735af7a998f2ae
+  zh: ab6bf3d0f098877a
+/qilin-agent-subprocess:
+  en: 6ab08fb7aa6e9736
+  zh: fd7b901fe1374a75
+/qilin-agent-subprocess/summary:
+  en: 87c6ecd841999072
+  zh: 8e0d4601d15c0b08
+/qilin-agent-subprocess/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-agent-subprocess/use-this-package:
+  en: a43391b5840a4c58
+  zh: a0a9c3fa577d92c0
+/qilin-agent-subprocess/use-this-package/mounting-the-service:
+  en: 82be7c63ab95994f
+  zh: 8810e7c489b444df
+/qilin-agent-subprocess/use-this-package/starting-a-managed-process:
+  en: 891cb74d5d35095c
+  zh: 296cb1890116fb05
+/qilin-agent-subprocess/use-this-package/choosing-how-output-is-delivered:
+  en: c02fe7246326c164
+  zh: 1d31096e31e1feee
+/qilin-agent-subprocess/use-this-package/using-a-control-pipe:
+  en: 6a246be51761434a
+  zh: c82c245484ebc810
+/qilin-agent-subprocess/use-this-package/managing-process-lifetime:
+  en: 83d662d278184411
+  zh: 2c4e7fbe76823fa8
+/qilin-agent-subprocess/use-this-package/running-a-terminal-session:
+  en: e3631497344c2ebd
+  zh: c4ebc7b08f0a316e
+/qilin-agent-subprocess/use-this-package/environment-every-child-starts-from:
+  en: 9a653a40ff7f91a4
+  zh: 11521e762b848df1
+/qilin-agent-subprocess/use-this-package/what-can-go-wrong:
+  en: 51f2f43087a1ed18
+  zh: 6d2ebb099b707df3
+/qilin-agent-subprocess/understand-the-implementation:
+  en: 25cd344c959cfd9e
+  zh: 045880776ab82d1e
+/qilin-agent-subprocess/understand-the-implementation/design-concept:
+  en: 88202ec45795ea88
+  zh: ce25ca53dfe367b9
+/qilin-agent-subprocess/understand-the-implementation/source-map:
+  en: 0c0a492befb161e1
+  zh: dc22dd87990a7fac
+/qilin-agent-subprocess/understand-the-implementation/data-model-and-flow:
+  en: 9998dc0a990fbcf1
+  zh: ba179617f60cb9bc
+/qilin-agent-subprocess/understand-the-implementation/lifecycle-and-invariants:
+  en: a132325eea7cadb4
+  zh: 434cbbc61ff9cd0e
+/qilin-agent-subprocess/further-exploration:
+  en: cbc95f1e4d71fb55
+  zh: 6d759e6c514aeba8
+/qilin-agent-subprocess/model-experience:
+  en: 36d8f1820f81de29
+  zh: da18a4123bdd28b7
+/qilin-agent-subprocess/model-experience/kv-cache-effect:
+  en: e290ccc9b3c92c08
+  zh: d75d48f485447a74
+/qilin-agent-subprocess/known-limitations-and-deferred-work:
+  en: 0b1c46aec1ba628d
+  zh: cf2a0db9d0682155
+/qilin-agent-subprocess/known-limitations-and-deferred-work/dev-note:
+  en: 56709c22873429b5
+  zh: c0e86c62982a3e29

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+---
+description: "The subprocess service (ctx.subprocess) for composition authors and capability consumers starting, observing, and terminating managed child processes and terminal sessions."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/subprocess
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`ctx.subprocess` resolves executables, starts explicitly specified child processes or real terminal sessions, streams or collects bounded output, and terminates the full managed process range. Configure one subprocess implementation for each composition, choosing local or remote execution according to where commands must run. Each request sets argv, working directory, stdio, environment overrides, termination grace, and cancellation, with no shell interpretation or hidden execution defaults. Child environments remove ambient credentials and `QILIN_*` values before applying explicit overrides; callers own deadlines, teardown policy, and model-facing rendering, while collected output remains readable after exit.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount a subprocess provider in any composition that must run child processes, and call `ctx.subprocess` from the capability that owns the command. The common path is explicit: resolve the executable, spawn with a fully specified request, read the output you asked for, and terminate the managed range when the work is done.
+
+### Mounting the service
+
+One provider registers `ctx.subprocess` per composition; load it beside the consumers that spawn through it — the bash executors, the LSP host, the PTY shell backend, or an out-of-process subagent backend. Loading a second provider fails loudly (one service per context, Cordis standard).
+
+```yaml
+- name: '@qilin-agent/subprocess-local'
+- name: '@qilin-agent/bash-local'
+```
+
+### Starting a managed process
+
+The request is fully explicit: the program and arguments, the working directory, one stdio disposition per stream, a termination grace, an optional abort signal, and optional environment overrides. Target and managed-range identities remain provider-private. `done` resolves with the direct command's exit facts (`exitCode` and `signal`) and rejects for spawn or provider failures; collected output stays readable after exit.
+
+```text
+const executable = await ctx.subprocess.resolveExecutable('bash')
+const handle = ctx.subprocess.spawn({
+  argv: [executable, '-c', 'echo hello'],
+  cwd: '/workspace',
+  stdio: { stdin: 'ignore', stdout: { maxBytes: 64 * 1024 }, stderr: 'inherit' },
+  graceMs: 5000,
+})
+const { exitCode, signal } = await handle.done
+const output = handle.collected.stdout?.readFrom(0)
+```
+
+### Choosing how output is delivered
+
+- `'pipe'` hands you the raw stream for your own protocol framing — JSON-RPC for the LSP host, ndjson for the ACP backend.
+- `'inherit'` lets the child write to the parent's own stream, for pass-through diagnostics.
+- A collect object buffers a bounded in-memory tail; add a `spill` cap and the complete stream is also recoverable from a spill file.
+
+Reads are offset-based and non-consuming: a background reader and a final batch read can share one stream without stealing each other's bytes.
+
+<a id="using-a-control-pipe"></a>
+### Using a control pipe
+
+Set `stdio.control: 'pipe'` to receive a separate raw `Duplex` in `handle.control`. The Node child opens fd 7 with `openInheritedControlChannel()` from `@qilin-agent/subprocess/control`; this helper consumes the provider-owned `QILIN_SUBPROCESS_CONTROL=pipe` marker. Callers cannot supply that marker through `env`. Control bytes never enter stdout/stderr collectors. The consumer owns framing, validation, backpressure, and closing its endpoint; provider disposal destroys any endpoint remaining after process teardown. Omitting the request returns `control: undefined`. This channel is available only for ordinary processes, and carries no authority to bypass tool approval.
+
+### Managing process lifetime
+
+Termination and waiting use one provider-managed range. `terminate()` starts the provider's documented procedure, is idempotent, and becomes a no-op after that range is empty; the request's abort signal starts the same procedure. `waitForExit()` observes the same range and resolves only after the provider proves it quiescent, so direct command completion does not hide a surviving descendant. It rejects when the selected owner can no longer prove quiescence. Providers document their native owners and weaker fallbacks; callers own deadlines, teardown ladders, and cause classification.
+
+### Running a terminal session
+
+For interactive programs, `spawnTerminal` allocates a real PTY: write text, read UTF-8 output, inspect and signal the current foreground process group, and await one `terminate()` that settles every session member the provider can still observe. Readiness, scrollback, and prompt policy stay with the PTY consumer.
+
+A terminal request can opt into `shellActivity`. `inspectActivity()` combines supported shell lifecycle evidence with owned-job observations and returns `idle`, `busy` or `unknown`, plus a handle-scoped revision. Unsupported or incomplete observations never imply idle; input invalidates existing prompt evidence. Opted-in terminals keep remaining work owned after the root shell exits instead of using that exit as permission to terminate descendants. Consumers own retention and cleanup deadlines.
+
+### Environment every child starts from
+
+Children never inherit the harness's ambient secrets: credential-shaped names and ambient `QILIN_*` facts are scrubbed, and the caller's explicit `env` merges after that scrub. A deliberately forwarded credential or a current `QILIN_*` deployment fact still reaches the child; an explicit `undefined` tombstone removes an ordinary ambient entry.
+
+### What can go wrong
+
+An executable that cannot be resolved fails loudly with a stable error. A spawn that never starts rejects `done`; there is no buffered output for a process that never ran. `waitForExit()` also rejects when the provider cannot prove its selected range is empty, and a provider fallback may not own descendants that escape its process group or observed session. When a transport owns its own spawn (the SDK client, MCP), route around the service and import `scrubbedParentEnv` directly so environment policy stays single-sourced.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the seam and points at the code that realizes them; the observable behavior is covered in [Use this package](#use-this-package).
+
+### Design concept
+
+The seam is built on one separation: the service owns process coordinates and lifetime; consumers own what a process means and every default that shapes one. That is why the spawn request is fully explicit — no hidden subprocess-service default — and why `SubprocessOutcome` carries exit facts only: callers own deadlines, teardown ladders, and cause classification. The `qilin-shell` request/spec split is the owning template.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: abstract `SubprocessRuntime`, `ctx.subprocess` registration, the shared `scrubbedParentEnv` scrub |
+| [`src/types.ts`](src/types.ts) | Vocabulary: spawn spec, stdio modes, handles, readers, outcomes, `QILIN_*` namespace |
+
+### Data model and flow
+
+A spawn returns a live handle immediately without exposing target identity. `done` independently reports the direct command outcome or failure, while `waitForExit()` reports managed-range quiescence. The request's abort signal drives the same termination procedure as `terminate()`. Collected readers are cursor-free: offsets are whole-stream byte coordinates the caller owns, so independent readers cannot consume one another's output, and a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. `spawnTerminal` is one deep primitive because ordinary pipes cannot allocate a controlling terminal or clean terminal-session members.
+
+### Lifecycle and invariants
+
+One implementation registers per context; loading a second throws (Cordis standard). Disposal of the service terminates every still-running managed process and awaits its exit, so process lifetime survives consumer reloads. `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself. Terminal allocation cancellation (the spec signal) is separate from the published handle's lifetime.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the exhaustive type reference to the providers and the decision evidence behind the seam.
+
+- [Subprocess subsystem](../../../docs/subsystems/subprocess.md) — spawn specs, output readers, outcomes, and the `QILIN_*` environment in full.
+- [qilin-subprocess-local](../subprocess-local/README.md) — the local host provider that implements this contract.
+- [qilin-bash-local](../../shell/bash-local/README.md) — the largest consumer: bash commands over this service.
+- [Subprocess seam Agent Note](../../../.agents/notes/archived/architecture/2026-07-26-subprocess-seam.md) — why the process half became its own seam and what moved with it.
+
+-----
+
+Terminal consumers use `terminalEnvironment()` to read the provider platform and preferred shell, and `resolveExecutable()` to verify candidates. A completed lookup miss throws `SubprocessExecutableNotFoundError`; transport failures remain distinct. `spawnTerminal` requires `terminalType` and initial dimensions, and its handle supports `resize(cols, rows)` without reallocating the process.
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through consumer seams such as the bash executor family, 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
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the seam is a poor fit or leaves work to its consumers. They are current package constraints, not a comparison or a backlog.
+
+- **SDK-managed spawns remain outside** — a transport that owns its internal spawn (the SDK client, MCP) cannot route that call through this service; it can still import `scrubbedParentEnv` so environment policy stays single-sourced.
+- **Teardown ladders are consumer-owned** — the seam ships signalling verbs and the managed-range wait, not a canned quiesce sequence; each out-of-process consumer encodes its child's cooperation shape itself (the ACP backend's stdin-EOF-first ladder is the in-repo template).
+- **Observability is provider-specific** — native providers may own escaped descendants through systemd scopes or Windows Jobs, while fallback providers expose weaker process-group, tree, or session visibility. The seam adds no continuous process-table monitor.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: open design questions and directions that are not decided. It is explicitly non-authoritative — shipped behavior, limits, and accepted rationale live in the sections above, the package code, and the linked Agent Notes.
+
+Future: non-shell runners. The seam was split so a direct-argv executor or worker supervisor could consume it without reaching into bash internals; none is shipped yet, and the terminal primitive keeps readiness policy in its consumer.
+
+</details>

package/README.zh.md

@@ -0,0 +1,163 @@
+---
+description: "面向组合作者与能力消费方的子进程服务（`ctx.subprocess`）说明：启动、观察并终止受管子进程与终端会话。"
+kind: "package-reference"
+---
+
+# @qilin-agent/subprocess
+
+[English](README.md) | 中文
+
+## 概述
+
+`ctx.subprocess` 可解析可执行文件、启动显式指定的子进程或真实终端会话、流式读取或有界收集输出，并终止完整的受管进程范围。每个组合配置一个 subprocess 实现，并根据命令运行位置选择本地或远程执行。每次请求都指定 argv、工作目录、stdio、环境覆盖、终止宽限期与取消信号，不会添加 shell 解释或隐藏的执行默认值。子进程环境会先移除环境中的凭据与 `QILIN_*` 值，再应用显式覆盖；时限、拆卸策略与面向模型的渲染由调用方负责，收集的输出在进程退出后仍可读取。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在需要运行子进程的组合中挂载一个 subprocess 提供方，并从拥有该命令的能力调用 `ctx.subprocess`。常用路径是显式的：解析可执行文件、用完全明确的请求 spawn、读取你要的输出，并在工作完成时终止受管范围。
+
+### 挂载服务
+
+每个组合由唯一一个提供方注册 `ctx.subprocess`；把它与经由它 spawn 的消费方放在一起加载——bash 执行器、LSP 主机、PTY shell 后端或进程外 subagent 后端。加载第二个提供方会快速失败（每个上下文只有一个服务，这是 Cordis 的标准行为）。
+
+```yaml
+- name: '@qilin-agent/subprocess-local'
+- name: '@qilin-agent/bash-local'
+```
+
+### 启动受管进程
+
+请求完全明确：程序与参数、工作目录、每条流一种 stdio 处置方式、终止宽限期、可选的中止信号与可选的环境覆盖。目标与受管范围标识保留在提供方内部。`done` 以直接命令的退出事实（`exitCode` 与 `signal`）resolve，并在 spawn 或提供方失败时 reject；收集输出在退出后仍可读取。
+
+```text
+const executable = await ctx.subprocess.resolveExecutable('bash')
+const handle = ctx.subprocess.spawn({
+  argv: [executable, '-c', 'echo hello'],
+  cwd: '/workspace',
+  stdio: { stdin: 'ignore', stdout: { maxBytes: 64 * 1024 }, stderr: 'inherit' },
+  graceMs: 5000,
+})
+const { exitCode, signal } = await handle.done
+const output = handle.collected.stdout?.readFrom(0)
+```
+
+### 选择输出投递方式
+
+- `'pipe'` 把原始流交给你做自己的协议分帧——LSP 主机用 JSON-RPC，ACP（Agent Client Protocol）后端用 ndjson。
+- `'inherit'` 让子进程直接写父进程自己的流，用于直通诊断输出。
+- 收集对象（collect object）在内存中缓冲一段有界尾部；加上 `spill` 上限后，完整流还可以从 spill 文件中恢复。
+
+读取基于偏移量且从不消费：后台读取与最终批量读取可以共享同一条流，而不会抢走彼此的字节。
+
+<a id="using-a-control-pipe"></a>
+### 使用控制管道
+
+设置 `stdio.control: 'pipe'` 后，`handle.control` 会返回独立的原始 `Duplex`。Node 子进程通过 `@qilin-agent/subprocess/control` 的 `openInheritedControlChannel()` 打开 fd 7；该辅助函数会消费提供方拥有的 `QILIN_SUBPROCESS_CONTROL=pipe` 标记。调用方不能通过 `env` 提供该标记。控制字节不会进入 stdout/stderr 收集器。消费方负责分帧、校验、背压和关闭自身端点；提供方销毁时会在进程拆卸后销毁仍存在的端点。省略请求则返回 `control: undefined`。该通道仅适用于普通进程，不授予绕过工具审批的权限。
+
+### 管理进程生命周期
+
+终止与等待使用同一个由提供方管理的范围。`terminate()` 会启动提供方记录的流程，具有幂等性，并在该范围为空后成为空操作；请求的中止信号会启动同一流程。`waitForExit()` 观察同一范围，只在提供方证明它完全停稳后 resolve，因此直接命令结束不会掩盖仍存活的后代。所选 owner 无法再证明完全停稳时，它会 reject。提供方记录其 native owner 与较弱 fallback；时限、拆卸阶梯与原因分类归调用方所有。
+
+### 运行终端会话
+
+对于交互式程序，`spawnTerminal` 分配真实 PTY：写入文本、读取 UTF-8 输出、检查当前前台进程组并向其发送信号，以及等待一次 `terminate()`，让提供方仍可观察到的每个会话成员完全停稳。就绪状态、scrollback 与提示符策略仍归 PTY 消费方所有。
+
+终端请求可显式启用 `shellActivity`。`inspectActivity()` 结合支持的 shell 生命周期信号与自有任务观察，返回 `idle`、`busy` 或 `unknown`，以及句柄内的 revision。不支持或不完整的观察不能推出空闲；输入会使已有提示符证据失效。启用后，根 shell 退出时继续持有剩余工作，不把该退出视为终止后代进程的许可。保活和清理期限由消费者决定。
+
+### 每个子进程起步时的环境
+
+子进程永远不会隐式继承 harness 的环境秘密：形似凭据的名称与环境中的 `QILIN_*` 事实都会被清除，调用方显式的 `env` 在该清除之后合并。有意转发的凭据或当前的 `QILIN_*` 部署事实仍会到达子进程；显式的 `undefined` 墓碑值则移除一个普通的环境项。
+
+### 可能出错的地方
+
+无法解析可执行文件时，服务会明确报出稳定的错误。从未启动成功的 spawn 会让 `done` reject；从未运行过的进程没有任何缓冲输出。提供方无法证明所选范围为空时，`waitForExit()` 也会 reject；提供方 fallback 可能无法拥有逃离其进程组或已观察会话的后代。当传输拥有自己的 spawn（SDK 客户端、MCP）时，请绕开本服务并直接导入 `scrubbedParentEnv`，让环境策略保持单一来源。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释 seam 背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中说明。
+
+### 设计理念
+
+本 seam 建立在一个分离之上：服务负责进程坐标与生命周期；消费方负责定义进程的含义，以及决定塑造该进程的每一项默认值。正因如此，spawn 请求完全明确——没有任何隐藏的子进程服务默认值——`SubprocessOutcome` 也只携带退出事实：时限、拆卸阶梯与原因分类归调用方所有。`qilin-shell` 的 request/spec 拆分是这条规则的所属模板。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：抽象 `SubprocessRuntime`、`ctx.subprocess` 注册、共享的 `scrubbedParentEnv` 清除 |
+| [`src/types.ts`](src/types.ts) | 词汇：spawn spec、stdio 模式、句柄、读取器、结果、`QILIN_*` 命名空间 |
+
+### 数据模型与流程
+
+spawn 会立即返回活动句柄，而不公开目标身份。`done` 独立报告直接命令的结果或失败，`waitForExit()` 则报告受管范围是否完全停稳。请求的中止信号驱动与 `terminate()` 相同的终止流程。收集模式的读取器无游标：偏移量是调用方拥有的全流字节坐标，因此独立读取器不会消费彼此的输出，偏移量滑出内存尾部的读取标记为 `lossy`，并在 spill 文件存在时指向它。`spawnTerminal` 是一项底层原语，因为普通管道无法分配控制终端或清理终端会话成员。
+
+### 生命周期与不变式
+
+每个上下文只注册一个实现；加载第二个会抛错（Cordis 标准行为）。服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出，因此进程生命周期在消费方重载后依然延续。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。终端分配的取消（spec 信号）与已发布句柄的生命周期相互独立。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从穷尽式类型参考逐步进入各提供方，以及 seam 背后的决策证据。
+
+- [子进程子系统](../../../docs/subsystems/subprocess.zh.md)——spawn spec、输出读取器、结果与完整的 `QILIN_*` 环境。
+- [qilin-subprocess-local](../subprocess-local/README.zh.md)——实现本约定的本地宿主提供方。
+- [qilin-bash-local](../../shell/bash-local/README.zh.md)——最大的消费方：经由本服务运行 bash 命令。
+- [subprocess seam Agent Note](../../../.agents/notes/archived/architecture/2026-07-26-subprocess-seam.md)——进程部分为何成为独立的 seam，以及随之迁移的内容。
+
+-----
+
+终端消费者通过 `terminalEnvironment()` 读取 provider 平台和首选 shell，通过 `resolveExecutable()` 验证候选。确定未找到可执行文件时抛出 `SubprocessExecutableNotFoundError`，传输故障仍单独报告。`spawnTerminal` 要求 `terminalType` 和初始尺寸，返回的 handle 通过 `resize(cols, rows)` 调整尺寸，不重新分配进程。
+
+<a id="model-experience"></a>
+## 模型体验
+
+通过消费方 seam（例如 bash 执行器家族）间接影响，它们负责进程输出与生命周期的全部面向模型渲染。
+
+#### KV Cache 影响
+
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明该 seam 何时不合适，或何时把工作留给消费方。它们是当前包约束，不是对比或任务积压。
+
+- **由 SDK 管理的 spawn 仍在服务之外**——拥有内部 spawn 的传输（SDK 客户端、MCP）无法把该调用路由到本服务；它仍可导入 `scrubbedParentEnv`，使环境策略保持单一来源。
+- **拆卸阶梯归消费方所有**——该 seam 只提供信号动词与受管范围等待，不提供现成的完全停稳序列；每个进程外消费方自行编码其子进程的配合方式（ACP 后端以 stdin EOF 打头的阶梯是仓库内模板）。
+- **可观察性取决于提供方**——native 提供方可以通过 systemd scope 或 Windows Job 拥有逃逸后代，fallback 提供方则只暴露较弱的进程组、进程树或会话可见性。该 seam 不新增持续的进程表监视器。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：开放设计问题与尚未决定的探索方向。它明确不具权威性——已交付的行为、限制与既定理由以上文、包代码和相关 Agent Note 为准。
+
+未来：非 shell 运行器。该 seam 拆分的目的就是让直接 argv 执行器或 worker supervisor 无需深入 bash 内部即可消费它；目前尚无任何实现交付，终端原语也把就绪策略留在其消费方。
+
+</details>

package/lib/control.js

@@ -0,0 +1,27 @@
+import { Socket } from "node:net";
+//#region lib/types/control.js
+/** Inherited byte-channel protocol shared by subprocess launchers and Node children. */
+/** Child descriptor reserved for the optional subprocess control channel. */
+const SUBPROCESS_CONTROL_FD = 7;
+/** Private launch marker consumed before a Node child executes application code. */
+const SUBPROCESS_CONTROL_ENV = "QILIN_SUBPROCESS_CONTROL";
+/**
+* Consume the launch marker and open the inherited control pipe at fd 7.
+* The returned stream owns the descriptor. Call once before executing untrusted code;
+* messages remain untrusted even though the endpoint was inherited.
+* @returns a connected byte-mode duplex stream owned by the caller.
+* @throws when the marker is missing/invalid or the inherited descriptor cannot be opened.
+*/
+function openInheritedControlChannel() {
+	const marker = process.env[SUBPROCESS_CONTROL_ENV];
+	Reflect.deleteProperty(process.env, SUBPROCESS_CONTROL_ENV);
+	if (marker !== "pipe") throw new Error("subprocess control channel was not inherited");
+	return new Socket({
+		fd: 7,
+		readable: true,
+		writable: true,
+		allowHalfOpen: true
+	});
+}
+//#endregion
+export { SUBPROCESS_CONTROL_ENV, SUBPROCESS_CONTROL_FD, openInheritedControlChannel };

package/lib/index.js

@@ -0,0 +1,103 @@
+import { Service } from "@qilin-agent/kylin";
+import { proxyEnvironmentForChild } from "@qilin-agent/http-proxy";
+//#region lib/types/types.js
+/**
+* Vocabulary for the subprocess Service Definition: fully-specified spawn requests with
+* Node-shaped per-stream stdio modes, bounded collected output with spill
+* recovery, raw piped streams, and managed-range termination. Command
+* defaulting, shell semantics, protocol framing, and presentation belong to
+* consumers such as the bash executor seam.
+* @module qilin-subprocess/types
+*/
+/** Namespace prefix reserved for QiLin-managed child environment facts. */
+const QILIN_ENV_PREFIX = "QILIN_";
+//#endregion
+//#region lib/types/index.js
+/**
+* Service Definition for the subprocess capability seam (`ctx.subprocess`): execution-world executable lookup,
+* fully specified provider-managed process ranges with raw or
+* collected stdio, and one terminal-process primitive. Command defaulting,
+* shell semantics, deadlines, protocol framing, terminal readiness, and
+* presentation belong to consumers. The local implementation lives in
+* `@qilin-agent/subprocess-local`.
+* @module @qilin-agent/subprocess
+*/
+/**
+* Credential-shaped environment names are NOT forwarded to children (the
+* harness's own `DEEPSEEK_API_KEY`/secrets must not leak into a spawned
+* process implicitly). One heuristic for every in-repo spawner; a
+* deliberately supplied entry survives because explicit env layers merge
+* after the scrub.
+*/
+const SENSITIVE_ENV_PATTERN = /KEY|PASSWORD|SECRET|TOKEN/i;
+/**
+* The ambient parent environment minus credential-shaped names and minus all
+* `QILIN_*` names — the canonical base every harness child starts from. `PATH`,
+* `HOME`, locale, and proxy variables survive, so child CLIs run normally;
+* harness identity never leaks implicitly (a deliberately forwarded
+* credential or current `QILIN_*` fact goes through the spec's explicit `env`,
+* which merges after this scrub). Both scrubs match case-insensitively:
+* Windows environment names are case-insensitive, so a parent `qilin_*` entry
+* would otherwise survive and read back as `$env:QILIN_*` in the child;
+* deliberate lowercase `qilin_*` names on POSIX are implausible. Exported as a plain function so spawners
+* that cannot route through the service (node-pty backends, SDK-managed
+* transports) share the one scrub definition.
+*
+* When a proxy is active the result also carries the resolved proxy names and the flag a child Node
+* needs to honor them, so a child inherits the same routing as its parent.
+* @returns a fresh environment object safe to hand to a child spawn.
+*/
+function scrubbedParentEnv() {
+	const env = {};
+	for (const [key, value] of Object.entries(process.env)) if (value !== void 0 && !SENSITIVE_ENV_PATTERN.test(key) && !key.toUpperCase().startsWith("QILIN_")) env[key] = value;
+	for (const [name, value] of Object.entries(proxyEnvironmentForChild())) if (value === void 0) Reflect.deleteProperty(env, name);
+	else env[name] = value;
+	return env;
+}
+/**
+* Abstract subprocess service. Subclass, implement {@link spawn}, and load the
+* subclass as a plugin — it registers as `ctx.subprocess` (one implementation
+* per context; loading a second throws, which is cordis' standard
+* duplicate-service behavior).
+*
+* Implementations must honor these semantics:
+* - Executable paths belong to one execution world shared with the mounted
+*   filesystem provider.
+* - {@link spawn} returns a live handle synchronously. Target identity remains
+*   provider-private; `done` resolves with the spawned command's exit facts and
+*   may reject for spawn or provider failures.
+* - Collect-mode readers are offset-based and non-consuming, so independent
+*   readers never consume one another's output; lossy reads report truncation
+*   and the spill file holding the complete stream when one exists. Piped
+*   streams are handed to the caller raw and never buffered here.
+* - {@link SubprocessHandle.terminate} (and the spec's abort signal) starts the
+*   provider's documented procedure against its managed range.
+*   {@link SubprocessHandle.waitForExit} observes that same range so a
+*   consumer-owned teardown ladder can hold each tier on real quiescence; each
+*   provider documents its signalling and observability limits.
+* - Disposal of the service terminates all still-running managed processes
+*   and awaits their exit.
+* - {@link spawnTerminal} owns terminal allocation, text transport,
+*   foreground groups, signalling, and whole-session quiescence behind one
+*   awaited termination method; readiness and persistent-shell policy stay
+*   in the PTY consumer. Its output stream ends after queued terminal output
+*   when the top-level process exits.
+*/
+var SubprocessRuntime = class extends Service {
+	constructor(ctx) {
+		super(ctx, "subprocess");
+	}
+};
+/** Executable lookup completed without finding an executable file. */
+var SubprocessExecutableNotFoundError = class extends Error {
+	/**
+	* @param message - provider-specific lookup diagnostic.
+	* @param options - original provider failure, when available.
+	*/
+	constructor(message, options) {
+		super(message, options);
+		this.name = "SubprocessExecutableNotFoundError";
+	}
+};
+//#endregion
+export { QILIN_ENV_PREFIX, SENSITIVE_ENV_PATTERN, SubprocessExecutableNotFoundError, SubprocessRuntime, SubprocessRuntime as default, scrubbedParentEnv };

package/lib/types/control.d.ts

@@ -0,0 +1,15 @@
+/** Inherited byte-channel protocol shared by subprocess launchers and Node children. */
+import type { Duplex } from 'node:stream';
+/** Child descriptor reserved for the optional subprocess control channel. */
+export declare const SUBPROCESS_CONTROL_FD = 7;
+/** Private launch marker consumed before a Node child executes application code. */
+export declare const SUBPROCESS_CONTROL_ENV: "QILIN_SUBPROCESS_CONTROL";
+/**
+ * Consume the launch marker and open the inherited control pipe at fd 7.
+ * The returned stream owns the descriptor. Call once before executing untrusted code;
+ * messages remain untrusted even though the endpoint was inherited.
+ * @returns a connected byte-mode duplex stream owned by the caller.
+ * @throws when the marker is missing/invalid or the inherited descriptor cannot be opened.
+ */
+export declare function openInheritedControlChannel(): Duplex;
+//# sourceMappingURL=control.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Service Definition for the subprocess capability seam (`ctx.subprocess`): execution-world executable lookup,
+ * fully specified provider-managed process ranges with raw or
+ * collected stdio, and one terminal-process primitive. Command defaulting,
+ * shell semantics, deadlines, protocol framing, terminal readiness, and
+ * presentation belong to consumers. The local implementation lives in
+ * `@qilin-agent/subprocess-local`.
+ * @module @qilin-agent/subprocess
+ */
+import { Context, Service } from '@qilin-agent/kylin';
+import type { SubprocessHandle, SubprocessSpawnSpec } from './types.ts';
+import type { SubprocessTerminalEnvironment, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from './types.ts';
+export { QILIN_ENV_PREFIX } from './types.ts';
+export type { CollectedOutput, QilinEnvironment, QilinEnvironmentKey, SubprocessCollect, SubprocessCollectedOutputs, SubprocessHandle, SubprocessOutcome, SubprocessOutputMode, SubprocessOutputRead, SubprocessOutputReader, SubprocessSpawnSpec, SubprocessStdinMode, SubprocessStdio, SubprocessTerminalForeground, SubprocessTerminalActivity, SubprocessTerminalEnvironment, SubprocessTerminalHandle, SubprocessTerminalSignal, SubprocessTerminalSpawnSpec, } from './types.ts';
+/**
+ * Credential-shaped environment names are NOT forwarded to children (the
+ * harness's own `DEEPSEEK_API_KEY`/secrets must not leak into a spawned
+ * process implicitly). One heuristic for every in-repo spawner; a
+ * deliberately supplied entry survives because explicit env layers merge
+ * after the scrub.
+ */
+export declare const SENSITIVE_ENV_PATTERN: RegExp;
+/**
+ * The ambient parent environment minus credential-shaped names and minus all
+ * `QILIN_*` names — the canonical base every harness child starts from. `PATH`,
+ * `HOME`, locale, and proxy variables survive, so child CLIs run normally;
+ * harness identity never leaks implicitly (a deliberately forwarded
+ * credential or current `QILIN_*` fact goes through the spec's explicit `env`,
+ * which merges after this scrub). Both scrubs match case-insensitively:
+ * Windows environment names are case-insensitive, so a parent `qilin_*` entry
+ * would otherwise survive and read back as `$env:QILIN_*` in the child;
+ * deliberate lowercase `qilin_*` names on POSIX are implausible. Exported as a plain function so spawners
+ * that cannot route through the service (node-pty backends, SDK-managed
+ * transports) share the one scrub definition.
+ *
+ * When a proxy is active the result also carries the resolved proxy names and the flag a child Node
+ * needs to honor them, so a child inherits the same routing as its parent.
+ * @returns a fresh environment object safe to hand to a child spawn.
+ */
+export declare function scrubbedParentEnv(): Record<string, string>;
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        subprocess: SubprocessRuntime;
+    }
+}
+/**
+ * Abstract subprocess service. Subclass, implement {@link spawn}, and load the
+ * subclass as a plugin — it registers as `ctx.subprocess` (one implementation
+ * per context; loading a second throws, which is cordis' standard
+ * duplicate-service behavior).
+ *
+ * Implementations must honor these semantics:
+ * - Executable paths belong to one execution world shared with the mounted
+ *   filesystem provider.
+ * - {@link spawn} returns a live handle synchronously. Target identity remains
+ *   provider-private; `done` resolves with the spawned command's exit facts and
+ *   may reject for spawn or provider failures.
+ * - Collect-mode readers are offset-based and non-consuming, so independent
+ *   readers never consume one another's output; lossy reads report truncation
+ *   and the spill file holding the complete stream when one exists. Piped
+ *   streams are handed to the caller raw and never buffered here.
+ * - {@link SubprocessHandle.terminate} (and the spec's abort signal) starts the
+ *   provider's documented procedure against its managed range.
+ *   {@link SubprocessHandle.waitForExit} observes that same range so a
+ *   consumer-owned teardown ladder can hold each tier on real quiescence; each
+ *   provider documents its signalling and observability limits.
+ * - Disposal of the service terminates all still-running managed processes
+ *   and awaits their exit.
+ * - {@link spawnTerminal} owns terminal allocation, text transport,
+ *   foreground groups, signalling, and whole-session quiescence behind one
+ *   awaited termination method; readiness and persistent-shell policy stay
+ *   in the PTY consumer. Its output stream ends after queued terminal output
+ *   when the top-level process exits.
+ */
+export declare abstract class SubprocessRuntime extends Service {
+    constructor(ctx: Context);
+    /**
+     * Resolve one configured executable in this provider's execution world.
+     * Absolute paths are verified; bare names use the provider's scrubbed PATH
+     * plus explicit environment overrides. Relative paths containing separators
+     * are rejected: the resolution base is undefined, so providers fail loud
+     * instead of guessing.
+     * @param command - absolute executable path or bare PATH name.
+     * @param env - explicit environment entries used for lookup.
+     * @param signal - aborts remote or local lookup.
+     * @returns a canonical executable path.
+     */
+    abstract resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;
+    /**
+     * Inspect shell-selection facts in the provider's execution environment.
+     * @param signal - cancellation of remote environment inspection.
+     * @returns platform and preferred shell; executable lookup and allocation remain separate operations.
+     */
+    abstract terminalEnvironment(signal?: AbortSignal): Promise<SubprocessTerminalEnvironment>;
+    /**
+     * Start one managed child process from a fully-specified spec; this seam
+     * applies no defaults.
+     * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment.
+     * @returns the live process handle (streams/readers, signalling, outcome promise).
+     * @throws synchronously when pre-aborted or when argv, cwd, environment, or grace is invalid before handle creation.
+     */
+    abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+    /**
+     * Allocate a real terminal and start one owned process session. This is the
+     * only non-pipe process primitive: implementations own terminal byte I/O,
+     * foreground groups, signals, and whole-session quiescence.
+     * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
+     * @returns the live terminal handle after allocation succeeds.
+     */
+    abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>;
+}
+export default SubprocessRuntime;
+/** Executable lookup completed without finding an executable file. */
+export declare class SubprocessExecutableNotFoundError extends Error {
+    /**
+     * @param message - provider-specific lookup diagnostic.
+     * @param options - original provider failure, when available.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Vocabulary for the subprocess Service Definition: fully-specified spawn requests with
+ * Node-shaped per-stream stdio modes, bounded collected output with spill
+ * recovery, raw piped streams, and managed-range termination. Command
+ * defaulting, shell semantics, protocol framing, and presentation belong to
+ * consumers such as the bash executor seam.
+ * @module qilin-subprocess/types
+ */
+import type { Duplex, Readable, Writable } from 'node:stream';
+/** Namespace prefix reserved for QiLin-managed child environment facts. */
+export declare const QILIN_ENV_PREFIX: "QILIN_";
+/** One environment key inside the managed {@link QILIN_ENV_PREFIX} namespace. */
+export type QilinEnvironmentKey = `${typeof QILIN_ENV_PREFIX}${string}`;
+/** Trusted QiLin variables for one child-process execution. */
+export type QilinEnvironment = Readonly<Record<QilinEnvironmentKey, string>>;
+/** One captured stream: the (possibly truncated) text plus recovery info. */
+export interface CollectedOutput {
+    /** Collected text — the TAIL of the stream when truncated. */
+    text: string;
+    /** True when bytes were dropped from `text`. */
+    truncated: boolean;
+    /** Path to a file holding the COMPLETE stream, when truncated and available. */
+    spillPath?: string;
+}
+/**
+ * stdin disposition. `'ignore'` leaves fd 0 on `/dev/null`; `'pipe'` exposes
+ * {@link SubprocessHandle.stdin} for the caller's ongoing protocol writes;
+ * `{ data }` writes the bytes and closes (the batch shape).
+ */
+export type SubprocessStdinMode = 'ignore' | 'pipe' | {
+    readonly data: string;
+};
+/**
+ * Bounded in-memory collection for one output stream, with an optional
+ * full-stream spill file. Omitting `spill` keeps only the in-memory tail —
+ * the diagnostic-tail shape (a language server's stderr); including it makes
+ * the complete stream recoverable up to its cap (the bash tool shape).
+ */
+export interface SubprocessCollect {
+    /** In-memory cap in bytes; overflow keeps the TAIL. */
+    maxBytes: number;
+    /** Full-stream spill file; absent disables spilling entirely. */
+    spill?: {
+        /** Whole-stream byte cap; a larger stream discards its now-incomplete spill. */
+        maxBytes: number;
+    };
+}
+/**
+ * stdout/stderr disposition. `'pipe'` exposes the raw `Readable` for the
+ * caller's protocol decoding; `'inherit'` passes the parent's descriptor
+ * through (child diagnostics land on the harness's own stream); a
+ * {@link SubprocessCollect} object buffers boundedly with offset-based reads.
+ */
+export type SubprocessOutputMode = 'pipe' | 'inherit' | SubprocessCollect;
+/** Per-stream stdio dispositions, all explicit — this seam applies no defaults. */
+export interface SubprocessStdio {
+    stdin: SubprocessStdinMode;
+    stdout: SubprocessOutputMode;
+    stderr: SubprocessOutputMode;
+    /** Request a separate byte-mode duplex channel; omission creates none. */
+    control?: 'pipe';
+}
+/**
+ * A fully-specified spawn request. This seam applies no defaults: every
+ * disposition, limit, and directory is explicit, so the caller's own config —
+ * not a hidden subprocess-service default — decides them (the `qilin-shell`
+ * request/spec split is the owning template).
+ */
+export interface SubprocessSpawnSpec {
+    /** Executable and arguments; `argv[0]` is the program. Never shell-interpreted here. */
+    argv: readonly string[];
+    /** Working directory for the child. */
+    cwd: string;
+    /** Per-stream stdio dispositions. */
+    stdio: SubprocessStdio;
+    /**
+     * Positive finite grace period in milliseconds, no greater than
+     * `MAX_TIMER_DELAY_MS`, available to the provider's termination procedure
+     * and used for draining still-open collected pipes after the process exits
+     * (an inherited descriptor held by a survivor cannot hold the outcome open
+     * indefinitely). Providers document whether range termination is staged or
+     * immediate.
+     */
+    graceMs: number;
+    /**
+     * Abort signal — starts the terminate escalation on the managed range when
+     * it fires. The caller owns deadlines and cause classification; this seam
+     * only reacts to the abort.
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * Explicit environment entries merged onto the implementation's scrubbed
+     * parent base (see `scrubbedParentEnv`), with no namespace validation. A
+     * string is a deliberate caller opt-in, so a forwarded credential-shaped
+     * entry or current `QILIN_*` fact survives the scrub; `undefined` is a
+     * tombstone that removes an ordinary ambient entry from the child.
+     */
+    env?: NodeJS.ProcessEnv | undefined;
+}
+/**
+ * Exit facts of one closed process — Node's `close`-event vocabulary.
+ * Deliberately carries NO timeout or cancellation classification (the caller
+ * reads the signal it owns to classify causes) and NO output: collected
+ * streams stay readable through {@link SubprocessHandle.collected} after
+ * settlement, so batch and streaming callers share one access path.
+ */
+export interface SubprocessOutcome {
+    /** Exit code; null when the process died from a signal. */
+    exitCode: number | null;
+    /** Terminating signal (e.g. 'SIGTERM'); null on normal exit. */
+    signal: NodeJS.Signals | null;
+}
+/** One incremental {@link SubprocessOutputReader.readFrom} read. */
+export interface SubprocessOutputRead {
+    /** Stream text from the requested offset (the whole retained tail when lossy). */
+    text: string;
+    /** Whole-stream offset to resume from on the next read. */
+    nextOffset: number;
+    /** True when the requested offset slid out of the in-memory tail window. */
+    lossy: boolean;
+    /** Path to the full-stream spill file, when one was created and remains intact. */
+    spillPath?: string;
+}
+/**
+ * Cursor-free incremental access to one collected output stream. Offsets are
+ * whole-stream byte coordinates owned by the caller, so independent readers
+ * cannot consume one another's output; `readFrom(0)` after settlement is the
+ * batch result (`lossy` then means the in-memory tail lost its head — the
+ * {@link CollectedOutput.truncated} fact).
+ */
+export interface SubprocessOutputReader {
+    /**
+     * Read everything captured since `fromByte`. When that offset has slid out
+     * of the in-memory tail window the read is `lossy` — it returns the whole
+     * retained tail and the gap is only recoverable from the spill file.
+     * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 for the first read).
+     * @returns the delta text, the next offset, the `lossy` flag, and the spill path when one exists.
+     */
+    readFrom(fromByte: number): SubprocessOutputRead;
+}
+/** Offset-based readers for the streams spawned in collect mode. */
+export interface SubprocessCollectedOutputs {
+    /** Present iff stdout is a {@link SubprocessCollect}. */
+    readonly stdout?: SubprocessOutputReader;
+    /** Present iff stderr is a {@link SubprocessCollect}. */
+    readonly stderr?: SubprocessOutputReader;
+}
+/**
+ * A live subprocess and its provider-managed process range. Collected output
+ * remains readable after exit; piped streams belong to the caller.
+ *
+ * Termination and {@link SubprocessHandle.waitForExit} use the same managed
+ * range. Each provider documents the range it can observe and its signalling
+ * and observation limits.
+ */
+export interface SubprocessHandle {
+    /** The child's stdin, present iff spawned with `stdin: 'pipe'`. */
+    readonly stdin: Writable | undefined;
+    /** The child's raw stdout, present iff spawned with `stdout: 'pipe'`. */
+    readonly stdout: Readable | undefined;
+    /** The child's raw stderr, present iff spawned with `stderr: 'pipe'`. */
+    readonly stderr: Readable | undefined;
+    /** Separate caller-owned byte channel when requested; native startup failure may leave it absent. */
+    readonly control: Duplex | undefined;
+    /** Offset-based readers for collect-mode streams (also readable after exit). */
+    readonly collected: SubprocessCollectedOutputs;
+    /** Resolves with spawned-command exit facts; rejects for spawn or provider failures. */
+    readonly done: Promise<SubprocessOutcome>;
+    /**
+     * Begin the provider's documented termination procedure on the managed range
+     * — the seam's only termination verb. Idempotent, a no-op once that range is
+     * gone, and also triggered by the spec's abort signal.
+     */
+    terminate(): void;
+    /**
+     * Wait until the same managed range is empty — not just until the spawned
+     * command reports its outcome, so surviving work remains observable.
+     * @param signal - optional bound for the wait.
+     * @returns `true` when the managed range is empty, `false` when the signal aborted first.
+     * @throws when the selected provider can no longer observe its managed range.
+     */
+    waitForExit(signal?: AbortSignal): Promise<boolean>;
+}
+/**
+ * Signals supported by the terminal-process primitive. Kept member-identical
+ * to `TerminalSignal` in `@qilin-agent/terminal` without a cross-seam dependency;
+ * change both together.
+ */
+export type SubprocessTerminalSignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP';
+/** Shell-selection facts from the subprocess provider's execution environment. */
+export interface SubprocessTerminalEnvironment {
+    /** Operating-system family that interprets executable paths and shell arguments. */
+    platform: 'posix' | 'windows';
+    /** Login or environment-selected shell, when the provider can resolve one. */
+    defaultShell?: string;
+}
+/** A fully specified terminal-process spawn. */
+export interface SubprocessTerminalSpawnSpec {
+    /** Executable and arguments; `argv[0]` is the program. */
+    argv: readonly string[];
+    /** Working directory in this subprocess provider's execution world. */
+    cwd: string;
+    /** Explicit environment layered after the provider's ambient scrub. */
+    env?: Record<string, string> | undefined;
+    /** Initial terminal row count. */
+    rows: number;
+    /** Initial terminal column count. */
+    cols: number;
+    /** Terminal emulation advertised to the child through TERM. */
+    terminalType: string;
+    /** Request supported interactive-shell lifecycle observation; unsupported launches report unknown activity. */
+    shellActivity?: boolean | undefined;
+    /** TERM-to-KILL cleanup grace for the complete terminal session. */
+    graceMs: number;
+    /** Cancellation of terminal allocation; a published handle owns its later lifetime. */
+    signal?: AbortSignal | undefined;
+}
+/** Current foreground process-group facts for one terminal. */
+export interface SubprocessTerminalForeground {
+    /** Foreground process-group id published by the terminal driver. */
+    processGroupId: number;
+    /** Whether the provider can currently prove that group is waiting on terminal input. */
+    inputWaiting: boolean;
+}
+/** Provider observation of shell lifecycle and surviving owned jobs. */
+export interface SubprocessTerminalActivity {
+    /** Idle requires positive prompt evidence and no observed foreground, background, or stopped jobs. */
+    state: 'idle' | 'busy' | 'unknown';
+    /** Changes with input, shell transitions, and changed process observations; scoped to this handle. */
+    revision: number;
+}
+/**
+ * One live terminal process and its owned OS session. Terminal allocation,
+ * foreground-group inspection/signalling, and whole-session quiescence are one
+ * deep subprocess primitive because none can be reconstructed from ordinary
+ * piped stdio without substrate-specific process control.
+ */
+export interface SubprocessTerminalHandle {
+    /** Top-level terminal process id. */
+    readonly pid: number;
+    /** UTF-8 terminal output bytes in delivery order; ends after queued output when the terminal exits. */
+    readonly output: Readable;
+    /** Resolves when the top-level process exits; rejects for a terminal startup, provider, or live transport failure. */
+    readonly done: Promise<SubprocessOutcome>;
+    /**
+     * Write text to the terminal input.
+     * @param data - text to deliver without implicit newline conversion.
+     */
+    write(data: string): Promise<void>;
+    /**
+     * Change the terminal dimensions and notify its foreground application.
+     * @param cols - positive terminal column count.
+     * @param rows - positive terminal row count.
+     */
+    resize(cols: number, rows: number): Promise<void>;
+    /**
+     * Inspect the current foreground process group.
+     * @returns its id and input-wait fact, or undefined when no foreground group can be resolved.
+     */
+    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
+    /**
+     * Observe command activity without interpreting output or treating silence as completion.
+     * @returns a fresh observation; unsupported shells and incomplete observations report unknown.
+     */
+    inspectActivity(): Promise<SubprocessTerminalActivity>;
+    /**
+     * Deliver a signal to the current foreground process group.
+     * @param signal - permitted terminal signal.
+     * @returns the exact group id that received it.
+     */
+    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;
+    /**
+     * Idempotently terminate every terminal-session member the provider can still observe and await quiescence.
+     * After settlement, no write, inspection, or signal call remains in flight.
+     * Providers document substrate-specific observability limits.
+     */
+    terminate(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@qilin-agent/subprocess",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Subprocess seam (ctx.subprocess) for the QiLin — managed process groups, bounded spill-backed output, and escalated kills behind one abstract service",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/subprocess/subprocess"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./control": {
+      "types": "./lib/types/control.d.ts",
+      "default": "./lib/control.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/control.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/http-proxy": "3.1.4"
+  },
+  "devDependencies": {
+    "@qilin-agent/http-proxy": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/launch-environment": "3.1.4"
+  }
 }