pi-crew 0.3.8 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.4.0] — 9arm-skills Enforcement Patterns & Integration Tests (2026-05-26)
+
+### Features
+- **systematic-debugging: Refuse Gate** — Hard constraints before proposing fixes. Must verify repro exists, root cause known, and hypothesis falsified before any fix.
+- **systematic-debugging: Recite Ritual** — Psychological anchor at session start. Recite 4-step mantra before beginning any debug session.
+- **systematic-debugging: Falsify-First** — Phase 3 now requires disproof before proof. Run disproof experiments first to save time on wrong hypotheses.
+- **systematic-debugging: Breadcrumb Ledger** — Structured experiment tracking within debug sessions.
+- **multi-perspective-review: Simpler Alternative Pass** — Mandatory pre-review step to question if the change should exist at all.
+- **New skill: scrutinize** — Outsider-perspective review questioning intent before tracing code.
+- **New skill: post-mortem** — Engineering RCA documentation with 4 required inputs gate.
+- **skills/REFERENCE.md** — New documentation of skill chains, inventory, and anti-patterns.
+- **Trigger conditions** added to all major skill descriptions for better skill invocation matching.
+
+### Bug Fixes
+- **CI reliability** — Fixed flaky tests on macOS: crew-widget and render-scheduler timing issues resolved.
+- **Team-context import detection** — Fixed regex to correctly match only direct `/team-tool.ts` imports, not `/team-tool/context.ts`.
+
+### Tests
+- **New test-integration-check.ts** — Integration tests for core pi-crew functionality (agent/team/workflow discovery, fast-fix team run).
+- **1740 tests passing** across all platforms (Ubuntu, macOS, Windows).
+
+---
+
 ## [0.3.8] — Zombie Run Auto-Repair & Test Stability (2026-05-25)
 
 ### Features

package/package.json

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

package/skills/REFERENCE.md

@@ -0,0 +1,136 @@
+# pi-crew Skills Reference
+
+## Skill Chains
+
+### Bug Investigation
+
+```
+systematic-debugging (4 phases with refuse gate)
+    ↓
+verification-before-done (evidence before claim)
+    ↓
+post-mortem (RCA documentation)
+```
+
+### Multi-phase Work
+
+```
+orchestration (phase coordination)
+    ↓
+delegation-patterns (task splitting)
+    ↓
+verification-before-done (after each phase)
+```
+
+### Code Review (Quick)
+
+```
+scrutinize (outsider perspective + simpler alternative)
+```
+
+### Code Review (Deep)
+
+```
+scrutinize (outsider perspective)
+    ↓
+multi-perspective-review (8-pass deep review)
+    ↓
+secure-agent-orchestration-review (security focus)
+```
+
+---
+
+## When to Invoke
+
+| Situation | Skill |
+|-----------|-------|
+| Bug / test failure / crash | `systematic-debugging` |
+| Before claiming done | `verification-before-done` |
+| Code review (quick) | `scrutinize` |
+| Code review (deep) | `multi-perspective-review` |
+| Task delegation | `delegation-patterns` |
+| Complex multi-phase work | `orchestration` |
+| After bug is fixed | `post-mortem` |
+| Security review | `secure-agent-orchestration-review` |
+| Workspace safety | `workspace-isolation` |
+| Bash safety | `safe-bash` |
+
+---
+
+## Skills Inventory
+
+### Core Discipline
+
+| Skill | Description |
+|-------|-------------|
+| `systematic-debugging` | Four-phase debugging with refuse gates, falsify-first discipline |
+| `verification-before-done` | Evidence before claims |
+| `orchestration` | Multi-phase coordination, 8 rules including "respawn not absorb" |
+
+### Review
+
+| Skill | Description |
+|-------|-------------|
+| `scrutinize` | Outsider-perspective review questioning intent |
+| `multi-perspective-review` | 8-pass deep code review |
+| `secure-agent-orchestration-review` | Security-focused review |
+
+### Documentation
+
+| Skill | Description |
+|-------|-------------|
+| `post-mortem` | Engineering RCA record |
+
+### Delegation
+
+| Skill | Description |
+|-------|-------------|
+| `delegation-patterns` | Task splitting patterns |
+| `requirements-to-task-packet` | Task packet creation |
+
+### Runtime/Safety
+
+| Skill | Description |
+|-------|-------------|
+| `workspace-isolation` | Security boundary enforcement |
+| `worktree-isolation` | Git worktree safety |
+| `safe-bash` | Bash command safety |
+| `state-mutation-locking` | State mutation protection |
+
+### Observability
+
+| Skill | Description |
+|-------|-------------|
+| `event-log-tracing` | JSONL event log analysis |
+| `runtime-state-reader` | Runtime state inspection |
+| `observability-reliability` | Reliability patterns |
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Skill | Rule |
+|--------------|-------|------|
+| Proposing fix before reproducing | `systematic-debugging` | Refuse Gate |
+| Running proof before disproof | `systematic-debugging` | Phase 3 |
+| Claiming "tests pass" without fresh run | `verification-before-done` | Gate Function |
+| Reviewing diff-local without tracing path | `scrutinize` | Trace step |
+| Skipping simpler-alternative pass | `multi-perspective-review` | Pre-review |
+| Editing files yourself as orchestrator | `orchestration` | Rule 1 |
+| Dispatching serially when parallel possible | `orchestration` | Rule 3 |
+| Committing a red tree | `orchestration` | Rule 6 |
+| Absorbing subagent's broken work | `orchestration` | Rule 7 |
+| Rubber-stamp review | `multi-perspective-review` | Rules |
+
+---
+
+## Key Enforcement Patterns (from 9arm)
+
+| Pattern | Implemented In |
+|---------|---------------|
+| **Refuse Gate** | `systematic-debugging` |
+| **Recite Ritual** | `systematic-debugging` (Invocation) |
+| **Falsify Before Proof** | `systematic-debugging` (Phase 3) |
+| **Simpler Alternative Pass** | `scrutinize`, `multi-perspective-review` |
+| **Required Inputs Gate** | `post-mortem` |
+| **Respawn Not Absorb** | `orchestration` (Rule 7) |

package/skills/delegation-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: delegation-patterns
-description: Subagent/team delegation workflow. Use when splitting work across pi-crew teams, direct agents, async background workers, chains, or parallel research/review tasks.
+description: "Subagent/team delegation workflow. Use when splitting work across pi-crew teams, direct agents, async background workers, chains, or parallel tasks. Triggers: delegate this, split this task, parallelize, dispatch workers, assign to team, spawn agents."
 ---
 
 # delegation-patterns

package/skills/event-log-tracing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-log-tracing
-description: Structured event logging system for worker lifecycle, live agents, and crash recovery. Use when debugging worker crashes, tracing agent lifecycle, or investigating stale runs.
+description: "Structured event logging for worker lifecycle, live agents, crash recovery. Use when debugging crashes, tracing agent lifecycle, investigating stale runs. Triggers: event log, trace events, worker crashed, agent died, stale run, events.jsonl."
 ---
 
 # event-log-tracing

package/skills/multi-perspective-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: multi-perspective-review
-description: Use when reviewing a plan, diff, implementation, worker output, release candidate, or external review feedback.
+description: "Multi-perspective code review with simpler-alternative pass. Use when reviewing a plan, diff, implementation, worker output, release candidate, or external feedback. Triggers: review this, look at this, LGTM check, sanity check, audit this, get a second opinion, check this PR, examine this code."
 ---
 
 # multi-perspective-review
@@ -9,6 +9,22 @@ Core principle: review early, review often, and separate concerns. Reviewer outp
 
 Distilled from detailed reads of requesting-code-review, receiving-code-review, subagent review checkpoints, differential review, and specialized review-agent patterns.
 
+## Pre-review: Simpler Alternative Pass (Mandatory)
+
+Before running any review passes, ask:
+
+1. **Is there a simpler, smaller, or more elegant way to achieve the same goal?**
+   - Doing nothing (is the problem real and load-bearing?)
+   - Using something that already exists in the codebase
+   - A smaller change that solves 90% of the goal with 10% of the risk
+   - Solving it at a different layer (config vs code, framework vs app)
+2. If a better alternative exists, surface it BEFORE the line-by-line review.
+3. Skip only if the user explicitly says "don't question scope."
+
+This is the most valuable finding you can produce — surfacing unnecessary complexity before reviewing its details.
+
+---
+
 ## Review Passes
 
 Run relevant passes separately:

package/skills/orchestration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orchestration
-description: Multi-phase orchestration skill for pi-crew planners and executors. Use when decomposing complex tasks into parallel phases, dispatching workers, verifying gates, and iterating until closure.
+description: "Multi-phase orchestration for planners and executors. Use when decomposing complex tasks into parallel phases, dispatching workers, verifying gates, and iterating to closure. Triggers: orchestrate this, coordinate these tasks, run this multi-phase, dispatch workers, coordinate team."
 ---
 
 # orchestration

package/skills/post-mortem/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: post-mortem
+description: "Write engineering RCA record after bug is fixed. Use when asking: write post-mortem, RCA, root cause analysis, document this fix, close out this bug. Triggers: post-mortem, postmortem, root cause, RCA, document this fix, write up the cause, close out bug."
+---
+
+# post-mortem
+
+The canonical engineering record of a bug fix. Written after debugging lands a real fix.
+
+## Required Inputs — Refuse to Draft Without These
+
+- [ ] **Reliable repro exists** (deterministic or high-rate flake)
+- [ ] **Root cause is known** (mechanism identified, not a hypothesis)
+- [ ] **Fix is identified** (PR / commit / branch)
+- [ ] **Fix is validated** (original repro now passes)
+
+If any missing → list what's missing and stop. Do not draft.
+
+## Structure
+
+### 1. Summary
+
+What broke (user terms), what fixed it (one sentence). JIRA key, PR, owner. A reader who stops here should have the right answer.
+
+### 2. Symptom
+
+Concrete: test output, error message, log line. No paraphrase. What was actually observed.
+
+### 3. Root Cause
+
+The actual bug mechanism. Code identifiers welcome — function names, file paths, branch conditions. Walk the cause chain end-to-end.
+
+### 4. Why It Produced the Symptom
+
+Walk the chain so reader connects symptom to cause. Often non-obvious — bug is in X but visible failure is in Y.
+
+### 5. Fix
+
+What changed and why this addresses root cause. Link to PR/commit. If a previous fix attempt papered over the symptom, name it and explain what was wrong.
+
+### 6. How It Was Found
+
+Short. The debugging path:
+
+- What repro made it deterministic
+- What tools cracked it
+- Hypotheses tried and rejected (with one-line reason each)
+- The single experiment that confirmed the cause
+
+### 7. Why It Slipped Through
+
+CI gap? Latent code? Workload gap? Incomplete prior fix? Review miss? Be specific.
+
+If honest answer is "no good reason" — say so. **Blameless** — describe the gap, not the person.
+
+### 8. Validation
+
+How we know the fix works:
+
+- Original failing test now passes (test name)
+- Customer workload now completes (workload identifier)
+- Other affected configs/workloads also tested
+
+If only one config validated, say so explicitly.
+
+### 9. Action Items
+
+What + owner + tracking artifact:
+
+- Regression test added at <seam>. (Owner, test name)
+- CI gap closed: <new check>. (Owner, ticket)
+- Doc/runbook updated. (Owner, link)
+
+If none needed: "None — fix is sufficient and no class-of-bug follow-up warranted."
+
+## Tone
+
+This is engineer-to-engineer:
+
+- **Code identifiers are first-class.** Keep them — future engineers grep their way back.
+- **Mechanism over narrative.** Walk the cause chain, don't soften.
+- **Blameless.** Describe gaps and bugs, never people.
+- **No hedging.** State it or don't write it.
+
+## Rules
+
+- Never invent facts.
+- Never strip code identifiers (they are the index).
+- State validation coverage honestly.
+- Get sign-off before posting to JIRA.

package/skills/safe-bash/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: "Safe shell-command workflow. Use when executing shell commands, prefer read-only, avoid destructive actions. Triggers: run this command, execute bash, safe bash, avoid rm, destructive command, shell injection."
 ---
 
 # safe-bash

package/skills/scrutinize/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: scrutinize
+description: "Outsider-perspective review questioning intent before tracing code. Use when asking: should this even exist?, is there a simpler way?, get a second opinion, before deep code review. Triggers: scrutinize this, question this, is there a better way?, simplify this, overkill?, too complex."
+---
+
+# Scrutinize
+
+Stand outside the change and ask whether it should exist at all, then verify it actually does what it claims end-to-end.
+
+## Operating Stance
+
+- **Outsider.** Forget who wrote it and why they think it's right. Read the artifact cold.
+- **End-to-end, not diff-local.** The diff is the entry point, not the scope.
+- **Actionable, concise, with rationale.** Every finding states what to change, why, and what evidence led you there.
+
+## Workflow
+
+### 1. Intent — Is this necessary?
+
+- State the goal in one sentence, in your own words. If you cannot, the artifact is underspecified — say so and stop.
+- Ask: **Is there a simpler way?**
+  - Delete/does-nothing (is the problem real and load-bearing?)
+  - Use existing code (does this already exist?)
+  - Smaller change (solves 90% of goal with 10% of risk?)
+  - Different layer (config vs code, framework vs app, build vs runtime?)
+- If a better alternative exists, name it BEFORE the line-by-line review.
+
+### 2. Trace — Walk the actual code path
+
+- For each behavior the change claims, trace end-to-end through real code — not just the lines in the diff.
+- Include unchanged code on either side of the diff. Bugs hide at the seams.
+- Entry point → call sites → branches taken → state mutated → exit/return/side effect.
+
+### 3. Verify — Does it do what it claims?
+
+- Does the traced code actually produce the behavior?
+- What inputs/states would break it? (Edge cases, concurrent callers, error paths, partial failures, retries, empty/null/unicode/huge inputs)
+- What does it silently change? (Performance, error semantics, observability, contracts)
+- How is it tested? (Do tests exercise the traced path, or pass while skipping it?)
+
+### 4. Report
+
+Format per finding:
+
+```text
+[severity] file:line
+Issue: ...
+Impact: ...
+Fix: ...
+```
+
+Severity:
+
+- critical: data loss, secret leak, arbitrary command/path escape
+- high: broken core workflow, ownership bypass
+- medium: regression, flaky behavior
+- low: polish, maintainability
+
+Close with verdict: **ship / fix-then-ship / rework / reject** — with single biggest reason.
+
+## Rules
+
+- **No rubber-stamps.** "LGTM" is not an output. If nothing found, say what you traced.
+- **Cite or it didn't happen.** Every claim needs specific path/file/line.
+- **One simpler-alternative pass is MANDATORY.** Skip only if user says "don't question scope."
+- **Distinguish claim from verification.** "The PR says X" and "I traced X and confirmed" are different.
+- **No flattery, no hedging.** State the finding.

package/skills/systematic-debugging/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: systematic-debugging
-description: Use when encountering a bug, test failure, blocked run, provider error, stale state, crash, or unexpected behavior before proposing fixes.
+description: "Four-phase debugging discipline with refuse gates. Use when encountering a bug, test failure, blocked run, provider error, stale state, crash, or unexpected behavior. Triggers: debug this, investigate, fix this bug, something is broken, crash, error, test failed, it broke, not working, unexpected."
 ---
 
 # systematic-debugging
@@ -9,6 +9,36 @@ Core principle: no fixes without root-cause investigation first. Symptom patches
 
 Distilled from detailed reads of systematic-debugging, root-cause tracing, TDD, and error-analysis skill patterns.
 
+## Invocation — Read Before Debugging
+
+Before beginning any debug session, recite these four steps:
+
+> **1. First is reproducibility.** Can the issue be reproduced reliably?
+> **2. Know the fail path.** Where does the code break and what stops it from breaking?
+> **3. Question your hypothesis.** What would disprove it?
+> **4. Every run is a breadcrumb.** Cross-reference all of them.
+
+If the user says "skip the ritual" → skip the recitation but still apply the four phases silently.
+
+---
+
+## Refuse Gate — Do NOT Proceed Without These
+
+Before proposing ANY fix:
+
+- [ ] **Can you reproduce the issue reliably?** (deterministic or >50% flake rate)
+- [ ] **Do you know the root cause?** (confirmed mechanism, not a hypothesis)
+- [ ] **Have you tried to FALSIFY your hypothesis first?** (disproof before proof)
+
+If ANY answer is NO:
+→ Stop.
+→ State what's missing.
+→ Do not propose a fix.
+
+Exception: if the user explicitly says "just patch the symptom" — proceed but flag it as a symptom patch, not a root-cause fix.
+
+---
+
 ## Four Phases
 
 ### 1. Root Cause Investigation
@@ -34,9 +64,14 @@ user/tool params → config resolution → team/workflow/agent discovery → mod
 - Identify dependencies: config home, project root markers, env vars, locks, stale caches, provider model capabilities.
 - Do not assume small differences are irrelevant.
 
-### 3. Hypothesis and Test
+### 3. Hypothesis and Test — Falsify First
 
-- State one hypothesis: “I think X is the root cause because Y.”
+- State one hypothesis: "I think X is the root cause because Y."
+- Generate 3-5 ranked hypotheses, not one. Single-hypothesis thinking anchors on the first plausible idea.
+- For each hypothesis:
+  - What is the simplest **proof**? What is the cleanest **disproof**?
+  - Run the **disproof FIRST**. If the hypothesis survives, it's real. If it dies, you saved time chasing a phantom.
+  - Does it explain the symptom end-to-end? Walk it through.
 - Test one variable at a time with the smallest read-only probe or targeted test.
 - If wrong, discard the hypothesis instead of piling on fixes.
 - After three failed fixes, question architecture or assumptions before continuing.
@@ -45,7 +80,7 @@ user/tool params → config resolution → team/workflow/agent discovery → mod
 
 - Add or identify a failing regression test when practical.
 - Fix the root cause, not the symptom.
-- Avoid “while I’m here” refactors.
+- Avoid "while I'm here" refactors.
 - Verify targeted behavior, then broader gates.
 
 ## Evidence to Collect
@@ -60,8 +95,28 @@ user/tool params → config resolution → team/workflow/agent discovery → mod
 
 ## Anti-patterns
 
-- Fixing before reproducing.
+- Proposing a fix before reproducing (the refuse gate exists for a reason).
+- Running proof experiments before disproof (disproof first saves time).
+- Trusting a single passing run as validation (check against all prior breadcrumbs).
 - Assuming real user global config cannot pollute tests.
 - Treating provider errors as only transient network failures.
 - Removing guards because they reveal a blocked state.
 - Editing unrelated layers before checking the hypothesis.
+
+## Breadcrumb Ledger
+
+Maintain a running ledger of every experiment in this session. Each entry:
+
+| # | What Changed | What Happened | Ruled In/Out |
+|---|-------------|--------------|-------------|
+| 1 | Added `[DBG-001]` probe | Got `[output]` | Hypothesis A ruled out |
+| 2 | Changed X to Y | Same error persists | Not X |
+| 3 | Checked Z config | Found mismatch | Z is contributing |
+
+When a new hypothesis surfaces, walk the ledger:
+- Does it hold for **every** prior observation?
+- If any past run contradicts it, the hypothesis is wrong or incomplete.
+
+When in doubt, design the **single experiment** whose outcome makes it certain — run that next.
+
+Update the ledger after every run. It is your memory across the session.

package/skills/verification-before-done/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verification-before-done
-description: Use when about to claim work is complete, fixed, passing, reviewed, committed, or ready to hand off.
+description: "Evidence before claims. Use before claiming work is complete, fixed, passing, reviewed, committed, or ready to hand off. Triggers: done, fixed, complete, ready to merge, can I close, is it working, verify this, check if it passes, all good, LGTM, ready to ship."
 ---
 
 # verification-before-done

package/skills/workspace-isolation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workspace-isolation
-description: Workspace isolation boundaries in pi-crew. Use when ensuring agents from workspace A cannot access workspace B, or when implementing worktree-based parallel execution.
+description: "Workspace isolation boundaries. Use when ensuring agents from workspace A cannot access workspace B, or worktree-based parallel execution. Triggers: workspace isolation, cross-workspace access, escape boundary, worktree safety."
 ---
 
 # workspace-isolation

package/src/agents/discover-agents.ts

@@ -6,6 +6,215 @@ import { parseCsv, parseFrontmatter } from "../utils/frontmatter.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { packageRoot, projectCrewRoot, userPiRoot } from "../utils/paths.ts";
 
+// ═══════════════════════════════════════════════════════════════════════════
+// SEC-001 Fix: Protected Agent Names Blocklist
+// Prevents privilege escalation via agent shadowing attacks.
+// See: SECURITY-ISSUES.md SEC-001
+// ═══════════════════════════════════════════════════════════════════════════
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SEC-005 Fix: Version-based Cache for Atomic Invalidation
+// Uses a global version counter for atomic cache invalidation instead of
+// relying on TTL alone. This eliminates race conditions where concurrent
+// callers might get stale cached snapshots.
+// See: SECURITY-ISSUES.md SEC-005
+// ═══════════════════════════════════════════════════════════════════════════
+
+
+/** Version counter for atomic cache invalidation. Incremented on every mutation. */
+let cacheVersion = 0;
+
+/** Get current cache version. Used for atomic cache stamping. */
+export function getCacheVersion(): number {
+	return cacheVersion;
+}
+
+/**
+ * Increment cache version for atomic invalidation.
+ * All cached entries with versions older than this are considered stale.
+ */
+function incrementCacheVersion(): void {
+	cacheVersion++;
+}
+
+/** Exact match blocklist for protected builtin agent names. */
+const PROTECTED_AGENT_NAMES = new Set([
+	"executor",
+	"test-engineer",
+	"explorer",
+	"planner",
+	"analyst",
+	"critic",
+	"reviewer",
+	"verifier",
+	"writer",
+	"security-reviewer",
+]);
+
+/**
+ * Pattern blocklist for agent names that would likely confuse or deceive
+ * workflows looking for builtin agents.
+ *
+ * Covers:
+ * - Name variations: "executor-v2", "my-executor", "custom-executor"
+ * - Misspellings that could be typo-squatted: "execultor", "explroer"
+ * - Prefix/suffix combinations with protected names
+ */
+const PROTECTED_AGENT_PATTERNS: Array<{ pattern: RegExp; example: string }> = [
+	// Exact variations with delimiters
+	{ pattern: /^executor[-_]?v?[0-9]/i, example: "executor-v2, executor_1" },
+	{ pattern: /^test[-_]?engineer/i, example: "test-engineer-proxy" },
+	{ pattern: /^explorer[-_]/i, example: "explorer-debug" },
+	{ pattern: /^planner[-_]/i, example: "planner-v3" },
+	// Generic prefixes that could impersonate builtins
+	{ pattern: /^(my|custom|new|local)[-_](executor|test[-_]?engineer|explorer|planner)$/i, example: "my-executor" },
+	{ pattern: /^(executor|test[-_]?engineer|explorer|planner)[-_]?(proxy|hook|override)$/i, example: "executor-override" },
+	// Common typosquatting patterns (intentional misspellings)
+	{ pattern: /^exec[au]t[o0]r$/i, example: "execator" },
+	{ pattern: /^expl[o0]rer$/i, example: "explorer" },
+	{ pattern: /^plann[ae]r$/i, example: "plannar" },
+	// Suffixes that indicate override意图
+	{ pattern: /^(executor|test[-_]?engineer|explorer|planner)[-_]?(override|replacement|shadow)$/i, example: "executor-override" },
+];
+
+/**
+ * Check if an agent name matches any protected pattern.
+ * Returns the matched pattern description for error messages.
+ */
+function matchProtectedPattern(name: string): string | null {
+	const key = name.toLowerCase();
+	for (const { pattern, example } of PROTECTED_AGENT_PATTERNS) {
+		if (pattern.test(key)) {
+			return `pattern "${pattern}" (example: ${example})`;
+		}
+	}
+	return null;
+}
+
+/**
+ * Security event types for audit logging.
+ */
+interface SecurityEvent {
+	type: "AGENT_REGISTRATION_BLOCKED" | "PROJECT_AGENT_SHADOW_WARNING";
+	name: string;
+	reason: string;
+	timestamp: number;
+}
+
+/**
+ * Security event log. In production, this should be sent to a security SIEM.
+ */
+const securityEventLog: SecurityEvent[] = [];
+
+/**
+ * Log a security event for audit purposes.
+ * TODO: In production, integrate with project's logging infrastructure
+ *       (e.g., send to SIEM, log aggregator, or security webhook).
+ */
+function logSecurityEvent(event: SecurityEvent): void {
+	securityEventLog.push(event);
+
+	// Console output for development/debugging (redacted in production)
+	const prefix = "\x1b[33m[SECURITY]\x1b[0m"; // Yellow warning
+	console.warn(
+		`${prefix} ${event.type}: agent="${event.name}" reason="${event.reason}" time=${new Date(event.timestamp).toISOString()}`
+	);
+}
+
+/**
+ * Get recent security events (for debugging/testing).
+ */
+export function getSecurityEventLog(): readonly SecurityEvent[] {
+	return securityEventLog;
+}
+
+/**
+ * Clear security event log (for testing).
+ */
+export function clearSecurityEventLog(): void {
+	securityEventLog.length = 0;
+}
+
+/**
+ * Security check: throws if the agent name is protected.
+ *
+ * Checks in order:
+ * 1. Exact match against PROTECTED_AGENT_NAMES
+ * 2. Pattern match against PROTECTED_AGENT_PATTERNS
+ *
+ * Throws with detailed error message on violation.
+ * Logs the event to securityEventLog for audit.
+ */
+function assertAgentNameAllowed(name: string): void {
+	const key = name.toLowerCase();
+
+	// Check 1: Exact match
+	if (PROTECTED_AGENT_NAMES.has(key)) {
+		logSecurityEvent({
+			type: "AGENT_REGISTRATION_BLOCKED",
+			name,
+			reason: `exact_match:${key}`,
+			timestamp: Date.now(),
+		});
+		throw new Error(
+			`SECURITY: Cannot register agent '${name}': protected builtin name. ` +
+			`Dynamic agents cannot shadow builtin agents (executor, explorer, planner, etc.) to prevent privilege escalation.`
+		);
+	}
+
+	// Check 2: Pattern match (custom-executor, my-planner, etc.)
+	const matchedPattern = matchProtectedPattern(key);
+	if (matchedPattern !== null) {
+		logSecurityEvent({
+			type: "AGENT_REGISTRATION_BLOCKED",
+			name,
+			reason: `pattern_match:${matchedPattern}`,
+			timestamp: Date.now(),
+		});
+		throw new Error(
+			`SECURITY: Cannot register agent '${name}': name matches protected pattern (${matchedPattern}). ` +
+			`This pattern is blocked to prevent privilege escalation via similar-named agents.`
+		);
+	}
+}
+
+/**
+ * Check if a project agent name would shadow a builtin agent.
+ * Logs a warning if so, but does NOT block (project agents can be legitimate overrides).
+ *
+ * Called during agent discovery to flag potential security concerns.
+ */
+function checkProjectAgentShadowsBuiltin(name: string): void {
+	const key = name.toLowerCase();
+
+	// Check exact match
+	if (PROTECTED_AGENT_NAMES.has(key)) {
+		logSecurityEvent({
+			type: "PROJECT_AGENT_SHADOW_WARNING",
+			name,
+			reason: "project_shadows_protected_builtin",
+			timestamp: Date.now(),
+		});
+		console.warn(
+			`\x1b[33m[SECURITY WARNING]\x1b[0m Project agent "${name}" shadows a protected builtin. ` +
+			`This agent will be loaded but builtin agents take priority. ` +
+			`If this is intentional, consider using a different name.`
+		);
+		return;
+	}
+
+	// Check pattern match
+	const matchedPattern = matchProtectedPattern(key);
+	if (matchedPattern !== null) {
+		logSecurityEvent({
+			type: "PROJECT_AGENT_SHADOW_WARNING",
+			name,
+			reason: `project_shadows_pattern:${matchedPattern}`,
+			timestamp: Date.now(),
+		});
+	}
+}
+
 export interface AgentDiscoveryResult {
 	builtin: AgentConfig[];
 	user: AgentConfig[];
@@ -28,6 +237,101 @@ function parseContextMode(value: string | undefined): "fresh" | "fork" | undefin
 	return value === "fresh" || value === "fork" ? value : undefined;
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// SEC-002 Fix: Agent System Prompt Sanitization
+// Prevents prompt injection via malicious agent files.
+// See: SECURITY-ISSUES.md SEC-002
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Trust levels for agent source classification.
+ * Determines how strictly to sanitize the system prompt.
+ */
+type TrustLevel = "builtin" | "user" | "project";
+
+/**
+ * Convert ResourceSource to TrustLevel for sanitization.
+ */
+function sourceToTrustLevel(source: ResourceSource): TrustLevel {
+	switch (source) {
+		case "builtin":
+			return "builtin";
+		case "user":
+			return "user";
+		case "project":
+		return "project";
+		default:
+			return "project";
+	}
+}
+
+/**
+ * Sanitize agent system prompt content to reduce prompt injection risk.
+ *
+ * Uses OWASP Agent Memory Guard-inspired patterns:
+ * - Strip zero-width Unicode (potential bypass vectors)
+ * - Strip HTML/JS comments and script tags
+ * - Strip known prompt injection directives
+ * - Strip encoded payloads (base64, hex)
+ * - Collapse excessive whitespace
+ *
+ * Trust levels affect sanitization strictness:
+ * - builtin: Minimal sanitization (trusted source)
+ * - user: Standard sanitization
+ * - project: Strict sanitization (untrusted source)
+ */
+export function sanitizeAgentSystemPrompt(
+	content: string,
+	source: ResourceSource
+): string {
+	const trustLevel = sourceToTrustLevel(source);
+	let sanitized = content;
+
+	// 1. Strip zero-width and invisible Unicode characters (all trust levels)
+	sanitized = sanitized.replace(/[\u200B-\u200F\u2028-\u202F\u2060-\u206F\uFEFF]/g, "");
+
+	// 2. Strip HTML/JS comments (instruction hiding) — all trust levels
+	sanitized = sanitized.replace(/<!--[\s\S]*?-->|<\/?script[^>]*>/gi, "");
+
+	// 3. Strip known prompt injection directive patterns — user and project
+	if (trustLevel !== "builtin") {
+		// Strip lines that look like system directives
+		sanitized = sanitized.replace(
+			/^\s*(?:SYSTEM|INSTRUCTION|IGNORE(?:\s+ALL)?\s+(?:PREVIOUS|INSTRUCTIONS)?|OVERRIDE|YOUR\s+ROLE\s+IS|MALICIOUS|BACKDOOR)\s*:.*$/gim,
+			""
+		);
+
+		// Strip embedded instruction patterns in brackets
+		sanitized = sanitized.replace(/\[(?:SYSTEM|INSTRUCTION|OVERRIDE|MALICIOUS)\s*:[^\]]*\]/gi, "");
+
+		// Strip base64/hex-encoded command payloads
+		sanitized = sanitized.replace(/\b(base64|base32|hex)\s*['":]\s*([A-Za-z0-9+\/=]{20,})/gi, "[encoded-command-redacted]");
+
+		// Strip eval/exec patterns with encoded content
+		sanitized = sanitized.replace(/\b(eval|exec|spawn|subprocess)\s*\(\s*(?:base64|Buffer\.from)\s*\(/gi, "[suspicious-call-redacted]");
+
+		// Strip markdown that attempts to hide instructions
+		sanitized = sanitized.replace(/```\s*(?:system|instruction|prompt)\n[\s\S]*?```/gi, "");
+	}
+
+	// 4. Project-level strict sanitization
+	if (trustLevel === "project") {
+		// Strip YAML-like assignment patterns that could override behavior
+		sanitized = sanitized.replace(/^\s*(?:role|persona|behavior|directive)\s*[=:].*$/gim, "");
+
+		// Strip potential exfiltration patterns
+		sanitized = sanitized.replace(/\b(write|append)\s+.*(?:secrets?|keys?|token|credential)/gi, "[suspicious-write-redacted]");
+
+		// Strip network exfiltration patterns
+		sanitized = sanitized.replace(/\b(fetch|curl|wget|axios)\s+.*(?:exfil|steal|leak|send)/gi, "[suspicious-network-redacted]");
+	}
+
+	// 5. Collapse multiple blank lines (cleanup after removals)
+	sanitized = sanitized.replace(/\n{3,}/g, "\n\n");
+
+	return sanitized.trim();
+}
+
 function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig | undefined {
 	try {
 		const content = fs.readFileSync(filePath, "utf-8");
@@ -39,12 +343,18 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 		const avoidWhen = parseCsv(frontmatter.avoidWhen);
 		const cost = parseCost(frontmatter.cost);
 		const category = frontmatter.category?.trim() || undefined;
+
+		// SEC-002: Sanitize system prompt based on source trust level
+		const rawSystemPrompt = body.trim();
+		const systemPrompt = sanitizeAgentSystemPrompt(rawSystemPrompt, source);
+
 		return {
 			name,
 			description,
 			source,
 			filePath,
-			systemPrompt: body.trim(),
+			systemPrompt,
+			// ... rest unchanged
 			model: frontmatter.model === "false" ? undefined : frontmatter.model || undefined,
 			fallbackModels: parseCsv(frontmatter.fallbackModels),
 			thinking: frontmatter.thinking === "false" ? undefined : frontmatter.thinking || undefined,
@@ -70,11 +380,20 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 
 function readAgentDir(dir: string, source: ResourceSource): AgentConfig[] {
 	if (!fs.existsSync(dir)) return [];
-	return fs.readdirSync(dir)
+	const agents = fs.readdirSync(dir)
 		.filter((entry) => entry.endsWith(".md") && !entry.endsWith(".team.md") && !entry.endsWith(".workflow.md"))
 		.map((entry) => parseAgentFile(path.join(dir, entry), source))
 		.filter((agent): agent is AgentConfig => agent !== undefined)
 		.sort((a, b) => a.name.localeCompare(b.name));
+
+	// SEC-001: Warn about project agents that shadow protected builtins
+	if (source === "project") {
+		for (const agent of agents) {
+			checkProjectAgentShadowsBuiltin(agent.name);
+		}
+	}
+
+	return agents;
 }
 
 function applyAgentOverrides(agents: AgentConfig[], cwd: string, loadedConfig?: LoadedPiTeamsConfig): AgentConfig[] {
@@ -101,22 +420,30 @@ function applyAgentOverrides(agents: AgentConfig[], cwd: string, loadedConfig?:
 }
 
 // ─── Agent Discovery Cache (Phase 3a) ────────────────────────────────────
-// Caches discoverAgents results by cwd with a short TTL to avoid repeated
-// disk I/O when multiple callers request agents for the same project.
+// SEC-005 Fix: Uses version-based cache for atomic invalidation.
+// ═══════════════════════════════════════════════════════════════════════════
 
 const DISCOVERY_CACHE_TTL_MS = 500;
-const discoveryCache = new Map<string, { result: AgentDiscoveryResult; expiresAt: number }>();
+interface CachedDiscoveryEntry {
+	result: AgentDiscoveryResult;
+	expiresAt: number;
+	cacheVersion: number;  // SEC-005: Version stamp for atomic invalidation
+}
+const discoveryCache = new Map<string, CachedDiscoveryEntry>();
 const DISCOVERY_CACHE_MAX_ENTRIES = 32;
 
 function pruneDiscoveryCache(): void {
 	const now = Date.now();
+	const currentVersion = cacheVersion;
 	for (const [key, entry] of discoveryCache) {
-		if (entry.expiresAt <= now) discoveryCache.delete(key);
+		if (entry.expiresAt <= now || entry.cacheVersion < currentVersion) {
+			discoveryCache.delete(key);
+		}
 	}
 }
 
-/** Invalidate cached discovery result for a given cwd (or all if omitted). */
 export function invalidateAgentDiscoveryCache(cwd?: string): void {
+	incrementCacheVersion();
 	if (cwd) {
 		discoveryCache.delete(cwd);
 	} else {
@@ -126,8 +453,10 @@ export function invalidateAgentDiscoveryCache(cwd?: string): void {
 
 export function discoverAgents(cwd: string): AgentDiscoveryResult {
 	pruneDiscoveryCache();
+	const currentVersion = cacheVersion;
 	const cached = discoveryCache.get(cwd);
-	if (cached && cached.expiresAt > Date.now()) {
+	// SEC-005: Check both TTL expiry AND version stamp
+	if (cached && cached.expiresAt > Date.now() && cached.cacheVersion >= currentVersion) {
 		return cached.result;
 	}
 	const loaded = loadConfig(cwd);
@@ -136,7 +465,8 @@ export function discoverAgents(cwd: string): AgentDiscoveryResult {
 		user: applyAgentOverrides(readAgentDir(path.join(userPiRoot(), "agents"), "user"), cwd, loaded),
 		project: applyAgentOverrides(readAgentDir(path.join(projectCrewRoot(cwd), "agents"), "project"), cwd, loaded),
 	};
-	discoveryCache.set(cwd, { result, expiresAt: Date.now() + DISCOVERY_CACHE_TTL_MS });
+	// SEC-005: Store with current version stamp
+	discoveryCache.set(cwd, { result, expiresAt: Date.now() + DISCOVERY_CACHE_TTL_MS, cacheVersion: currentVersion });
 	while (discoveryCache.size > DISCOVERY_CACHE_MAX_ENTRIES) {
 		const oldest = discoveryCache.keys().next().value;
 		if (oldest !== undefined) discoveryCache.delete(oldest);
@@ -150,13 +480,15 @@ export function discoverAgents(cwd: string): AgentDiscoveryResult {
 
 const dynamicAgents = new Map<string, AgentConfig>();
 
-/** Register a dynamic agent at runtime. Throws if already registered. */
+/** Register a dynamic agent at runtime. Throws if already registered or if name is protected. */
 export function registerDynamicAgent(config: AgentConfig): void {
 	const key = config.name.toLowerCase();
+	// Security check: prevent shadowing of builtin agents (SEC-001)
+	assertAgentNameAllowed(config.name);
 	if (dynamicAgents.has(key)) {
 		throw new Error(`Agent already registered: ${config.name}`);
 	}
-	dynamicAgents.set(key, { ...config, source: config.source ?? "project" });
+	dynamicAgents.set(key, { ...config, source: "dynamic" });  // Always "dynamic" — cannot be spoofed
 	invalidateAgentDiscoveryCache();
 }
 
@@ -183,10 +515,16 @@ export function allAgents(discovery: AgentDiscoveryResult | undefined): AgentCon
 	for (const agent of [...discovery.project, ...discovery.builtin, ...discovery.user]) {
 		byName.set(agent.name.toLowerCase(), agent);
 	}
-	// Dynamic agents (registered at runtime) take highest precedence.
-	// They can override any discovered agent (project/builtin/user).
+	// Dynamic agents only fill gaps — they cannot override builtin/user agents.
+	// SECURITY: Dynamic agents are less trusted (registered at runtime by extensions/hooks).
+	// They are only used if no builtin/user agent with the same name exists.
 	for (const agent of dynamicAgents.values()) {
-		byName.set(agent.name.toLowerCase(), agent);
+		const key = agent.name.toLowerCase();
+		if (!byName.has(key)) {
+			byName.set(key, agent);
+		}
+		// NOTE: If an agent with the same name exists, the dynamic version is ignored.
+		// This prevents privilege escalation via agent shadowing (SEC-001).
 	}
 	return [...byName.values()].filter((agent) => !agent.disabled).sort((a, b) => a.name.localeCompare(b.name));
 }

package/src/runtime/skill-instructions.ts

@@ -91,10 +91,16 @@ export function resolveTaskSkillNames(input: ResolveTaskSkillsInput): string[] {
 	return collectTaskSkillNames(input).slice(0, MAX_SELECTED_SKILLS);
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// SEC-003 Fix: Reverse skill search order (package first, project second)
+// Prevents malicious project skills from overriding trusted package skills.
+// See: SECURITY-ISSUES.md SEC-003
+// ═══════════════════════════════════════════════════════════════════════════
+
 function candidateSkillDirs(cwd: string): Array<{ root: string; source: "project" | "package" }> {
 	return [
-		{ root: path.resolve(cwd, "skills"), source: "project" },
-		{ root: PACKAGE_SKILLS_DIR, source: "package" },
+		{ root: PACKAGE_SKILLS_DIR, source: "package" },   // ✓ Trusted first
+		{ root: path.resolve(cwd, "skills"), source: "project" },  // ⚠️ Override second
 	];
 }
 

package/src/runtime/task-packet.ts

@@ -2,6 +2,51 @@ import * as path from "node:path";
 import type { TeamRunManifest, TaskPacket, TaskScope, VerificationContract } from "../state/types.ts";
 import type { WorkflowStep } from "../workflows/workflow-config.ts";
 
+// ═══════════════════════════════════════════════════════════════════════════
+// SEC-007 Fix: Workflow Step Task Sanitization
+// Context provided by workers comes from workflow definitions that could
+// be user-controlled. Sanitize task text to prevent injection.
+// See: SECURITY-ISSUES.md SEC-007
+// ═══════════════════════════════════════════════════════════════════════════
+
+
+/**
+ * Sanitize workflow step task text to reduce injection risk.
+ *
+ * The task text is used as a prompt for worker agents. In a multi-tenant
+ * or shared workflow scenario, malicious workflow definitions could
+ * embed injection instructions.
+ *
+ * Sanitization:
+ * - Strip zero-width Unicode characters
+ * - Strip known prompt injection directive patterns
+ * - Strip base64/hex encoded payloads
+ * - Collapse excessive whitespace
+ */
+export function sanitizeTaskText(task: string): string {
+	let sanitized = task;
+
+	// 1. Strip zero-width and invisible Unicode characters
+	sanitized = sanitized.replace(/[\u200B-\u200F\u2028-\u202F\u2060-\u206F\uFEFF]/g, "");
+
+	// 2. Strip known prompt injection directive patterns
+	sanitized = sanitized.replace(
+		/^\s*(?:SYSTEM|INSTRUCTION|IGNORE(?:\s+ALL)?\s+INSTRUCTIONS|OVERRIDE|YOUR\s+ROLE\s+IS|MALICIOUS)\s*:.*$/gim,
+		""
+	);
+
+	// 3. Strip base64/hex encoded command payloads
+	sanitized = sanitized.replace(/\b(?:base64|base32|hex)\s*['":]\s*([A-Za-z0-9+\/=]{16,})/gi, "[encoded-redacted]");
+
+	// 4. Strip embedded instruction patterns in brackets
+	sanitized = sanitized.replace(/\[(?:SYSTEM|INSTRUCTION|OVERRIDE)\s*:[^\]]*\]/gi, "");
+
+	// 5. Collapse multiple blank lines
+	sanitized = sanitized.replace(/\n{3,}/g, "\n\n");
+
+	return sanitized.trim();
+}
+
 export interface BuildTaskPacketInput {
 	manifest: TeamRunManifest;
 	step: WorkflowStep;
@@ -34,8 +79,10 @@ export function buildTaskPacket(input: BuildTaskPacketInput): TaskPacket {
 	const scope = inferTaskScope(input.step);
 	const reads = input.step.reads === false ? [] : input.step.reads ?? [];
 	const scopePath = reads.length === 1 ? reads[0] : reads.length > 1 ? reads.join(", ") : undefined;
+	// SEC-007: Sanitize task text before inserting into task packet
+	const sanitizedTask = sanitizeTaskText(input.step.task);
 	return {
-		objective: input.step.task.replaceAll("{goal}", input.manifest.goal),
+		objective: sanitizedTask.replaceAll("{goal}", input.manifest.goal),
 		scope,
 		scopePath,
 		repo: path.basename(input.manifest.cwd) || input.manifest.cwd,

package/test-integration-check.ts

@@ -0,0 +1,114 @@
+/**
+ * Integration check: validates pi-crew core discovery and team-run functionality.
+ * Run with: node --experimental-strip-types --test test-integration-check.ts
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { discoverAgents, allAgents } from "./src/agents/discover-agents.ts";
+import { discoverTeams, allTeams } from "./src/teams/discover-teams.ts";
+import { discoverWorkflows, allWorkflows } from "./src/workflows/discover-workflows.ts";
+import { handleTeamTool } from "./src/extension/team-tool.ts";
+import { loadRunManifestById } from "./src/state/state-store.ts";
+
+const pkgRoot = path.resolve(import.meta.dirname ?? ".");
+
+// ── Discovery tests ──────────────────────────────────────────────────────
+
+test("discovers builtin agents", () => {
+	const discovery = discoverAgents(pkgRoot);
+	assert.ok(discovery, "discoverAgents should return a result");
+	assert.ok(
+		discovery.builtin.length >= 10,
+		`Expected ≥10 builtin agents, got ${discovery.builtin.length}`,
+	);
+	const all = allAgents(discovery);
+	const names = all.map((a) => a.name);
+	assert.ok(names.includes("executor"), `Missing "executor" agent. Got: ${names.join(", ")}`);
+});
+
+test("discovers builtin teams", () => {
+	const discovery = discoverTeams(pkgRoot);
+	assert.ok(discovery, "discoverTeams should return a result");
+	assert.ok(
+		discovery.builtin.length >= 6,
+		`Expected ≥6 builtin teams, got ${discovery.builtin.length}`,
+	);
+	const all = allTeams(discovery);
+	const names = all.map((t) => t.name);
+	assert.ok(names.includes("fast-fix"), `Missing "fast-fix" team. Got: ${names.join(", ")}`);
+});
+
+test("discovers builtin workflows", () => {
+	const discovery = discoverWorkflows(pkgRoot);
+	assert.ok(discovery, "discoverWorkflows should return a result");
+	assert.ok(
+		discovery.builtin.length >= 6,
+		`Expected ≥6 builtin workflows, got ${discovery.builtin.length}`,
+	);
+	const all = allWorkflows(discovery);
+	const names = all.map((w) => w.name);
+	assert.ok(
+		names.includes("fast-fix"),
+		`Missing "fast-fix" workflow. Got: ${names.join(", ")}`,
+	);
+});
+
+// ── Team run test ─────────────────────────────────────────────────────────
+
+test("fast-fix team run completes successfully with mock child Pi", async () => {
+	const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "pi-crew-int-check-"));
+	fs.mkdirSync(path.join(cwd, ".crew"), { recursive: true });
+
+	const prevExec = process.env.PI_TEAMS_EXECUTE_WORKERS;
+	const prevMock = process.env.PI_TEAMS_MOCK_CHILD_PI;
+	process.env.PI_TEAMS_EXECUTE_WORKERS = "1";
+	process.env.PI_TEAMS_MOCK_CHILD_PI = "success";
+
+	try {
+		const run = await handleTeamTool(
+			{ action: "run", team: "fast-fix", goal: "create a hello.txt file" },
+			{ cwd },
+		);
+
+		// run result is not an error
+		assert.equal(run.isError, false, `handleTeamTool returned error: ${JSON.stringify(run)}`);
+
+		const runId = run.details.runId;
+		assert.ok(runId, "Expected a runId in details");
+
+		// manifest should be persisted and completed
+		const loaded = loadRunManifestById(cwd, runId!);
+		assert.ok(loaded, "loadRunManifestById should return data");
+		assert.equal(
+			loaded!.manifest.status,
+			"completed",
+			`Expected manifest status "completed", got "${loaded!.manifest.status}"`,
+		);
+
+		// all tasks should be completed
+		const taskStatuses = loaded!.tasks.map((t) => t.status);
+		assert.ok(
+			taskStatuses.every((s) => s === "completed"),
+			`Not all tasks completed: ${JSON.stringify(taskStatuses)}`,
+		);
+
+		// artifacts directory should exist
+		const artifactsDir = path.join(cwd, ".crew", "artifacts", runId!);
+		assert.ok(
+			fs.existsSync(artifactsDir),
+			`Artifacts directory should exist: ${artifactsDir}`,
+		);
+
+		console.log(`✅ fast-fix run ${runId} completed successfully with ${loaded!.tasks.length} tasks`);
+	} finally {
+		if (prevExec === undefined) delete process.env.PI_TEAMS_EXECUTE_WORKERS;
+		else process.env.PI_TEAMS_EXECUTE_WORKERS = prevExec;
+		if (prevMock === undefined) delete process.env.PI_TEAMS_MOCK_CHILD_PI;
+		else process.env.PI_TEAMS_MOCK_CHILD_PI = prevMock;
+		fs.rmSync(cwd, { recursive: true, force: true });
+	}
+});