pi-claude-supervisor 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+## [0.2.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.1.0...v0.2.0) (2026-09-12)
+
+
+### Features
+
+* persist decision worker sessions across restarts ([a926c0e](https://github.com/btnalit/pi-claude-supervisor/commit/a926c0e4f3455cbc5dfbbcff1441d1d1497939ed))
+* persist Decision Worker sessions and add release gates ([de73d29](https://github.com/btnalit/pi-claude-supervisor/commit/de73d29549605026985db301112ae3745d164bd7))
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- Standard Pi/npm package metadata and TypeScript extension entry point.
+- Dependency-free process-pipe WorkerAdapter with process-group control.
+- Explicit Supervisor state machine, append-only event log and turn budget.
+- Deterministic Policy Gate and independent verification phase.
+- Minimal worker environment, argv-aware permission policy, watchdog timeouts and startup cleanup.
+- Opt-in Claude JSONL framing with duplicate-message suppression and transport Spike evidence for prompt, multi-turn and session resume.
+- Event-log sequence recovery and credential-shaped redaction.
+- Bounded output capture, stdin-write timeout, process-group cleanup retry and stop preemption.
+- Linux cgroup-v2 descendant cleanup, including a `setsid()` regression fixture, with required/auto modes.
+- Lifecycle event retry/order preservation, output restoration after log failure and shutdown cleanup retries.
+- Claude CLI 2.1.268 permission allow/deny and SIGTERM/SIGINT transport spike evidence.
+- Event-driven JSONL `control_request`/`result`/exit events, permission responses, persistent Pi Decision Worker automation, bounded duplicate/turn handling, and outbound human-intervention webhooks.
+- Long-task defaults are now 100 automatic turns, 4 hours wall time and 20 minutes without output; Decision Worker API failures alert human operators directly instead of attempting an LLM fallback.
+- Automatic Decision Worker sessions now persist as Pi JSONL with a 0600 task registry. Unclean Pi restarts expose explicit `/supervise recover <task-id>` recovery; Claude work is not silently duplicated.
+- Local tests and package-content checks.
+
+### Limitations
+
+- PTY transport and cross-version Claude CLI permission/session semantics are out of scope for this pinned release; Claude JSONL support remains opt-in outside automatic mode. The installed 2.1.268 CLI is covered by local permission and signal spikes, while the cgroup startup-attachment window remains.
+- No automatic merge, deployment, release or publication is implemented.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yancao
+
+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.cn.md

@@ -0,0 +1,98 @@
+# pi-claude-supervisor
+
+[![CI](https://github.com/btnalit/pi-claude-supervisor/actions/workflows/ci.yml/badge.svg)](https://github.com/btnalit/pi-claude-supervisor/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/pi-claude-supervisor)](https://www.npmjs.com/package/pi-claude-supervisor)
+[![MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+[English](README.md)
+
+用于 Pi 的 Claude Code Worker 监督扩展。MVP 中 Pi 负责生命周期、状态机、策略门和独立验收；Worker 只是被显式启动的子进程。
+
+> 当前默认 transport 是无额外依赖的 process pipe，不是 PTY。已新增可选 Claude JSONL framing，并通过基础 prompt、多轮和 resume Spike。当前优先保证生命周期、进程组清理、恢复和独立验收；低权限用户、OS sandbox 与网络隔离不作为当前主线，按明确授权和宿主机策略运行，后续再做安全加固。
+
+## 关键安全边界
+
+- 不会在扩展加载时自动启动 Worker。
+- 不经过 shell 启动子进程。
+- Worker 只继承最小环境；凭据必须由调用方显式传入。
+- 破坏性命令和绕过权限的 Worker 参数默认拒绝；需要复核的启动命令会请求用户批准，不会一律拒绝。
+- Linux 上优先使用可写的 cgroup v2 清理后代进程，包括 `setsid()` 后代；不可用时回退到进程组清理。需要强制失败闭环时，embedding 集成可使用 `cgroupMode: "required"`。
+- 普通联网查询不因联网本身被拒绝；下载后直接交给 shell 等高风险模式仍需人工复核。
+- Worker 声称完成只会进入 `verifying`，不能作为成功证据。
+- 默认独立验收命令为 `git diff --check`。
+- 扩展运行时不执行 merge、deploy、release 或 publish；仓库 Release 只会在维护者合并 Release Please PR 且 CI 门禁全部通过后自动发布。
+- 默认 4 小时总时限、20 分钟无输出 watchdog 超时即停止 Worker，适合长程开发任务；嵌入调用方可将对应选项设为 `0` 关闭。
+
+## 安装和使用
+
+需要 Pi 0.85+ 和 Node.js 22.19+：
+
+```text
+pi install npm:pi-claude-supervisor
+```
+
+在 Pi 中使用。手动/兼容模式默认使用 process-pipe。要启用事件驱动的 Pi Decision Worker，使用 Claude JSONL 自动模式：
+
+```bash
+export PI_CLAUDE_SUPERVISOR_MODE=auto
+export PI_CLAUDE_SUPERVISOR_WORKER='claude --safe-mode --tools Bash'
+# 可选：人工升级通知；generic 或 wecom
+export PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL='https://example.invalid/webhook'
+export PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_FORMAT=generic
+# export PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_SECRET='shared-secret'
+```
+
+自动模式会强制使用 `claude-jsonl`，通过 `result`、`control_request` 和进程
+`exit` 事件唤醒 Decision Worker；不会依赖 `/supervise poll` 轮询。本版本固定按已验证设备的
+Claude CLI `2.1.268` 运行，跨版本兼容性不在本轮范围内。
+
+然后在 Pi 中使用：
+
+```text
+/supervise capabilities
+/supervise start inspect the current repository
+/supervise poll
+/supervise sessions
+/supervise recover <task-id>
+/supervise stop human requested stop
+/supervise verify
+/supervise approve <task-id> allow|deny [request-id]
+/supervise takeover <task-id>
+/supervise resume-auto <task-id>
+```
+
+人工升级通知的 generic JSON 格式为：
+
+```json
+{
+  "schema": "pi-claude-supervisor/human-intervention/v1",
+  "event": "human_intervention_required",
+  "task": { "id": "...", "goal": "...", "cwd": "..." },
+  "worker": { "id": "..." },
+  "reason": "...",
+  "question": "...",
+  "permission": { "requestId": "...", "toolUseId": "...", "toolName": "Bash", "input": {} },
+  "actions": ["approve_or_deny_permission", "send_instruction", "stop_worker", "takeover"]
+}
+```
+
+当前 webhook 是出站通知，不直接接受批准命令；批准或接管仍通过 Pi。
+自动模式会将 Decision Worker 会话持久化到状态目录。Pi 非正常重启后，`/supervise sessions`
+会显示 `recoverable` 任务；显式执行 `/supervise recover <task-id>` 会恢复 Decision Worker 上下文并
+重新启动 Claude Worker，不会静默恢复或重复执行任务。
+自动模式下，Decision Worker 可以安全拒绝 `AskUserQuestion`，让 Claude 将问题转成普通文本，
+再根据任务和仓库证据自动回答；无法确定时才升级人工。如需微信内闭环，需要另建带签名验证、
+一次性 action token 和重放保护的入站 callback 服务。
+
+可以从不同工作目录启动多个任务会话；活动会话不能共享同一 cwd，建议每个任务使用独立 worktree：
+
+```text
+/supervise sessions
+/supervise poll all
+/supervise poll <task-id>
+/supervise send <task-id> continue after checking the test failure
+```
+
+Pull Request 必须通过聚合的 `CI / Quality gate`。Release Please 根据 Conventional Commits 创建版本 PR；维护者合并后，Release workflow 会针对精确 tag commit 重新验证，并通过受保护的 `npm` environment 使用 npm provenance 发布。
+
+详细内容见 [engineering-plan.md](docs/engineering-plan.md)、[independent-review.md](docs/independent-review.md)、[architecture.md](docs/architecture.md)、[testing.md](docs/testing.md) 和 [releasing.md](docs/releasing.md)。

package/README.md

@@ -0,0 +1,122 @@
+# pi-claude-supervisor
+
+[![CI](https://github.com/btnalit/pi-claude-supervisor/actions/workflows/ci.yml/badge.svg)](https://github.com/btnalit/pi-claude-supervisor/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/pi-claude-supervisor)](https://www.npmjs.com/package/pi-claude-supervisor)
+[![MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+English · [简体中文](README.cn.md)
+
+A policy-gated [Pi](https://pi.dev) extension for supervising a Claude Code worker.
+The MVP keeps Pi in control of lifecycle, state, policy and verification while the
+worker remains an explicitly started child process.
+
+> **MVP status:** the default transport is dependency-free process pipes, not PTY.
+> An opt-in Claude JSONL framing mode has passed basic prompt, multi-turn and
+> resume fixtures. The current priority is signal, shutdown, process-group and
+> recovery validation; OS sandbox, low-privilege execution and network isolation
+> are deferred hardening items and are not required by the current MVP plan.
+
+## Safety boundary
+
+- The extension never starts a worker automatically.
+- Worker commands are launched without a shell.
+- Workers receive a minimal environment; credentials must be explicitly supplied by the caller.
+- Destructive command patterns and permission-bypass worker flags are denied; review-level patterns request explicit user approval instead of being blanket-denied.
+- Ordinary network use is not denied merely because it is network use; download-to-shell patterns still require review.
+- A worker completion is only a transition to `verifying`; it is not evidence of success.
+- Verification is an independent host command (default: `git diff --check`).
+- The extension never performs merge, deploy, release, or publish at runtime. Repository releases are automated only after a maintainer merges a Release Please PR and the full CI gate passes.
+- A 4-hour wall-clock and 20-minute no-output watchdog stop a worker by default for long development tasks; embedding callers can set either to `0` to disable.
+- On Linux, the adapter automatically uses a writable cgroup v2 for descendant cleanup, including `setsid()` descendants; it falls back to process-group cleanup when unavailable. Use the adapter's `cgroupMode: "required"` for a fail-closed integration.
+- Events are append-only JSONL records in `~/.pi/agent/claude-supervisor/events.jsonl`.
+
+## Install
+
+Requires Pi 0.85+ and Node.js 22.19+.
+
+```text
+pi install npm:pi-claude-supervisor
+```
+
+For local development:
+
+```bash
+npm ci --ignore-scripts
+npm run check
+npm run build
+```
+
+## Use
+
+Set the worker executable if needed, then use explicit commands in Pi:
+
+```bash
+export PI_CLAUDE_SUPERVISOR_WORKER=claude
+```
+
+```text
+/supervise capabilities
+/supervise start inspect the current repository and report what should be changed
+/supervise sessions
+/supervise recover <task-id>
+/supervise poll
+/supervise poll all
+/supervise send continue with read-only inspection
+/supervise pause
+/supervise resume
+/supervise stop human requested stop
+/supervise verify
+```
+
+The default MVP writes the task to the worker's stdin as plain process-pipe
+text. After running the transport spike for the target CLI, JSONL framing can
+be selected explicitly:
+
+```bash
+export PI_CLAUDE_SUPERVISOR_TRANSPORT=jsonl
+export PI_CLAUDE_SUPERVISOR_WORKER='claude --safe-mode --tools ""'
+```
+
+This adds Claude Code stream-json flags and frames supervisor messages as JSONL.
+The supervisor allows only one active JSONL request per session: poll until its
+`result` and `waiting` state before sending the next turn. Session resume is not
+yet exposed by the adapter. Multiple independent task sessions can run
+concurrently when they use different canonical working directories or
+worktrees; same-directory starts are rejected even when concurrent, and
+`/supervise sessions` lists the sessions. Unattended use still requires the
+remaining lifecycle, signal and recovery checks. Host permissions and network
+access follow explicit caller authorization and host policy; there is no
+automatic merge, deploy, release or publish.
+
+Automatic mode persists the Pi Decision Worker session under the configured state
+directory. After an unclean Pi restart, `/supervise sessions` lists recoverable
+tasks; `/supervise recover <task-id>` explicitly restores the Decision Worker
+context and starts a new Claude Worker. It never silently resumes or duplicates
+work. The adapter intentionally does not inherit arbitrary host environment variables.
+Pass credentials through an explicit `WorkerStartInput.env` in an embedding
+integration. For the built-in command, opt in to named variables, for example
+`PI_CLAUDE_SUPERVISOR_WORKER_ENV=ANTHROPIC_API_KEY`.
+
+## Development
+
+```bash
+npm run typecheck
+npm test
+npm run check:package
+npm run check:docs
+npm run check:automation
+npm run check:workflows
+npm run build
+```
+
+See [the engineering plan](docs/engineering-plan.md), [the independent review](docs/independent-review.md),
+[architecture](docs/architecture.md), [testing](docs/testing.md), and [releasing](docs/releasing.md).
+
+Pull requests are gated by the aggregated `CI / Quality gate`. Release Please
+creates version PRs from Conventional Commits; after a maintainer merges one,
+`Release` verifies the exact tag commit and publishes the package with npm
+provenance through the protected `npm` environment.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/docs/architecture.md

@@ -0,0 +1,122 @@
+# Architecture
+
+## Control boundary
+
+Pi owns the `Supervisor`. The supervisor owns the task state machine, event log,
+turn budget, policy decision and independent verifier. `WorkerAdapter` owns only
+process lifecycle and transport details.
+
+```text
+Pi extension
+    |
+    v
+Supervisor -> Policy Gate -> WorkerAdapter -> child process
+    |
+    +------> EventLog (JSONL)
+    +------> Independent Verifier
+```
+
+The Worker cannot advance a task directly to `completed`. A clean worker exit
+moves the supervisor to `verifying`; only a successful verifier moves it to
+`completed`.
+
+The extension keeps a registry of independent task sessions. Each session has
+its own Supervisor, watchdog, state machine and Worker handle, while the event
+log is shared and protected by an inter-process lock. Concurrent active sessions must use non-overlapping canonical working
+directories/worktrees; same-cwd and parent/child cwd starts are rejected before
+spawn, including concurrent starts, to prevent uncoordinated edits. Pending starts
+are also awaited during Pi shutdown.
+
+## MVP transport
+
+`ProcessWorkerAdapter` uses `node:child_process.spawn` with:
+
+- `shell: false` (the default and intentionally not overridden);
+- a detached process group for pause/resume/kill control;
+- separate stdout/stderr capture;
+- idempotency keys for messages;
+- no session-resume claim.
+
+This is a control-boundary fixture and headless transport. It does not emulate a
+terminal. Manual compatibility mode remains `process-pipe`; automatic mode
+(`PI_CLAUDE_SUPERVISOR_MODE=auto`) forces Claude JSONL and uses the CLI contract
+validated by the fixed-version spike.
+
+A worker exit automatically triggers cleanup, and terminal status waits for
+that cleanup to be confirmed (or reports a cleanup error). On Linux the adapter
+uses cgroup v2 automatically when the current user cgroup is writable; the
+`required` mode fails startup if cgroup attachment is unavailable. Cgroup
+cleanup kills descendants even when they call `setsid()` or create another
+process group. Attachment occurs immediately after spawn, so a worker that
+forks before attachment remains a documented startup-window limitation.
+
+When cgroup v2 is unavailable, the adapter falls back to detached
+process-group cleanup. That fallback is not recursive: `setsid()` descendants
+can escape, and PID reuse between leader exit and cleanup is a host-level
+limitation. Production deployments that require an atomic boundary should use a
+service-manager scope, Job Object, pidfd-aware reaper, or equivalent supervisor.
+The Pi host installs graceful `SIGTERM`/`SIGINT` handlers, but `SIGSTOP` and
+`SIGKILL` cannot be handled; no orphan guarantee is claimed for those host-fatal
+signals.
+
+## State machine
+
+```text
+idle -> starting -> running -> waiting -> running -> verifying -> completed
+                  |       |       |             |
+                  v       v       v             v
+                paused  failed  stopped        idle
+```
+
+`stop` is available from `starting`, `running`, `waiting` and `paused`. Invalid
+transitions fail closed. Supervisor lifecycle operations and their state/event
+updates run through one serial queue, so concurrent `poll`, `send`, `stop`,
+watchdog and shutdown work cannot produce duplicate terminal transitions. If a
+lifecycle event append fails after the state transition, it remains pending and
+is retried before the next lifecycle operation; output events restore their
+chunks for a lossless retry.
+
+## Event log
+
+Events are JSONL with a monotonic sequence number, timestamp, task ID and worker
+ID. Appends use a per-log atomic lock directory with owner PID, bounded waiting
+and stale-owner detection. Each append refreshes the sequence from disk while
+holding the lock, so independent Pi processes cannot reuse sequence numbers.
+The log is diagnostic evidence, not an authorization mechanism. Log contents
+must be treated as sensitive because worker output may contain repository data.
+
+For Claude JSONL, the adapter tracks `activeRequests`, `lastInputAt` and
+`lastOutputAt`. A `result` record closes an active request; malformed output does
+not. JSONL sends are rejected while a request is active, and a valid terminal
+result moves the session to `waiting`; only then may the next turn be sent.
+Input writes are serialized with stop and are acknowledged through the stream
+write callback before their idempotency key is consumed. Writes have a bounded
+timeout, and `stop()` preempts a queued lifecycle operation by initiating adapter
+termination immediately. This status is observable by `poll` and prevents blind
+duplicate turns. The adapter also exposes event subscriptions for `result`,
+`control_request`, permission requests and process exit. Automatic mode routes
+those events to a persistent, read-only Pi Decision Worker; its Pi session JSONL
+and task mapping are persisted under the supervisor state directory. After an
+unclean Pi restart, recovery is explicit: `/supervise recover <task-id>` restores
+the Decision Worker context and starts a new Claude Worker. It does not silently
+resume or duplicate a task. It does not poll to detect turn completion. A watchdog timer remains only as a deadlock safety
+fallback. Permission actions pass through `evaluatePermission` and can be
+approved or denied manually with `/supervise approve`; human escalation is sent
+to an outbound webhook when configured. If the Decision Worker API/model call
+fails, the system records `decision_worker_failed` and directly alerts the
+human operator; it does not attempt a second LLM fallback. Alert delivery is
+kept independent from event-log persistence so an audit write failure cannot
+suppress the alert.
+
+## Deliberate non-goals
+
+- automatic merge/deploy/release;
+- unauthenticated inbound webhook commands; outbound notifications do not grant
+  permission and do not replace Pi human takeover;
+- treating an unknown Claude interactive question as safe to answer automatically;
+- bypassing Claude Code permissions;
+- accepting model text as verification;
+- shell command interpolation;
+- automatic network denial or a fake domain allowlist. Network access follows
+  Claude's own permission model and the command policy; suspicious download-to-
+  shell patterns require human review rather than blanket network rejection.