pi-crew 0.9.53 → 0.9.55

package/src/runtime/goal-state-store.ts

@@ -0,0 +1,219 @@
+/**
+ * goal-state-store.ts — Persistent outer state for the autonomous goal loop (P0/P1).
+ *
+ * Spec: research-findings/goal-workflow/00-SPEC.md §2.3
+ * Plan: research-findings/goal-workflow/07-PLAN.md v3 §0b G2 (one manifest per turn,
+ * goal loop owns OUTER state) + §0c C10 (hardening: assertSafePathId + UUID goalId).
+ *
+ * Stores GoalLoopState as atomic JSON at <crewRoot>/state/goals/<goalId>.json.
+ * Modeled on ScheduleStore (state/schedule.ts:86) but with atomicWriteJson +
+ * path-traversal defense (assertSafePathId on every public method).
+ *
+ * Per §0c C2: budget lives here (budgetUsed accumulates collectRunMetrics across turns);
+ * per-turn usage stays on each turn's TeamRunManifest/tasks.json.
+ */
+
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { dirname } from "node:path";
+import { atomicWriteJson } from "../state/atomic-write.ts";
+import { appendEvent } from "../state/event-log.ts";
+import type { GoalLoopState, GoalLoopStatus } from "../state/types.ts";
+import { createRunId } from "../utils/ids.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import { projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
+import { assertSafePathId } from "../utils/safe-paths.ts";
+
+/** Default state-root resolver: project scope if a project crew-root exists, else user scope. */
+function resolveGoalsRoot(cwd: string): string {
+	const crewRoot = projectCrewRoot(cwd) ?? userCrewRoot();
+	return `${crewRoot}/state/goals`;
+}
+
+/** Goal file path for a goalId. Asserts the id is path-safe (§0c C10). */
+function goalFilePath(cwd: string, goalId: string): string {
+	assertSafePathId("goalId", goalId);
+	return `${resolveGoalsRoot(cwd)}/${goalId}.json`;
+}
+
+/**
+ * GoalStore — CRUD for GoalLoopState files.
+ *
+ * Concurrency: writes are atomic (temp+rename+fsync via atomicWriteJson). For
+ * read-modify-write sequences under contention, callers should coordinate via
+ * GoalLoopState.state transitions (cooperative, the goal loop is single-writer
+ * between turns). There is no file-lock here because the loop is the sole writer
+ * during its lifetime; `goal stop`/`pause`/`resume` from another session flip
+ * state fields that the loop checks between turns (cooperative, §0c C11).
+ */
+export class GoalStore {
+	private readonly cwd: string;
+
+	constructor(cwd: string) {
+		this.cwd = cwd;
+	}
+
+	/** Generate a fresh, path-safe goalId (never user-derived — §0c C10). */
+	createGoalId(): string {
+		return createRunId("goal");
+	}
+
+	/** Load a goal by id. Returns undefined if missing/corrupt. Throws on unsafe goalId (§0c C10). */
+	load(goalId: string): GoalLoopState | undefined {
+		// Path-safety check runs BEFORE the try/catch so traversal attempts throw (not silently return undefined).
+		const path = goalFilePath(this.cwd, goalId);
+		try {
+			if (!existsSync(path)) return undefined;
+			const raw = readFileSync(path, "utf-8");
+			const parsed = JSON.parse(raw);
+			if (!parsed || typeof parsed !== "object" || typeof parsed.goalId !== "string") return undefined;
+			return parsed as GoalLoopState;
+		} catch {
+			return undefined;
+		}
+	}
+
+	/** Atomically persist a goal state. Emits a goal.state_changed event if eventsPath given. */
+	save(state: GoalLoopState, eventsPath?: string): void {
+		assertSafePathId("goalId", state.goalId);
+		const path = goalFilePath(this.cwd, state.goalId);
+		const next = { ...state, updatedAt: new Date().toISOString() };
+		try {
+			mkdirSync(dirname(path), { recursive: true });
+			atomicWriteJson(path, next);
+			if (eventsPath) {
+				appendEvent(eventsPath, {
+					type: "goal.state_changed",
+					runId: state.goalId,
+					data: { goalId: state.goalId, state: state.state },
+				});
+			}
+		} catch (error) {
+			logInternalError("goal-state-store.save", error, `goalId=${state.goalId}`);
+			throw error;
+		}
+	}
+
+	/** Patch a goal's top-level fields (e.g. state, turnsUsed, budgetUsed, currentRunId). */
+	patch(goalId: string, patch: Partial<GoalLoopState>, eventsPath?: string): GoalLoopState | undefined {
+		const current = this.load(goalId);
+		if (!current) return undefined;
+		const next: GoalLoopState = {
+			...current,
+			...patch,
+			goalId: current.goalId,
+			createdAt: current.createdAt,
+		};
+		this.save(next, eventsPath);
+		return next;
+	}
+
+	/** Convenience: transition state with optional event emission. */
+	setStatus(goalId: string, state: GoalLoopStatus, eventsPath?: string): GoalLoopState | undefined {
+		return this.patch(goalId, { state }, eventsPath);
+	}
+
+	/**
+	 * Compare-And-Set status for atomic stuck↔resume transitions (P1b, RFC v0.5 §P1b).
+	 *
+	 * Loads current state; if `current.state === expected`, sets it to `next`,
+	 * persists, and emits a `goal.state_changed` event (reusing the save()
+	 * emission pattern). Otherwise returns undefined (CAS failed — no mutation,
+	 * no event). This prevents lost updates when the background loop and a
+	 * `goal resume`/idle-sweeper session race to flip `state`.
+	 *
+	 * Legal P1b transitions enforced by callers (not by this method):
+	 *   running → stuck,  stuck → running,  stuck → cancelled.
+	 */
+	/**
+	 * Cross-process-safe compare-and-set (cold-review #2 HIGH #2 fix).
+	 *
+	 * The synchronous read-check-write is only atomic within one event loop. `goal resume` runs
+	 * in a DIFFERENT process than the (exited) loop, so two concurrent resumes both see
+	 * `stuck`, both pass the CAS, both spawn → double background loops, double budget burn.
+	 *
+	 * Fix: wrap the read-modify-write in an O_EXCL lockfile per goalId. O_EXCL is atomic at the
+	 * OS level — only one process can create the lockfile. The operation is fast (ms), so stale
+	 * lockfiles are rare; a 5s age guard force-clears them (crash recovery).
+	 */
+	compareAndSetStatus(goalId: string, expected: GoalLoopStatus, next: GoalLoopStatus, eventsPath?: string): GoalLoopState | undefined {
+		const lockPath = `${goalFilePath(this.cwd, goalId)}.cas.lock`;
+		if (!this.acquireCasLock(lockPath)) {
+			return undefined; // Another process holds the CAS lock — caller treats as CAS-failed.
+		}
+		try {
+			const current = this.load(goalId);
+			if (!current) return undefined;
+			if (current.state !== expected) return undefined; // CAS failed — state moved underneath us.
+			const updated: GoalLoopState = { ...current, state: next };
+			this.save(updated, eventsPath);
+			return updated;
+		} finally {
+			try {
+				unlinkSync(lockPath);
+			} catch {
+				/* best-effort; may already be gone */
+			}
+		}
+	}
+
+	/** Acquire an O_EXCL lockfile for CAS, with stale-lock recovery (5s age guard). */
+	private acquireCasLock(lockPath: string): boolean {
+		try {
+			const fd = openSync(lockPath, "wx"); // O_EXCL — throws EEXIST if already exists.
+			closeSync(fd);
+			return true;
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code !== "EEXIST") return false;
+			// Stale recovery: if the lockfile is older than 5s, force-delete and retry once.
+			try {
+				const stat = statSync(lockPath);
+				if (Date.now() - stat.mtimeMs > 5000) {
+					unlinkSync(lockPath);
+					const fd = openSync(lockPath, "wx");
+					closeSync(fd);
+					return true;
+				}
+			} catch {
+				/* fall through */
+			}
+			return false;
+		}
+	}
+
+	/** Remove a goal file (used by `goal clear`). Returns true if deleted. */
+	remove(goalId: string): boolean {
+		try {
+			const path = goalFilePath(this.cwd, goalId);
+			if (!existsSync(path)) return false;
+			unlinkSync(path);
+			return true;
+		} catch (error) {
+			logInternalError("goal-state-store.remove", error, `goalId=${goalId}`);
+			return false;
+		}
+	}
+
+	/** List all known goals (newest first by updatedAt). */
+	list(): GoalLoopState[] {
+		try {
+			const root = resolveGoalsRoot(this.cwd);
+			if (!existsSync(root)) return [];
+			const entries = readdirSync(root) as string[];
+			const goals: GoalLoopState[] = [];
+			for (const entry of entries) {
+				if (!entry.endsWith(".json")) continue;
+				const goalId = entry.slice(0, -".json".length);
+				// Skip entries that fail the safe-id check (defensive; createGoalId always produces safe ids).
+				if (!/^[A-Za-z0-9_-]+$/.test(goalId)) continue;
+				const g = this.load(goalId);
+				if (g) goals.push(g);
+			}
+			goals.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
+			return goals;
+		} catch (error) {
+			logInternalError("goal-state-store.list", error, `cwd=${this.cwd}`);
+			return [];
+		}
+	}
+}

package/src/runtime/green-contract.ts

@@ -0,0 +1,55 @@
+import type { GreenLevel, VerificationContract, VerificationEvidence } from "../state/types.ts";
+
+const GREEN_ORDER: Record<GreenLevel, number> = {
+	none: 0,
+	targeted: 1,
+	package: 2,
+	workspace: 3,
+	merge_ready: 4,
+};
+
+export interface GreenContractOutcome {
+	requiredGreenLevel: GreenLevel;
+	observedGreenLevel: GreenLevel;
+	satisfied: boolean;
+}
+
+export function greenLevelSatisfies(observed: GreenLevel, required: GreenLevel): boolean {
+	return GREEN_ORDER[observed] >= GREEN_ORDER[required];
+}
+
+export function evaluateGreenContract(contract: VerificationContract, evidence?: VerificationEvidence): GreenContractOutcome {
+	const observedGreenLevel = evidence?.observedGreenLevel ?? "none";
+	return {
+		requiredGreenLevel: contract.requiredGreenLevel,
+		observedGreenLevel,
+		satisfied: greenLevelSatisfies(observedGreenLevel, contract.requiredGreenLevel),
+	};
+}
+
+export function inferGreenLevelFromTask(success: boolean, contract: VerificationContract): GreenLevel {
+	if (!success) return "none";
+	if (contract.requiredGreenLevel === "none") return "none";
+	return contract.allowManualEvidence ? contract.requiredGreenLevel : "targeted";
+}
+
+export function createVerificationEvidence(contract: VerificationContract, success: boolean, notes: string): VerificationEvidence {
+	const observedGreenLevel = inferGreenLevelFromTask(success, contract);
+	const outcome = evaluateGreenContract(contract, {
+		requiredGreenLevel: contract.requiredGreenLevel,
+		observedGreenLevel,
+		satisfied: false,
+		commands: [],
+		notes,
+	});
+	return {
+		requiredGreenLevel: contract.requiredGreenLevel,
+		observedGreenLevel,
+		satisfied: outcome.satisfied,
+		commands: contract.commands.map((cmd) => ({
+			cmd,
+			status: "not_run" as const,
+		})),
+		notes,
+	};
+}

package/src/runtime/group-join.ts

@@ -0,0 +1,267 @@
+import type { CrewRuntimeConfig } from "../config/config.ts";
+import { writeArtifact } from "../state/artifact-store.ts";
+import { appendEvent } from "../state/event-log.ts";
+import { appendMailboxMessage, findMailboxMessageByRequestId, readDeliveryState } from "../state/mailbox.ts";
+import type { ArtifactDescriptor, TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { aggregateTaskOutputs } from "./task-output-context.ts";
+
+export type CrewGroupJoinMode = "off" | "group" | "smart";
+
+export interface CrewGroupJoinDelivery {
+	batchId: string;
+	mode: CrewGroupJoinMode;
+	partial: boolean;
+	taskIds: string[];
+	completed: string[];
+	failed: string[];
+	skipped: string[];
+	remaining: string[];
+	artifact?: ArtifactDescriptor;
+	messageId?: string;
+	requestId?: string;
+	ackRequired?: boolean;
+	ackStatus?: "pending" | "acknowledged";
+}
+
+export function resolveGroupJoinMode(runtime?: CrewRuntimeConfig): CrewGroupJoinMode {
+	return runtime?.groupJoin ?? "smart";
+}
+
+export function shouldGroupJoin(mode: CrewGroupJoinMode, batch: TeamTaskState[]): boolean {
+	if (mode === "off") return false;
+	if (mode === "group") return batch.length > 0;
+	return batch.length > 1;
+}
+
+function batchIdFor(runId: string, taskIds: string[]): string {
+	return `${runId}_${taskIds.join("+").replace(/[^a-zA-Z0-9_+-]/g, "_")}`;
+}
+
+function requestIdFor(runId: string, batchId: string, partial: boolean): string {
+	return `${runId}:group-join:${partial ? "partial" : "completed"}:${batchId}`;
+}
+
+function statusList(tasks: TeamTaskState[], status: TeamTaskState["status"]): string[] {
+	return tasks.filter((task) => task.status === status).map((task) => task.id);
+}
+
+export function deliverGroupJoin(input: {
+	manifest: TeamRunManifest;
+	mode: CrewGroupJoinMode;
+	batch: TeamTaskState[];
+	allTasks: TeamTaskState[];
+	partial?: boolean;
+}): CrewGroupJoinDelivery | undefined {
+	if (!shouldGroupJoin(input.mode, input.batch)) return undefined;
+	const taskIds = input.batch.map((task) => task.id);
+	const latest = taskIds
+		.map((id) => input.allTasks.find((task) => task.id === id))
+		.filter((task): task is TeamTaskState => Boolean(task));
+	const completed = statusList(latest, "completed");
+	const failed = statusList(latest, "failed");
+	const skipped = statusList(latest, "skipped");
+	const remaining = latest.filter((task) => task.status === "queued" || task.status === "running").map((task) => task.id);
+	const partial = input.partial ?? remaining.length > 0;
+	const batchId = batchIdFor(input.manifest.runId, taskIds);
+	const summary = aggregateTaskOutputs(latest, input.manifest);
+	const requestId = requestIdFor(input.manifest.runId, batchId, partial);
+	const existingMailbox = findMailboxMessageByRequestId(input.manifest, requestId);
+	const existingStatus = existingMailbox
+		? (readDeliveryState(input.manifest).messages[existingMailbox.id] ?? existingMailbox.status)
+		: undefined;
+	const delivery: CrewGroupJoinDelivery = {
+		batchId,
+		mode: input.mode,
+		partial,
+		taskIds,
+		completed,
+		failed,
+		skipped,
+		remaining,
+		requestId,
+		ackRequired: true,
+		ackStatus: existingStatus === "acknowledged" ? "acknowledged" : "pending",
+	};
+	const content = `${JSON.stringify({ ...delivery, createdAt: new Date().toISOString() }, null, 2)}\n`;
+	const artifact = writeArtifact(input.manifest.artifactsRoot, {
+		kind: "metadata",
+		relativePath: `metadata/group-joins/${batchId}.json`,
+		producer: "group-join",
+		content,
+	});
+	const mailbox =
+		existingMailbox ??
+		appendMailboxMessage(input.manifest, {
+			direction: "outbox",
+			from: "group-join",
+			to: "leader",
+			body: [
+				`Group join ${partial ? "partial" : "completed"}: ${taskIds.join(", ")}`,
+				`Request: ${requestId}`,
+				`Completed: ${completed.join(", ") || "none"}`,
+				`Failed: ${failed.join(", ") || "none"}`,
+				`Skipped: ${skipped.join(", ") || "none"}`,
+				`Remaining: ${remaining.join(", ") || "none"}`,
+				"",
+				summary,
+			].join("\n"),
+			status: "delivered",
+			data: {
+				kind: "group_join",
+				requestId,
+				batchId,
+				partial,
+				ackRequired: true,
+				taskIds,
+				completed,
+				failed,
+				skipped,
+				remaining,
+			},
+		});
+	appendEvent(input.manifest.eventsPath, {
+		type: partial ? "agent.group_join.partial" : "agent.group_join.completed",
+		runId: input.manifest.runId,
+		message: `Group join ${partial ? "partial" : "completed"} for ${taskIds.length} task(s).`,
+		data: {
+			...delivery,
+			artifactPath: artifact.path,
+			messageId: mailbox.id,
+			fallback: "mailbox-delivered",
+			reused: Boolean(existingMailbox),
+		},
+	});
+	if (existingMailbox)
+		appendEvent(input.manifest.eventsPath, {
+			type: "agent.group_join.delivery_reused",
+			runId: input.manifest.runId,
+			message: `Reused group join mailbox delivery for ${taskIds.length} task(s).`,
+			data: { requestId, messageId: mailbox.id, batchId, partial },
+		});
+	return { ...delivery, artifact, messageId: mailbox.id };
+}
+
+import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
+
+export type JoinMode = "async" | "group" | "smart";
+export type DeliveryCallback = (records: CrewAgentRecord[], partial: boolean) => void;
+
+interface AgentGroup {
+	groupId: string;
+	agentIds: Set<string>;
+	completedRecords: Map<string, CrewAgentRecord>;
+	timeoutHandle?: ReturnType<typeof setTimeout>;
+	delivered: boolean;
+	isStraggler: boolean;
+}
+
+const DEFAULT_TIMEOUT = 30_000;
+const STRAGGLER_TIMEOUT = 15_000;
+
+export class GroupJoinManager {
+	private groups = new Map<string, AgentGroup>();
+	private agentToGroup = new Map<string, string>();
+
+	private deliverCb: DeliveryCallback;
+	private groupTimeout: number;
+
+	constructor(deliverCb: DeliveryCallback, groupTimeout = DEFAULT_TIMEOUT) {
+		this.deliverCb = deliverCb;
+		this.groupTimeout = groupTimeout;
+	}
+
+	registerGroup(groupId: string, agentIds: string[]): void {
+		const group: AgentGroup = {
+			groupId,
+			agentIds: new Set(agentIds),
+			completedRecords: new Map(),
+			delivered: false,
+			isStraggler: false,
+		};
+		this.groups.set(groupId, group);
+		for (const id of agentIds) {
+			this.agentToGroup.set(id, groupId);
+		}
+	}
+
+	onAgentComplete(record: CrewAgentRecord): "delivered" | "held" | "pass" {
+		const groupId = this.agentToGroup.get(record.taskId);
+		if (!groupId) return "pass";
+
+		const group = this.groups.get(groupId);
+		if (!group || group.delivered) return "pass";
+
+		group.completedRecords.set(record.taskId, record);
+
+		if (group.completedRecords.size >= group.agentIds.size) {
+			this.deliver(group, false);
+			return "delivered";
+		}
+
+		if (!group.timeoutHandle) {
+			const timeout = group.isStraggler ? STRAGGLER_TIMEOUT : this.groupTimeout;
+			group.timeoutHandle = setTimeout(() => {
+				this.onTimeout(group);
+			}, timeout);
+		}
+
+		return "held";
+	}
+
+	private onTimeout(group: AgentGroup): void {
+		if (group.delivered) return;
+		group.timeoutHandle = undefined;
+
+		const remaining = new Set<string>();
+		for (const id of group.agentIds) {
+			if (!group.completedRecords.has(id)) remaining.add(id);
+		}
+
+		for (const id of group.completedRecords.keys()) {
+			this.agentToGroup.delete(id);
+		}
+
+		this.deliverCb([...group.completedRecords.values()], true);
+
+		group.completedRecords.clear();
+		group.agentIds = remaining;
+		group.isStraggler = true;
+
+		// Re-arm timer for remaining stragglers so they aren't silently abandoned
+		if (remaining.size > 0) {
+			group.timeoutHandle = setTimeout(() => this.onTimeout(group), STRAGGLER_TIMEOUT);
+			group.timeoutHandle.unref();
+		}
+	}
+
+	private deliver(group: AgentGroup, partial: boolean): void {
+		if (group.timeoutHandle) {
+			clearTimeout(group.timeoutHandle);
+			group.timeoutHandle = undefined;
+		}
+		group.delivered = true;
+		this.deliverCb([...group.completedRecords.values()], partial);
+		this.cleanupGroup(group.groupId);
+	}
+
+	private cleanupGroup(groupId: string): void {
+		const group = this.groups.get(groupId);
+		if (!group) return;
+		for (const id of group.agentIds) {
+			this.agentToGroup.delete(id);
+		}
+		this.groups.delete(groupId);
+	}
+
+	isGrouped(agentId: string): boolean {
+		return this.agentToGroup.has(agentId);
+	}
+
+	dispose(): void {
+		for (const group of this.groups.values()) {
+			if (group.timeoutHandle) clearTimeout(group.timeoutHandle);
+		}
+		this.groups.clear();
+		this.agentToGroup.clear();
+	}
+}