pi-crew 0.2.3 → 0.2.5

package/docs/templates/story.md

@@ -0,0 +1,44 @@
+# US-XXX Story Title
+
+## Status
+
+planned
+
+## Lane
+
+tiny | normal | high-risk
+
+## Product Contract
+
+Describe the behavior this story must make true.
+
+## Affected Modules
+
+- `src/...`
+
+## Acceptance Criteria
+
+- Criterion 1.
+- Criterion 2.
+
+## Design Notes
+
+- Commands:
+- State changes:
+- API changes:
+
+## Validation
+
+| Layer | Command | Expected |
+|-------|---------|----------|
+| Typecheck | `npm run typecheck` | pass |
+| Unit | `npm test` | 0 fail |
+| CI | GitHub Actions | 3/3 green |
+
+## Harness Delta
+
+Harness updates made or proposed.
+
+## Evidence
+
+Add commands, results, CI links after validation.

package/docs/templates/validation-report.md

@@ -0,0 +1,32 @@
+# Validation Report
+
+Date: YYYY-MM-DD
+
+## Scope
+
+What story or change was validated?
+
+## Commands Run
+
+```text
+npm test
+npm run typecheck
+```
+
+## Results
+
+| Check | Result | Notes |
+|-------|--------|-------|
+| Typecheck | | |
+| Unit tests | | |
+| CI (ubuntu) | | |
+| CI (windows) | | |
+| CI (macos) | | |
+
+## Evidence
+
+Links to CI runs, screenshots, or logs.
+
+## Gaps
+
+Remaining risk or missing validation.

package/docs/usage.md

@@ -1,238 +1,238 @@
-# pi-crew Usage
-
-## Config
-
-Optional config path:
-
-```text
-~/.pi/agent/extensions/pi-crew/config.json
-```
-
-Create a default config:
-
-```bash
-node ./pi-crew/install.mjs
-```
-
-Supported fields:
-
-```json
-{
-  "asyncByDefault": false,
-  "executeWorkers": true,
-  "notifierIntervalMs": 5000,
-  "requireCleanWorktreeLeader": true,
-  "autonomous": {
-    "profile": "suggested",
-    "enabled": true,
-    "injectPolicy": true,
-    "preferAsyncForLongTasks": false,
-    "allowWorktreeSuggestion": true
-  },
-  "runtime": {
-    "mode": "auto",
-    "groupJoin": "smart",
-    "groupJoinAckTimeoutMs": 300000,
-    "completionMutationGuard": "warn",
-    "requirePlanApproval": false
-  },
-  "ui": {
-    "widgetPlacement": "aboveEditor",
-    "widgetMaxLines": 8,
-    "powerbar": true,
-    "dashboardPlacement": "center",
-    "dashboardWidth": 72,
-    "dashboardLiveRefreshMs": 1000,
-    "autoOpenDashboard": false,
-    "autoOpenDashboardForForegroundRuns": false,
-    "showModel": true,
-    "showTokens": true,
-    "showTools": true
-  }
-}
-```
-
-## Local Pi smoke test
-
-```bash
-cd pi-crew
-npm run smoke:pi
-```
-
-Then open Pi and run:
-
-```text
-/team-doctor
-/team-validate
-/team-autonomy status
-```
-
-## Default run: real worker execution
-
-By default, `pi-crew` launches each task as a separate child Pi worker process. The parent Pi session orchestrates; workers execute independently and stream output to durable run state.
-
-```json
-{
-  "action": "run",
-  "team": "default",
-  "goal": "Implement login with tests"
-}
-```
-
-## Scaffold / dry run
-
-Use scaffold mode only when you want durable prompts/artifacts without launching child workers.
-
-```json
-{
-  "action": "run",
-  "team": "default",
-  "goal": "Plan only",
-  "config": {
-    "runtime": { "mode": "scaffold" }
-  }
-}
-```
-
-## Async run
-
-```json
-{
-  "action": "run",
-  "team": "implementation",
-  "goal": "Refactor auth module",
-  "async": true
-}
-```
-
-Check status:
-
-```json
-{
-  "action": "status",
-  "runId": "team_..."
-}
-```
-
-Background `Agent`/`crew_agent` subagents wake the parent Pi session when they complete, so the parent can call `get_subagent_result`/`crew_agent_result` and continue without waiting for another user prompt.
-
-## State and API safety
-
-State paths are validated before read/write operations. Run ids, imported bundles, artifact and transcript references, mailbox files, and agent control/log files must stay inside their expected `.crew` roots and symlink escapes are rejected. Read-only mailbox APIs return default state without creating mailbox files when no messages exist.
-
-Group-join result delivery uses the normal outbox mailbox and normal `/team-api ... ack-message`. `runtime.groupJoinAckTimeoutMs` only emits observability (`agent.group_join.ack_timeout`) and does not block run completion.
-
-`runtime.completionMutationGuard` defaults to `warn`. Use `off` to disable or `fail` to fail implementation-style workers that complete without observed mutation tool calls.
-
-## Worktree mode
-
-```json
-{
-  "action": "run",
-  "team": "implementation",
-  "goal": "Refactor API layer",
-  "workspaceMode": "worktree"
-}
-```
-
-The leader repository must be clean. Per-task worktrees are created under the project crew root (`.crew/` for new projects, `.pi/teams/` when the repo already has `.pi/`):
-
-```text
-<crewRoot>/worktrees/{runId}/{taskId}
-```
-
-Cleanup:
-
-```json
-{
-  "action": "cleanup",
-  "runId": "team_..."
-}
-```
-
-Dirty worktrees are preserved unless `force: true` is provided.
-
-## Slash commands
-
-```text
-/teams
-/team-run default "Implement login with tests"
-/team-run --team=implementation --workflow=implementation --async "Refactor auth"
-/team-cancel team_...
-/team-run --worktree default "Change API safely"
-/team-status team_...
-/team-summary team_...
-/team-resume team_...
-/team-events team_...
-/team-artifacts team_...
-/team-worktrees team_...
-/team-cleanup team_...
-/team-forget team_... --confirm
-/team-export team_...
-/team-import .crew/artifacts/team_.../export/run-export.json   # or .pi/teams/artifacts/... on legacy layout
-/team-imports
-/team-prune --keep=20 --confirm
-/team-manager
-/team-dashboard
-/team-api team_... read-mailbox direction=outbox
-/team-api team_... send-message direction=outbox taskId=task_... to=worker body="hello"
-/team-api team_... validate-mailbox repair=true
-/team-init
-/team-init --copy-builtins
-/team-config
-/team-config autonomous.profile=assisted autonomous.preferAsyncForLongTasks=true --project
-/team-config --unset=autonomous.preferAsyncForLongTasks --project
-/team-autonomy status
-/team-autonomy on
-/team-autonomy off
-/team-autonomy manual
-/team-autonomy suggested
-/team-autonomy assisted
-/team-autonomy aggressive
-/team-validate
-/team-help
-/team-doctor
-```
-
-## Management
-
-Create resources:
-
-```json
-{
-  "action": "create",
-  "resource": "team",
-  "config": {
-    "name": "Backend Team",
-    "description": "Backend work",
-    "scope": "project",
-    "defaultWorkflow": "default",
-    "roles": [{ "name": "executor", "agent": "executor" }]
-  }
-}
-```
-
-Rename an agent and update team references:
-
-```json
-{
-  "action": "update",
-  "resource": "agent",
-  "agent": "worker",
-  "scope": "project",
-  "updateReferences": true,
-  "config": { "name": "better-worker" }
-}
-```
-
-Delete requires confirmation:
-
-```json
-{
-  "action": "delete",
-  "resource": "team",
-  "team": "backend-team",
-  "scope": "project",
-  "confirm": true
-}
-```
+# pi-crew Usage
+
+## Config
+
+Optional config path:
+
+```text
+~/.pi/agent/extensions/pi-crew/config.json
+```
+
+Create a default config:
+
+```bash
+node ./pi-crew/install.mjs
+```
+
+Supported fields:
+
+```json
+{
+  "asyncByDefault": false,
+  "executeWorkers": true,
+  "notifierIntervalMs": 5000,
+  "requireCleanWorktreeLeader": true,
+  "autonomous": {
+    "profile": "suggested",
+    "enabled": true,
+    "injectPolicy": true,
+    "preferAsyncForLongTasks": false,
+    "allowWorktreeSuggestion": true
+  },
+  "runtime": {
+    "mode": "auto",
+    "groupJoin": "smart",
+    "groupJoinAckTimeoutMs": 300000,
+    "completionMutationGuard": "warn",
+    "requirePlanApproval": false
+  },
+  "ui": {
+    "widgetPlacement": "aboveEditor",
+    "widgetMaxLines": 8,
+    "powerbar": true,
+    "dashboardPlacement": "center",
+    "dashboardWidth": 72,
+    "dashboardLiveRefreshMs": 1000,
+    "autoOpenDashboard": false,
+    "autoOpenDashboardForForegroundRuns": false,
+    "showModel": true,
+    "showTokens": true,
+    "showTools": true
+  }
+}
+```
+
+## Local Pi smoke test
+
+```bash
+cd pi-crew
+npm run smoke:pi
+```
+
+Then open Pi and run:
+
+```text
+/team-doctor
+/team-validate
+/team-autonomy status
+```
+
+## Default run: real worker execution
+
+By default, `pi-crew` launches each task as a separate child Pi worker process. The parent Pi session orchestrates; workers execute independently and stream output to durable run state.
+
+```json
+{
+  "action": "run",
+  "team": "default",
+  "goal": "Implement login with tests"
+}
+```
+
+## Scaffold / dry run
+
+Use scaffold mode only when you want durable prompts/artifacts without launching child workers.
+
+```json
+{
+  "action": "run",
+  "team": "default",
+  "goal": "Plan only",
+  "config": {
+    "runtime": { "mode": "scaffold" }
+  }
+}
+```
+
+## Async run
+
+```json
+{
+  "action": "run",
+  "team": "implementation",
+  "goal": "Refactor auth module",
+  "async": true
+}
+```
+
+Check status:
+
+```json
+{
+  "action": "status",
+  "runId": "team_..."
+}
+```
+
+Background `Agent`/`crew_agent` subagents wake the parent Pi session when they complete, so the parent can call `get_subagent_result`/`crew_agent_result` and continue without waiting for another user prompt.
+
+## State and API safety
+
+State paths are validated before read/write operations. Run ids, imported bundles, artifact and transcript references, mailbox files, and agent control/log files must stay inside their expected `.crew` roots and symlink escapes are rejected. Read-only mailbox APIs return default state without creating mailbox files when no messages exist.
+
+Group-join result delivery uses the normal outbox mailbox and normal `/team-api ... ack-message`. `runtime.groupJoinAckTimeoutMs` only emits observability (`agent.group_join.ack_timeout`) and does not block run completion.
+
+`runtime.completionMutationGuard` defaults to `warn`. Use `off` to disable or `fail` to fail implementation-style workers that complete without observed mutation tool calls.
+
+## Worktree mode
+
+```json
+{
+  "action": "run",
+  "team": "implementation",
+  "goal": "Refactor API layer",
+  "workspaceMode": "worktree"
+}
+```
+
+The leader repository must be clean. Per-task worktrees are created under the project crew root (`.crew/` for new projects, `.pi/teams/` when the repo already has `.pi/`):
+
+```text
+<crewRoot>/worktrees/{runId}/{taskId}
+```
+
+Cleanup:
+
+```json
+{
+  "action": "cleanup",
+  "runId": "team_..."
+}
+```
+
+Dirty worktrees are preserved unless `force: true` is provided.
+
+## Slash commands
+
+```text
+/teams
+/team-run default "Implement login with tests"
+/team-run --team=implementation --workflow=implementation --async "Refactor auth"
+/team-cancel team_...
+/team-run --worktree default "Change API safely"
+/team-status team_...
+/team-summary team_...
+/team-resume team_...
+/team-events team_...
+/team-artifacts team_...
+/team-worktrees team_...
+/team-cleanup team_...
+/team-forget team_... --confirm
+/team-export team_...
+/team-import .crew/artifacts/team_.../export/run-export.json   # or .pi/teams/artifacts/... on legacy layout
+/team-imports
+/team-prune --keep=20 --confirm
+/team-manager
+/team-dashboard
+/team-api team_... read-mailbox direction=outbox
+/team-api team_... send-message direction=outbox taskId=task_... to=worker body="hello"
+/team-api team_... validate-mailbox repair=true
+/team-init
+/team-init --copy-builtins
+/team-config
+/team-config autonomous.profile=assisted autonomous.preferAsyncForLongTasks=true --project
+/team-config --unset=autonomous.preferAsyncForLongTasks --project
+/team-autonomy status
+/team-autonomy on
+/team-autonomy off
+/team-autonomy manual
+/team-autonomy suggested
+/team-autonomy assisted
+/team-autonomy aggressive
+/team-validate
+/team-help
+/team-doctor
+```
+
+## Management
+
+Create resources:
+
+```json
+{
+  "action": "create",
+  "resource": "team",
+  "config": {
+    "name": "Backend Team",
+    "description": "Backend work",
+    "scope": "project",
+    "defaultWorkflow": "default",
+    "roles": [{ "name": "executor", "agent": "executor" }]
+  }
+}
+```
+
+Rename an agent and update team references:
+
+```json
+{
+  "action": "update",
+  "resource": "agent",
+  "agent": "worker",
+  "scope": "project",
+  "updateReferences": true,
+  "config": { "name": "better-worker" }
+}
+```
+
+Delete requires confirmation:
+
+```json
+{
+  "action": "delete",
+  "resource": "team",
+  "team": "backend-team",
+  "scope": "project",
+  "confirm": true
+}
+```

package/index.ts

@@ -1,6 +1,7 @@
-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 { waitForRun } from "./src/runtime/run-tracker.ts";
+
+export default function (pi: ExtensionAPI): void {
+	registerPiTeams(pi);
+}