pi-crew 0.1.51 → 0.2.0

package/docs/commands-reference.md

@@ -0,0 +1,347 @@
+# pi-crew — Slash Commands Reference
+
+Slash commands là thao tác thủ công từ Pi chat. Autonomous tool use qua `team` action là path chính; slash commands dành cho ops/debug.
+
+## Lệnh chính
+
+| Command | Mô tả |
+|---------|-------|
+| `/teams` | Liệt kê teams, agents, workflows, recent runs |
+| `/team-run [options] <goal>` | Chạy team workflow |
+| `/team-cancel <runId>` | Hủy run |
+| `/team-status <runId>` | Xem trạng thái |
+| `/team-summary <runId>` | Xem/ghi summary |
+| `/team-resume <runId>` | Tiếp tục run đã dừng |
+| `/team-events <runId>` | Xem event log |
+| `/team-artifacts <runId>` | Xem artifacts |
+| `/team-worktrees <runId>` | Xem worktree metadata |
+| `/team-cleanup <runId>` | Xóa worktrees |
+| `/team-forget <runId>` | Xóa run hoàn toàn |
+| `/team-prune` | Xóa nhiều runs cũ |
+| `/team-export <runId>` | Export run bundle |
+| `/team-import <path>` | Import run bundle |
+| `/team-imports` | Liệt kê imported bundles |
+| `/team-api <runId> <op>` | State API interop |
+| `/team-metrics [filter]` | Xem metrics |
+| `/team-manager` | Interactive helper |
+| `/team-dashboard` | Live dashboard overlay |
+| `/team-init [options]` | Khởi tạo project layout |
+| `/team-config [options]` | Xem/sửa config |
+| `/team-settings <subcmd>` | Quản lý config keys |
+| `/team-autonomy <subcmd>` | Quản lý delegation |
+| `/team-validate` | Validate resources |
+| `/team-help` | Help text |
+| `/team-doctor` | Chẩn đoán môi trường |
+
+---
+
+## `/team-run` — Chi tiết
+
+```text
+/team-run <goal>
+/team-run --team=implementation <goal>
+/team-run --team=default --workflow=default <goal>
+/team-run --async <goal>
+/team-run --worktree <goal>
+```
+
+Options:
+
+| Flag | Mô tả |
+|------|-------|
+| `--team=<name>` | Chọn team (default: `default`) |
+| `--workflow=<name>` | Chọn workflow (default: team's defaultWorkflow) |
+| `--async` | Chạy bất đồng bộ |
+| `--worktree` | Sử dụng worktree isolation |
+
+Ví dụ:
+
+```text
+# Chạy default team
+/team-run Investigate failing tests and propose a fix
+
+# Implementation team, async
+/team-run --team=implementation --async Refactor auth module
+
+# Worktree isolation
+/team-run --team=implementation --worktree Add API endpoint and tests
+```
+
+---
+
+## `/team-forget` — Xóa run
+
+```text
+/team-forget <runId> --confirm        # Xóa state + artifacts
+/team-forget <runId> --confirm --force # Xóa kể cả dirty worktrees
+```
+
+⚠️ Cần `--confirm`. Dirty worktrees được giữ lại trừ khi thêm `--force`.
+
+---
+
+## `/team-prune` — Dọn dẹp hàng loạt
+
+```text
+/team-prune --keep=20 --confirm
+```
+
+Giữ lại 20 runs gần nhất, xóa phần còn lại.
+
+---
+
+## `/team-api` — State Operations
+
+```text
+/team-api <runId> <operation> [key=value ...]
+```
+
+### Read operations
+
+```text
+/team-api team_... read-manifest
+/team-api team_... list-tasks
+/team-api team_... read-task taskId=task_...
+/team-api team_... read-events
+/team-api team_... read-heartbeat taskId=task_...
+/team-api team_... read-mailbox direction=outbox
+/team-api team_... read-mailbox taskId=task_... direction=inbox
+/team-api team_... read-delivery
+```
+
+### Write operations
+
+```text
+/team-api team_... write-heartbeat taskId=task_... alive=true
+/team-api team_... claim-task taskId=task_... owner=worker-1
+/team-api team_... release-task-claim taskId=task_... owner=worker-1 token=...
+/team-api team_... transition-task-status taskId=task_... owner=worker-1 token=... status=running
+```
+
+### Mailbox operations
+
+```text
+/team-api team_... send-message direction=outbox to=worker body="please check this"
+/team-api team_... send-message taskId=task_... direction=inbox to=worker body="task scoped"
+/team-api team_... ack-message messageId=msg_...
+/team-api team_... validate-mailbox repair=true
+```
+
+### Plan operations
+
+```text
+/team-api team_... approve-plan
+/team-api team_... cancel-plan
+```
+
+---
+
+## `/team-metrics` — Observability
+
+```text
+/team-metrics                          # Toàn bộ metrics
+/team-metrics crew.task.*              # Filter theo glob pattern
+```
+
+---
+
+## `/team-config` — Configuration
+
+```text
+/team-config                           # Xem config hiện tại
+/team-config asyncByDefault=true       # Update key
+/team-config --unset=key.path          # Unset key
+/team-config ... --project             # Project scope
+```
+
+---
+
+## `/team-settings` — Config Management
+
+```text
+/team-settings                          # Liệt kê tất cả keys
+/team-settings get limits.maxTurns      # Đọc 1 key
+/team-settings set limits.maxTurns 20   # Ghi key
+/team-settings unset runtime.maxTurns   # Reset về default
+/team-settings path                     # Đường dẫn file config
+/team-settings scope                    # Scope hiện tại (user/project)
+```
+
+### Supported Keys
+
+| Key | Type | Default | Mô tả |
+|-----|------|---------|-------|
+| `asyncByDefault` | boolean | `false` | Chạy async mặc định |
+| `executeWorkers` | boolean | `true` | Spawn child Pi workers |
+| `notifierIntervalMs` | number | `5000` | Polling interval cho async notifications |
+| `runtime.mode` | string | `"auto"` | Runtime: `auto`, `scaffold`, `child-process`, `live-session` |
+| `runtime.maxTurns` | number | — | Max turns per worker |
+| `runtime.graceTurns` | number | — | Grace turns sau max |
+| `runtime.inheritContext` | boolean | — | Workers kế thừa parent context |
+| `runtime.promptMode` | string | — | `replace` hoặc `append` |
+| `runtime.groupJoin` | string | `"smart"` | Group join: `off`, `group`, `smart` |
+| `runtime.groupJoinAckTimeoutMs` | number | `300000` | Group join ack timeout (ms) |
+| `runtime.requirePlanApproval` | boolean | `false` | Yêu cầu approve plan trước execute |
+| `runtime.completionMutationGuard` | string | `"warn"` | `off`, `warn`, `fail` |
+| `limits.maxConcurrentWorkers` | number | — | Max workers chạy song song |
+| `limits.maxTaskDepth` | number | `2` | Max task tree depth |
+| `limits.maxChildrenPerTask` | number | `5` | Max children per task |
+| `limits.maxRunMinutes` | number | `60` | Max run duration (phút) |
+| `limits.maxRetriesPerTask` | number | `1` | Max retries per task |
+| `limits.maxTasksPerRun` | number | — | Max tasks per run |
+| `limits.heartbeatStaleMs` | number | `60000` | Heartbeat stale threshold |
+| `control.enabled` | boolean | — | Enable agent control-plane |
+| `control.needsAttentionAfterMs` | number | — | Attention timeout |
+| `autonomous.profile` | string | `"suggested"` | `manual`, `suggested`, `assisted`, `aggressive` |
+| `autonomous.injectPolicy` | boolean | `true` | Inject policy vào prompt |
+| `autonomous.preferAsyncForLongTasks` | boolean | `false` | Auto-async cho tasks dài |
+| `autonomous.allowWorktreeSuggestion` | boolean | `true` | Gợi ý worktree mode |
+| `tools.enableClaudeStyleAliases` | boolean | `true` | Enable Claude-style aliases |
+| `tools.enableSteer` | boolean | `true` | Enable steer tool |
+| `tools.terminateOnForeground` | boolean | `false` | Return terminate từ foreground Agent |
+| `agents.disableBuiltins` | boolean | `false` | Disable builtin agents |
+| `observability.prometheus.enabled` | boolean | `false` | Enable Prometheus exporter |
+| `observability.otlp.enabled` | boolean | `false` | Enable OTLP exporter |
+| `worktree.enabled` | boolean | — | Enable worktree isolation |
+
+---
+
+## `/team-autonomy` — Delegation Policy
+
+```text
+/team-autonomy status                   # Xem trạng thái
+/team-autonomy on                       # Bật autonomous delegation
+/team-autonomy off                      # Tắt
+/team-autonomy manual                   # Profile: manual
+/team-autonomy suggested                # Profile: suggested (default)
+/team-autonomy assisted                 # Profile: assisted
+/team-autonomy aggressive               # Profile: aggressive
+```
+
+Options:
+
+```text
+/team-autonomy suggested --prefer-async          # Tự động async cho tasks dài
+/team-autonomy suggested --no-worktree-suggest   # Không gợi ý worktree
+```
+
+### Autonomy Profiles
+
+| Profile | Hành vi |
+|---------|---------|
+| `manual` | Không tự động delegate. Chạy khi host agent gọi team tool trực tiếp |
+| `suggested` | Đề xuất khi phù hợp, host agent quyết định (default) |
+| `assisted` | Chủ động delegate cho hầu hết tasks phức tạp |
+| `aggressive` | Luôn delegate, tối đa parallel execution |
+
+---
+
+## `/team-init` — Project Setup
+
+```text
+/team-init                             # Khởi tạo layout cơ bản
+/team-init --copy-builtins             # Copy builtin resources vào project
+/team-init --copy-builtins --overwrite # Copy và ghi đè
+```
+
+Tạo directories:
+
+```text
+# New projects (.crew/ layout)
+.crew/agents/
+.crew/teams/
+.crew/workflows/
+.crew/imports/
+
+# Legacy (.pi/ layout, khi .pi/ đã tồn tại)
+.pi/teams/agents/
+.pi/teams/teams/
+.pi/teams/workflows/
+.pi/teams/imports/
+```
+
+---
+
+## `/team-dashboard` — Live Dashboard
+
+```text
+/team-dashboard
+```
+
+### Keyboard Shortcuts
+
+| Key | Hành động |
+|-----|-----------|
+| `↑`/`↓` hoặc `j`/`k` | Chọn run |
+| `r` | Reload run list |
+| `p` | Toggle short/long progress |
+| `Enter` hoặc `s` | Xem status |
+| `a` | Xem artifacts |
+| `u` | Xem summary |
+| `i` | API read-manifest |
+| `q` hoặc `Esc` | Đóng |
+
+---
+
+## `/team-manager` — Interactive Helper
+
+```text
+/team-manager
+```
+
+Flows:
+- Liệt kê resources/runs
+- Chạy team
+- Xem run status
+- Cleanup worktrees
+- Tạo/sửa agent/team resources
+- Doctor check
+
+---
+
+## `/team-validate` — Resource Validation
+
+```text
+/team-validate
+```
+
+Kiểm tra:
+- Agents, teams, workflows hợp lệ
+- References đúng (agent tồn tại trong team roles)
+- Model hints hợp lệ
+- Workflow steps đúng format
+
+---
+
+## `/team-doctor` — Environment Check
+
+```text
+/team-doctor
+```
+
+Kiểm tra:
+- cwd, platform, architecture
+- Node.js version
+- `pi --version`
+- `git --version`
+- State paths writable
+- Config parse
+- Discovery counts (agents, teams, workflows)
+- Resource validation
+- Current model/provider
+- Model/fallback hints
+
+Child Pi smoke test (explicit):
+
+```text
+/team-api team_... doctor smokeChildPi=true
+```
+
+hoặc qua tool:
+
+```json
+{
+  "action": "doctor",
+  "config": { "smokeChildPi": true }
+}
+```

package/docs/runtime-flow.md

@@ -1,148 +1,148 @@
-# pi-crew Runtime Flow
-
-This document is a compact map of the runtime paths used by `pi-crew`.
-
-## Main sequence
-
-```text
-User / model
-  │ calls team({ action: "run", ... }) or /team-run
-  ▼
-handleTeamTool()
-  │ validates schema and routes action
-  ▼
-handleRun()
-  ├─ discoverTeams/discoverWorkflows/discoverAgents
-  ├─ validateWorkflowForTeam
-  ├─ expandParallelResearchWorkflow when applicable
-  ├─ createRunManifest + tasks.json + goal artifact
-  ├─ if async=true ─────────────────────────────────────────────┐
-  │   spawnBackgroundTeamRun()                                  │
-  │     ├─ resolve jiti-register.mjs                            │
-  │     ├─ fail-fast if jiti missing                            │
-  │     ├─ node --import jiti-register.mjs background-runner.ts  │
-  │     └─ parent schedules early-exit guard                    │
-  │                                                            ▼
-  │   background-runner.ts
-  │     ├─ append async.started
-  │     ├─ write async.pid startup marker
-  │     ├─ rediscover team/workflow/agents
-  │     └─ executeTeamRun()
-  │
-  └─ if foreground/default
-      ├─ startForegroundRun schedules session-bound run, or
-      └─ executeTeamRun inline for scaffold/non-scheduled paths
-
-executeTeamRun()
-  ├─ write run.running
-  ├─ materialize queued/running agent records lazily
-  ├─ build task graph index
-  ├─ while queued tasks exist
-  │   ├─ taskGraphSnapshot
-  │   ├─ resolveBatchConcurrency
-  │   ├─ getReadyTasks
-  │   ├─ append task.progress batch event
-  │   ├─ mapConcurrent ready batch
-  │   │   └─ runTeamTask()
-  │   │       ├─ prepare workspace/worktree
-  │   │       ├─ build task packet
-  │   │       ├─ render prompt + dependency context
-  │   │       ├─ choose model candidates from Pi config
-  │   │       ├─ spawn child Pi process
-  │   │       ├─ ChildPiLineObserver parses stdout/stderr
-  │   │       ├─ append per-agent events/output
-  │   │       ├─ update agent progress/task state
-  │   │       ├─ parse final JSONL/session usage
-  │   │       └─ write result/log/transcript/metadata artifacts
-  │   ├─ merge task updates monotonically
-  │   ├─ optional adaptive plan injection
-  │   ├─ save tasks/agents/progress
-  │   └─ write batch artifact
-  ├─ policy closeout
-  └─ run.completed / run.failed / run.blocked / run.cancelled
-```
-
-## Action router
-
-| Action | Handler | Purpose |
-|---|---|---|
-| `run` | `team-tool/run.ts` | Create and execute a run, foreground or async. |
-| `status` | `team-tool.ts` | Show manifest/tasks/agents/events and mark stale async runs failed. |
-| `summary` | `session-summary.ts`/summary handler | Write/read run summary artifact. |
-| `events` | `team-tool.ts` | Tail durable run events. |
-| `artifacts` | `team-tool.ts` | List run artifacts. |
-| `resume` | `team-tool.ts` | Requeue failed/cancelled/skipped/running tasks. |
-| `cancel` | `team-tool.ts` | Mark queued/running tasks cancelled and request foreground interrupt. |
-| `forget` | `run-maintenance.ts` | Delete run state/artifacts with confirmation. |
-| `prune` | `run-maintenance.ts` | Remove old finished runs with confirmation. |
-| `export` | `run-export.ts` | Create portable run bundle. |
-| `import` / `imports` | `run-import.ts` / `import-index.ts` | Store/list imported bundles. |
-| `config` | `config.ts` + config action | Show/update user/project config. |
-| `doctor` | `team-tool/doctor.ts` | Platform/resource/runtime diagnostics. |
-| `validate` | `validate-resources.ts` | Validate agents/teams/workflows. |
-| `recommend` | `team-recommendation.ts` | Suggest team/workflow/action for a goal. |
-| management | `management.ts` | Create/update/delete/rename teams, agents, workflows. |
-| API | `team-tool/api.ts` | File-backed observability/control/mailbox API. |
-
-## Worker modes
-
-| Mode | Behavior |
-|---|---|
-| `child-process` | Default. Launches real child `pi` processes per task. |
-| `scaffold` | Explicit dry-run. No child Pi worker execution. |
-| `live-session` | Experimental/gated in-process/live agent path. |
-| `auto` | Resolves to child-process unless config/env requests otherwise. |
-
-## Important files
-
-```text
-src/extension/register.ts              Pi extension entry/wiring
-src/extension/team-tool/run.ts         run creation and foreground/async split
-src/runtime/background-runner.ts       detached async entrypoint
-src/runtime/async-runner.ts            background spawn command/options
-src/runtime/team-runner.ts             workflow/task graph scheduler
-src/runtime/task-runner.ts             single task execution
-src/runtime/child-pi.ts                child Pi process and output observer
-src/runtime/model-fallback.ts          configured model candidates/routing
-src/runtime/concurrency.ts             batch concurrency decisions
-src/runtime/process-status.ts          pid/liveness/stale detection
-src/state/state-store.ts               manifest/tasks persistence
-src/state/event-log.ts                 JSONL run events
-src/runtime/crew-agent-records.ts      aggregate + per-agent status files
-```
-
-## Environment variables
-
-| Env | Effect |
-|---|---|
-| `PI_CREW_EXECUTE_WORKERS=0` | Disable real workers, use scaffold behavior. |
-| `PI_TEAMS_EXECUTE_WORKERS=0` | Legacy alias for worker disable. |
-| `PI_CREW_ENABLE_EXPERIMENTAL_LIVE_SESSION=1` | Allow experimental live-session runtime. |
-| `PI_CREW_MOCK_LIVE_SESSION=success` | Test hook for live-session mock. |
-| `PI_TEAMS_MOCK_CHILD_PI` | Test hook for mocked child Pi execution. |
-| `PI_CREW_DEPTH`, `PI_CREW_MAX_DEPTH` | Canonical subagent recursion guard. |
-| `PI_TEAMS_DEPTH`, `PI_TEAMS_MAX_DEPTH` | Legacy recursion guard aliases. |
-| `PI_TEAMS_HOME` | Override user config/state home in tests. |
-| `PI_TEAMS_PI_BIN` | Override child `pi` executable. |
-| `PI_CODING_AGENT_DIR` | Override Pi settings/models directory for model discovery. |
-| `PI_CREW_ASYNC_EARLY_EXIT_GUARD=0` | Disable 3s background early-exit guard. |
-
-## State transition summary
-
-```text
-queued/planning/running  ── completed
-                         ├─ failed
-                         ├─ blocked
-                         └─ cancelled
-```
-
-Task states follow the same durable contract plus `skipped`. Terminal states are monotonic during parallel merge.
-
-## Observability tips
-
-- Use `/team-dashboard` for a UI overview.
-- Use `team status runId=...` for canonical state and stale async detection.
-- Read `background.log` for early import/spawn errors.
-- Read `events.jsonl` for event chronology.
-- Read `agents/{taskId}/status.json` for per-agent model/progress/tool status.
-- Read `artifacts/{runId}/transcripts/{taskId}.jsonl` for raw child Pi transcript.
+# pi-crew Runtime Flow
+
+This document is a compact map of the runtime paths used by `pi-crew`.
+
+## Main sequence
+
+```text
+User / model
+  │ calls team({ action: "run", ... }) or /team-run
+  ▼
+handleTeamTool()
+  │ validates schema and routes action
+  ▼
+handleRun()
+  ├─ discoverTeams/discoverWorkflows/discoverAgents
+  ├─ validateWorkflowForTeam
+  ├─ expandParallelResearchWorkflow when applicable
+  ├─ createRunManifest + tasks.json + goal artifact
+  ├─ if async=true ─────────────────────────────────────────────┐
+  │   spawnBackgroundTeamRun()                                  │
+  │     ├─ resolve jiti-register.mjs                            │
+  │     ├─ fail-fast if jiti missing                            │
+  │     ├─ node --import jiti-register.mjs background-runner.ts  │
+  │     └─ parent schedules early-exit guard                    │
+  │                                                            ▼
+  │   background-runner.ts
+  │     ├─ append async.started
+  │     ├─ write async.pid startup marker
+  │     ├─ rediscover team/workflow/agents
+  │     └─ executeTeamRun()
+  │
+  └─ if foreground/default
+      ├─ startForegroundRun schedules session-bound run, or
+      └─ executeTeamRun inline for scaffold/non-scheduled paths
+
+executeTeamRun()
+  ├─ write run.running
+  ├─ materialize queued/running agent records lazily
+  ├─ build task graph index
+  ├─ while queued tasks exist
+  │   ├─ taskGraphSnapshot
+  │   ├─ resolveBatchConcurrency
+  │   ├─ getReadyTasks
+  │   ├─ append task.progress batch event
+  │   ├─ mapConcurrent ready batch
+  │   │   └─ runTeamTask()
+  │   │       ├─ prepare workspace/worktree
+  │   │       ├─ build task packet
+  │   │       ├─ render prompt + dependency context
+  │   │       ├─ choose model candidates from Pi config
+  │   │       ├─ spawn child Pi process
+  │   │       ├─ ChildPiLineObserver parses stdout/stderr
+  │   │       ├─ append per-agent events/output
+  │   │       ├─ update agent progress/task state
+  │   │       ├─ parse final JSONL/session usage
+  │   │       └─ write result/log/transcript/metadata artifacts
+  │   ├─ merge task updates monotonically
+  │   ├─ optional adaptive plan injection
+  │   ├─ save tasks/agents/progress
+  │   └─ write batch artifact
+  ├─ policy closeout
+  └─ run.completed / run.failed / run.blocked / run.cancelled
+```
+
+## Action router
+
+| Action | Handler | Purpose |
+|---|---|---|
+| `run` | `team-tool/run.ts` | Create and execute a run, foreground or async. |
+| `status` | `team-tool.ts` | Show manifest/tasks/agents/events and mark stale async runs failed. |
+| `summary` | `session-summary.ts`/summary handler | Write/read run summary artifact. |
+| `events` | `team-tool.ts` | Tail durable run events. |
+| `artifacts` | `team-tool.ts` | List run artifacts. |
+| `resume` | `team-tool.ts` | Requeue failed/cancelled/skipped/running tasks. |
+| `cancel` | `team-tool.ts` | Mark queued/running tasks cancelled and request foreground interrupt. |
+| `forget` | `run-maintenance.ts` | Delete run state/artifacts with confirmation. |
+| `prune` | `run-maintenance.ts` | Remove old finished runs with confirmation. |
+| `export` | `run-export.ts` | Create portable run bundle. |
+| `import` / `imports` | `run-import.ts` / `import-index.ts` | Store/list imported bundles. |
+| `config` | `config.ts` + config action | Show/update user/project config. |
+| `doctor` | `team-tool/doctor.ts` | Platform/resource/runtime diagnostics. |
+| `validate` | `validate-resources.ts` | Validate agents/teams/workflows. |
+| `recommend` | `team-recommendation.ts` | Suggest team/workflow/action for a goal. |
+| management | `management.ts` | Create/update/delete/rename teams, agents, workflows. |
+| API | `team-tool/api.ts` | File-backed observability/control/mailbox API. |
+
+## Worker modes
+
+| Mode | Behavior |
+|---|---|
+| `child-process` | Default. Launches real child `pi` processes per task. |
+| `scaffold` | Explicit dry-run. No child Pi worker execution. |
+| `live-session` | Experimental/gated in-process/live agent path. |
+| `auto` | Resolves to child-process unless config/env requests otherwise. |
+
+## Important files
+
+```text
+src/extension/register.ts              Pi extension entry/wiring
+src/extension/team-tool/run.ts         run creation and foreground/async split
+src/runtime/background-runner.ts       detached async entrypoint
+src/runtime/async-runner.ts            background spawn command/options
+src/runtime/team-runner.ts             workflow/task graph scheduler
+src/runtime/task-runner.ts             single task execution
+src/runtime/child-pi.ts                child Pi process and output observer
+src/runtime/model-fallback.ts          configured model candidates/routing
+src/runtime/concurrency.ts             batch concurrency decisions
+src/runtime/process-status.ts          pid/liveness/stale detection
+src/state/state-store.ts               manifest/tasks persistence
+src/state/event-log.ts                 JSONL run events
+src/runtime/crew-agent-records.ts      aggregate + per-agent status files
+```
+
+## Environment variables
+
+| Env | Effect |
+|---|---|
+| `PI_CREW_EXECUTE_WORKERS=0` | Disable real workers, use scaffold behavior. |
+| `PI_TEAMS_EXECUTE_WORKERS=0` | Legacy alias for worker disable. |
+| `PI_CREW_ENABLE_EXPERIMENTAL_LIVE_SESSION=1` | Allow experimental live-session runtime. |
+| `PI_CREW_MOCK_LIVE_SESSION=success` | Test hook for live-session mock. |
+| `PI_TEAMS_MOCK_CHILD_PI` | Test hook for mocked child Pi execution. |
+| `PI_CREW_DEPTH`, `PI_CREW_MAX_DEPTH` | Canonical subagent recursion guard. |
+| `PI_TEAMS_DEPTH`, `PI_TEAMS_MAX_DEPTH` | Legacy recursion guard aliases. |
+| `PI_TEAMS_HOME` | Override user config/state home in tests. |
+| `PI_TEAMS_PI_BIN` | Override child `pi` executable. |
+| `PI_CODING_AGENT_DIR` | Override Pi settings/models directory for model discovery. |
+| `PI_CREW_ASYNC_EARLY_EXIT_GUARD=0` | Disable 3s background early-exit guard. |
+
+## State transition summary
+
+```text
+queued/planning/running  ── completed
+                         ├─ failed
+                         ├─ blocked
+                         └─ cancelled
+```
+
+Task states follow the same durable contract plus `skipped`. Terminal states are monotonic during parallel merge.
+
+## Observability tips
+
+- Use `/team-dashboard` for a UI overview.
+- Use `team status runId=...` for canonical state and stale async detection.
+- Read `background.log` for early import/spawn errors.
+- Read `events.jsonl` for event chronology.
+- Read `agents/{taskId}/status.json` for per-agent model/progress/tool status.
+- Read `artifacts/{runId}/transcripts/{taskId}.jsonl` for raw child Pi transcript.

package/index.ts

@@ -1,6 +1,6 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { registerPiTeams } from "./src/extension/register.ts";
-
-export default function (pi: ExtensionAPI): void {
-	registerPiTeams(pi);
-}
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerPiTeams } from "./src/extension/register.ts";
+
+export default function (pi: ExtensionAPI): void {
+	registerPiTeams(pi);
+}