pi-crew 0.3.6 → 0.3.8

package/src/schema/team-tool-schema.ts

@@ -1,10 +1,15 @@
 import { Type } from "@sinclair/typebox";
 
 const SkillOverride = Type.Unsafe({
-	description: "Skill name(s) to add to role/default skills, an array of skill names, or false to disable all injected skills for this run.",
+	description:
+		"Skill name(s) to add to role/default skills, an array of skill names, or false to disable all injected skills for this run.",
 	anyOf: [
 		{ type: "string", maxLength: 2048 },
-		{ type: "array", maxItems: 32, items: { type: "string", maxLength: 80 } },
+		{
+			type: "array",
+			maxItems: 32,
+			items: { type: "string", maxLength: 80 },
+		},
 		{ type: "boolean" },
 	],
 });
@@ -16,85 +21,208 @@ const FreeformConfig = Type.Unsafe({
 });
 
 export const TeamToolParams = Type.Object({
-	action: Type.Optional(Type.Union([
-		Type.Literal("run"),
-		Type.Literal("parallel"),
-		Type.Literal("plan"),
-		Type.Literal("status"),
-		Type.Literal("list"),
-		Type.Literal("get"),
-		Type.Literal("cancel"),
-		Type.Literal("retry"),
-		Type.Literal("resume"),
-		Type.Literal("respond"),
-		Type.Literal("create"),
-		Type.Literal("update"),
-		Type.Literal("delete"),
-		Type.Literal("doctor"),
-		Type.Literal("cleanup"),
-		Type.Literal("events"),
-		Type.Literal("artifacts"),
-		Type.Literal("worktrees"),
-		Type.Literal("forget"),
-		Type.Literal("summary"),
-		Type.Literal("prune"),
-		Type.Literal("export"),
-		Type.Literal("import"),
-		Type.Literal("imports"),
-		Type.Literal("help"),
-		Type.Literal("validate"),
-		Type.Literal("config"),
-		Type.Literal("init"),
-		Type.Literal("recommend"),
-		Type.Literal("autonomy"),
-		Type.Literal("api"),
-		Type.Literal("settings"),
-		Type.Literal("steer"),
-	], { description: "Team action. Defaults to 'list' when omitted." })),
-	resource: Type.Optional(Type.Union([
-		Type.Literal("agent"),
-		Type.Literal("team"),
-		Type.Literal("workflow"),
-	], { description: "Resource kind for get/create/update/delete/list. Defaults to all for list." })),
-	team: Type.Optional(Type.String({ description: "Team name, e.g. default or implementation." })),
-	workflow: Type.Optional(Type.String({ description: "Workflow name, e.g. default or review." })),
-	role: Type.Optional(Type.String({ description: "Role name to run directly within a team." })),
-	agent: Type.Optional(Type.String({ description: "Agent name to inspect or run directly." })),
-	goal: Type.Optional(Type.String({ description: "High-level objective for a team run." })),
-	task: Type.Optional(Type.String({ description: "Concrete task text for direct role/agent execution." })),
-	runId: Type.Optional(Type.String({ description: "Run ID for status, cancel, or resume." })),
-	taskId: Type.Optional(Type.String({ description: "Task ID for respond action." })),
-	message: Type.Optional(Type.String({ description: "Message for respond action." })),
-	async: Type.Optional(Type.Boolean({ description: "Run in background when execution support is enabled." })),
-	workspaceMode: Type.Optional(Type.Union([
-		Type.Literal("single"),
-		Type.Literal("worktree"),
-	], { description: "Workspace isolation mode. Worktree mode is planned after MVP." })),
-	context: Type.Optional(Type.Union([
-		Type.Literal("fresh"),
-		Type.Literal("fork"),
-	], { description: "Child context mode for workers." })),
-	cwd: Type.Optional(Type.String({ description: "Working directory override." })),
-	model: Type.Optional(Type.String({ description: "Model override for direct runs." })),
+	action: Type.Optional(
+		Type.Union(
+			[
+				Type.Literal("run"),
+				Type.Literal("parallel"),
+				Type.Literal("plan"),
+				Type.Literal("status"),
+				Type.Literal("wait"),
+				Type.Literal("list"),
+				Type.Literal("get"),
+				Type.Literal("cancel"),
+				Type.Literal("retry"),
+				Type.Literal("resume"),
+				Type.Literal("respond"),
+				Type.Literal("create"),
+				Type.Literal("update"),
+				Type.Literal("delete"),
+				Type.Literal("doctor"),
+				Type.Literal("cleanup"),
+				Type.Literal("events"),
+				Type.Literal("artifacts"),
+				Type.Literal("worktrees"),
+				Type.Literal("forget"),
+				Type.Literal("summary"),
+				Type.Literal("prune"),
+				Type.Literal("export"),
+				Type.Literal("import"),
+				Type.Literal("imports"),
+				Type.Literal("help"),
+				Type.Literal("validate"),
+				Type.Literal("config"),
+				Type.Literal("init"),
+				Type.Literal("recommend"),
+				Type.Literal("autonomy"),
+				Type.Literal("api"),
+				Type.Literal("settings"),
+				Type.Literal("steer"),
+				Type.Literal("health"),
+			],
+			{ description: "Team action. Defaults to 'list' when omitted." },
+		),
+	),
+	resource: Type.Optional(
+		Type.Union(
+			[
+				Type.Literal("agent"),
+				Type.Literal("team"),
+				Type.Literal("workflow"),
+			],
+			{
+				description:
+					"Resource kind for get/create/update/delete/list. Defaults to all for list.",
+			},
+		),
+	),
+	team: Type.Optional(
+		Type.String({
+			description: "Team name, e.g. default or implementation.",
+		}),
+	),
+	workflow: Type.Optional(
+		Type.String({ description: "Workflow name, e.g. default or review." }),
+	),
+	role: Type.Optional(
+		Type.String({
+			description: "Role name to run directly within a team.",
+		}),
+	),
+	agent: Type.Optional(
+		Type.String({ description: "Agent name to inspect or run directly." }),
+	),
+	goal: Type.Optional(
+		Type.String({ description: "High-level objective for a team run." }),
+	),
+	task: Type.Optional(
+		Type.String({
+			description: "Concrete task text for direct role/agent execution.",
+		}),
+	),
+	runId: Type.Optional(
+		Type.String({ description: "Run ID for status, cancel, or resume." }),
+	),
+	taskId: Type.Optional(
+		Type.String({ description: "Task ID for respond action." }),
+	),
+	message: Type.Optional(
+		Type.String({ description: "Message for respond action." }),
+	),
+	async: Type.Optional(
+		Type.Boolean({
+			description: "Run in background when execution support is enabled.",
+		}),
+	),
+	workspaceMode: Type.Optional(
+		Type.Union([Type.Literal("single"), Type.Literal("worktree")], {
+			description:
+				"Workspace isolation mode. Worktree mode is planned after MVP.",
+		}),
+	),
+	context: Type.Optional(
+		Type.Union([Type.Literal("fresh"), Type.Literal("fork")], {
+			description: "Child context mode for workers.",
+		}),
+	),
+	cwd: Type.Optional(
+		Type.String({ description: "Working directory override." }),
+	),
+	model: Type.Optional(
+		Type.String({ description: "Model override for direct runs." }),
+	),
 	skill: Type.Optional(SkillOverride),
-	scope: Type.Optional(Type.Union([
-		Type.Literal("user"),
-		Type.Literal("project"),
-		Type.Literal("both"),
-	], { description: "Resource scope for discovery or management." })),
+	scope: Type.Optional(
+		Type.Union(
+			[
+				Type.Literal("user"),
+				Type.Literal("project"),
+				Type.Literal("both"),
+			],
+			{ description: "Resource scope for discovery or management." },
+		),
+	),
 	config: Type.Optional(FreeformConfig),
-	dryRun: Type.Optional(Type.Boolean({ description: "Preview a management mutation without writing files." })),
-	confirm: Type.Optional(Type.Boolean({ description: "Required for destructive management actions." })),
-	force: Type.Optional(Type.Boolean({ description: "Override reference checks for destructive management actions." })),
-	keep: Type.Optional(Type.Integer({ minimum: 0, description: "Number of finished runs to keep for prune." })),
-	updateReferences: Type.Optional(Type.Boolean({ description: "When renaming agents or workflows, update team references in the same project/user scope." })),
-	replyTo: Type.Optional(Type.String({ description: "ID of the original mailbox message this is a reply to." })),
-	replyFrom: Type.Optional(Type.String({ description: "Task ID sending the reply." })),
-	replyDeadline: Type.Optional(Type.Integer({ description: "Ms epoch deadline for a reply." })),
+	dryRun: Type.Optional(
+		Type.Boolean({
+			description: "Preview a management mutation without writing files.",
+		}),
+	),
+	confirm: Type.Optional(
+		Type.Boolean({
+			description: "Required for destructive management actions.",
+		}),
+	),
+	force: Type.Optional(
+		Type.Boolean({
+			description:
+				"Override reference checks for destructive management actions.",
+		}),
+	),
+	keep: Type.Optional(
+		Type.Integer({
+			minimum: 0,
+			description: "Number of finished runs to keep for prune.",
+		}),
+	),
+	updateReferences: Type.Optional(
+		Type.Boolean({
+			description:
+				"When renaming agents or workflows, update team references in the same project/user scope.",
+		}),
+	),
+	replyTo: Type.Optional(
+		Type.String({
+			description:
+				"ID of the original mailbox message this is a reply to.",
+		}),
+	),
+	replyFrom: Type.Optional(
+		Type.String({ description: "Task ID sending the reply." }),
+	),
+	replyDeadline: Type.Optional(
+		Type.Integer({ description: "Ms epoch deadline for a reply." }),
+	),
 });
 
 export interface TeamToolParamsValue {
-	action?: "run" | "parallel" | "plan" | "status" | "list" | "get" | "cancel" | "retry" | "resume" | "respond" | "create" | "update" | "delete" | "doctor" | "cleanup" | "events" | "artifacts" | "worktrees" | "forget" | "summary" | "prune" | "export" | "import" | "imports" | "help" | "validate" | "config" | "init" | "recommend" | "autonomy" | "api" | "settings" | "steer";
+	action?:
+		| "run"
+		| "parallel"
+		| "plan"
+		| "status"
+		| "wait"
+		| "list"
+		| "get"
+		| "cancel"
+		| "retry"
+		| "resume"
+		| "respond"
+		| "create"
+		| "update"
+		| "delete"
+		| "doctor"
+		| "cleanup"
+		| "events"
+		| "artifacts"
+		| "worktrees"
+		| "forget"
+		| "summary"
+		| "prune"
+		| "export"
+		| "import"
+		| "imports"
+		| "help"
+		| "validate"
+		| "config"
+		| "init"
+		| "recommend"
+		| "autonomy"
+		| "api"
+		| "settings"
+		| "steer"
+		| "invalidate"
+		| "health";
 	resource?: "agent" | "team" | "workflow";
 	team?: string;
 	workflow?: string;

package/src/state/atomic-write.ts

@@ -102,7 +102,7 @@ export function atomicWriteFile(filePath: string, content: string): void {
 	// Write temp with restrictive permissions
 	const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
 	try {
-		const fd = fs.openSync(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o644);
+		const fd = fs.openSync(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o600);
 		// Post-open verification: on Windows O_NOFOLLOW is 0, so verify FD is a regular file
 		const openedStat = fs.fstatSync(fd);
 		if (!openedStat.isFile()) {
@@ -168,7 +168,7 @@ export async function atomicWriteFileAsync(filePath: string, content: string): P
 	const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
 	try {
 		const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
-		const fd = await fs.promises.open(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o644);
+		const fd = await fs.promises.open(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o600);
 		// Post-open verification: on Windows O_NOFOLLOW is 0, so verify FD is a regular file
 		const openedStat = await fd.stat();
 		if (!openedStat.isFile()) {

package/src/state/locks.ts

@@ -113,6 +113,25 @@ async function acquireLockWithRetryAsync(filePath: string, staleMs: number): Pro
 	}
 }
 
+/**
+ * General-purpose file lock for arbitrary file paths.
+ * Uses the same O_EXCL atomic create strategy as run locks.
+ */
+export function withFileLockSync<T>(filePath: string, fn: () => T, options: RunLockOptions = {}): T {
+	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	acquireLockWithRetry(filePath, staleMs);
+	try {
+		return fn();
+	} finally {
+		try {
+			fs.rmSync(filePath, { force: true });
+		} catch {
+			// Best-effort lock cleanup.
+		}
+	}
+}
+
 export function withRunLockSync<T>(manifest: TeamRunManifest, fn: () => T, options: RunLockOptions = {}): T {
 	const filePath = lockPath(manifest);
 	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;

package/src/state/mailbox.ts

@@ -68,7 +68,13 @@ function mailboxDir(manifest: TeamRunManifest): string {
 function safeMailboxDir(manifest: TeamRunManifest, create = false): string {
 	const dir = mailboxDir(manifest);
 	if (create) fs.mkdirSync(dir, { recursive: true });
-	if (!fs.existsSync(dir)) return dir;
+	// SECURITY: When create=true, dir now exists and must be validated via
+	// resolveRealContainedPath. When create=false, missing dir must throw —
+	// never return an unvalidated bare path (bypasses containment checks).
+	if (!fs.existsSync(dir)) {
+		if (create) throw new Error(`Mailbox directory creation failed: ${dir}`);
+		return path.join(dir); // will throw in callers via resolveRealContainedPath on read
+	}
 	if (fs.lstatSync(dir).isSymbolicLink()) throw new Error(`Invalid mailbox directory: ${dir}`);
 	return resolveRealContainedPath(manifest.stateRoot, "mailbox");
 }
@@ -93,8 +99,6 @@ function taskMailboxDir(manifest: TeamRunManifest, taskId: string, create = fals
 	const relative = path.relative(tasksRoot, resolved);
 	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Invalid mailbox task id: ${taskId}`);
 	if (create) fs.mkdirSync(resolved, { recursive: true });
-	if (!fs.existsSync(resolved)) return resolved;
-	if (fs.lstatSync(resolved).isSymbolicLink()) throw new Error(`Invalid mailbox task directory: ${resolved}`);
 	return resolveRealContainedPath(tasksRoot, normalizedTaskId);
 }
 
@@ -118,8 +122,21 @@ function mailboxFile(manifest: TeamRunManifest, direction: MailboxDirection, tas
 }
 
 function deliveryFile(manifest: TeamRunManifest, create = false): string {
-	const parent = safeMailboxDir(manifest, create);
-	return safeMailboxFile(path.join(parent, "delivery.json"), parent);
+	// Pass create=true to ensure mailbox dir exists before computing delivery.json path.
+	// This mirrors ensureRunMailbox() pattern — always create before computing nested paths.
+	// When create=false, a missing directory is tolerated (callers like readDeliveryState
+	// handle missing file via try/catch; but missing directory must not throw here).
+	try {
+		const parent = safeMailboxDir(manifest, create);
+		return safeMailboxFile(path.join(parent, "delivery.json"), parent);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+			// Directory missing and create=false: return unvalidated path so callers
+			// (readDeliveryState) that have their own try/catch can handle gracefully.
+			return path.join(mailboxDir(manifest), "delivery.json");
+		}
+		throw err;
+	}
 }
 
 function ensureRunMailbox(manifest: TeamRunManifest): void {

package/src/state/state-store.ts

@@ -1,7 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { TeamRunManifest, TeamTaskState } from "./types.ts";
-import { canTransitionRunStatus } from "./contracts.ts";
+import { canTransitionRunStatus, isTerminalRunStatus } from "./contracts.ts";
+import { unregisterActiveRun } from "./active-run-registry.ts";
 import { atomicWriteJson, atomicWriteJsonAsync, atomicWriteJsonCoalesced, readJsonFile } from "./atomic-write.ts";
 import { appendEvent } from "./event-log.ts";
 import { DEFAULT_CACHE, DEFAULT_PATHS } from "../config/defaults.ts";
@@ -61,9 +62,11 @@ function resolveRunStateRoot(cwd: string, runId: string): string | undefined {
 	assertSafePathId("runId", runId);
 	const runsRoot = path.join(scopeBaseRoot(cwd), DEFAULT_PATHS.state.runsSubdir);
 	const scopedPath = resolveContainedRelativePath(runsRoot, runId, "runId");
-	if (!fs.existsSync(scopedPath)) return undefined;
 	try {
-		if (fs.lstatSync(scopedPath).isSymbolicLink()) return undefined;
+		// Single atomic validation: resolves through symlinks via realpath,
+		// verifies containment within runsRoot, and throws ENOENT if missing.
+		// Eliminates the TOCTOU window from the previous existsSync + lstatSync
+		// + resolveRealContainedPath sequence.
 		resolveRealContainedPath(runsRoot, runId);
 	} catch {
 		return undefined;
@@ -242,6 +245,13 @@ export function updateRunStatus(manifest: TeamRunManifest, status: TeamRunManife
 	}
 	const updated: TeamRunManifest = { ...manifest, status, updatedAt: new Date().toISOString(), summary: summary ?? manifest.summary };
 	saveRunManifest(updated);
+	// Unregister from active-run-index when run reaches a terminal status.
+	// Without this, stale entries accumulate (e.g. integration tests in /tmp) and
+	// Pi UI shows ghost "queued" runs that are actually completed/failed/cancelled.
+	// Note: "blocked" is excluded because blocked runs can be unblocked later.
+	if (status === "completed" || status === "failed" || status === "cancelled") {
+		try { unregisterActiveRun(updated.runId); } catch { /* non-critical */ }
+	}
 	appendEvent(updated.eventsPath, {
 		type: `run.${status}`,
 		runId: updated.runId,

package/src/teams/discover-teams.ts

@@ -107,7 +107,8 @@ export function discoverTeams(cwd: string): TeamDiscoveryResult {
 	};
 }
 
-export function allTeams(discovery: TeamDiscoveryResult): TeamConfig[] {
+export function allTeams(discovery: TeamDiscoveryResult | undefined): TeamConfig[] {
+	if (!discovery) return [];
 	const byName = new Map<string, TeamConfig>();
 	for (const team of [...discovery.project, ...discovery.builtin, ...discovery.user]) {
 		byName.set(team.name, team);

package/src/ui/run-event-bus.ts

@@ -11,7 +11,8 @@ export type RunEventType =
 	| "run_started"
 	| "run_completed"
 	| "run_blocked"
-	| "run_cancelled";
+	| "run_cancelled"
+	| "run.cache_invalidated";
 
 /** Typed channel names for category-based event subscription. */
 export type EventChannel =

package/src/ui/settings-overlay.ts

@@ -85,6 +85,7 @@ const SETTINGS: SettingDef[] = [
 	{ id: "notifierIntervalMs", label: "Notifier Interval", type: "number", tab: "advanced", description: "Async run notifier check interval in ms." },
 	{ id: "reliability.autoRetry", label: "Auto Retry", type: "boolean", tab: "advanced", description: "Automatically retry failed tasks." },
 	{ id: "reliability.autoRecover", label: "Auto Recover", type: "boolean", tab: "advanced", description: "Automatically recover from crashes." },
+	{ id: "reliability.cleanupOrphanedTempDirs", label: "Cleanup Orphaned Temp Dirs", type: "boolean", tab: "advanced", description: "Remove /tmp/pi-crew-* directories after reconciliation (1h age threshold)." },
 	{ id: "telemetry.enabled", label: "Telemetry", type: "boolean", tab: "advanced", description: "Enable telemetry collection." },
 	{ id: "notifications.enabled", label: "Notifications", type: "boolean", tab: "advanced", description: "Enable run notifications." },
 ];
@@ -124,6 +125,7 @@ const EFFECTIVE_DEFAULTS: Record<string, unknown> = {
 	"notifierIntervalMs": 5000,
 	"reliability.autoRetry": false,
 	"reliability.autoRecover": false,
+	"reliability.cleanupOrphanedTempDirs": true,
 	"telemetry.enabled": false,
 	"notifications.enabled": false,
 };

package/src/workflows/discover-workflows.ts

@@ -123,6 +123,9 @@ function readWorkflowDir(dir: string, source: ResourceSource): WorkflowConfig[]
 }
 
 export function discoverWorkflows(cwd: string): WorkflowDiscoveryResult {
+	if (!cwd || typeof cwd !== "string") {
+		return { builtin: [], user: [], project: [] };
+	}
 	return {
 		builtin: readWorkflowDir(path.join(packageRoot(), "workflows"), "builtin"),
 		user: readWorkflowDir(path.join(userPiRoot(), "workflows"), "user"),
@@ -130,7 +133,8 @@ export function discoverWorkflows(cwd: string): WorkflowDiscoveryResult {
 	};
 }
 
-export function allWorkflows(discovery: WorkflowDiscoveryResult): WorkflowConfig[] {
+export function allWorkflows(discovery: WorkflowDiscoveryResult | undefined): WorkflowConfig[] {
+	if (!discovery) return [];
 	const byName = new Map<string, WorkflowConfig>();
 	for (const workflow of [...discovery.project, ...discovery.builtin, ...discovery.user]) {
 		byName.set(workflow.name, workflow);