pi-crew 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.3.0] — Phase 3a+3b: Discovery Cache, Dynamic Agent Registry, Rich TUI Rendering (2026-05-23)
+
+### Phase 3a: Agent Discovery Cache
+- **500ms TTL cache** with max 32 entries and per-cwd invalidation
+- **FIFO eviction** when cache is full
+- Cache pruned on every `discoverAgents()` call
+- `invalidateAgentDiscoveryCache(cwd?)` exposed for explicit invalidation
+
+### Phase 3b: Dynamic Agent Registry
+- **`registerDynamicAgent(config)`** — runtime agent registration with cache invalidation
+- **`unregisterDynamicAgent(name)`** — throws on missing agent
+- **`listDynamicAgents()`** — returns all registered dynamic agents
+- Dynamic agents get **highest priority** over discovered agents (security: project < builtin < user < dynamic)
+- **CrewRegistry v2** — extended from v1 with `registerAgent`/`unregisterAgent`/`listDynamicAgents`
+- Factory `installCrewGlobalRegistry()` for clean initialization
+
+### Rich TUI Tool Rendering
+- **New `src/ui/tool-render.ts`** (304 lines) — shared rendering module ported from pi-subagent4
+- **`renderTeamToolCall`** — collapsed: `team action='run' (default) "goal preview"` / expanded: header + goal streaming
+- **`renderAgentToolCall`** — collapsed: `Agent explorer "prompt preview"` / expanded: header + prompt
+- **`renderTeamToolResult`** — `[status] goal text` for run actions / compact info for others
+- **`renderAgentToolResult`** — status icons (⟳○✓✗) + output lines for agent results
+- **`renderAgentProgress`** — icon + header + tool log + context gauge + usage line (↑↓RW$ctx)
+- Helpers: `formatTokens`, `formatDuration`, `formatContextUsage`, `truncLine`, `formatToolPreview`
+- All tools use **`@mariozechner/pi-tui`** Components (Container, Text, Spacer) directly
+- `renderCall`/`renderResult` added to: `team`, `Agent` tools
+
+### Tests
+- **1662 tests pass** (1652 unit + 46 integration + 4 new)
+- New test suites: `agent-discovery-cache.test.ts` (10 tests), `tool-render.test.ts` (10 tests)
+- Bug fix: `allAgents` priority corrected (discovery: project < builtin < user; dynamic separate/highest)
+
 ## [0.2.21] — 3 Bugs Fixed — Background Runner, Child-pi stdin, Phantom Runs (2026-05-22)
 
 ## [0.2.25] — CI Fixes & needs_attention Terminal Status (2026-05-22)

package/package.json

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

package/src/extension/run-import.ts

@@ -21,11 +21,20 @@ function importRoot(cwd: string, scope: "project" | "user"): string {
 
 export function importRunBundle(cwd: string, bundlePath: string, scope: "project" | "user" = "project"): ImportedRunBundleInfo {
 	const resolvedPath = path.isAbsolute(bundlePath) ? bundlePath : path.resolve(cwd, bundlePath);
-	// Path containment: only allow reading bundles from cwd or user home
-	const allowedBases = [cwd];
+	// Path containment: use resolveRealContainedPath for canonical real-path check
+	// to prevent symlink/../ bypass of the startsWith string comparison.
+	const allowedBases: string[] = [];
 	try { allowedBases.push(userCrewRoot()); } catch { /* ignore */ }
 	try { allowedBases.push(projectCrewRoot(cwd)); } catch { /* ignore */ }
-	const isContained = allowedBases.some((base) => resolvedPath.startsWith(base + path.sep) || resolvedPath === base);
+	allowedBases.push(cwd); // always include cwd last (highest priority)
+	let isContained = false;
+	for (const base of allowedBases) {
+		try {
+			resolveRealContainedPath(base, resolvedPath);
+			isContained = true;
+			break;
+		} catch { /* not contained — try next base */ }
+	}
 	if (!isContained) throw new Error(`Import path must be within project directory or crew root: ${resolvedPath}`);
 	const raw = JSON.parse(fs.readFileSync(resolvedPath, "utf-8")) as unknown;
 	assertRunBundle(raw);
@@ -81,4 +90,4 @@ export function importRunBundle(cwd: string, bundlePath: string, scope: "project
 		"",
 	].join("\n"), "utf-8");
 	return { runId, importedAt, bundlePath: targetJson, summaryPath: targetSummary, ...(conflictReport?.hasConflicts ? { conflictReport } : {}) };
-}
+}

package/src/runtime/background-runner.ts

@@ -147,16 +147,21 @@ async function main(): Promise<void> {
 			if (loaded) appendEvent(loaded.manifest.eventsPath, { type: "async.failed", runId, message: `Background runner received ${sig} — exiting.`, data: { signal: sig, pid: process.pid } });
 		}
 	};
-	// BUG #17 DIAGNOSTIC: Write exit code to file for debugging.
-	process.on("exit", (code) => {
-		try {
-			require("node:fs").appendFileSync(
-				manifest.stateRoot + '/exit-code.txt',
-				`${new Date().toISOString()} exit_code=${code} pid=${process.pid}\n`
-			);
-		} catch {}
-	});
-
+	// BUG #17 FIX: Compute exitCodePath at module load time using args,
+	// NOT by referencing `manifest` (declared inside main() and not in scope at module load).
+	const exitCodePath = ((): string | undefined => {
+		const cwd = argValue("--cwd");
+		const runId = argValue("--run-id");
+		if (!cwd || !runId) return undefined;
+		return path.join(cwd, ".crew", "state", "runs", runId, "exit-code.txt");
+	})();
+	if (exitCodePath) {
+		process.on("exit", (code) => {
+			try {
+				fs.appendFileSync(exitCodePath, `${new Date().toISOString()} exit_code=${code} pid=${process.pid}\n`);
+			} catch {}
+		});
+	}
 	process.on("SIGTERM", () => {
 		// BUG #17 FIX: Ignore SIGTERM.
 		// IMPORTANT: Perform real I/O here to flush io_uring state after EINTR.

package/src/runtime/child-pi.ts

@@ -394,7 +394,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			const finalDrainMs = input.finalDrainMs ?? FINAL_DRAIN_MS;
 			const hardKillMs = input.hardKillMs ?? HARD_KILL_MS;
 			const responseTimeoutEnv = Number.parseInt(process.env.PI_TEAMS_CHILD_RESPONSE_TIMEOUT_MS ?? "", 10);
-			const responseTimeoutMs = Number.isFinite(responseTimeoutEnv) && responseTimeoutEnv >= 0 ? responseTimeoutEnv : input.responseTimeoutMs ?? RESPONSE_TIMEOUT_MS;
+			const responseTimeoutMs = Number.isFinite(responseTimeoutEnv) && responseTimeoutEnv > 0 ? responseTimeoutEnv : input.responseTimeoutMs ?? RESPONSE_TIMEOUT_MS;
 			let responseTimeoutHit = false;
 			let forcedFinalDrain = false;
 			let abortRequested = input.signal?.aborted === true;

package/src/runtime/iteration-hooks.ts

@@ -6,6 +6,7 @@
  */
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
+import * as path from "node:path";
 import { resolveShellForScript } from "../utils/resolve-shell.ts";
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
 import { DENIED_METRIC_NAMES } from "./metric-parser.ts";
@@ -56,6 +57,25 @@ const MAX_STDOUT_BYTES = 8192;
 /** Hook execution timeout in milliseconds (30 seconds). */
 const HOOK_TIMEOUT_MS = 30_000;
 
+/**
+ * Validates that a hook script path is within an allowed directory.
+ * Allowed paths:
+ * - Relative paths starting with ".hooks/" (case-sensitive)
+ * - Absolute paths under $HOME/.pi/hooks/
+ * All other paths are rejected to prevent arbitrary script execution.
+ * @param hookPath - The hook script path to validate
+ * @returns true if the path is allowed, false otherwise
+ */
+export function isAllowedHookPath(hookPath: string): boolean {
+	if (!hookPath || hookPath.trim().length === 0) return false;
+	if (!path.isAbsolute(hookPath)) {
+		const normalized = path.normalize(hookPath);
+		return normalized === ".hooks" || normalized.startsWith(".hooks/");
+	}
+	const homeHooks = path.join(process.env.HOME ?? "", "", ".pi", "hooks");
+	return hookPath === homeHooks || hookPath.startsWith(homeHooks + path.sep);
+}
+
 /**
  * Create a not-fired result for when the hook script is absent or not executable.
  */
@@ -113,9 +133,9 @@ function isScriptRunnable(scriptPath: string): boolean {
  * Spawns `bash <script>` with the hook payload as JSON on stdin.
  * Captures stdout (capped at 8KB) and stderr. Enforces a 30-second timeout.
  *
- * **Security note:** The script path is user-configurable and executed with
- * minimal environment (PATH, HOME, USER, LANG). Only use with trusted script paths from
- * workspace-owned configuration. No path containment validation is performed.
+ * **Security note:** Hook paths are restricted to `.hooks/` relative paths
+ * or `$HOME/.pi/hooks/` absolute paths. All other paths are rejected before
+ * execution.
  *
  * @param payload - Structured hook payload
  * @param hookScriptPath - Absolute or relative path to the hook script
@@ -126,7 +146,12 @@ export async function runIterationHook(
 	hookScriptPath: string,
 	options?: { timeoutMs?: number },
 ): Promise<HookResult> {
-	if (!isScriptRunnable(hookScriptPath)) {
+	if (!isAllowedHookPath(hookScriptPath)) {
+		return { fired: false, stdout: "", stderr: "hook path not allowed: " + hookScriptPath, exitCode: null, timedOut: false, durationMs: 0 };
+	}
+	// Resolve relative paths relative to cwd
+	const resolvedScript = path.isAbsolute(hookScriptPath) ? hookScriptPath : path.join(payload.cwd, hookScriptPath);
+	if (!isScriptRunnable(resolvedScript)) {
 		return notFiredResult();
 	}
 
@@ -136,7 +161,7 @@ export async function runIterationHook(
 	const stderrChunks: Buffer[] = [];
 
 	return new Promise<HookResult>((resolve) => {
-		const { command, args } = resolveShellForScript(hookScriptPath);
+		const { command, args } = resolveShellForScript(resolvedScript);
 		const child = spawn(command, args, {
 			cwd: payload.cwd,
 			env: { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", "USERPROFILE", "TEMP", "TMP", "TMPDIR", "LANG", "LC_ALL", "ComSpec", "SystemRoot", "PI_*"] }), PI_CREW_HOOK: "1" },
@@ -264,4 +289,4 @@ export function hookLogEntry(
 	}
 
 	return entry;
-}
+}

package/src/runtime/live-agent-manager.ts

@@ -145,12 +145,12 @@ export async function terminateLiveAgent(agentIdOrTaskId: string, status: CrewAg
 	if (!handle) return undefined;
 	handle.status = status;
 	handle.updatedAt = new Date().toISOString();
-	liveAgents.delete(handle.agentId);
 	try { if (eventLogFn && eventsPath) eventLogFn(eventsPath, { type: "live_agent.terminated", runId: handle.runId, taskId: handle.taskId, message: `Live agent terminated: ${handle.agent} status=${status}`, data: { agentId: handle.agentId, status, role: handle.role, workspaceId: handle.workspaceId } }); } catch { /* non-critical */ }
 	try {
 		await handle.session.abort?.();
 	} finally {
 		safeDisposeLiveSession(handle);
+		liveAgents.delete(handle.agentId);  // Move AFTER abort completes to prevent race
 	}
 	return handle;
 }

package/src/runtime/role-permission.ts

@@ -1,3 +1,5 @@
+import { isSensitivePath } from "./sensitive-paths.ts";
+
 export type RolePermissionMode = "read_only" | "workspace_write" | "danger_full_access" | "explicit_confirm";
 
 const READ_ONLY_ROLES = new Set(["explorer", "reviewer", "security-reviewer", "verifier", "analyst", "critic", "planner", "writer"]);
@@ -21,8 +23,12 @@ export function isReadOnlyCommand(command: string): boolean {
 	return READ_ONLY_COMMANDS.has(first) && !/\s(-i|--in-place)\b|\s>{1,2}\s|\brm\b|\bmv\b|\bcp\b|\b(?:npm|pnpm|yarn|bun)\s+(install|add|ci|remove)\b|\bgit\s+(commit|push|merge|rebase|reset|checkout|clean)\b/.test(command);
 }
 
-export function checkRolePermission(role: string, command: string): PermissionCheckResult {
+export function checkRolePermission(role: string, command: string, filePath?: string): PermissionCheckResult {
 	const mode = permissionForRole(role);
+	// Also block access to known sensitive paths even for read-only commands
+	if (filePath && isSensitivePath(filePath)) {
+		return { allowed: false, mode, reason: `Path '${filePath}' is sensitive (credentials, SSH keys, etc.) — access denied for all roles.` };
+	}
 	if (mode === "read_only" && !isReadOnlyCommand(command)) return { allowed: false, mode, reason: `Role '${role}' is read-only and command may modify state.` };
 	return { allowed: true, mode };
 }

package/src/worktree/worktree-manager.ts

@@ -68,11 +68,38 @@ function normalizeSyntheticPath(worktreePath: string, rawPath: string): string {
 	return path.normalize(relative);
 }
 
+/**
+ * Validates that a worktree setupHook script path is within an allowed directory.
+ * Allowed paths:
+ * - Relative paths starting with ".hooks/" (case-sensitive)
+ * - Absolute paths under $HOME/.pi/hooks/
+ * Rejects all other paths to prevent arbitrary script execution.
+ * @param hookPath - The hook script path to validate
+ * @returns true if the path is allowed, false otherwise
+ */
+function isAllowedSetupHook(hookPath: string): boolean {
+	if (!hookPath || hookPath.trim().length === 0) return false;
+	if (!path.isAbsolute(hookPath)) {
+		const normalized = path.normalize(hookPath);
+		return normalized === ".hooks" || normalized.startsWith(".hooks/");
+	}
+	const homeHooks = path.join(process.env.HOME ?? "", "", ".pi", "hooks");
+	return hookPath === homeHooks || hookPath.startsWith(homeHooks + path.sep);
+}
+
 function runSetupHook(manifest: TeamRunManifest, task: TeamTaskState, repoRoot: string, worktreePath: string, branch: string): string[] {
 	const cfg = loadConfig(manifest.cwd).config.worktree;
 	if (!cfg?.setupHook) return [];
-	const hookPath = path.isAbsolute(cfg.setupHook) ? cfg.setupHook : path.resolve(repoRoot, cfg.setupHook);
-	if (!fs.existsSync(hookPath) || fs.statSync(hookPath).isDirectory()) throw new Error(`worktree setup hook not found or not a file: ${hookPath}`);
+	const rawHookPath = cfg.setupHook;
+	if (!isAllowedSetupHook(rawHookPath)) {
+		logInternalError("worktree.setupHook.rejected", new Error("hook path not allowed: " + rawHookPath), `cwd=${manifest.cwd}`);
+		return [];
+	}
+	const hookPath = path.isAbsolute(rawHookPath) ? rawHookPath : path.resolve(repoRoot, rawHookPath);
+	if (!fs.existsSync(hookPath) || fs.statSync(hookPath).isDirectory()) {
+		logInternalError("worktree.setupHook.missing", new Error("hook not found or is directory: " + hookPath), `cwd=${manifest.cwd}`);
+		return [];
+	}
 	const nodeHook = hookPath.endsWith(".js") || hookPath.endsWith(".cjs") || hookPath.endsWith(".mjs");
 	const result = spawnSync(nodeHook ? process.execPath : hookPath, nodeHook ? [hookPath] : [], {
 		cwd: worktreePath,