pi-crew 0.1.28 → 0.1.30

package/docs/runtime-flow.md

@@ -0,0 +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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/schema.json

@@ -47,6 +47,7 @@
       "description": "Runtime safety limits for crew workers and policy decisions.",
       "properties": {
         "maxConcurrentWorkers": { "type": "integer", "minimum": 1 },
+        "allowUnboundedConcurrency": { "type": "boolean" },
         "maxTaskDepth": { "type": "integer", "minimum": 1 },
         "maxChildrenPerTask": { "type": "integer", "minimum": 1 },
         "maxRunMinutes": { "type": "integer", "minimum": 1 },

package/skills/git-master/SKILL.md

@@ -0,0 +1,19 @@
+# git-master
+
+Use this skill for commit/release hygiene.
+
+## Commit rules
+
+- Check `git status --short` before staging.
+- Stage only files related to the current task.
+- Keep commits independently revertible.
+- Use concise imperative commit messages.
+- Do not push or publish unless explicitly requested.
+- Do not include secrets, OTPs, local temp files, or generated tarballs.
+
+## Release rules
+
+- Run the required verification gate before version bumps.
+- Bump version only after tests pass and user confirms publish intent.
+- Verify registry after publish with `npm view`.
+- Install through `pi install npm:pi-crew` when validating Pi package loading.

package/skills/read-only-explorer/SKILL.md

@@ -0,0 +1,21 @@
+# read-only-explorer
+
+Use this skill for explorer, analyst, reviewer, and source-audit roles.
+
+## Contract
+
+- Do not edit files.
+- Do not write generated artifacts outside the run artifact directory.
+- Prefer `read`, `rg`, `find`, `git status`, and package metadata inspection.
+- Record exact files inspected.
+- Distinguish direct evidence from inference.
+- If implementation is needed, recommend it instead of modifying code.
+
+## Output shape
+
+Return:
+
+1. files inspected;
+2. findings with path references;
+3. risks/unknowns;
+4. recommended next tests or implementation tasks.

package/skills/safe-bash/SKILL.md

@@ -0,0 +1,16 @@
+# safe-bash
+
+Use this skill whenever a task may execute shell commands.
+
+## Rules
+
+- Prefer read-only commands first: `pwd`, `ls`, `find`, `rg`, `git status`, package-manager dry runs.
+- Before mutating commands, explain the target path and expected effect.
+- Never run destructive cleanup (`rm -rf`, `git clean`, force delete, prune, reset hard) without explicit confirmation.
+- Avoid shell-specific assumptions when a cross-platform Node/Pi API exists.
+- On Windows, prefer argv-based process execution and avoid `cmd /c start` or `/bin/bash` unless explicitly required.
+- Capture verification output and summarize exit status.
+
+## Reporting
+
+Mention commands run and whether they were read-only or mutating.

package/skills/task-packet/SKILL.md

@@ -0,0 +1,23 @@
+# task-packet
+
+Use this skill when creating or executing a worker task.
+
+## Required sections
+
+Each task should clarify:
+
+- objective;
+- scope and paths;
+- constraints and permissions;
+- dependencies and expected inputs;
+- expected outputs/artifacts;
+- acceptance criteria;
+- verification commands;
+- escalation conditions.
+
+## Worker behavior
+
+- Read dependency outputs before starting dependent work.
+- Keep outputs concise and artifact-oriented.
+- Do not claim completion until required artifacts and status are durable.
+- If blocked, report the blocker and the smallest recoverable next action.

package/skills/verify-evidence/SKILL.md

@@ -0,0 +1,22 @@
+# verify-evidence
+
+Use this skill before finalizing implementation, review, or audit work.
+
+## Required final evidence
+
+Include:
+
+- changed files, or `none` for read-only work;
+- tests/checks run with pass/fail result;
+- relevant artifacts, run IDs, or log paths;
+- unresolved risks and rollback notes when code changed.
+
+## Verification ladder
+
+Prefer the smallest reliable check first, then escalate:
+
+1. Targeted unit tests for touched behavior.
+2. Typecheck for TypeScript changes.
+3. Integration tests for runtime/spawn/state changes.
+4. `npm pack --dry-run` for package/release/doc changes.
+5. Real Pi smoke only when needed and safe.

package/src/config/config.ts

@@ -18,6 +18,7 @@ export interface PiTeamsAutonomousConfig {
 
 export interface CrewLimitsConfig {
 	maxConcurrentWorkers?: number;
+	allowUnboundedConcurrency?: boolean;
 	maxTaskDepth?: number;
 	maxChildrenPerTask?: number;
 	maxRunMinutes?: number;
@@ -292,6 +293,7 @@ function parseLimitsConfig(value: unknown): CrewLimitsConfig | undefined {
 	if (!obj) return undefined;
 	const limits: CrewLimitsConfig = {
 		maxConcurrentWorkers: parsePositiveInteger(obj.maxConcurrentWorkers, LIMIT_CEILINGS.maxConcurrentWorkers),
+		allowUnboundedConcurrency: parseWithSchema(Type.Boolean(), obj.allowUnboundedConcurrency),
 		maxTaskDepth: parsePositiveInteger(obj.maxTaskDepth, LIMIT_CEILINGS.maxTaskDepth),
 		maxChildrenPerTask: parsePositiveInteger(obj.maxChildrenPerTask, LIMIT_CEILINGS.maxChildrenPerTask),
 		maxRunMinutes: parsePositiveInteger(obj.maxRunMinutes, LIMIT_CEILINGS.maxRunMinutes),

package/src/config/defaults.ts

@@ -17,6 +17,7 @@ export const DEFAULT_LOCKS = {
 };
 
 export const DEFAULT_CONCURRENCY = {
+	hardCap: 8,
 	workflow: {
 		parallelResearch: 4,
 		research: 2,

package/src/extension/async-notifier.ts

@@ -1,4 +1,8 @@
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { appendEvent, readEvents, type TeamEvent } from "../state/event-log.ts";
+import { checkProcessLiveness, isActiveRunStatus } from "../runtime/process-status.ts";
+import { updateRunStatus } from "../state/state-store.ts";
+import type { TeamRunManifest } from "../state/types.ts";
 import { listRuns } from "./run-index.ts";
 
 export interface AsyncNotifierState {
@@ -10,6 +14,30 @@ function isFinished(status: string): boolean {
 	return status === "completed" || status === "failed" || status === "cancelled" || status === "blocked";
 }
 
+function isAsyncTerminalEvent(event: TeamEvent): boolean {
+	return event.type === "async.completed" || event.type === "async.failed" || event.type === "async.died";
+}
+
+function latestEventAgeMs(events: TeamEvent[], now = Date.now()): number {
+	const latest = events.at(-1);
+	if (!latest) return Number.POSITIVE_INFINITY;
+	const time = new Date(latest.time).getTime();
+	return Number.isFinite(time) ? now - time : Number.POSITIVE_INFINITY;
+}
+
+export function markDeadAsyncRunIfNeeded(run: TeamRunManifest, now = Date.now(), quietMs = 30_000): TeamRunManifest | undefined {
+	if (!run.async || !isActiveRunStatus(run.status)) return undefined;
+	const liveness = checkProcessLiveness(run.async.pid);
+	if (liveness.alive) return undefined;
+	const events = readEvents(run.eventsPath);
+	if (events.some(isAsyncTerminalEvent)) return undefined;
+	if (latestEventAgeMs(events, now) < quietMs) return undefined;
+	const message = `Background runner died unexpectedly; check background.log (${liveness.detail}).`;
+	const failed = updateRunStatus(run, "failed", message);
+	appendEvent(failed.eventsPath, { type: "async.died", runId: failed.runId, message, data: { pid: run.async.pid, detail: liveness.detail } });
+	return failed;
+}
+
 export function startAsyncRunNotifier(ctx: ExtensionContext, state: AsyncNotifierState, intervalMs = 5000): void {
 	if (state.interval) clearInterval(state.interval);
 	for (const run of listRuns(ctx.cwd)) {
@@ -20,10 +48,11 @@ export function startAsyncRunNotifier(ctx: ExtensionContext, state: AsyncNotifie
 	state.interval = setInterval(() => {
 		try {
 			for (const run of listRuns(ctx.cwd).slice(0, 20)) {
-				if (!isFinished(run.status) || state.seenFinishedRunIds.has(run.runId)) continue;
-				state.seenFinishedRunIds.add(run.runId);
-				const level = run.status === "completed" ? "info" : run.status === "cancelled" ? "warning" : "error";
-				ctx.ui.notify(`pi-crew run ${run.status}: ${run.runId} (${run.team}/${run.workflow ?? "none"})`, level);
+				const current = markDeadAsyncRunIfNeeded(run) ?? run;
+				if (!isFinished(current.status) || state.seenFinishedRunIds.has(current.runId)) continue;
+				state.seenFinishedRunIds.add(current.runId);
+				const level = current.status === "completed" ? "info" : current.status === "cancelled" ? "warning" : "error";
+				ctx.ui.notify(`pi-crew run ${current.status}: ${current.runId} (${current.team}/${current.workflow ?? "none"})`, level);
 			}
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);