pi-claude-supervisor 0.2.0

package/docs/implementation-review.md

@@ -0,0 +1,62 @@
+# Implementation Review
+
+An independent read-only reviewer examined the implementation before the final
+hardening pass. The review found no blocker in the TypeScript/Pi registration
+surface. The MVP intentionally does not provide OS sandboxing, low-privilege
+execution, or network isolation; those are deferred security-hardening items,
+not blockers for the lifecycle and recovery track.
+
+## Findings addressed in this pass
+
+- Policy now evaluates the executable and argv together, including Claude
+  permission-bypass flags.
+- Worker and verifier processes use a minimal environment; explicit worker
+  variables can be selected with `PI_CLAUDE_SUPERVISOR_WORKER_ENV` or an
+  embedding caller's `WorkerStartInput.env`.
+- Startup failures clean up a worker and do not let event-log failures hide the
+  original error.
+- Default wall-clock and no-output watchdogs stop stalled workers.
+- New tasks clear stale handles and verification results.
+- Custom verifier commands pass through the same deterministic policy gate.
+- CI runs package-install and Pi-registration smoke tests.
+- Spawn failures have a regression test; process termination escalates to the
+  process group after a grace period.
+
+## Residual risks and follow-up hardening
+
+These are verified limitations and follow-up work, not reasons to stop the
+lifecycle track:
+
+- OS sandbox, lower-privilege execution, and network allowlisting are not
+  provided by the adapter. The caller may run with explicitly authorized host
+  permissions; the deployment owner accepts responsibility for that boundary.
+- Event contents can contain worker output or user messages; common credential
+  patterns are now redacted and sequence recovery is persisted, but broader
+  structured-secret coverage remains follow-up work.
+- PTY semantics, permission-event handling, and process-group behavior with the
+  target Claude Code versions still require dedicated transport evidence. Basic
+  Claude JSONL prompt, multi-turn and session-resume fixtures now pass in the
+  recorded Spike.
+- Fault injection coverage now includes lifecycle-log failure, SIGTERM refusal,
+  blocked stdin and managed orphan descendants; shutdown cleanup under injected
+  adapter failure remains a follow-up failure-injection case.
+- The default transport is process-pipe. Claude JSONL framing is opt-in; the
+  next priority is signal, shutdown and descendant-cleanup evidence rather than
+  network or low-privilege isolation.
+
+## Evidence
+
+The review was performed against `src/`, `package.json`, workflows and tests.
+The final local evidence is recorded by:
+
+```text
+npm ci --ignore-scripts --include=dev
+npm run check
+npm run test:pi
+npm run test:install
+npm audit --audit-level=high
+npm run build
+```
+
+All commands passed on Node `v26.8.1`; Node `>=22.19` remains the declared
+runtime target and still requires validation on the minimum supported version.

package/docs/independent-review.md

@@ -0,0 +1,332 @@
+# 独立子 Agent 方案评审报告
+
+> 评审对象：`requirement.txt`、`docs/engineering-plan.md`  
+> 评审重点：复用现有扩展、减少重复开发、形成可整合架构并验证到生产
+
+## 1. 评审结论
+
+总体架构合理，但当前不能把候选扩展直接叠加到生产环境。推荐采用：
+
+> **复用 Pi 扩展加载机制和 Claude Code runtime；选择一个 Worker transport；自建极薄 Adapter、Policy Gate、状态机、事件日志和独立验证器。**
+
+核心原则：
+
+- 不让多个扩展同时拥有 Claude 的 spawn、watchdog、resume、stop 控制权。
+- PTY 和 headless JSONL 只选择一个作为 MVP 主传输路径。
+- `pi-goals` 主要复用 Goal / Evidence / Sign-off 数据模型。
+- `pi-foreground-chains` 主要复用有限循环、等待检测和 reviewer 阶段思想。
+- `pi-interactive-shell` 如果通过版本、API、许可证和故障测试，应优先复用其 PTY 和人工接管实现。
+- `pi-claude-code`、`pi-harness-delegate` 在完成供应链、API 和故障语义审计前，不作为核心依赖。
+
+**结论：架构方向 GO；先完成固定版本 Spike、生命周期和故障恢复主线。低权限用户、sandbox 与网络隔离属于后续安全加固，不作为当前主线硬阻塞。**
+
+## 2. 外部参考源审查结果
+
+| 参考源 | 建议 | 可复用内容 | 当前判断 |
+|---|---|---|---|
+| `pi-interactive-shell` | 优先做 Spike | PTY、实时输出、输入、人工接管、worktree 会话 | 候选主 transport，但必须验证 |
+| `pi-foreground-chains` | 借鉴并局部复用 | continue loop、有限轮次、reviewer 阶段、进度记录 | 不能直接复制 regex 决策；文档主要展示 Codex Worker |
+| `@mporenta/pi-claude-code` | 暂不作为核心依赖 | headless Claude 执行、watchdog、完成/异常事件 | 版本、日期、API、许可证和稳定性待核验 |
+| `pi-goals-extension` / 相关 pi-goals 页面 | 复用设计思想或 schema | Goal、discriminator、evidence、sign-off | 不直接作为 Claude runtime |
+| `pi-harness-delegate` | 可作为可选 adapter | Claude delegate、review、resume | 可能与本项目生命周期和审计逻辑重复 |
+| Claude Code hooks | 作为 Worker 内部护栏 | Stop 前测试、阻止不完整停止 | 不能替代外部 Supervisor 和独立验收 |
+
+### 2.1 需要特别纠正的事实
+
+- `requirement.txt` 中的“70%～85% 已完成”没有计算方法，不能作为进度依据。
+- 相关包的版本、发布日期、API 和生产能力必须以精确版本、commit、许可证和实测结果为准。
+- 搜索结果显示 `pi-goals-extension` 这一名称更值得核验，不能直接假设普通 `pi-goals` 包名可安装。
+- `pi-foreground-chains` 的资料重点是 Codex Worker 的自动继续流程，不应表述为 Claude 已经完成端到端验证。
+- `@mporenta/pi-claude-code` 的发布时间和版本信息存在时间核验问题，在 lockfile 固定前必须重新确认。
+
+## 3. 最小整合架构
+
+```text
+Pi Extension Loader / UI / Human Takeover
+                  │
+                  ▼
+         pi-claude-supervisor
+                  │
+       ┌──────────┼──────────┐
+       ▼          ▼          ▼
+  Policy Gate  State Machine  Event Log
+                  │
+                  ▼
+            Worker Adapter
+                  │
+        只选择一个 transport
+          ┌───────┴────────┐
+          ▼                ▼
+       PTY Spike       Headless Spike
+          │                │
+          └───────┬────────┘
+                  ▼
+            Claude Code CLI
+                  │
+                  ▼
+          Git Worktree / Tests
+                  │
+                  ▼
+         Independent Verifier
+```
+
+### 3.1 唯一控制权原则
+
+MVP 中以下职责只能由一个组件负责：
+
+| 职责 | 唯一拥有者 |
+|---|---|
+| spawn | Worker Adapter |
+| stop / kill process group | Worker Adapter + Policy Gate |
+| watchdog | Supervisor |
+| session resume | Worker Adapter，但必须由 Supervisor 授权 |
+| 状态转换 | Supervisor State Machine |
+| 最终完成批准 | Independent Verifier + Supervisor |
+| 人工接管 | Human，系统必须立即让权 |
+
+任何第三方扩展如果内部再次自动重试、自动 resume 或自动 stop，必须关闭这些能力，或者不能纳入 MVP。
+
+### 3.2 Adapter 必须具备的能力
+
+当前方案中的 `WorkerAdapter` 需要增加：
+
+```ts
+interface WorkerAdapter {
+  capabilities(): Promise<WorkerCapabilities>;
+  start(input: WorkerStartInput): Promise<WorkerHandle>;
+  getStatus(handle: WorkerHandle): Promise<WorkerStatus>;
+  readOutput(handle: WorkerHandle): Promise<WorkerOutputChunk[]>;
+  send(handle: WorkerHandle, message: string, idempotencyKey: string): Promise<void>;
+  pause(handle: WorkerHandle): Promise<void>;
+  resume(handle: WorkerHandle): Promise<void>;
+  takeover(handle: WorkerHandle): Promise<void>;
+  stop(handle: WorkerHandle, reason: string): Promise<void>;
+  killProcessGroup(handle: WorkerHandle, reason: string): Promise<void>;
+  resumeSession(sessionId: string): Promise<WorkerHandle>;
+}
+```
+
+每个事件还必须包含：
+
+- 单调递增 `seq`；
+- `taskId` 和 `workerId`；
+- `idempotencyKey`；
+- `timestamp`；
+- 原始输出 artifact 引用；
+- `exitReason`；
+- `lastHeartbeat`；
+- 工作目录和权限声明。
+
+## 4. 分阶段复用策略
+
+### Phase 0：本地源码和包审计
+
+对每个候选项目记录：
+
+- GitHub URL；
+- npm/package 名称；
+- 精确版本和 commit SHA；
+- 安装命令；
+- 导出的 API；
+- `LICENSE` 和 SPDX；
+- 传递依赖；
+- 最近 release/commit；
+- CI 和测试状态；
+- 是否支持当前 Pi 版本；
+- 是否有 Claude 真实运行样例；
+- 退出码、超时、信号和恢复语义。
+
+没有完成这些记录，不进入生产依赖。
+
+### Phase 1：只验证 Worker transport
+
+优先验证 `pi-interactive-shell` 的：
+
+- spawn Claude；
+- 实时读取输出；
+- 输入是否丢失；
+- 人工 takeover；
+- SIGTERM/SIGKILL；
+- 窗口尺寸和提示符变化；
+- 长时间无输出；
+- 孤儿进程回收；
+- session resume。
+
+如果 PTY 可靠，MVP 复用其 transport；如果 PTY 无法提供稳定、可回放的事件，则切换为 headless JSONL，不在两个 transport 之间做混合控制。
+
+### Phase 2：自有 Supervisor 核心
+
+以下能力建议自建，原因是它们属于本项目的控制权和审计边界：
+
+- Goal schema；
+- 状态机；
+- Policy Gate；
+- 预算和最大轮数；
+- 重复停顿检测；
+- 人工升级；
+- 事件日志；
+- 证据收集；
+- 独立验收；
+- 回滚和 fail-closed。
+
+这部分不应依赖某个第三方扩展的隐式行为。
+
+### Phase 3：选择性接入 headless 扩展
+
+只有在以下条件都满足时，才考虑接入 `pi-claude-code` 或 `pi-harness-delegate`：
+
+- 许可证允许目标使用方式；
+- 版本和 commit 已锁定；
+- API 能映射到 Worker Adapter；
+- 不与 Supervisor 重复管理生命周期；
+- 事件和错误语义可记录；
+- session resume 可回放；
+- 故障注入测试通过；
+- 能够随时卸载并回退到基础 Claude CLI adapter。
+
+## 5. 生产验证路线
+
+### 5.1 PoC 阶段
+
+只做一条真实任务闭环：
+
+```text
+创建任务
+  → 启动 Claude
+  → 读取输出
+  → 处理普通提问
+  → 人工接管
+  → 恢复执行
+  → 测试
+  → 独立验收
+  → 输出报告
+```
+
+必须注入：
+
+- 普通确认；
+- 架构二选一；
+- 120 秒无输出；
+- Worker 崩溃；
+- 输入竞争；
+- 重复停顿；
+- 危险命令；
+- 验收失败；
+- Supervisor 重启。
+
+### 5.2 MVP 阶段
+
+MVP 必须满足：
+
+- 单仓库、单 worktree、单 Worker；
+- 低风险动作才可自动继续；
+- 架构和危险动作人工审批；
+- 事件可以完整回放；
+- 人工 takeover 后零自动发送；
+- 验收失败绝不进入 `COMPLETE`；
+- 重复停顿不会无限循环；
+- 进程组不会泄漏；
+- 日志不会泄露密钥；
+- Worker 输出不能改变 Supervisor 安全规则。
+
+### 5.3 生产候选阶段
+
+生产候选的后续加固项包括：
+
+- 依赖 lockfile 和 SBOM；
+- 包来源校验；
+- 可选最小权限和 sandbox；
+- 可选网络白名单；
+- 密钥隔离；
+- 日志脱敏；
+- 成本和时间告警；
+- 灰度 feature flag；
+- 可随时关闭自动化；
+- 故障回滚和人工值守。
+
+其中低权限用户、sandbox 和网络白名单不阻塞当前生命周期验证；运行权限由
+调用者明确授权，危险操作仍由 Policy Gate 和人工审批控制。
+
+### 5.4 建议 Go / No-Go 门槛
+
+必须全部满足才允许生产灰度：
+
+- P0 安全用例 100% 通过；
+- 无孤儿 Worker 进程；
+- 无密钥泄露；
+- 人工 takeover 可重复成功；
+- 所有失败场景 fail-closed；
+- 关键事件可完整回放；
+- 验收流水线可独立重跑；
+- 依赖许可证和版本已审计；
+- 通过一组固定任务的成功率、恢复率和费用门槛。
+
+未满足生命周期、恢复、审计和独立验收门槛时只能称为 PoC 或生产候选；
+安全加固项未完成时，不应称为安全加固完成或适合无人工值守部署。
+
+## 6. 回滚方案
+
+任何以下情况发生时，立即停止自动发送并进入 `HUMAN_REQUIRED`：
+
+- 状态不一致；
+- 重复发送指令；
+- Policy Gate 解析失败；
+- 验证器不可用；
+- Worker 输出协议变化；
+- 第三方扩展加载失败；
+- 发现权限越界或密钥风险；
+- watchdog 与 Worker 状态矛盾。
+
+回滚动作：
+
+1. 停止自动控制；
+2. 保留 worktree、事件日志和原始输出；
+3. 终止或交还 Worker 控制权；
+4. 人工接管；
+5. 使用锁定的旧 Adapter 或直接使用 Claude CLI；
+6. 生成故障报告；
+7. 未完成根因分析前，不重新打开自动化开关。
+
+第三方包升级必须通过 lockfile、独立 worktree、回放测试和 feature flag 灰度，不能直接替换生产版本。
+
+## 7. 对现有 engineering-plan.md 的修改建议
+
+现有方案已经具备较好的边界，但建议补充：
+
+1. 参考源审计表和许可证门禁；
+2. PTY/headless transport 的明确主备选择；
+3. 唯一控制权和职责归属；
+4. Adapter capability negotiation、幂等、事件序号、进程组终止和 artifact 引用；
+5. 供应链和 SBOM 要求；
+6. prompt injection、symlink 越界、shell escape 和外部文档注入威胁模型；
+7. 输入竞争、孤儿进程、重复事件和恢复测试；
+8. 量化的 Go/No-Go 指标；
+9. 扩展加载失败时的回退路径；
+10. 明确 Stop hook 只是 Worker 内部早停护栏，不是独立验收器。
+
+## 8. 最终技术决策建议
+
+### 推荐直接复用
+
+- Pi 的 extension/package loader 和人工交互机制；
+- Claude Code CLI runtime；
+- 通过 Spike 验证后的 `pi-interactive-shell` PTY 层；
+- Git worktree、OS 进程组控制和项目已有测试命令。
+
+### 推荐只借鉴
+
+- `pi-goals` 的 Goal / Evidence / Sign-off 数据模型；
+- `pi-foreground-chains` 的有限循环和 reviewer 阶段；
+- Claude Stop hook 的 Worker 内部护栏思路。
+
+### 暂不作为核心依赖
+
+- 未审计的 `pi-claude-code`；
+- 未审计的 `pi-harness-delegate`；
+- 同时拥有 spawn、watchdog、resume、stop 权限的多个扩展；
+- Reviewer 直接修改工作树；
+- 自动 merge、deploy、release。
+
+## 9. 给 W 的一句话结论
+
+> 不要从零重写 Claude 控制层，也不要把多个扩展直接叠加。先验证并复用一个可靠的 Worker transport，再自建最薄的 Adapter、策略、状态机和独立验收层；所有候选包经过版本、许可证、API、故障和安全验证后，才允许进入生产灰度。

package/docs/releasing.md

@@ -0,0 +1,112 @@
+# Releasing
+
+## Pull request gate
+
+All changes must enter `main` through a pull request. Use a Conventional Commit
+PR title, for example:
+
+```text
+feat: persist Decision Worker sessions
+fix: close orphaned workers during shutdown
+```
+
+The required `CI / Quality gate` aggregates every prerequisite. It fails when
+any job fails, is cancelled, or is skipped:
+
+- Node 22.19.0 and Node 24 checks;
+- npm 10 and npm 12 compatibility checks;
+- TypeScript, unit tests, package checks and documentation checks;
+- Pi smoke and native package-install tests;
+- npm audit at high severity;
+- deterministic package artifact build with SHA-256 and npm integrity metadata.
+
+Configure branch protection for `main` with:
+
+- pull request required;
+- `CI / Quality gate` required and up to date;
+- conversation resolution required;
+- force pushes and branch deletion disabled.
+
+The workflow does not auto-merge arbitrary pull requests.
+
+## Local release checks
+
+```bash
+npm ci --ignore-scripts --include=dev
+npm run check
+npm run test:pi
+npm run test:install
+npm run build
+npm audit --audit-level=high
+```
+
+`npm run build` writes exactly these files to `dist/`:
+
+```text
+pi-claude-supervisor-X.Y.Z.tgz
+release-manifest.json
+SHA256SUMS
+```
+
+The manifest binds the archive to the exact source commit, SHA-256 digest and
+npm SHA-512 integrity value. Never manually replace an artifact after CI builds
+it.
+
+## Versioning and automatic publication
+
+The `Release` workflow runs on `main` and uses Release Please:
+
+1. Release Please opens or updates a release PR from Conventional Commits.
+2. A maintainer reviews and merges the release PR.
+3. Release Please creates a stable `vX.Y.Z` Git tag and GitHub Release.
+4. The workflow runs the full reusable CI against the exact tag commit.
+5. Only after verification succeeds does the `npm` environment publish the
+   verified archive with `npm publish --provenance`.
+6. The archive, manifest and checksum file are attached to the GitHub Release.
+
+A failed publication must be retried from the original release workflow. Do not
+move tags, overwrite versions, or rebuild a different artifact to bypass a
+failed verification.
+
+## npm authentication
+
+Preferred mode is npm trusted publishing (OIDC):
+
+- configure `btnalit/pi-claude-supervisor` and `.github/workflows/release.yml`
+  as a trusted publisher in npm;
+- configure the GitHub environment named `npm`;
+- set repository/environment variable `NPM_AUTH_MODE=oidc`;
+- grant only the publish job `id-token: write`.
+
+Temporary fallback mode uses the GitHub environment secret `NPM_TOKEN` and
+variable `NPM_AUTH_MODE=token`. The token must be package-scoped, short-lived
+and rotated. It is never committed or copied into workflow source.
+
+For local/manual recovery only, the machine-held credential is stored in:
+
+```text
+/home/yancao/.config/key.conf
+```
+
+Keep that file at mode `0600`. It must not be copied into the repository,
+GitHub Actions variables, npm package contents, logs or pull requests. Local
+publication should use a temporary `npm_config_userconfig` file and remove it
+immediately after the command.
+
+## Dependency and workflow updates
+
+Dependabot is configured for both npm dependencies and GitHub Actions. Minor and
+patch updates are grouped; every update must pass the same CI quality gate.
+Major updates remain separate for explicit review. There is no blanket auto-merge.
+
+## Manual retry
+
+A maintainer can retry an existing stable release from Actions:
+
+```bash
+gh workflow run release.yml --ref main -f tag=v0.1.1
+```
+
+The workflow verifies that the release tag is stable and belongs to `main`, then
+reruns CI before publication. A tag or GitHub Release alone is not evidence that
+npm publication succeeded; verify the npm registry separately.

package/docs/testing.md

@@ -0,0 +1,109 @@
+# Testing
+
+## Local checks
+
+```bash
+npm ci --ignore-scripts --include=dev
+npm run check
+npm run test:pi
+npm run test:install
+npm audit --audit-level=high
+npm run build
+```
+
+`npm run check` performs strict TypeScript checking, Node tests, and npm package
+content assertions. `npm run build` creates an installable npm archive; Pi loads
+the published TypeScript source directly and there is no second runtime bundle.
+
+## Test layers
+
+- `policy.test.ts`: deterministic allow/review/deny behavior.
+- `state.test.ts`: legal and illegal lifecycle transitions.
+- `events.test.ts`: ordered JSONL persistence, sequence recovery and credential-shaped redaction.
+- `decision-session-store.test.ts`: atomic Decision Worker task mapping, permissions, restart discovery and corrupt-record isolation.
+- `index.test.ts`: command-level cwd reservation/reuse and session-shutdown
+  cleanup for a real child process.
+- `supervisor.test.ts`: a real local child process must reach `verifying` and
+  require a separate successful verification command before `completed`.
+- `worker/process-adapter.test.ts`: spawn failure is observable, JSONL framing and
+  idempotent duplicate suppression work, and a child does not remain indefinitely
+  in a running state.
+- `worker/environment.test.ts`: unrelated host credentials are excluded unless
+  explicitly supplied.
+- `supervisor.test.ts`: the no-output watchdog stops a stalled worker, lifecycle event failures are retried, and output is restored when event persistence fails.
+- `scripts/check-package.mjs`: verifies the Pi manifest, peer dependency policy,
+  required files and forbidden secret paths.
+
+## Transport spike acceptance
+
+Run `npm run spike:transport` only in an isolated test workspace after the test
+account is authenticated with Claude Code. The script uses `spawn` with
+`shell: false`, disables session persistence, restricts tools, sends one fixed
+non-sensitive prompt, and prints protocol metadata rather than raw model output.
+It must not be added to the normal CI gate because authentication is an owner
+controlled prerequisite.
+
+The current fixtures validate one prompt, multiple turns, session resume,
+permission allow/deny and SIGTERM/SIGINT behavior with Claude Code 2.1.268.
+The adapter regression suite also verifies event subscription, parsed
+`permission_request` events, and the exact nested `control_response` envelope.
+The automation spike additionally exercises a real Pi SDK Decision Worker with
+Claude: ordinary completion, harmless Bash permission approval, and an
+`AskUserQuestion` denial-to-text fallback followed by automatic verification.
+The extension persists each automatic Decision Worker session as Pi JSONL plus a
+0600 task mapping. Recovery is explicit and safe: after an unclean Pi restart,
+`/supervise sessions` shows the task as `recoverable`, and `/supervise recover
+<task-id>` restores the Decision Worker history before starting a new Claude
+Worker.
+Run the permission and signal probes explicitly when validating a CLI release:
+
+```bash
+npm run spike:permissions
+SPIKE_PERMISSION_DECISION=deny npm run spike:permissions
+npm run spike:signals
+npm run spike:automation
+SPIKE_AUTOMATION_PERMISSION=1 npm run spike:automation
+SPIKE_AUTOMATION_QUESTION=1 npm run spike:automation
+```
+
+For this release, pin and record Claude Code `2.1.268` and its resolved
+executable path. Record:
+
+1. exact version and resolved executable path;
+2. license and source revision;
+3. startup, prompt delivery and output framing;
+4. stop, process-group cleanup and crash behavior;
+5. timeout, duplicate-message and recovery behavior;
+6. human takeover and session-resume semantics;
+7. no secret leakage in event logs or npm archives.
+
+A passing worker task is not sufficient. The independent verifier must repeat the
+relevant checks from a clean host perspective.
+
+Automatic mode is enabled with `PI_CLAUDE_SUPERVISOR_MODE=auto`; it forces JSONL
+and routes `result`, permission, and process-exit events to the persistent Pi
+Decision Worker. `process-pipe` remains the manual compatibility mode. Human
+escalation is outbound-only through `PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL`;
+approval callbacks are deliberately not accepted without a separately
+authenticated endpoint.
+
+## Failure injection
+
+The automated adapter matrix covers external `SIGTERM`, `SIGINT`, `SIGKILL`,
+`SIGSTOP`/`SIGCONT`, SIGTERM refusal/escalation, leader-early-exit descendant
+cleanup, required cgroup cleanup of a `setsid()` descendant, repeated stop,
+spawn failure, output truncation, blocked stdin write timeouts, and immediate
+JSONL results. The Supervisor matrix also covers
+retrying failed lifecycle events, preserving startup event order, stopping under
+persistent timeout-event failure, and restoring output after event-log failure. The Supervisor matrix covers startup rejection, externally terminated
+workers, lifecycle serialization and stop races.
+
+Before release, manually test at least: immediate crash, hung process, malformed
+output, duplicate send, send/exit race, Pi `SIGTERM`/`SIGINT` shutdown,
+verification failure, blocked stdin writes/stop preemption, corrupt event-log
+tails, and descendants that call `setsid()` when cgroup mode is unavailable (expected
+fallback limitation). The cgroup test proves cleanup after attachment but does
+not eliminate the post-spawn attachment window. `SIGSTOP` and `SIGKILL` of the Pi host cannot be handled;
+verify and document the resulting orphan behavior.
+Default behavior must be fail-closed and leave no orphaned worker process within
+the managed process group.