pi-crew 0.1.37 → 0.1.39

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/docs/source-runtime-refactor-map.md

@@ -1,83 +1,83 @@
-# pi-crew runtime refactor source map
-
-This document records the source projects used as the baseline for the pi-crew subagent/runtime refactor. The goal is to avoid ad-hoc fixes in critical process orchestration paths and instead align pi-crew with proven Pi extension patterns.
-
-## Source/pi-subagents
-
-Primary source for child-process worker execution.
-
-- `pi-spawn.ts`: robust Pi CLI resolution on Windows and package installs.
-- `async-execution.ts`: detached async runner with `windowsHide: true` to avoid blank console windows.
-- `subagent-runner.ts`: streaming child Pi process runner, output capture, result extraction.
-- `post-exit-stdio-guard.ts`: guards for child processes that exit before stdio fully closes.
-- `result-watcher.ts` and `async-job-tracker.ts`: durable async job/result observation patterns.
-- `model-fallback.ts`: model fallback policy independent of hardcoded provider assumptions.
-- `subagent-control.ts`, `run-status.ts`: status and control semantics.
-
-pi-crew alignment:
-
-- Background runner and child worker spawn options now explicitly set `windowsHide: true`.
-- Parallel research no longer gates all shard workers behind a single discover worker.
-- Further work should consolidate `child-pi.ts`, `async-runner.ts`, and `subagent-manager.ts` into a durable-first subagent runtime module.
-
-## Source/pi-subagents2
-
-Primary source for higher-level agent management and UI patterns.
-
-- `src/agent-manager.ts`: agent lifecycle registry boundaries.
-- `src/agent-runner.ts`: invocation/run abstraction separate from UI registration.
-- `src/model-resolver.ts`: cleaner model resolution responsibility.
-- `src/output-file.ts`: output file abstraction.
-- `src/ui/agent-widget.ts`, `src/ui/conversation-viewer.ts`: compact live status and transcript viewing.
-
-pi-crew alignment:
-
-- Keep `Agent`/`crew_agent` tools as thin adapters over a durable manager.
-- Avoid storing essential run mapping in memory only.
-- Keep UI active-only and file-backed.
-
-## Source/pi-mono
-
-Primary source for Pi extension API/lifecycle constraints.
-
-- `packages/coding-agent/src/core/extensions/types.ts`: extension context/tool contracts.
-- `packages/coding-agent/src/core/extensions/runner.ts`: extension execution boundaries.
-- `packages/coding-agent/src/core/model-registry.ts`: available model discovery.
-- `packages/coding-agent/src/modes/interactive/interactive-mode.ts`: session lifecycle/UI behavior.
-
-pi-crew alignment:
-
-- Treat session-bound foreground workers differently from explicit async background workers.
-- Do not assume hardcoded providers/models.
-- Use Pi-native UI calls without modal auto-open by default.
-
-## Source/pi-powerbar, pi-plan, pi-diff-review, pi-extensions*
-
-Sources for UI and small-extension patterns.
-
-- `pi-powerbar/src/powerbar/*`: low-noise status segment publishing.
-- `pi-plan/src/plan-action-ui.ts`: action-oriented UI without persistent heavy overlays.
-- `pi-diff-review/src/*`: command/tool registration and review UX patterns.
-- `pi-extensions2/files-widget/*`: file-backed UI composition and navigation.
-
-pi-crew alignment:
-
-- Keep persistent widget active-only.
-- Prefer manual dashboard/transcript commands for history.
-- Avoid expensive render scans and auto-opening focus-capturing overlays.
-
-## Current refactor checkpoints
-
-- [x] Hide Windows console windows for background runner and child Pi workers.
-- [x] Make parallel research shard workers start in parallel instead of depending on a single discover worker.
-- [x] Keep direct-agent reconstruction gated by `workflow === "direct-agent"` only.
-- [x] Persist subagent records and recover terminal results after restart.
-- [x] Fail fast for unrecoverable persisted records without `runId` instead of hanging.
-- [x] Persist direct-agent model override into task state for background/resume reconstruction.
-
-## Remaining larger subsystem work
-
-- Consolidate subagent runtime into `src/subagents/*` or equivalent durable-first module.
-- Move model routing transparency into persisted task/subagent records: requested model, selected model, fallback chain, fallback reason.
-- Add real integration smoke scripts for Windows process visibility, async restart recovery, and multi-shard fanout.
-- Add adaptive planner repair/retry for invalid JSON instead of immediate block when safe.
+# pi-crew runtime refactor source map
+
+This document records the source projects used as the baseline for the pi-crew subagent/runtime refactor. The goal is to avoid ad-hoc fixes in critical process orchestration paths and instead align pi-crew with proven Pi extension patterns.
+
+## Source/pi-subagents
+
+Primary source for child-process worker execution.
+
+- `pi-spawn.ts`: robust Pi CLI resolution on Windows and package installs.
+- `async-execution.ts`: detached async runner with `windowsHide: true` to avoid blank console windows.
+- `subagent-runner.ts`: streaming child Pi process runner, output capture, result extraction.
+- `post-exit-stdio-guard.ts`: guards for child processes that exit before stdio fully closes.
+- `result-watcher.ts` and `async-job-tracker.ts`: durable async job/result observation patterns.
+- `model-fallback.ts`: model fallback policy independent of hardcoded provider assumptions.
+- `subagent-control.ts`, `run-status.ts`: status and control semantics.
+
+pi-crew alignment:
+
+- Background runner and child worker spawn options now explicitly set `windowsHide: true`.
+- Parallel research no longer gates all shard workers behind a single discover worker.
+- Further work should consolidate `child-pi.ts`, `async-runner.ts`, and `subagent-manager.ts` into a durable-first subagent runtime module.
+
+## Source/pi-subagents2
+
+Primary source for higher-level agent management and UI patterns.
+
+- `src/agent-manager.ts`: agent lifecycle registry boundaries.
+- `src/agent-runner.ts`: invocation/run abstraction separate from UI registration.
+- `src/model-resolver.ts`: cleaner model resolution responsibility.
+- `src/output-file.ts`: output file abstraction.
+- `src/ui/agent-widget.ts`, `src/ui/conversation-viewer.ts`: compact live status and transcript viewing.
+
+pi-crew alignment:
+
+- Keep `Agent`/`crew_agent` tools as thin adapters over a durable manager.
+- Avoid storing essential run mapping in memory only.
+- Keep UI active-only and file-backed.
+
+## Source/pi-mono
+
+Primary source for Pi extension API/lifecycle constraints.
+
+- `packages/coding-agent/src/core/extensions/types.ts`: extension context/tool contracts.
+- `packages/coding-agent/src/core/extensions/runner.ts`: extension execution boundaries.
+- `packages/coding-agent/src/core/model-registry.ts`: available model discovery.
+- `packages/coding-agent/src/modes/interactive/interactive-mode.ts`: session lifecycle/UI behavior.
+
+pi-crew alignment:
+
+- Treat session-bound foreground workers differently from explicit async background workers.
+- Do not assume hardcoded providers/models.
+- Use Pi-native UI calls without modal auto-open by default.
+
+## Source/pi-powerbar, pi-plan, pi-diff-review, pi-extensions*
+
+Sources for UI and small-extension patterns.
+
+- `pi-powerbar/src/powerbar/*`: low-noise status segment publishing.
+- `pi-plan/src/plan-action-ui.ts`: action-oriented UI without persistent heavy overlays.
+- `pi-diff-review/src/*`: command/tool registration and review UX patterns.
+- `pi-extensions2/files-widget/*`: file-backed UI composition and navigation.
+
+pi-crew alignment:
+
+- Keep persistent widget active-only.
+- Prefer manual dashboard/transcript commands for history.
+- Avoid expensive render scans and auto-opening focus-capturing overlays.
+
+## Current refactor checkpoints
+
+- [x] Hide Windows console windows for background runner and child Pi workers.
+- [x] Make parallel research shard workers start in parallel instead of depending on a single discover worker.
+- [x] Keep direct-agent reconstruction gated by `workflow === "direct-agent"` only.
+- [x] Persist subagent records and recover terminal results after restart.
+- [x] Fail fast for unrecoverable persisted records without `runId` instead of hanging.
+- [x] Persist direct-agent model override into task state for background/resume reconstruction.
+
+## Remaining larger subsystem work
+
+- Consolidate subagent runtime into `src/subagents/*` or equivalent durable-first module.
+- Move model routing transparency into persisted task/subagent records: requested model, selected model, fallback chain, fallback reason.
+- Add real integration smoke scripts for Windows process visibility, async restart recovery, and multi-shard fanout.
+- Add adaptive planner repair/retry for invalid JSON instead of immediate block when safe.

package/docs/usage.md

@@ -107,6 +107,12 @@ Check status:
 }
 ```
 
+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.
+
 ## Worktree mode
 
 ```json

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);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -47,8 +47,8 @@
     "ci": "npm run typecheck && npm test && npm pack --dry-run",
     "typecheck": "tsc --noEmit && node --experimental-strip-types -e \"await import('./index.ts'); console.log('strip-types import ok')\"",
     "test": "npm run test:unit && npm run test:integration",
-    "test:unit": "node --experimental-strip-types --test --test-timeout=30000 test/unit/*.test.ts",
-    "test:integration": "node --experimental-strip-types --test --test-timeout=120000 test/integration/*.test.ts",
+    "test:unit": "node --experimental-strip-types --test --test-concurrency=1 --test-timeout=30000 test/unit/*.test.ts",
+    "test:integration": "node --experimental-strip-types --test --test-concurrency=1 --test-timeout=120000 test/integration/*.test.ts",
     "smoke:pi": "pi install ."
   },
   "exports": {

package/schema.json

@@ -11,7 +11,7 @@
     },
     "executeWorkers": {
       "type": "boolean",
-      "description": "Allow real child Pi workers without setting PI_TEAMS_EXECUTE_WORKERS=1."
+      "description": "Allow real child Pi workers. Defaults to true; set false or use PI_CREW_EXECUTE_WORKERS=0/PI_TEAMS_EXECUTE_WORKERS=0 to force scaffold mode."
     },
     "notifierIntervalMs": {
       "type": "number",
@@ -128,7 +128,7 @@
         "showModel": { "type": "boolean", "default": true, "description": "Show worker model attempts in dashboard agent rows." },
         "showTokens": { "type": "boolean", "description": "Show token usage in dashboard agent rows." },
         "showTools": { "type": "boolean", "description": "Show tool activity in dashboard agent rows." },
-        "transcriptTailBytes": { "type": "integer", "minimum": 1024, "default": 262144, "description": "Maximum transcript bytes to parse by default; use viewer hotkey f to load full content." },
+        "transcriptTailBytes": { "type": "integer", "minimum": 1024, "maximum": 52428800, "default": 262144, "description": "Maximum transcript bytes to parse by default; use viewer hotkey f to load full content." },
         "mascotStyle": { "type": "string", "enum": ["cat", "armin"] },
         "mascotEffect": { "type": "string", "enum": ["random", "none", "typewriter", "scanline", "rain", "fade", "crt", "glitch", "dissolve"] }
       }

package/src/agents/agent-serializer.ts

@@ -1,34 +1,34 @@
-import type { AgentConfig } from "./agent-config.ts";
-
-function line(key: string, value: string | boolean | string[] | undefined): string | undefined {
-	if (value === undefined) return undefined;
-	if (Array.isArray(value)) return `${key}: ${value.join(", ")}`;
-	return `${key}: ${String(value)}`;
-}
-
-export function serializeAgent(agent: AgentConfig): string {
-	const lines = [
-		"---",
-		`name: ${agent.name}`,
-		`description: ${agent.description}`,
-		line("model", agent.model),
-		line("fallbackModels", agent.fallbackModels),
-		line("thinking", agent.thinking),
-		line("tools", agent.tools),
-		agent.extensions !== undefined ? line("extensions", agent.extensions) ?? "extensions:" : undefined,
-		line("skills", agent.skills),
-		line("systemPromptMode", agent.systemPromptMode),
-		line("inheritProjectContext", agent.inheritProjectContext),
-		line("inheritSkills", agent.inheritSkills),
-		line("triggers", agent.routing?.triggers),
-		line("useWhen", agent.routing?.useWhen),
-		line("avoidWhen", agent.routing?.avoidWhen),
-		line("cost", agent.routing?.cost),
-		line("category", agent.routing?.category),
-		"---",
-		"",
-		agent.systemPrompt.trim(),
-		"",
-	].filter((entry): entry is string => entry !== undefined);
-	return lines.join("\n");
-}
+import type { AgentConfig } from "./agent-config.ts";
+
+function line(key: string, value: string | boolean | string[] | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	if (Array.isArray(value)) return `${key}: ${value.join(", ")}`;
+	return `${key}: ${String(value)}`;
+}
+
+export function serializeAgent(agent: AgentConfig): string {
+	const lines = [
+		"---",
+		`name: ${agent.name}`,
+		`description: ${agent.description}`,
+		line("model", agent.model),
+		line("fallbackModels", agent.fallbackModels),
+		line("thinking", agent.thinking),
+		line("tools", agent.tools),
+		agent.extensions !== undefined ? line("extensions", agent.extensions) ?? "extensions:" : undefined,
+		line("skills", agent.skills),
+		line("systemPromptMode", agent.systemPromptMode),
+		line("inheritProjectContext", agent.inheritProjectContext),
+		line("inheritSkills", agent.inheritSkills),
+		line("triggers", agent.routing?.triggers),
+		line("useWhen", agent.routing?.useWhen),
+		line("avoidWhen", agent.routing?.avoidWhen),
+		line("cost", agent.routing?.cost),
+		line("category", agent.routing?.category),
+		"---",
+		"",
+		agent.systemPrompt.trim(),
+		"",
+	].filter((entry): entry is string => entry !== undefined);
+	return lines.join("\n");
+}

package/src/config/config.ts

@@ -319,8 +319,12 @@ function parseWithSchema<T extends TSchema>(schema: T, value: unknown): Static<T
 	return Value.Decode(schema, value);
 }
 
+function parseIntegerInRange(value: unknown, minimum = 1, maximum = Number.MAX_SAFE_INTEGER): number | undefined {
+	return parseWithSchema(Type.Integer({ minimum, maximum }), value);
+}
+
 function parsePositiveInteger(value: unknown, max = Number.MAX_SAFE_INTEGER): number | undefined {
-	return parseWithSchema(Type.Integer({ minimum: 1, maximum: max }), value);
+	return parseIntegerInRange(value, 1, max);
 }
 
 function parseProfile(value: unknown): PiTeamsAutonomyProfile | undefined {
@@ -462,14 +466,14 @@ function parseUiConfig(value: unknown): CrewUiConfig | undefined {
 		widgetMaxLines: parsePositiveInteger(obj.widgetMaxLines, 50),
 		powerbar: parseWithSchema(Type.Boolean(), obj.powerbar),
 		dashboardPlacement: rawDashboardPlacement,
-		dashboardWidth: parsePositiveInteger(obj.dashboardWidth, 120),
-		dashboardLiveRefreshMs: parsePositiveInteger(obj.dashboardLiveRefreshMs, 60_000),
+		dashboardWidth: parseIntegerInRange(obj.dashboardWidth, 32, 120),
+		dashboardLiveRefreshMs: parseIntegerInRange(obj.dashboardLiveRefreshMs, 250, 60_000),
 		autoOpenDashboard: parseWithSchema(Type.Boolean(), obj.autoOpenDashboard),
 		autoOpenDashboardForForegroundRuns: parseWithSchema(Type.Boolean(), obj.autoOpenDashboardForForegroundRuns),
 		showModel: parseWithSchema(Type.Boolean(), obj.showModel),
 		showTokens: parseWithSchema(Type.Boolean(), obj.showTokens),
 		showTools: parseWithSchema(Type.Boolean(), obj.showTools),
-		transcriptTailBytes: parsePositiveInteger(obj.transcriptTailBytes, 50 * 1024 * 1024),
+		transcriptTailBytes: parseIntegerInRange(obj.transcriptTailBytes, 1024, 50 * 1024 * 1024),
 		mascotStyle: parseWithSchema(Type.Union([Type.Literal("cat"), Type.Literal("armin")]), obj.mascotStyle),
 		mascotEffect: parseWithSchema(Type.Union([Type.Literal("random"), Type.Literal("none"), Type.Literal("typewriter"), Type.Literal("scanline"), Type.Literal("rain"), Type.Literal("fade"), Type.Literal("crt"), Type.Literal("glitch"), Type.Literal("dissolve")]), obj.mascotEffect),
 	};