pi-crew 0.1.45 → 0.1.49

package/src/runtime/process-status.ts

@@ -51,6 +51,10 @@ export function hasStaleAsyncProcess(run: TeamRunManifest): boolean {
 
 export function isDisplayActiveRun(run: TeamRunManifest, agents: CrewAgentRecord[] = [], now = Date.now()): boolean {
 	if (!isActiveRunStatus(run.status) || hasStaleAsyncProcess(run) || isLikelyOrphanedActiveRun(run, agents, now)) return false;
-	if (agents.length === 0) return true;
+	// Keep the always-visible widget quiet until a worker actually exists.
+	// Empty active manifests can be created briefly at startup, by old fixture/scaffold
+	// runs, or from cross-cwd registry history; showing them causes noisy 0/0 rows and
+	// needless spinner redraws. The full dashboard can still list historical runs.
+	if (agents.length === 0) return false;
 	return agents.some(hasDurableActiveAgentEvidence);
 }

package/src/runtime/prose-compressor.ts

@@ -0,0 +1,164 @@
+/**
+ * Pure TypeScript prose compression module.
+ *
+ * Inspired by caveman's compress.js — reduces tool descriptions and other
+ * prose by removing filler words, pleasantries, hedging, and articles while
+ * preserving code, URLs, paths, identifiers, and other protected segments
+ * byte-for-byte.
+ *
+ * No external dependencies. No `any` types. Regex-only pattern matching.
+ */
+
+// ---------------------------------------------------------------------------
+// Protected segment patterns (order matters — earlier patterns take priority)
+// ---------------------------------------------------------------------------
+
+const PROTECTED_PATTERNS: readonly RegExp[] = [
+	/```[\s\S]*?```/g,                                    // fenced code blocks
+	/`[^`\n]+`/g,                                         // inline code
+	/\bhttps?:\/\/\S+/gi,                                 // URLs
+	/\b[\w.-]*[\/\\][\w.\/\\\-]+/g,                       // paths with / or \
+	/\b[A-Z][A-Z0-9]*(?:_[A-Z][A-Z0-9]*)+\b/g,           // CONSTANT_CASE
+	/\b\w+(?:\.\w+)+\(\)/g,                               // dotted.method() calls
+	/[A-Za-z_][A-Za-z0-9_]*\s*\([^)]*\)/g,                // function calls: name(args)
+	/\b\d+\.\d+\.\d+\b/g,                                 // version numbers x.y.z
+];
+
+// ---------------------------------------------------------------------------
+// Compression patterns (applied to unprotected prose only)
+// ---------------------------------------------------------------------------
+
+const FILLERS = /\b(?:just|really|basically|actually|simply|quite|very|essentially|literally)\b/gi;
+
+const PLEASANTRIES = /\b(?:please|kindly|thank you|thanks|sure|certainly|of course|happy to)\b[,.]?\s*/gi;
+
+const HEDGES = /\b(?:perhaps|maybe|might|could potentially|would like to|i think|in my opinion)\b\s*/gi;
+
+const LEADERS = /^(?:i'?\s*ll|i will|i can|you can|we will|we can|let me|let'?\s*s)\s+/gim;
+
+const ARTICLES = /\b(?:a|an|the)\s+(?=[a-z])/gi;
+
+// ---------------------------------------------------------------------------
+// Sentinel helpers
+// ---------------------------------------------------------------------------
+
+const SENTINEL_OPEN = "\x00";
+const SENTINEL_CLOSE = "\x00";
+const SENTINEL_RE = /\x00(\d+)\x00/g;
+
+interface SegmentStore {
+	segments: string[];
+}
+
+function extractProtected(text: string, store: SegmentStore): string {
+	let working = text;
+	for (const re of PROTECTED_PATTERNS) {
+		// Reset lastIndex for reused RegExp objects
+		re.lastIndex = 0;
+		working = working.replace(re, (match: string): string => {
+			const index = store.segments.length;
+			store.segments.push(match);
+			return `${SENTINEL_OPEN}${index}${SENTINEL_CLOSE}`;
+		});
+	}
+	return working;
+}
+
+function restoreProtected(text: string, store: SegmentStore): string {
+	return text.replace(SENTINEL_RE, (_match: string, indexStr: string): string => {
+		const index = Number(indexStr);
+		return store.segments[index] ?? "";
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Core prose compression
+// ---------------------------------------------------------------------------
+
+function compressProseText(text: string): string {
+	let s = text;
+
+	// Remove leading "I'll / I will / you can / ..." sentence openers
+	s = s.replace(LEADERS, "");
+
+	// Remove pleasantries
+	s = s.replace(PLEASANTRIES, "");
+
+	// Remove hedging phrases
+	s = s.replace(HEDGES, "");
+
+	// Remove filler adverbs
+	s = s.replace(FILLERS, "");
+
+	// Remove articles before lowercase words
+	s = s.replace(ARTICLES, "");
+
+	// Collapse whitespace introduced by removals
+	s = s.replace(/[ \t]{2,}/g, " ");
+
+	// Fix punctuation spacing (e.g. "word ," → "word,")
+	s = s.replace(/\s+([,.;:!?])/g, "$1");
+
+	// Collapse excessive newlines
+	s = s.replace(/\n{3,}/g, "\n\n");
+
+	// Re-capitalize first letter of each sentence after removals
+	s = s.replace(/(^|[.!?]\s+)([a-z])/g, (_match: string, pre: string, ch: string): string => {
+		return pre + ch.toUpperCase();
+	});
+
+	return s.trim();
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface CompressResult {
+	compressed: string;
+	originalLength: number;
+	compressedLength: number;
+	savingsPercent: number;
+}
+
+/**
+ * Compress prose text by removing filler, pleasantries, hedging, and articles
+ * while preserving code blocks, URLs, paths, identifiers, and other protected
+ * segments byte-for-byte.
+ */
+export function compressProse(text: string): CompressResult {
+	if (typeof text !== "string" || text.length === 0) {
+		return {
+			compressed: "",
+			originalLength: 0,
+			compressedLength: 0,
+			savingsPercent: 0,
+		};
+	}
+
+	const store: SegmentStore = { segments: [] };
+	const extracted = extractProtected(text, store);
+	const compressed = compressProseText(extracted);
+	const restored = restoreProtected(compressed, store);
+
+	const originalLength = text.length;
+	const compressedLength = restored.length;
+	const savingsPercent = originalLength > 0
+		? Math.round(((originalLength - compressedLength) / originalLength) * 100 * 100) / 100
+		: 0;
+
+	return {
+		compressed: restored,
+		originalLength,
+		compressedLength,
+		savingsPercent,
+	};
+}
+
+/**
+ * Convenience wrapper — returns just the compressed string for tool
+ * descriptions and other single-field use cases.
+ */
+export function compressToolDescription(description: string): string {
+	return compressProse(description).compressed;
+}

package/src/runtime/result-extractor.ts

@@ -0,0 +1,121 @@
+/**
+ * Structured Result Extractor — attempts to extract structured data from worker output.
+ * Tries multiple extraction strategies before falling back to raw text.
+ */
+export interface ExtractedResult {
+	/** Whether structured data was successfully extracted */
+	structured: boolean;
+	/** Parsed structured data (if structured=true) */
+	data: unknown;
+	/** Raw text output (always available) */
+	rawText: string;
+	/** Error message if extraction was attempted but failed */
+	error?: string;
+}
+
+/**
+ * Extract structured result from raw worker output text.
+ * Tries strategies in order: direct JSON, fenced JSON, key-value markers.
+ */
+export function extractStructuredResult(raw: string, _schema?: Record<string, unknown>): ExtractedResult {
+	const trimmed = raw.trim();
+	if (!trimmed) {
+		return { structured: false, data: null, rawText: raw };
+	}
+
+	// Strategy 1: Direct JSON parse (entire output is JSON)
+	const directResult = tryDirectJson(trimmed);
+	if (directResult !== undefined) {
+		return { structured: true, data: directResult, rawText: raw };
+	}
+
+	// Strategy 2: Extract from ```json ... ``` fence
+	const fencedResult = tryFencedJson(trimmed);
+	if (fencedResult !== undefined) {
+		return { structured: true, data: fencedResult, rawText: raw };
+	}
+
+	// Strategy 3: Extract from markers like "RESULT:" or "OUTPUT:"
+	const markerResult = tryMarkerExtraction(trimmed);
+	if (markerResult !== undefined) {
+		return { structured: true, data: markerResult, rawText: raw };
+	}
+
+	return { structured: false, data: null, rawText: raw };
+}
+
+function tryDirectJson(text: string): unknown | undefined {
+	if (!text.startsWith("{") && !text.startsWith("[")) return undefined;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return undefined;
+	}
+}
+
+function tryFencedJson(text: string): unknown | undefined {
+	const match = text.match(/```json\s*\n([\s\S]*?)\n\s*```/);
+	if (!match?.[1]) return undefined;
+	try {
+		return JSON.parse(match[1].trim());
+	} catch {
+		return undefined;
+	}
+}
+
+function tryMarkerExtraction(text: string): unknown | undefined {
+	// Try to find JSON after common markers
+	const markers = ["RESULT:", "OUTPUT:", "ANSWER:", "### Result\n", "## Output\n"];
+	for (const marker of markers) {
+		const idx = text.indexOf(marker);
+		if (idx === -1) continue;
+		const after = text.slice(idx + marker.length).trim();
+		// Try JSON parse on text after marker
+		if (after.startsWith("{") || after.startsWith("[")) {
+			try {
+				return JSON.parse(after);
+			} catch {
+				// Try to find just the JSON object/array
+				const jsonEnd = findMatchingBracket(after);
+				if (jsonEnd > 0) {
+					try {
+						return JSON.parse(after.slice(0, jsonEnd));
+					} catch {
+						continue;
+					}
+				}
+			}
+		}
+	}
+	return undefined;
+}
+
+function findMatchingBracket(text: string): number {
+	const openChar = text[0];
+	const closeChar = openChar === "{" ? "}" : "]";
+	let depth = 0;
+	let inString = false;
+	let escape = false;
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i];
+		if (escape) {
+			escape = false;
+			continue;
+		}
+		if (ch === "\\") {
+			escape = true;
+			continue;
+		}
+		if (ch === '"') {
+			inString = !inString;
+			continue;
+		}
+		if (inString) continue;
+		if (ch === openChar) depth++;
+		if (ch === closeChar) {
+			depth--;
+			if (depth === 0) return i + 1;
+		}
+	}
+	return -1;
+}

package/src/runtime/retry-executor.ts

@@ -1,64 +1,81 @@
-import { sleep } from "../utils/sleep.ts";
-
-export interface RetryPolicy {
-	maxAttempts: number;
-	backoffMs: number;
-	jitterRatio: number;
-	exponentialFactor: number;
-	retryableErrors?: string[];
-}
-
-export interface RetryHooks {
-	onAttemptFailed?: (attempt: number, error: Error, nextDelayMs: number) => void;
-	onRetryGivenUp?: (attempts: number, error: Error) => void;
-	signal?: AbortSignal;
-}
-
-export const DEFAULT_RETRY_POLICY: RetryPolicy = { maxAttempts: 3, backoffMs: 1000, jitterRatio: 0.3, exponentialFactor: 2 };
-
-function asError(error: unknown): Error {
-	return error instanceof Error ? error : new Error(String(error));
-}
-
-function globToRegex(pattern: string): RegExp {
-	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
-	return new RegExp(`^${escaped}$`, "i");
-}
-
-function isRetryable(error: Error, policy: RetryPolicy): boolean {
-	const patterns = policy.retryableErrors ?? [];
-	if (!patterns.length) return true;
-	return patterns.some((pattern) => globToRegex(pattern).test(error.message));
-}
-
-export function calculateRetryDelay(attempt: number, policy: RetryPolicy = DEFAULT_RETRY_POLICY, random = Math.random): number {
-	const base = policy.backoffMs * Math.pow(policy.exponentialFactor, Math.max(0, attempt - 1));
-	const jitter = (random() * 2 - 1) * policy.jitterRatio * base;
-	return Math.max(0, base + jitter);
-}
-
-export async function executeWithRetry<T>(fn: (attempt: number) => Promise<T>, policy: RetryPolicy = DEFAULT_RETRY_POLICY, hooks: RetryHooks = {}): Promise<T> {
-	const normalized: RetryPolicy = { ...DEFAULT_RETRY_POLICY, ...policy, maxAttempts: Math.max(1, policy.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts) };
-	let lastError: Error | undefined;
-	for (let attempt = 1; attempt <= normalized.maxAttempts; attempt += 1) {
-		if (hooks.signal?.aborted) throw new Error("Retry aborted.");
-		try {
-			return await fn(attempt);
-		} catch (error) {
-			lastError = asError(error);
-			// Never retry if aborted — sleep() would immediately reject on every attempt.
-			if (hooks.signal?.aborted) {
-				hooks.onRetryGivenUp?.(attempt, lastError);
-				throw lastError;
-			}
-			if (attempt >= normalized.maxAttempts || !isRetryable(lastError, normalized)) {
-				hooks.onRetryGivenUp?.(attempt, lastError);
-				throw lastError;
-			}
-			const delay = calculateRetryDelay(attempt, normalized);
-			hooks.onAttemptFailed?.(attempt, lastError, delay);
-			await sleep(delay, hooks.signal);
-		}
-	}
-	throw lastError ?? new Error("Retry failed without error.");
-}
+import { sleep } from "../utils/sleep.ts";
+import { throwIfCancelled } from "./cancellation.ts";
+
+export interface RetryPolicy {
+	maxAttempts: number;
+	backoffMs: number;
+	jitterRatio: number;
+	exponentialFactor: number;
+	retryableErrors?: string[];
+}
+
+export interface RetryAttemptInfo {
+	attempt: number;
+	attemptId: string;
+}
+
+export interface RetryHooks {
+	onAttemptFailed?: (attempt: number, error: Error, nextDelayMs: number, info: RetryAttemptInfo) => void;
+	onRetryGivenUp?: (attempts: number, error: Error, info: RetryAttemptInfo) => void;
+	attemptId?: (attempt: number) => string;
+	signal?: AbortSignal;
+}
+
+export const DEFAULT_RETRY_POLICY: RetryPolicy = { maxAttempts: 3, backoffMs: 1000, jitterRatio: 0.3, exponentialFactor: 2 };
+
+function asError(error: unknown): Error {
+	return error instanceof Error ? error : new Error(String(error));
+}
+
+function globToRegex(pattern: string): RegExp {
+	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+	return new RegExp(`^${escaped}$`, "i");
+}
+
+function isRetryable(error: Error, policy: RetryPolicy): boolean {
+	const patterns = policy.retryableErrors ?? [];
+	if (!patterns.length) return true;
+	return patterns.some((pattern) => globToRegex(pattern).test(error.message));
+}
+
+export function calculateRetryDelay(attempt: number, policy: RetryPolicy = DEFAULT_RETRY_POLICY, random = Math.random): number {
+	const base = policy.backoffMs * Math.pow(policy.exponentialFactor, Math.max(0, attempt - 1));
+	const jitter = (random() * 2 - 1) * policy.jitterRatio * base;
+	return Math.max(0, base + jitter);
+}
+
+function retryAttemptInfo(attempt: number, hooks: RetryHooks): RetryAttemptInfo {
+	return { attempt, attemptId: hooks.attemptId?.(attempt) ?? `retry_attempt_${attempt}` };
+}
+
+export async function executeWithRetry<T>(fn: (attempt: number, info: RetryAttemptInfo) => Promise<T>, policy: RetryPolicy = DEFAULT_RETRY_POLICY, hooks: RetryHooks = {}): Promise<T> {
+	const normalized: RetryPolicy = { ...DEFAULT_RETRY_POLICY, ...policy, maxAttempts: Math.max(1, policy.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts) };
+	let lastError: Error | undefined;
+	for (let attempt = 1; attempt <= normalized.maxAttempts; attempt += 1) {
+		throwIfCancelled(hooks.signal);
+		const info = retryAttemptInfo(attempt, hooks);
+		try {
+			return await fn(attempt, info);
+		} catch (error) {
+			lastError = asError(error);
+			// Never retry if aborted — sleep() would immediately reject on every attempt.
+			if (hooks.signal?.aborted) {
+				hooks.onRetryGivenUp?.(attempt, lastError, info);
+				throw lastError;
+			}
+			if (attempt >= normalized.maxAttempts || !isRetryable(lastError, normalized)) {
+				hooks.onRetryGivenUp?.(attempt, lastError, info);
+				throw lastError;
+			}
+			const delay = calculateRetryDelay(attempt, normalized);
+			hooks.onAttemptFailed?.(attempt, lastError, delay, info);
+			try {
+				await sleep(delay, hooks.signal);
+			} catch (sleepError) {
+				if (hooks.signal?.aborted) throwIfCancelled(hooks.signal);
+				throw sleepError;
+			}
+		}
+	}
+	throw lastError ?? new Error("Retry failed without error.");
+}

package/src/runtime/runtime-resolver.ts

@@ -1,8 +1,11 @@
 import type { PiTeamsConfig } from "../config/config.ts";
+import type { RuntimeResolutionState } from "../state/types.ts";
 import type { CrewRuntimeKind } from "./crew-agent-runtime.ts";
 
 export type CrewRuntimeMode = "auto" | "scaffold" | "child-process" | "live-session";
 
+export type CrewRuntimeSafety = "trusted" | "explicit_dry_run" | "blocked";
+
 export interface CrewRuntimeCapabilities {
 	kind: CrewRuntimeKind;
 	requestedMode: CrewRuntimeMode;
@@ -13,12 +16,22 @@ export interface CrewRuntimeCapabilities {
 	liveToolActivity: boolean;
 	transcript: boolean;
 	reason?: string;
+	safety: CrewRuntimeSafety;
+}
+
+export function runtimeResolutionState(runtime: CrewRuntimeCapabilities, resolvedAt = new Date().toISOString()): RuntimeResolutionState {
+	return {
+		kind: runtime.kind,
+		requestedMode: runtime.requestedMode,
+		safety: runtime.safety,
+		available: runtime.available,
+		...(runtime.fallback ? { fallback: runtime.fallback } : {}),
+		...(runtime.reason ? { reason: runtime.reason } : {}),
+		resolvedAt,
+	};
 }
 
 export async function isLiveSessionRuntimeAvailable(timeoutMs = 1500, env: NodeJS.ProcessEnv = process.env): Promise<{ available: boolean; reason?: string }> {
-	if (env.PI_CREW_ENABLE_EXPERIMENTAL_LIVE_SESSION !== "1") {
-		return { available: false, reason: "Live-session runtime adapter is experimental and disabled. Set PI_CREW_ENABLE_EXPERIMENTAL_LIVE_SESSION=1 to probe SDK support." };
-	}
 	if (env.PI_CREW_MOCK_LIVE_SESSION === "success") {
 		return { available: true, reason: "Mock live-session runtime is enabled." };
 	}
@@ -52,26 +65,26 @@ export async function isLiveSessionRuntimeAvailable(timeoutMs = 1500, env: NodeJ
 export async function resolveCrewRuntime(config: PiTeamsConfig, env: NodeJS.ProcessEnv = process.env): Promise<CrewRuntimeCapabilities> {
 	const requestedMode = config.runtime?.mode ?? "auto";
 	const workersDisabled = config.executeWorkers === false || env.PI_CREW_EXECUTE_WORKERS === "0" || env.PI_TEAMS_EXECUTE_WORKERS === "0";
-	if (requestedMode === "scaffold") return scaffoldCaps(requestedMode);
-	if (workersDisabled) return scaffoldCaps(requestedMode, "Child worker execution disabled by config/env. Set runtime.mode=scaffold or executeWorkers=false only for dry runs.");
+	if (requestedMode === "scaffold") return scaffoldCaps(requestedMode, undefined, "explicit_dry_run");
+	if (workersDisabled) return scaffoldCaps(requestedMode, "Child worker execution disabled by config/env. Set runtime.mode=scaffold or executeWorkers=false only for dry runs.", "blocked");
 	if (requestedMode === "child-process") return childCaps(requestedMode);
 	if (requestedMode === "live-session" || (requestedMode === "auto" && config.runtime?.preferLiveSession === true)) {
 		const live = await isLiveSessionRuntimeAvailable(1500, env);
 		if (live.available) return liveCaps(requestedMode);
-		if (requestedMode === "live-session" && config.runtime?.allowChildProcessFallback === false) return { ...scaffoldCaps(requestedMode), available: false, reason: live.reason };
+		if (requestedMode === "live-session" && config.runtime?.allowChildProcessFallback === false) return scaffoldCaps(requestedMode, live.reason, "blocked");
 		return { ...childCaps(requestedMode), fallback: "child-process", reason: live.reason };
 	}
 	return childCaps(requestedMode);
 }
 
-function scaffoldCaps(requestedMode: CrewRuntimeMode, reason?: string): CrewRuntimeCapabilities {
-	return { kind: "scaffold", requestedMode, available: true, steer: false, resume: false, liveToolActivity: false, transcript: false, ...(reason ? { reason } : {}) };
+function scaffoldCaps(requestedMode: CrewRuntimeMode, reason?: string, safety: CrewRuntimeSafety = "explicit_dry_run"): CrewRuntimeCapabilities {
+	return { kind: "scaffold", requestedMode, available: safety !== "blocked", steer: false, resume: false, liveToolActivity: false, transcript: false, safety, ...(reason ? { reason } : {}) };
 }
 
 function childCaps(requestedMode: CrewRuntimeMode, reason?: string): CrewRuntimeCapabilities {
-	return { kind: "child-process", requestedMode, available: true, steer: false, resume: false, liveToolActivity: false, transcript: true, ...(reason ? { reason } : {}) };
+	return { kind: "child-process", requestedMode, available: true, steer: false, resume: false, liveToolActivity: false, transcript: true, safety: "trusted", ...(reason ? { reason } : {}) };
 }
 
 function liveCaps(requestedMode: CrewRuntimeMode): CrewRuntimeCapabilities {
-	return { kind: "live-session", requestedMode, available: true, steer: true, resume: true, liveToolActivity: true, transcript: true };
+	return { kind: "live-session", requestedMode, available: true, steer: true, resume: true, liveToolActivity: true, transcript: true, safety: "trusted" };
 }

package/src/runtime/semaphore.ts

@@ -0,0 +1,131 @@
+/**
+ * Phase 6: Semaphore and fail-fast parallel execution.
+ *
+ * Adapted from oh-my-pi's `parallel.ts` Semaphore class and
+ * `mapWithConcurrencyLimit` implementation. Provides:
+ * - Explicit acquire/release Semaphore for concurrency control
+ * - Fail-fast on first error (via Promise.race)
+ * - AbortSignal support for graceful cancellation
+ * - Partial results on abort
+ */
+
+/**
+ * Simple counting semaphore for limiting concurrency across independently-scheduled async work.
+ */
+export class Semaphore {
+	#max: number;
+	#current = 0;
+	#queue: Array<() => void> = [];
+
+	constructor(max: number) {
+		this.#max = Math.max(1, max);
+	}
+
+	async acquire(): Promise<void> {
+		if (this.#current < this.#max) {
+			this.#current++;
+			return;
+		}
+		const { promise, resolve } = (() => {
+			let res: () => void;
+			const p = new Promise<void>((r) => { res = r; });
+			return { promise: p, resolve: res! };
+		})();
+		this.#queue.push(resolve);
+		return promise;
+	}
+
+	release(): void {
+		const next = this.#queue.shift();
+		if (next) {
+			next();
+		} else if (this.#current > 0) {
+			this.#current--;
+		}
+		// Guard: over-release is a no-op to prevent #current going negative
+	}
+
+	/** Current number of acquired slots. */
+	get current(): number {
+		return this.#current;
+	}
+
+	/** Number of waiters in the queue. */
+	get waiting(): number {
+		return this.#queue.length;
+	}
+}
+
+/**
+ * Result of parallel execution with fail-fast support.
+ */
+export interface ParallelResult<R> {
+	/** Results array — undefined entries indicate tasks that were skipped due to abort. */
+	results: (R | undefined)[];
+	/** Whether execution was aborted before all tasks completed. */
+	aborted: boolean;
+	/** The first error that triggered fail-fast, if any. */
+	firstError?: unknown;
+}
+
+/**
+ * Execute items with a concurrency limit, fail-fast, and abort signal support.
+ *
+ * - On first error: aborts remaining workers and rethrows.
+ * - On external abort: returns partial results with `aborted: true`.
+ * - Results are returned in the same order as input items.
+ *
+ * Adapted from oh-my-pi's `mapWithConcurrencyLimit`.
+ */
+export async function mapWithFailFast<T, R>(
+	items: T[],
+	concurrency: number,
+	fn: (item: T, index: number, signal: AbortSignal) => Promise<R>,
+	signal?: AbortSignal,
+): Promise<ParallelResult<R>> {
+	const limit = Math.max(1, Math.min(concurrency, items.length));
+	const results: (R | undefined)[] = new Array(items.length);
+	let nextIndex = 0;
+
+	// Internal abort controller for fail-fast
+	const abortController = new AbortController();
+	const workerSignal = signal
+		? AbortSignal.any([signal, abortController.signal])
+		: abortController.signal;
+
+	// Promise that rejects on first error — used for fail-fast
+	let rejectFirst: (error: unknown) => void;
+	const firstErrorPromise = new Promise<never>((_, reject) => {
+		rejectFirst = reject;
+	});
+
+	const worker = async (): Promise<void> => {
+		while (true) {
+			if (workerSignal.aborted) return;
+			const index = nextIndex++;
+			if (index >= items.length) return;
+			try {
+				results[index] = await fn(items[index], index, workerSignal);
+			} catch (error) {
+				if (!workerSignal.aborted) {
+					abortController.abort();
+					rejectFirst(error);
+					throw error;
+				}
+			}
+		}
+	};
+
+	const workers = Array.from({ length: limit }, () => worker());
+
+	try {
+		await Promise.race([Promise.all(workers), firstErrorPromise]);
+	} catch (error) {
+		if (signal?.aborted) {
+			return { results, aborted: true, firstError: error };
+		}
+		throw error;
+	}
+
+	return { results, aborted: signal?.aborted ?? false };
+}