pi-crew 0.9.53 → 0.9.55

package/src/runtime/runtime-warmup.ts

@@ -0,0 +1,160 @@
+/**
+ * Runtime module-graph warmup — general fix for the cold-start race.
+ *
+ * Problem: when N in-process live-session subagents spawn CONCURRENTLY, the
+ * tsx loader can race module-record instantiation, yielding
+ * `Cannot read properties of undefined (reading '<binding>')` for ANY named
+ * import in the hot graph (observed: `existsSync`, `validateWorkflowForTeam`).
+ * v0.8.1's per-import latch covered only the peer-dep namespace; this is the
+ * GENERAL fix.
+ *
+ * Root cause: under tsx, a named import `import { X } from "mod"` compiles to
+ * `mod_1.X` — a namespace-property access at runtime. If `mod_1` (the module
+ * namespace object) is observed mid-instantiation as `undefined`, the access
+ * throws. ANY module in the graph is vulnerable, not just the peer dep. So
+ * per-import latching doesn't scale.
+ *
+ * Fix: pre-warm the hot module graph during SINGLE-THREADED extension
+ * registration (before any subagent can spawn), then `await` the warmup at
+ * every spawn entry point. By the time concurrent subagents touch the graph,
+ * every module record is fully instantiated → no race window.
+ *
+ * Why this is general (not per-import):
+ *   - `startRuntimeWarmup()` fires `import()` for the ROOT modules of each
+ *     hot execution path. ESM transitively instantiates their entire import
+ *     graph, so one import per path warms the whole reachable subgraph.
+ *   - `awaitRuntimeWarmup()` is the gate: spawn paths await it before
+ *     touching any module, guaranteeing the graph is warm regardless of
+ *     which specific binding races.
+ *
+ * The warmup runs during `registerPiTeams()` (single-threaded, before pi
+ * accepts user input). It resolves in milliseconds (module loading only, no
+ * I/O for local modules). The `await` at spawn boundaries is belt-and-
+ * suspenders for pathological cases where a spawn races the warmup promise.
+ *
+ * @module runtime-warmup
+ */
+
+/**
+ * The modules whose transitive import graphs cover every hot execution path
+ * a concurrent subagent can reach. Importing the ROOT of each path warms the
+ * full subgraph (ESM instantiates imports eagerly during `import()`).
+ *
+ * - `./live-session-runtime.ts` — the in-process subagent spawn path
+ *   (pulls in the peer dep + the entire runtime layer).
+ * - `./task-runner.ts` — the child-process task dispatch path.
+ * - `../extension/team-tool.ts` — the team tool (pulls in
+ *   validate-resources → validate-workflow, the `validateWorkflowForTeam` site).
+ * - `../extension/validate-resources.ts` — direct warm of the aggregator.
+ * - `@earendil-works/pi-coding-agent` — the peer dep (the `existsSync` site;
+ *   also latched in v0.8.1 — defense in depth).
+ */
+const HOT_MODULE_SPECIFIERS = [
+	"./live-session-runtime.ts",
+	"./task-runner.ts",
+	"../extension/team-tool.ts",
+	"../extension/team-tool/run.ts", // handleRun path — latched in team-tool.ts but its static graph (config-patch, validate-workflow) still cold-start-races under concurrent fanout
+	"../extension/team-tool/config-patch.ts", // effectiveRunConfig (crash variant observed in repro)
+	"../extension/validate-resources.ts",
+	"../workflows/validate-workflow.ts", // validateWorkflowForTeam (crash variant observed across sessions)
+	"../state/crew-init.ts", // TDZ-prone top-level consts (CREW_README); dynamically imported by team-tool/run.ts
+] as const;
+
+/** Additional bare-specifier peer deps to warm. */
+const HOT_PEER_DEPS = ["@earendil-works/pi-coding-agent"] as const;
+
+let warmupPromise: Promise<void> | undefined;
+let warmupStarted = false;
+let warmupCompleted = false;
+let warmupDurationMs: number | undefined;
+let warmupError: string | undefined;
+
+/**
+ * Start the runtime warmup (idempotent). Fires eager `import()` of the hot
+ * module graph. Safe to call during single-threaded registration — the
+ * promises resolve on the event loop before any subagent can spawn.
+ *
+ * Errors are swallowed: a failed warmup (e.g. peer dep absent) must never
+ * block the extension from loading. The worst case is the old race returns
+ * (which is no worse than before this fix).
+ */
+export function startRuntimeWarmup(): void {
+	if (warmupStarted) return;
+	warmupStarted = true;
+	const startedAt = Date.now();
+	warmupPromise = (async (): Promise<void> => {
+		const imports: Array<Promise<unknown>> = [];
+		for (const spec of HOT_MODULE_SPECIFIERS) {
+			imports.push(
+				import(new URL(spec, import.meta.url).href).catch(() => {
+					// swallow — never block registration on a warmup failure
+				}),
+			);
+		}
+		for (const dep of HOT_PEER_DEPS) {
+			imports.push(
+				import(dep).catch(() => {
+					// peer dep may be absent (optional dep) — swallow
+				}),
+			);
+		}
+		await Promise.all(imports);
+	})()
+		.then(() => {
+			warmupCompleted = true;
+			warmupDurationMs = Date.now() - startedAt;
+		})
+		.catch((err: unknown) => {
+			// final safety net — warmup must never reject. Record for diagnostics.
+			warmupError = err instanceof Error ? err.message : String(err ?? "unknown");
+		});
+}
+
+/**
+ * Await the runtime warmup at a spawn entry point. No-op if warmup hasn't
+ * started (back-compat for callers that don't call startRuntimeWarmup) or has
+ * already resolved. Guarantees the hot module graph is instantiated before
+ * the caller touches any module — eliminating the concurrent cold-start race.
+ */
+export async function awaitRuntimeWarmup(): Promise<void> {
+	if (warmupPromise) await warmupPromise;
+}
+
+/**
+ * Test seam: reset the warmup state so tests can re-trigger it. Also lets
+ * tests verify idempotency by calling startRuntimeWarmup() multiple times.
+ */
+export function resetRuntimeWarmupForTest(): void {
+	warmupPromise = undefined;
+	warmupStarted = false;
+	warmupCompleted = false;
+	warmupDurationMs = undefined;
+	warmupError = undefined;
+}
+
+/** Test seam: has startRuntimeWarmup() been called? */
+export function isRuntimeWarmupStarted(): boolean {
+	return warmupStarted;
+}
+
+/**
+ * Diagnostic snapshot of warmup state for `team doctor`. Surfaces whether the
+ * v0.8.6 cold-start fix is active and how long the graph warmup took, so a
+ * session can confirm the fix loaded (post-restart) and isn't pathologically
+ * slow.
+ */
+export interface RuntimeWarmupStatus {
+	started: boolean;
+	completed: boolean;
+	durationMs: number | undefined;
+	error: string | undefined;
+}
+
+export function getRuntimeWarmupStatus(): RuntimeWarmupStatus {
+	return {
+		started: warmupStarted,
+		completed: warmupCompleted,
+		durationMs: warmupDurationMs,
+		error: warmupError,
+	};
+}

package/src/runtime/scheduler.ts

@@ -0,0 +1,353 @@
+export type ScheduleType = "cron" | "once" | "interval";
+
+export interface ScheduledJob {
+	id: string;
+	name: string;
+	description: string;
+	schedule: string;
+	scheduleType: ScheduleType;
+	intervalMs?: number;
+	subagentType: string;
+	prompt: string;
+	enabled: boolean;
+	createdAt: string;
+	lastRun?: string;
+	lastStatus?: "success" | "error" | "running";
+	nextRun?: string;
+	runCount: number;
+	/** Run IDs spawned by this job. Used to cancel runs when job is removed. */
+	spawnedRunIds?: string[];
+}
+
+export type ScheduleChangeEvent =
+	| { type: "added"; job: ScheduledJob }
+	| { type: "removed"; jobId: string; spawnedRunIds?: string[] }
+	| { type: "updated"; job: ScheduledJob }
+	| { type: "fired"; jobId: string; agentId: string; name: string }
+	| { type: "error"; jobId: string; error: string };
+
+export class CrewScheduler {
+	private jobs = new Map<string, ScheduledJob>();
+	private timers = new Map<string, ReturnType<typeof setInterval | typeof setTimeout>>();
+	private emit?: (event: ScheduleChangeEvent) => void;
+	private executor?: (job: ScheduledJob) => string;
+	private finalizer?: (jobId: string, agentId: string) => void;
+	private runCancelFn?: (runId: string) => void;
+
+	start(options: {
+		emit: (event: ScheduleChangeEvent) => void;
+		executor: (job: ScheduledJob) => string;
+		finalizer: (jobId: string, agentId: string) => void;
+		/** Optional callback to cancel a spawned run by runId. */
+		runCancelFn?: (runId: string) => void;
+	}): void {
+		this.emit = options.emit;
+		this.executor = options.executor;
+		this.finalizer = options.finalizer;
+		this.runCancelFn = options.runCancelFn;
+	}
+
+	stop(): void {
+		for (const t of this.timers.values()) {
+			clearInterval(t as ReturnType<typeof setInterval>);
+			clearTimeout(t as ReturnType<typeof setTimeout>);
+		}
+		this.timers.clear();
+		this.emit = undefined;
+		this.executor = undefined;
+		this.finalizer = undefined;
+		this.runCancelFn = undefined;
+	}
+
+	add(job: ScheduledJob): void {
+		this.jobs.set(job.id, job);
+		if (job.enabled) this.arm(job);
+		this.emit?.({ type: "added", job });
+	}
+
+	remove(id: string): boolean {
+		const job = this.jobs.get(id);
+		const spawnedRunIds = job?.spawnedRunIds;
+		this.disarm(id);
+		// Cancel all spawned runs that are still active
+		if (spawnedRunIds && this.runCancelFn) {
+			for (const runId of spawnedRunIds) {
+				try {
+					this.runCancelFn(runId);
+				} catch {
+					/* best-effort */
+				}
+			}
+		}
+		const ok = this.jobs.delete(id);
+		if (ok) this.emit?.({ type: "removed", jobId: id, spawnedRunIds });
+		return ok;
+	}
+
+	update(id: string, patch: Partial<ScheduledJob>): ScheduledJob | undefined {
+		const existing = this.jobs.get(id);
+		if (!existing) return undefined;
+		this.disarm(id);
+		const updated = { ...existing, ...patch };
+		this.jobs.set(id, updated);
+		if (updated.enabled) this.arm(updated);
+		this.emit?.({ type: "updated", job: updated });
+		return updated;
+	}
+
+	list(): ScheduledJob[] {
+		return [...this.jobs.values()];
+	}
+
+	/** Record a runId spawned by a job. Call this after executor fires. */
+	recordSpawnedRun(jobId: string, runId: string): void {
+		const job = this.jobs.get(jobId);
+		if (!job) return;
+		const spawnedRunIds = [...(job.spawnedRunIds ?? []), runId];
+		this.jobs.set(jobId, { ...job, spawnedRunIds });
+	}
+
+	private arm(job: ScheduledJob): void {
+		if (this.timers.has(job.id)) return;
+		if (job.scheduleType === "interval" && job.intervalMs) {
+			const t = setInterval(() => this.fire(job.id), job.intervalMs);
+			t.unref();
+			this.timers.set(job.id, t);
+		} else if (job.scheduleType === "once") {
+			const target = new Date(job.schedule).getTime();
+			const delay = target - Date.now();
+			if (delay > 0) {
+				const t = setTimeout(() => {
+					this.fire(job.id);
+					this.update(job.id, { enabled: false });
+				}, delay);
+				t.unref();
+				this.timers.set(job.id, t);
+			} else {
+				this.update(job.id, { enabled: false, lastStatus: "error" });
+				this.emit?.({
+					type: "error",
+					jobId: job.id,
+					error: `Scheduled time ${job.schedule} is in the past`,
+				});
+			}
+		}
+	}
+
+	private disarm(id: string): void {
+		const t = this.timers.get(id);
+		if (t) {
+			// Branch on timer type to use correct clear function
+			const job = this.jobs.get(id);
+			if (job?.scheduleType === "once") {
+				clearTimeout(t as ReturnType<typeof setTimeout>);
+			} else {
+				clearInterval(t as ReturnType<typeof setInterval>);
+			}
+			this.timers.delete(id);
+		}
+	}
+
+	private fire(id: string): void {
+		const job = this.jobs.get(id);
+		if (!job?.enabled || !this.executor) return;
+		this.update(id, { lastStatus: "running" });
+		let agentId: string;
+		try {
+			agentId = this.executor(job);
+		} catch (err) {
+			const error = err instanceof Error ? err.message : String(err);
+			this.update(id, {
+				lastRun: new Date().toISOString(),
+				lastStatus: "error",
+			});
+			this.emit?.({ type: "error", jobId: id, error });
+			return;
+		}
+		this.emit?.({ type: "fired", jobId: id, agentId, name: job.name });
+		this.finalizer?.(id, agentId);
+	}
+
+	static detectSchedule(s: string): {
+		type: ScheduleType;
+		intervalMs?: number;
+		normalized: string;
+	} {
+		const trimmed = s.trim();
+		// Relative: +10m
+		const rel = trimmed.match(/^\+(\d+)(s|m|h|d)$/);
+		if (rel) {
+			const ms = parseInt(rel[1], 10) * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[rel[2] as "s" | "m" | "h" | "d"];
+			return {
+				type: "once",
+				normalized: new Date(Date.now() + ms).toISOString(),
+			};
+		}
+		// Interval: 5m
+		const ivl = trimmed.match(/^(\d+)(s|m|h|d)$/);
+		if (ivl) {
+			const ms = parseInt(ivl[1], 10) * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[ivl[2] as "s" | "m" | "h" | "d"];
+			return { type: "interval", intervalMs: ms, normalized: trimmed };
+		}
+		// ISO timestamp
+		if (/^\d{4}-\d{2}-\d{2}T/.test(trimmed)) {
+			const d = new Date(trimmed);
+			if (!Number.isNaN(d.getTime())) {
+				if (d.getTime() <= Date.now()) throw new Error(`Scheduled time ${d.toISOString()} is in the past.`);
+				return { type: "once", normalized: d.toISOString() };
+			}
+		}
+		// Simple cron-like (5 fields)
+		const cronFields = trimmed.split(/\s+/);
+		if (cronFields.length >= 5) {
+			return { type: "cron", normalized: trimmed };
+		}
+		throw new Error(`Invalid schedule "${s}". Use "5m", "+10m", ISO timestamp, or cron expression.`);
+	}
+}
+
+export interface ScheduleSpec {
+	kind: "once" | "interval" | "cron";
+	spec: string;
+}
+
+function parseIntervalMs(s: string): number | undefined {
+	let ms = 0;
+	let remaining = s;
+	const unitMs: Record<string, number> = {
+		s: 1000,
+		m: 60_000,
+		h: 3_600_000,
+		d: 86_400_000,
+	};
+	while (remaining.length > 0) {
+		const m = remaining.match(/^(\d+)(s|m|h|d)/);
+		if (!m) return undefined;
+		ms += parseInt(m[1], 10) * unitMs[m[2]];
+		remaining = remaining.slice(m[0].length);
+	}
+	return ms;
+}
+
+function nextCronDate(spec: string, from: Date): Date | { error: string } | null {
+	const parts = spec.split(/\s+/);
+	if (parts.length < 5) return { error: "Invalid cron expression" };
+	const [minStr, hourStr, domStr, monthStr, dowStr] = parts;
+
+	function matchField(value: number, str: string, min: number, max: number): boolean {
+		if (str === "*") return true;
+		const n = parseInt(str, 10);
+		if (!Number.isNaN(n) && n >= min && n <= max && n === value) return true;
+		if (/^\d+-\d+$/.test(str)) {
+			const [a, b] = str.split("-").map(Number);
+			return value >= a && value <= b;
+		}
+		if (str.includes(",")) {
+			return str.split(",").some((part) => matchField(value, part.trim(), min, max));
+		}
+		return false;
+	}
+
+	let cursor = new Date(from.getTime());
+	cursor.setSeconds(0, 0);
+	cursor = new Date(cursor.getTime() + 60_000);
+
+	const maxIterations = 366 * 24 * 60;
+	for (let i = 0; i < maxIterations; i++) {
+		const min = cursor.getUTCMinutes();
+		const hour = cursor.getUTCHours();
+		const dom = cursor.getUTCDate();
+		const month = cursor.getUTCMonth() + 1;
+		const dow = cursor.getUTCDay();
+
+		if (
+			matchField(min, minStr, 0, 59) &&
+			matchField(hour, hourStr, 0, 23) &&
+			matchField(dom, domStr, 1, 31) &&
+			matchField(month, monthStr, 1, 12) &&
+			matchField(dow, dowStr, 0, 6)
+		) {
+			return cursor;
+		}
+
+		cursor = new Date(cursor.getTime() + 60_000);
+	}
+
+	return { error: "No next cron occurrence found within search window" };
+}
+
+export function parseSchedule(spec: string): ScheduleSpec | { error: string } {
+	const trimmed = spec.trim();
+	if (/^\d{4}-\d{2}-\d{2}T/.test(trimmed)) {
+		const d = new Date(trimmed);
+		if (!Number.isNaN(d.getTime())) {
+			return { kind: "once", spec: trimmed };
+		}
+	}
+	if (/^\+\d+(s|m|h|d)$/.test(trimmed)) {
+		return { kind: "once", spec: trimmed };
+	}
+	const ivlMs = parseIntervalMs(trimmed);
+	if (ivlMs !== undefined && ivlMs > 0) {
+		return { kind: "interval", spec: trimmed };
+	}
+	const fields = trimmed.split(/\s+/);
+	if (fields.length >= 5) {
+		return { kind: "cron", spec: trimmed };
+	}
+	return {
+		error: `Invalid schedule "${spec}". Use "5m", "+10m", ISO timestamp, or cron expression.`,
+	};
+}
+
+export function nextRunTime(spec: ScheduleSpec, from: Date = new Date()): Date | { error: string } {
+	if (spec.kind === "once") {
+		const rel = spec.spec.match(/^\+(\d+)(s|m|h|d)$/);
+		if (rel) {
+			const ms = parseInt(rel[1], 10) * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[rel[2] as "s" | "m" | "h" | "d"];
+			return new Date(from.getTime() + ms);
+		}
+		const d = new Date(spec.spec);
+		if (Number.isNaN(d.getTime())) {
+			return { error: `Invalid once schedule: ${spec.spec}` };
+		}
+		return d;
+	}
+	if (spec.kind === "interval") {
+		const ms = parseIntervalMs(spec.spec);
+		if (ms === undefined || ms <= 0) {
+			return { error: `Invalid interval: ${spec.spec}` };
+		}
+		return new Date(from.getTime() + ms);
+	}
+	if (spec.kind === "cron") {
+		const next = nextCronDate(spec.spec, from);
+		if (!next || !(next instanceof Date)) {
+			return (
+				(next as { error: string } | null) ?? {
+					error: "Invalid cron expression",
+				}
+			);
+		}
+		return next;
+	}
+	return {
+		error: `Unknown schedule kind: ${(spec as unknown as Record<string, unknown>).kind}`,
+	};
+}
+
+export function humanizeSchedule(spec: ScheduleSpec): string {
+	if (spec.kind === "once") {
+		if (/^\+\d+(s|m|h|d)$/.test(spec.spec)) {
+			return `once in ${spec.spec.slice(1)}`;
+		}
+		return `once at ${spec.spec}`;
+	}
+	if (spec.kind === "interval") {
+		return `every ${spec.spec}`;
+	}
+	if (spec.kind === "cron") {
+		return `cron ${spec.spec}`;
+	}
+	return "unknown schedule";
+}

package/src/runtime/semaphore.ts

@@ -0,0 +1,141 @@
+/**
+ * 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> = [];
+	// FIX (Round 15): Cap the waiter queue to prevent unbounded memory growth
+	// if the semaphore is held for a long period and many tasks accumulate.
+	static readonly MAX_QUEUE = 10_000;
+
+	constructor(max: number) {
+		this.#max = Math.max(1, max);
+	}
+
+	async acquire(): Promise<void> {
+		if (this.#current < this.#max) {
+			this.#current++;
+			return;
+		}
+		// FIX (Round 15): Reject when the waiter queue is full. The previous
+		// implementation let #queue grow without bound, risking memory
+		// exhaustion under sustained high concurrency with slow releases.
+		if (this.#queue.length >= Semaphore.MAX_QUEUE) {
+			throw new Error(`Semaphore queue full: ${this.#queue.length} waiters (max ${Semaphore.MAX_QUEUE}); cannot acquire slot`);
+		}
+		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`.
+ */
+/** @internal */
+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 };
+}