pi-crew 0.1.4 → 0.1.6

package/src/runtime/team-runner.ts

@@ -1,13 +1,20 @@
 import type { AgentConfig } from "../agents/agent-config.ts";
-import type { CrewLimitsConfig } from "../config/config.ts";
+import type { CrewLimitsConfig, CrewRuntimeConfig } from "../config/config.ts";
+import type { CrewRuntimeCapabilities } from "./runtime-resolver.ts";
 import { writeArtifact } from "../state/artifact-store.ts";
 import { appendEvent } from "../state/event-log.ts";
 import type { TeamConfig } from "../teams/team-config.ts";
-import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import type { ArtifactDescriptor, PolicyDecision, TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { saveRunManifest, saveRunTasks, updateRunStatus } from "../state/state-store.ts";
 import { aggregateUsage, formatUsage } from "../state/usage.ts";
 import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
 import { evaluateCrewPolicy, summarizePolicyDecisions } from "./policy-engine.ts";
+import { buildRecoveryLedger } from "./recovery-recipes.ts";
+import { getReadyTasks, refreshTaskGraphQueues, taskGraphSnapshot } from "./task-graph-scheduler.ts";
+import { checkBranchFreshness } from "../worktree/branch-freshness.ts";
+import { aggregateTaskOutputs } from "./task-output-context.ts";
+import { recordFromTask, saveCrewAgents } from "./crew-agent-records.ts";
+import { deliverGroupJoin, resolveGroupJoinMode } from "./group-join.ts";
 import { runTeamTask } from "./task-runner.ts";
 
 export interface ExecuteTeamRunInput {
@@ -18,12 +25,13 @@ export interface ExecuteTeamRunInput {
 	agents: AgentConfig[];
 	executeWorkers: boolean;
 	limits?: CrewLimitsConfig;
+	runtime?: CrewRuntimeCapabilities;
+	runtimeConfig?: CrewRuntimeConfig;
 	signal?: AbortSignal;
 }
 
 function findReadyTask(tasks: TeamTaskState[]): TeamTaskState | undefined {
-	const completedStepIds = new Set(tasks.filter((task) => task.status === "completed").map((task) => task.stepId).filter((id): id is string => id !== undefined));
-	return tasks.find((task) => task.status === "queued" && task.dependsOn.every((dep) => completedStepIds.has(dep)));
+	return getReadyTasks(tasks, 1)[0];
 }
 
 function findStep(workflow: WorkflowConfig, task: TeamTaskState): WorkflowStep {
@@ -42,6 +50,26 @@ function markBlocked(tasks: TeamTaskState[], reason: string): TeamTaskState[] {
 	return tasks.map((task) => task.status === "queued" ? { ...task, status: "skipped", error: reason, finishedAt: new Date().toISOString(), graph: task.graph ? { ...task.graph, queue: "blocked" } : undefined } : task);
 }
 
+function mergeArtifacts(items: ArtifactDescriptor[]): ArtifactDescriptor[] {
+	const byPath = new Map<string, ArtifactDescriptor>();
+	for (const item of items) byPath.set(item.path, item);
+	return [...byPath.values()];
+}
+
+function mergeTaskUpdates(base: TeamTaskState[], results: Array<{ tasks: TeamTaskState[] }>): TeamTaskState[] {
+	let merged = base;
+	for (const result of results) {
+		for (const updated of result.tasks) {
+			const current = merged.find((task) => task.id === updated.id);
+			if (!current) continue;
+			if (updated.status !== current.status || updated.finishedAt || updated.startedAt || updated.resultArtifact || updated.error) {
+				merged = merged.map((task) => task.id === updated.id ? updated : task);
+			}
+		}
+	}
+	return refreshTaskGraphQueues(merged);
+}
+
 function formatTaskProgress(task: TeamTaskState): string {
 	return `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${task.taskPacket ? ` scope=${task.taskPacket.scope}` : ""}${task.verification ? ` green=${task.verification.observedGreenLevel}/${task.verification.requiredGreenLevel}` : ""}${task.error ? ` - ${task.error}` : ""}`;
 }
@@ -49,6 +77,7 @@ function formatTaskProgress(task: TeamTaskState): string {
 function writeProgress(manifest: TeamRunManifest, tasks: TeamTaskState[], producer: string): TeamRunManifest {
 	const counts = new Map<string, number>();
 	for (const task of tasks) counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
+	const queue = taskGraphSnapshot(tasks);
 	const progress = writeArtifact(manifest.artifactsRoot, {
 		kind: "progress",
 		relativePath: "progress.md",
@@ -61,6 +90,7 @@ function writeProgress(manifest: TeamRunManifest, tasks: TeamTaskState[], produc
 			`Workflow: ${manifest.workflow ?? "(none)"}`,
 			`Updated: ${new Date().toISOString()}`,
 			`Task counts: ${[...counts.entries()].map(([status, count]) => `${status}=${count}`).join(", ") || "none"}`,
+			`Queue: ready=${queue.ready.length}, blocked=${queue.blocked.length}, running=${queue.running.length}, done=${queue.done.length}, failed=${queue.failed.length}, cancelled=${queue.cancelled.length}`,
 			"",
 			"## Tasks",
 			...tasks.map(formatTaskProgress),
@@ -71,22 +101,49 @@ function writeProgress(manifest: TeamRunManifest, tasks: TeamTaskState[], produc
 }
 
 function applyPolicy(manifest: TeamRunManifest, tasks: TeamTaskState[], limits?: CrewLimitsConfig): TeamRunManifest {
-	const decisions = evaluateCrewPolicy({ manifest, tasks, limits });
+	const branchFreshness = checkBranchFreshness(manifest.cwd);
+	const branchArtifact = writeArtifact(manifest.artifactsRoot, {
+		kind: "metadata",
+		relativePath: "metadata/branch-freshness.json",
+		producer: "branch-freshness",
+		content: `${JSON.stringify(branchFreshness, null, 2)}\n`,
+	});
+	let decisions: PolicyDecision[] = evaluateCrewPolicy({ manifest, tasks, limits });
+	if (branchFreshness.status === "stale" || branchFreshness.status === "diverged") {
+		const branchDecision: PolicyDecision = {
+			action: "notify",
+			reason: "branch_stale",
+			message: branchFreshness.message,
+			createdAt: new Date().toISOString(),
+		};
+		decisions = [...decisions, branchDecision];
+		appendEvent(manifest.eventsPath, { type: "branch.stale", runId: manifest.runId, message: branchFreshness.message, data: { branchFreshness } });
+	}
 	const policyArtifact = writeArtifact(manifest.artifactsRoot, {
 		kind: "metadata",
 		relativePath: "policy-decisions.json",
 		producer: "policy-engine",
 		content: `${JSON.stringify(decisions, null, 2)}\n`,
 	});
+	const recoveryLedger = buildRecoveryLedger(decisions);
+	const recoveryArtifact = writeArtifact(manifest.artifactsRoot, {
+		kind: "metadata",
+		relativePath: "recovery-ledger.json",
+		producer: "recovery-engine",
+		content: `${JSON.stringify(recoveryLedger, null, 2)}\n`,
+	});
 	for (const item of decisions) appendEvent(manifest.eventsPath, { type: item.action === "escalate" ? "policy.escalated" : "policy.action", runId: manifest.runId, taskId: item.taskId, message: item.message, data: { action: item.action, reason: item.reason } });
-	return { ...manifest, updatedAt: new Date().toISOString(), policyDecisions: decisions, artifacts: [...manifest.artifacts.filter((artifact) => !(artifact.kind === "metadata" && artifact.path.endsWith("policy-decisions.json"))), policyArtifact] };
+	for (const item of recoveryLedger.entries) appendEvent(manifest.eventsPath, { type: item.state === "escalation_required" ? "recovery.escalated" : "recovery.attempted", runId: manifest.runId, taskId: item.taskId, message: item.message, data: { scenario: item.scenario, steps: item.steps, attempt: item.attempt, state: item.state } });
+	return { ...manifest, updatedAt: new Date().toISOString(), policyDecisions: decisions, artifacts: [...manifest.artifacts.filter((artifact) => !(artifact.kind === "metadata" && (artifact.path.endsWith("policy-decisions.json") || artifact.path.endsWith("recovery-ledger.json") || artifact.path.endsWith("branch-freshness.json")))), branchArtifact, policyArtifact, recoveryArtifact] };
 }
 
 export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
 	let manifest = updateRunStatus(input.manifest, "running", input.executeWorkers ? "Executing team workflow." : "Creating workflow prompts and placeholder results.");
-	let tasks = input.tasks;
+	let tasks = refreshTaskGraphQueues(input.tasks);
 	manifest = writeProgress(manifest, tasks, "team-runner");
 	saveRunManifest(manifest);
+	const runtimeKind = input.runtime?.kind ?? (input.executeWorkers ? "child-process" : "scaffold");
+	saveCrewAgents(manifest, tasks.map((task) => recordFromTask(manifest, task, runtimeKind)));
 
 	while (tasks.some((task) => task.status === "queued")) {
 		if (input.signal?.aborted) {
@@ -104,19 +161,34 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 			return { manifest, tasks };
 		}
 
-		const task = findReadyTask(tasks);
-		if (!task) {
+		const maxConcurrent = Math.max(1, input.limits?.maxConcurrentWorkers ?? 1);
+		const readyBatch = getReadyTasks(tasks, maxConcurrent);
+		if (readyBatch.length === 0) {
 			tasks = markBlocked(tasks, "No ready queued task; dependency graph may be invalid.");
 			saveRunTasks(manifest, tasks);
 			manifest = updateRunStatus(manifest, "blocked", "No ready queued task.");
 			return { manifest, tasks };
 		}
 
-		const step = findStep(input.workflow, task);
-		const agent = findAgent(input.agents, task);
-		const result = await runTeamTask({ manifest, tasks, task, step, agent, signal: input.signal, executeWorkers: input.executeWorkers });
-		manifest = result.manifest;
-		tasks = result.tasks;
+		appendEvent(manifest.eventsPath, { type: "task.progress", runId: manifest.runId, message: `Starting ready batch with ${readyBatch.length} task(s).`, data: { taskIds: readyBatch.map((task) => task.id), maxConcurrent } });
+		const results = await Promise.all(readyBatch.map((task) => {
+			const step = findStep(input.workflow, task);
+			const agent = findAgent(input.agents, task);
+			return runTeamTask({ manifest, tasks, task, step, agent, signal: input.signal, executeWorkers: input.executeWorkers });
+		}));
+		manifest = { ...results.at(-1)!.manifest, artifacts: mergeArtifacts([manifest.artifacts, ...results.map((item) => item.manifest.artifacts)].flat()) };
+		tasks = mergeTaskUpdates(tasks, results);
+		saveRunTasks(manifest, tasks);
+		saveCrewAgents(manifest, tasks.map((task) => recordFromTask(manifest, task, runtimeKind)));
+		const completedBatch = readyBatch.map((task) => tasks.find((item) => item.id === task.id) ?? task);
+		const batchArtifact = writeArtifact(manifest.artifactsRoot, {
+			kind: "summary",
+			relativePath: `batches/${readyBatch.map((task) => task.id).join("+")}.md`,
+			producer: "team-runner",
+			content: aggregateTaskOutputs(completedBatch),
+		});
+		const groupDelivery = deliverGroupJoin({ manifest, mode: resolveGroupJoinMode(input.runtimeConfig), batch: readyBatch, allTasks: tasks });
+		manifest = { ...manifest, artifacts: mergeArtifacts([...manifest.artifacts, batchArtifact, ...(groupDelivery?.artifact ? [groupDelivery.artifact] : [])]) };
 		manifest = writeProgress(manifest, tasks, "team-runner");
 		saveRunManifest(manifest);
 	}

package/src/runtime/worker-startup.ts

@@ -0,0 +1,57 @@
+export type WorkerLifecycleState = "spawning" | "trust_required" | "ready_for_prompt" | "running" | "finished" | "failed";
+export type StartupFailureClassification = "trust_required" | "prompt_misdelivery" | "prompt_acceptance_timeout" | "transport_dead" | "worker_crashed" | "unknown";
+
+export interface WorkerStartupEvidence {
+	lastLifecycleState: WorkerLifecycleState;
+	command: string;
+	promptSentAt?: string;
+	promptAccepted: boolean;
+	trustPromptDetected: boolean;
+	transportHealthy: boolean;
+	childProcessAlive: boolean;
+	elapsedMs: number;
+	classification: StartupFailureClassification;
+	stderrPreview?: string;
+}
+
+export function detectTrustPrompt(text: string): boolean {
+	const lowered = text.toLowerCase();
+	return lowered.includes("do you trust") || lowered.includes("trust this") || lowered.includes("untrusted") || lowered.includes("workspace trust") || lowered.includes("allow this folder");
+}
+
+export function classifyStartupFailure(evidence: Omit<WorkerStartupEvidence, "classification">): StartupFailureClassification {
+	if (!evidence.transportHealthy) return "transport_dead";
+	if (evidence.trustPromptDetected || evidence.lastLifecycleState === "trust_required") return "trust_required";
+	if (evidence.promptSentAt && !evidence.promptAccepted && evidence.childProcessAlive) return "prompt_acceptance_timeout";
+	if (evidence.promptSentAt && !evidence.promptAccepted && !evidence.childProcessAlive) return "worker_crashed";
+	if (evidence.stderrPreview?.toLowerCase().includes("command not found") || evidence.stderrPreview?.toLowerCase().includes("not recognized")) return "prompt_misdelivery";
+	if (!evidence.childProcessAlive && evidence.lastLifecycleState !== "finished") return "worker_crashed";
+	return "unknown";
+}
+
+export function createStartupEvidence(input: {
+	command: string;
+	startedAt: Date;
+	finishedAt?: Date;
+	promptSentAt?: Date;
+	promptAccepted?: boolean;
+	stderr?: string;
+	error?: string;
+	exitCode?: number | null;
+}): WorkerStartupEvidence {
+	const stderrPreview = (input.error || input.stderr || "").slice(0, 500) || undefined;
+	const trustPromptDetected = detectTrustPrompt(stderrPreview ?? "");
+	const childProcessAlive = input.exitCode === undefined || input.exitCode === null ? !input.finishedAt : false;
+	const base: Omit<WorkerStartupEvidence, "classification"> = {
+		lastLifecycleState: input.error || (input.exitCode !== undefined && input.exitCode !== null && input.exitCode !== 0) ? "failed" : input.finishedAt ? "finished" : "running",
+		command: input.command,
+		promptSentAt: input.promptSentAt?.toISOString(),
+		promptAccepted: input.promptAccepted ?? !input.error,
+		trustPromptDetected,
+		transportHealthy: !input.error || !/enoent|spawn|transport/i.test(input.error),
+		childProcessAlive,
+		elapsedMs: Math.max(0, (input.finishedAt ?? new Date()).getTime() - input.startedAt.getTime()),
+		stderrPreview,
+	};
+	return { ...base, classification: classifyStartupFailure(base) };
+}

package/src/state/contracts.ts

@@ -42,10 +42,15 @@ export const TEAM_EVENT_TYPES = [
 	"task.red",
 	"task.completed",
 	"task.failed",
+	"task.cancelled",
+	"task.skipped",
 	"review.approved",
 	"review.rejected",
 	"policy.action",
 	"policy.escalated",
+	"recovery.attempted",
+	"recovery.escalated",
+	"branch.stale",
 	"mailbox.timeout",
 	"worktree.cleanup",
 	"worktree.dirty",
@@ -64,6 +69,8 @@ export const TEAM_WAKEABLE_EVENT_TYPES: ReadonlySet<TeamEventType> = new Set([
 	"run.cancelled",
 	"task.completed",
 	"task.failed",
+	"task.cancelled",
+	"task.skipped",
 	"async.completed",
 	"async.failed",
 	"async.stale",

package/src/state/event-log.ts

@@ -1,6 +1,33 @@
+import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+export type TeamEventProvenance = "live_worker" | "test" | "healthcheck" | "replay" | "api" | "background" | "team_runner";
+export type TeamWatcherAction = "act" | "observe" | "ignore";
+
+export interface TeamEventSessionIdentity {
+	title: string;
+	workspace: string;
+	purpose: string;
+	placeholderReason?: string;
+}
+
+export interface TeamEventOwnership {
+	owner: string;
+	workflowScope: string;
+	watcherAction: TeamWatcherAction;
+}
+
+export interface TeamEventMetadata {
+	seq: number;
+	provenance: TeamEventProvenance;
+	sessionIdentity?: TeamEventSessionIdentity;
+	ownership?: TeamEventOwnership;
+	nudgeId?: string;
+	fingerprint?: string;
+	confidence?: "low" | "medium" | "high";
+}
+
 export interface TeamEvent {
 	time: string;
 	type: string;
@@ -8,11 +35,52 @@ export interface TeamEvent {
 	taskId?: string;
 	message?: string;
 	data?: Record<string, unknown>;
+	metadata?: TeamEventMetadata;
 }
 
-export function appendEvent(eventsPath: string, event: Omit<TeamEvent, "time">): TeamEvent {
+export type AppendTeamEvent = Omit<TeamEvent, "time" | "metadata"> & { metadata?: Partial<TeamEventMetadata> };
+
+const TERMINAL_EVENT_TYPES = new Set(["run.blocked", "run.completed", "run.failed", "run.cancelled", "task.completed", "task.failed", "task.cancelled", "task.skipped"]);
+
+function nextSequence(eventsPath: string): number {
+	if (!fs.existsSync(eventsPath)) return 1;
+	let max = 0;
+	for (const line of fs.readFileSync(eventsPath, "utf-8").split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			const event = JSON.parse(line) as TeamEvent;
+			max = Math.max(max, event.metadata?.seq ?? 0);
+		} catch {
+			max += 1;
+		}
+	}
+	return max + 1;
+}
+
+export function computeEventFingerprint(event: Pick<TeamEvent, "type" | "runId" | "taskId" | "data">): string {
+	return createHash("sha256").update(JSON.stringify({ type: event.type, runId: event.runId, taskId: event.taskId, data: event.data ?? null })).digest("hex").slice(0, 16);
+}
+
+export function appendEvent(eventsPath: string, event: AppendTeamEvent): TeamEvent {
 	fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
-	const fullEvent: TeamEvent = { time: new Date().toISOString(), ...event };
+	const baseMetadata = event.metadata;
+	let metadata: TeamEventMetadata = {
+		seq: baseMetadata?.seq ?? nextSequence(eventsPath),
+		provenance: baseMetadata?.provenance ?? "team_runner",
+		...(baseMetadata?.sessionIdentity ? { sessionIdentity: baseMetadata.sessionIdentity } : {}),
+		...(baseMetadata?.ownership ? { ownership: baseMetadata.ownership } : {}),
+		...(baseMetadata?.nudgeId ? { nudgeId: baseMetadata.nudgeId } : {}),
+		...(baseMetadata?.confidence ? { confidence: baseMetadata.confidence } : {}),
+	};
+	const fullEvent: TeamEvent = {
+		time: new Date().toISOString(),
+		...event,
+		metadata,
+	};
+	if (baseMetadata?.fingerprint || TERMINAL_EVENT_TYPES.has(fullEvent.type)) {
+		metadata = { ...metadata, fingerprint: baseMetadata?.fingerprint ?? computeEventFingerprint(fullEvent) };
+		fullEvent.metadata = metadata;
+	}
 	fs.appendFileSync(eventsPath, `${JSON.stringify(fullEvent)}\n`, "utf-8");
 	return fullEvent;
 }
@@ -25,3 +93,17 @@ export function readEvents(eventsPath: string): TeamEvent[] {
 		.filter(Boolean)
 		.map((line) => JSON.parse(line) as TeamEvent);
 }
+
+export function dedupeTerminalEvents(events: TeamEvent[]): TeamEvent[] {
+	const seen = new Set<string>();
+	const output: TeamEvent[] = [];
+	for (const event of events) {
+		const fingerprint = event.metadata?.fingerprint;
+		if (fingerprint && TERMINAL_EVENT_TYPES.has(event.type)) {
+			if (seen.has(fingerprint)) continue;
+			seen.add(fingerprint);
+		}
+		output.push(event);
+	}
+	return output;
+}

package/src/state/state-store.ts

@@ -97,7 +97,18 @@ export function createRunManifest(params: {
 	fs.mkdirSync(paths.artifactsRoot, { recursive: true });
 	atomicWriteJson(paths.manifestPath, manifest);
 	atomicWriteJson(paths.tasksPath, tasks);
-	appendEvent(paths.eventsPath, { type: "run.created", runId: paths.runId, data: { team: params.team.name, workflow: params.workflow?.name } });
+	appendEvent(paths.eventsPath, {
+		type: "run.created",
+		runId: paths.runId,
+		data: { team: params.team.name, workflow: params.workflow?.name },
+		metadata: {
+			seq: 1,
+			provenance: "team_runner",
+			sessionIdentity: { title: params.team.name, workspace: params.cwd, purpose: params.goal },
+			ownership: { owner: params.team.name, workflowScope: params.workflow?.name ?? "manual", watcherAction: "act" },
+			confidence: "high",
+		},
+	});
 	return { manifest, tasks, paths };
 }
 
@@ -115,7 +126,17 @@ export function updateRunStatus(manifest: TeamRunManifest, status: TeamRunManife
 	}
 	const updated: TeamRunManifest = { ...manifest, status, updatedAt: new Date().toISOString(), summary: summary ?? manifest.summary };
 	saveRunManifest(updated);
-	appendEvent(updated.eventsPath, { type: `run.${status}`, runId: updated.runId, message: summary });
+	appendEvent(updated.eventsPath, {
+		type: `run.${status}`,
+		runId: updated.runId,
+		message: summary,
+		metadata: {
+			provenance: "team_runner",
+			sessionIdentity: { title: updated.team, workspace: updated.cwd, purpose: updated.goal },
+			ownership: { owner: updated.team, workflowScope: updated.workflow ?? "manual", watcherAction: "act" },
+			confidence: "high",
+		},
+	});
 	return updated;
 }
 

package/src/state/types.ts

@@ -1,6 +1,7 @@
 import type { TeamRunStatus, TeamTaskStatus } from "./contracts.ts";
 import type { TaskClaimState } from "./task-claims.ts";
 import type { WorkerHeartbeatState } from "../runtime/worker-heartbeat.ts";
+import type { CrewAgentProgress } from "../runtime/crew-agent-runtime.ts";
 export type { TeamRunStatus, TeamTaskStatus } from "./contracts.ts";
 
 export interface ArtifactDescriptor {
@@ -137,12 +138,14 @@ export interface TeamTaskState {
 	promptArtifact?: ArtifactDescriptor;
 	resultArtifact?: ArtifactDescriptor;
 	logArtifact?: ArtifactDescriptor;
+	transcriptArtifact?: ArtifactDescriptor;
 	startedAt?: string;
 	finishedAt?: string;
 	exitCode?: number | null;
 	modelAttempts?: ModelAttemptState[];
 	usage?: UsageState;
 	jsonEvents?: number;
+	agentProgress?: CrewAgentProgress;
 	error?: string;
 	claim?: TaskClaimState;
 	heartbeat?: WorkerHeartbeatState;

package/src/worktree/branch-freshness.ts

@@ -0,0 +1,45 @@
+import { execFileSync } from "node:child_process";
+
+export type BranchFreshnessStatus = "fresh" | "stale" | "diverged" | "unknown";
+export type StaleBranchPolicy = "warn" | "block" | "auto_rebase" | "auto_merge_forward";
+
+export interface BranchFreshness {
+	status: BranchFreshnessStatus;
+	branch?: string;
+	mainRef: string;
+	ahead: number;
+	behind: number;
+	missingFixes: string[];
+	message: string;
+	error?: string;
+}
+
+function git(cwd: string, args: string[]): string {
+	return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function count(cwd: string, range: string): number {
+	const raw = git(cwd, ["rev-list", "--count", range]);
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) ? parsed : 0;
+}
+
+export function checkBranchFreshness(cwd: string, mainRef = "main"): BranchFreshness {
+	try {
+		git(cwd, ["rev-parse", "--is-inside-work-tree"]);
+		const branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+		const behind = count(cwd, `${branch}..${mainRef}`);
+		const ahead = count(cwd, `${mainRef}..${branch}`);
+		const missingFixes = behind > 0 ? git(cwd, ["log", "--format=%s", `${branch}..${mainRef}`]).split("\n").map((line) => line.trim()).filter(Boolean) : [];
+		if (behind === 0) return { status: "fresh", branch, mainRef, ahead, behind, missingFixes, message: `Branch '${branch}' is fresh against ${mainRef}.` };
+		if (ahead > 0) return { status: "diverged", branch, mainRef, ahead, behind, missingFixes, message: `Branch '${branch}' diverged from ${mainRef}: ahead=${ahead}, behind=${behind}.` };
+		return { status: "stale", branch, mainRef, ahead, behind, missingFixes, message: `Branch '${branch}' is ${behind} commit(s) behind ${mainRef}.` };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { status: "unknown", mainRef, ahead: 0, behind: 0, missingFixes: [], message: "Branch freshness could not be determined.", error: message };
+	}
+}
+
+export function shouldBlockForBranchFreshness(freshness: BranchFreshness, policy: StaleBranchPolicy = "warn"): boolean {
+	return policy === "block" && (freshness.status === "stale" || freshness.status === "diverged");
+}