pi-crew 0.1.30 → 0.1.32

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

@@ -118,10 +118,10 @@ Check status:
 }
 ```
 
-The leader repository must be clean. Per-task worktrees are created under:
+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
-.pi/teams/worktrees/{runId}/{taskId}
+<crewRoot>/worktrees/{runId}/{taskId}
 ```
 
 Cleanup:
@@ -152,7 +152,7 @@ Dirty worktrees are preserved unless `force: true` is provided.
 /team-cleanup team_...
 /team-forget team_... --confirm
 /team-export team_...
-/team-import .pi/teams/artifacts/team_.../export/run-export.json
+/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

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.30",
+  "version": "0.1.32",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/schema.json

@@ -80,6 +80,38 @@
         "needsAttentionAfterMs": { "type": "integer", "minimum": 1 }
       }
     },
+    "worktree": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Worktree setup hooks and dependency-linking options.",
+      "properties": {
+        "setupHook": { "type": "string", "minLength": 1 },
+        "setupHookTimeoutMs": { "type": "integer", "minimum": 1 },
+        "linkNodeModules": { "type": "boolean" }
+      }
+    },
+    "agents": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Builtin agent override settings.",
+      "properties": {
+        "disableBuiltins": { "type": "boolean" },
+        "overrides": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "disabled": { "type": "boolean" },
+              "model": { "oneOf": [{ "type": "string", "minLength": 1 }, { "const": false }] },
+              "fallbackModels": { "oneOf": [{ "type": "array", "items": { "type": "string", "minLength": 1 } }, { "const": false }] },
+              "thinking": { "oneOf": [{ "type": "string", "minLength": 1 }, { "const": false }] },
+              "tools": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+            }
+          }
+        }
+      }
+    },
     "ui": {
       "type": "object",
       "additionalProperties": false,
@@ -95,7 +127,27 @@
         "autoOpenDashboardForForegroundRuns": { "type": "boolean", "default": true },
         "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." }
+        "showTools": { "type": "boolean", "description": "Show tool activity in dashboard agent rows." },
+        "mascotStyle": { "type": "string", "enum": ["cat", "armin"] },
+        "mascotEffect": { "type": "string", "enum": ["random", "none", "typewriter", "scanline", "rain", "fade", "crt", "glitch", "dissolve"] }
+      }
+    },
+    "tools": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Public tool registration and foreground result behavior.",
+      "properties": {
+        "enableClaudeStyleAliases": { "type": "boolean", "default": true },
+        "enableSteer": { "type": "boolean", "default": true },
+        "terminateOnForeground": { "type": "boolean", "default": false, "description": "Opt in to returning terminate:true from foreground Agent/crew_agent calls after the child result is available." }
+      }
+    },
+    "telemetry": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Pi-crew telemetry event controls.",
+      "properties": {
+        "enabled": { "type": "boolean", "default": true }
       }
     }
   }

package/skills/git-master/SKILL.md

@@ -1,19 +1,24 @@
-# 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.
+---
+name: git-master
+description: Commit and release hygiene for safe version-control work. Use when preparing commits, releases, version bumps, publishing, or validating package installation.
+---
+
+# 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

@@ -1,21 +1,26 @@
-# 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.
+---
+name: read-only-explorer
+description: Read-only exploration and audit workflow. Use for explorer, analyst, reviewer, and source-audit roles that must inspect code without modifying files.
+---
+
+# 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

@@ -1,16 +1,21 @@
-# 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.
+---
+name: safe-bash
+description: Safe shell-command workflow. Use whenever a task may execute shell commands, especially to prefer read-only commands and avoid destructive actions without confirmation.
+---
+
+# 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

@@ -1,23 +1,28 @@
-# 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.
+---
+name: task-packet
+description: Structured worker task-packet template. Use when creating or executing worker tasks that need clear objective, scope, constraints, outputs, acceptance criteria, and verification.
+---
+
+# 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

@@ -1,22 +1,27 @@
-# 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.
+---
+name: verify-evidence
+description: Final verification evidence checklist. Use before finalizing implementation, review, or audit work to report changed files, checks run, artifacts, risks, and rollback notes.
+---
+
+# 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/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");
+}