@shivaedev/work-fleet 0.0.0 → 0.1.1

package/src/engine/makeObserve.ts

@@ -0,0 +1,113 @@
+import { Effect, Option } from "effect";
+import { BadRequest } from "@shivaedev/platform/errors/taxonomy.ts";
+import type { EngineState } from "#engine/makeState.ts";
+import { observedAttempt } from "#engine/observedAttempt.ts";
+import { reconcileAttempt } from "#engine/reconcileAttempt.ts";
+import { recoverStall } from "#engine/recoverStall.ts";
+import { recoverUnobservable } from "#engine/recoverUnobservable.ts";
+import { retryTerminal } from "#engine/retryTerminal.ts";
+import { type Attempt, executing, type FleetRecord } from "#model.ts";
+import { reportedQuestion } from "#prompt/worker.ts";
+import type { SessionObservation } from "#session/schema.ts";
+import { validateReceipt } from "#session/validateReceipt.ts";
+import type { Versioned } from "#storage/model.ts";
+export function makeObserve(state: EngineState) {
+	const { sessions, load, save } = state;
+	return Effect.fn("Fleet.makeObserve")(function* (input: Versioned<FleetRecord>) {
+		const current = yield* observationRecord(state, input);
+		if (current === undefined) {
+			return input;
+		}
+		let stored = current;
+		const paused = stored.value.stage === "needs-human";
+		if (!observable(stored.value, paused)) {
+			return stored;
+		}
+		const latest = paused
+			? stored.value.attempts.findLast((attempt) => ["submitting", "accepted", "running"].includes(attempt.status))
+			: stored.value.attempts.at(-1);
+		if (latest === undefined) {
+			return yield* Effect.fail(new BadRequest({ message: "Execution lacks an intent" }));
+		}
+		if (state.launching.has(latest.operationId) || (paused && latest.receipt === undefined)) {
+			return stored;
+		}
+		const receipt = latest.receipt ?? (yield* reconcileAttempt(state)(stored, latest));
+		stored = yield* load(stored.value.workId);
+		const observation = yield* sessions.observe(receipt);
+		yield* validateReceipt(observation.receipt, receipt);
+		const attempts = stored.value.attempts.map((attempt) =>
+			attempt.operationId === latest.operationId ? observedAttempt(attempt, observation, state.policy.now()) : attempt,
+		);
+		stored = yield* save(stored, { ...stored.value, attempts, blocker: observationBlocker(stored.value, latest) });
+		return yield* advanceObservation(state, stored, observation, paused);
+	});
+}
+
+const observationRecord = Effect.fn("Fleet.observationRecord")(function* (state: EngineState, input: Versioned<FleetRecord>) {
+	const pending = input.value.attempts.at(-1);
+	if (pending !== undefined && state.launching.has(pending.operationId)) {
+		return undefined;
+	}
+	// A completed submission persists its receipt before releasing the launching guard.
+	return yield* state.load(input.value.workId);
+});
+
+function observationBlocker(record: FleetRecord, attempt: Attempt) {
+	return attempt.readRetry === undefined ? record.blocker : undefined;
+}
+
+function observable(record: FleetRecord, paused: boolean) {
+	return record.stage === "executing" || (paused && executing(record));
+}
+
+function finishObservation(state: EngineState) {
+	const { board, decision, reportInspection, save } = state;
+	return Effect.fn("Fleet.finishObservation")(function* (stored: Versioned<FleetRecord>, observation: SessionObservation, paused: boolean) {
+		if (stored.value.deliverable === "report") {
+			const work = yield* board.get(stored.value.workId);
+			yield* Option.match(reportInspection, { onNone: () => Effect.void, onSome: (inspection) => inspection.check(work) });
+		}
+		if (paused) {
+			return stored;
+		}
+		if (observation.execution !== "completed") {
+			if (yield* retryTerminal(state, stored.value, observation)) {
+				return yield* state.load(stored.value.workId);
+			}
+			return yield* decision(stored, "worker-terminal", terminalReason(observation), "Inspect the terminal evidence and retry or safely release");
+		}
+		const question = reportedQuestion(observation.output);
+		if (question !== undefined) {
+			return yield* decision(
+				stored,
+				"worker-question",
+				question.question,
+				"Record an answer to continue this worker thread",
+				observation.receipt,
+				question.attentionOwner,
+			);
+		}
+		return yield* save(stored, { ...stored.value, stage: "adopting" });
+	});
+}
+
+function terminalReason(observation: SessionObservation) {
+	return `Provider turn ${observation.receipt.turnId} ${observation.execution}${observation.error === undefined ? "" : `: ${observation.error}`}`;
+}
+
+const advanceObservation = Effect.fn("Fleet.advanceObservation")(function* (
+	state: EngineState,
+	stored: Versioned<FleetRecord>,
+	observation: SessionObservation,
+	paused: boolean,
+) {
+	const attempt = stored.value.attempts.find(
+		(entry) => entry.receipt?.turnId === observation.receipt.turnId && entry.receipt.sessionId === observation.receipt.sessionId,
+	);
+	const recovered = (yield* recoverUnobservable(state, stored, attempt)) ?? (yield* recoverStall(state, stored, attempt));
+	if (recovered !== undefined) {
+		return recovered;
+	}
+	return ["accepted", "running"].includes(observation.execution) ? stored : yield* finishObservation(state)(stored, observation, paused);
+});

package/src/engine/makeReview.ts

@@ -0,0 +1,104 @@
+import { Effect } from "effect";
+import { validateReview } from "#completion.ts";
+import { authorizeBriefContext } from "#engine/boardBrief.ts";
+import { makeDeliver } from "#engine/makeDeliver.ts";
+import type { EngineState } from "#engine/makeState.ts";
+import { observedAttempt } from "#engine/observedAttempt.ts";
+import { obtainReview, reviewMatchesBrief } from "#engine/obtainReview.ts";
+import { readOrContinueReview } from "#engine/readOrContinueReview.ts";
+import { recoverStall } from "#engine/recoverStall.ts";
+import { recoverUnobservable } from "#engine/recoverUnobservable.ts";
+import { refreshReviewResult } from "#engine/refreshReviewResult.ts";
+import { retryTerminal } from "#engine/retryTerminal.ts";
+import type { Attempt, FleetRecord } from "#model.ts";
+import type { BoardWork, Review, WorkResult } from "#policy.ts";
+import type { SessionObservation } from "#session/schema.ts";
+import type { Versioned } from "#storage/model.ts";
+
+export function makeReview(state: EngineState) {
+	const { sessions, load, save } = state;
+	return Effect.fn("Fleet.makeReview")(function* (input: Versioned<FleetRecord>, work: BoardWork) {
+		let stored = input;
+		const result = stored.value.result;
+		if (result === undefined || stored.value.stage !== "reviewing") {
+			return stored;
+		}
+		yield* authorizeBriefContext(stored.value, work);
+		if (stored.value.launchRetry !== undefined && state.policy.now() < stored.value.launchRetry.retryAt) {
+			return stored;
+		}
+		const receipt = yield* obtainReview(state)(stored, work, result);
+		stored = yield* load(stored.value.workId);
+		const observation = yield* sessions.observe(receipt);
+		const attempts = recordObservation(stored.value.attempts, observation, state.policy.now());
+		stored = yield* save(stored, { ...stored.value, attempts, blocker: undefined });
+		const latest = stored.value.attempts.at(-1);
+		const recovered = (yield* recoverUnobservable(state, stored, latest)) ?? (yield* recoverStall(state, stored, latest));
+		if (recovered !== undefined) {
+			return recovered;
+		}
+		if (["accepted", "running"].includes(observation.execution)) {
+			return stored;
+		}
+		const attempt = stored.value.attempts.find((entry) => entry.receipt?.turnId === receipt.turnId && entry.receipt.sessionId === receipt.sessionId);
+		if (!reviewMatchesBrief(attempt, work)) {
+			return stored;
+		}
+		return yield* finishReviewObservation(state)(stored, work, result, observation);
+	});
+}
+
+function finishReviewObservation(state: EngineState) {
+	const { load, decision } = state;
+	return Effect.fn("Fleet.finishReviewObservation")(function* (
+		input: Versioned<FleetRecord>,
+		work: BoardWork,
+		result: WorkResult,
+		observation: SessionObservation,
+	) {
+		const stored = yield* makeDeliver(state)(input);
+		if (stored.value.stage === "released" || stored.value.result?.head !== result.head) {
+			return stored;
+		}
+		const currentWork = yield* state.board.get(work.workId);
+		yield* authorizeBriefContext(stored.value, currentWork);
+		if (observation.execution !== "completed") {
+			if (yield* retryTerminal(state, stored.value, observation)) {
+				return yield* load(stored.value.workId);
+			}
+			return yield* decision(
+				stored,
+				"reviewer-terminal",
+				`Reviewer turn ${observation.execution}`,
+				"Inspect terminal reviewer evidence before retrying",
+			);
+		}
+		const review = yield* readOrContinueReview(state)(stored, work, result, observation.receipt, observation.output);
+		if (review === undefined) {
+			return yield* load(stored.value.workId);
+		}
+		return yield* finishReview(state)(stored, work, result, review);
+	});
+}
+
+function recordObservation(attempts: readonly Attempt[], observation: SessionObservation, now: number): readonly Attempt[] {
+	const { receipt } = observation;
+	return attempts.map((attempt) =>
+		attempt.receipt?.turnId === receipt.turnId && attempt.receipt.sessionId === receipt.sessionId
+			? observedAttempt(attempt, observation, now)
+			: attempt,
+	);
+}
+
+function finishReview(state: EngineState) {
+	const { save } = state;
+	return Effect.fn("Fleet.finishReview")(function* (stored: Versioned<FleetRecord>, work: BoardWork, result: WorkResult, review: Review) {
+		yield* validateReview(stored.value, review, result.head);
+		const reviewed = yield* save(stored, { ...stored.value, review });
+		const refreshed = yield* refreshReviewResult(state)(reviewed, work, result);
+		if (refreshed.value.result?.head !== review.head || refreshed.value.stage !== "reviewing") {
+			return refreshed;
+		}
+		return yield* save(refreshed, { ...refreshed.value, stage: review.verdict === "changes" ? "repairing" : "validating" });
+	});
+}

package/src/engine/makeState.ts

@@ -0,0 +1,89 @@
+import { Effect } from "effect";
+import { NotFound } from "@shivaedev/platform/errors/taxonomy.ts";
+import { type AttentionOwner, waitingOwner } from "#attention.ts";
+import type { DecisionCode } from "#DecisionCode.ts";
+import { originalWork } from "#engine/originalWork.ts";
+import { ReportInspection } from "#engine/ReportInspection.ts";
+import { FleetRepository } from "#engine/repository.ts";
+import type { Attempt, FleetRecord } from "#model.ts";
+import { BoardGateway, type BoardWork, type Decision, FleetIntegrations, FleetPolicy } from "#policy.ts";
+import { DEFAULT_AREA_MERGE_WAIT_MS } from "#scheduling/areas.ts";
+import type { SessionReceipt } from "#session/schema.ts";
+import { SessionService } from "#session/service.ts";
+import type { Versioned } from "#storage/model.ts";
+export const makeState = Effect.gen(function* () {
+	const store = yield* FleetRepository;
+	const board = yield* BoardGateway;
+	const policy = yield* FleetPolicy;
+	const integrations = yield* FleetIntegrations;
+	const sessions = yield* SessionService;
+	const reportInspection = yield* Effect.serviceOption(ReportInspection);
+	const launchScope = yield* Effect.scope;
+	const launching = new Set<string>();
+	function load(workId: string) {
+		return store
+			.load(workId)
+			.pipe(
+				Effect.flatMap((stored) =>
+					stored === undefined ? Effect.fail(new NotFound({ message: `Unknown Board work ${workId}` })) : Effect.succeed(stored),
+				),
+			);
+	}
+	function save(
+		stored: Versioned<FleetRecord>,
+		value: FleetRecord,
+		admission?: {
+			readonly role: Attempt["role"];
+			readonly quota: typeof policy.quota;
+		},
+	) {
+		return store.compareAndSet(
+			value.workId,
+			stored.version,
+			{ ...value, attentionOwner: waitingOwner(value) },
+			admission === undefined
+				? undefined
+				: {
+						scheduling: { areaMergeWaitMs: policy.areaMergeWaitMs ?? DEFAULT_AREA_MERGE_WAIT_MS, now: policy.now() },
+						...(admission.quota.available === undefined
+							? {}
+							: { quota: { available: admission.quota.available, observedAt: admission.quota.observedAt } }),
+						...(policy.executionConcurrency === undefined ? {} : { maxExecuting: policy.executionConcurrency }),
+						...(admission.role !== "worker" || policy.deliveryBacklog === undefined ? {} : { maxBacklog: policy.deliveryBacklog }),
+					},
+		);
+	}
+	const decision = Effect.fn("Fleet.decision")(function* (
+		stored: Versioned<FleetRecord>,
+		code: DecisionCode,
+		reason: string,
+		recommendation: string,
+		worker?: SessionReceipt,
+		attentionOwner: AttentionOwner = "orchestrator",
+		publicationWork?: BoardWork,
+	) {
+		const value: Decision = {
+			attentionOwner,
+			code,
+			id: `${stored.value.workId}.${stored.version}`,
+			...(publicationWork === undefined ? {} : { publicationWork }),
+			links: stored.value.result?.kind === "change" ? [stored.value.result.pr] : [],
+			reason,
+			recommendation,
+			...(worker === undefined ? {} : { worker }),
+		};
+		const updated = yield* save(stored, {
+			...stored.value,
+			attentionOwner,
+			blocker: undefined,
+			decision: value,
+			decisionPublished: false,
+			launchRetry: undefined,
+			stage: "needs-human",
+		});
+		const published = yield* board.decision(stored.value.workId, value, publicationWork ?? originalWork(stored.value));
+		return yield* save(updated, { ...updated.value, decision: { ...value, published }, decisionPublished: true });
+	});
+	return { board, decision, integrations, launching, launchScope, load, policy, reportInspection, save, sessions, store };
+});
+export type EngineState = Effect.Success<typeof makeState>;

package/src/engine/makeValidate.ts

@@ -0,0 +1,43 @@
+import { Effect } from "effect";
+import { validateChecks } from "#completion.ts";
+import { exhaustedCheckRepairs } from "#engine/exhaustedCheckRepairs.ts";
+import type { EngineState } from "#engine/makeState.ts";
+import type { FleetRecord } from "#model.ts";
+import type { BoardWork, Checks } from "#policy.ts";
+import type { Versioned } from "#storage/model.ts";
+export function makeValidate(state: EngineState) {
+	const { integrations, save } = state;
+	return Effect.fn("Fleet.makeValidate")(function* (input: Versioned<FleetRecord>, work: BoardWork) {
+		let stored = input;
+		const result = stored.value.result;
+		if (result === undefined) {
+			return stored;
+		}
+		const head = result.head;
+		if (stored.value.stage === "validating") {
+			const checks = yield* integrations.checks(work, result);
+			stored = yield* save(stored, { ...stored.value, blocker: undefined, checks });
+			if (checks.head === head && checks.pending && !checks.passed) {
+				return stored;
+			}
+			if (checks.head === head && checks.evidence.length > 0 && !checks.passed && checks.repairPrompt?.trim()) {
+				return yield* repairChecks(state, stored, checks);
+			}
+			yield* validateChecks(checks, head);
+			stored = yield* save(stored, { ...stored.value, blocker: undefined, checks, stage: "delivering" });
+		}
+		return stored;
+	});
+}
+
+function repairChecks(state: EngineState, stored: Versioned<FleetRecord>, checks: Checks) {
+	const exhausted = exhaustedCheckRepairs(stored.value, checks.failedChecks ?? []);
+	return exhausted.length === 0
+		? state.save(stored, { ...stored.value, blocker: undefined, stage: "repairing" })
+		: state.decision(
+				stored,
+				"checks-repair-exhausted",
+				`Required checks still fail after 3 consecutive check repairs: ${exhausted.join(", ")}`,
+				"Inspect the failing checks and decide whether to retry or release the work",
+			);
+}

package/src/engine/mergeReadiness.ts

@@ -0,0 +1,44 @@
+import { Effect } from "effect";
+import type { EngineState } from "#engine/makeState.ts";
+import type { FleetRecord } from "#model.ts";
+import { DEFAULT_AREA_MERGE_WAIT_MS, mergeWaitExpired } from "#scheduling/areas.ts";
+import type { Versioned } from "#storage/model.ts";
+
+export function invalidateMergeReadiness({ save }: EngineState, stored: Versioned<FleetRecord>) {
+	return stored.value.mergeReadyAt === undefined
+		? Effect.succeed(stored)
+		: save(stored, { ...stored.value, mergeReadyAt: undefined, mergeReadyHead: undefined });
+}
+
+export const awaitHumanMerge = Effect.fn("Fleet.awaitHumanMerge")(function* (
+	{ save, decision, policy }: EngineState,
+	stored: Versioned<FleetRecord>,
+	head: string,
+) {
+	const record = stored.value;
+	const ready =
+		record.mergeReadyAt !== undefined && record.mergeReadyHead === head
+			? stored
+			: yield* save(stored, { ...record, mergeReadyAt: policy.now(), mergeReadyHead: head });
+	if (
+		record.responses?.some((response) => response.decisionId === record.decision?.id && response.action === undefined)
+		|| record.decision?.code === "reviewed-pr-ready"
+	) {
+		return ready;
+	}
+	return yield* decision(
+		ready,
+		"reviewed-pr-ready",
+		"Reviewed PR is ready to merge",
+		"Merge the reviewed, green PR, or choose retry with an overall response to request changes on the same branch and PR",
+		undefined,
+		"maintainer",
+	);
+});
+
+export function expireMergeAreas({ save, policy }: EngineState, stored: Versioned<FleetRecord>) {
+	return stored.value.mergeAreasReleased !== true
+		&& mergeWaitExpired(stored.value, policy.now(), policy.areaMergeWaitMs ?? DEFAULT_AREA_MERGE_WAIT_MS)
+		? save(stored, { ...stored.value, mergeAreasReleased: true })
+		: Effect.succeed(stored);
+}

package/src/engine/observeDeliveryFailure.ts

@@ -0,0 +1,67 @@
+import { Effect } from "effect";
+import type { AttentionOwner } from "#attention.ts";
+import type { DecisionCode } from "#DecisionCode.ts";
+import { failureCode } from "#engine/failureCode.ts";
+import { failureContext } from "#engine/failureContext.ts";
+import type { EngineState } from "#engine/makeState.ts";
+import { invalidateMergeReadiness } from "#engine/mergeReadiness.ts";
+import { refreshReviewResult } from "#engine/refreshReviewResult.ts";
+import { requestConflictRepair } from "#engine/requestConflictRepair.ts";
+import { type FleetError, isFleetError } from "#errors.ts";
+import { executing, type FleetRecord } from "#model.ts";
+import type { ChangeResult } from "#policy.ts";
+import type { Versioned } from "#storage/model.ts";
+
+export const observeDeliveryFailure = Effect.fn("Fleet.observeDeliveryFailure")(function* (
+	state: EngineState,
+	stored: Versioned<FleetRecord>,
+	result: typeof ChangeResult.Type,
+	error: FleetError,
+) {
+	const { decision } = state;
+	const record = stored.value;
+	let current = stored;
+	function waitingDecision(code: DecisionCode, reason: string, recommendation: string, attentionOwner: AttentionOwner = "orchestrator") {
+		return record.decision?.code === code ? Effect.succeed(current) : decision(current, code, reason, recommendation, undefined, attentionOwner);
+	}
+
+	const repair = yield* requestConflictRepair(state, stored, error);
+	if (repair !== undefined) {
+		return repair;
+	}
+	if (
+		failureCode(error) === "pr-head-moved"
+		&& failureContext(error).head !== undefined
+		&& !executing(record)
+		&& (["delivering", "reviewing", "validating"].includes(record.stage)
+			|| (record.review?.verdict === "approved" && record.review.head === result.head))
+	) {
+		const work = yield* state.board.get(record.workId);
+		current = yield* invalidateMergeReadiness(state, stored);
+		return yield* refreshReviewResult(state)(current, work, result, failureContext(error).head).pipe(
+			Effect.catchIf(isFleetError, (refreshFailure) =>
+				Effect.gen(function* () {
+					if (refreshFailure._tag === "ServiceUnavailable") {
+						return record.decision === undefined ? yield* Effect.fail(refreshFailure) : current;
+					}
+					return yield* waitingDecision(
+						failureCode(refreshFailure),
+						refreshFailure.message,
+						"Inspect the current PR result before retrying or releasing this work",
+						failureContext(refreshFailure).attentionOwner,
+					);
+				}),
+			),
+		);
+	}
+	if (error._tag === "ServiceUnavailable") {
+		return record.decision === undefined ? yield* Effect.fail(error) : stored;
+	}
+	current = yield* invalidateMergeReadiness(state, stored);
+	return yield* waitingDecision(
+		failureCode(error),
+		error.message,
+		"Inspect the adopted PR and its delivery evidence before retrying or releasing this work",
+		failureContext(error).attentionOwner,
+	);
+});

package/src/engine/observeRenewal.ts

@@ -0,0 +1,36 @@
+import { Effect } from "effect";
+import { Forbidden } from "@shivaedev/platform/errors/taxonomy.ts";
+import type { EngineState } from "#engine/makeState.ts";
+import type { Attempt, FleetRecord } from "#model.ts";
+import type { BoardWork } from "#policy.ts";
+import type { SessionReceipt } from "#session/schema.ts";
+import type { Versioned } from "#storage/model.ts";
+
+export function observeRenewal({ sessions, save }: EngineState) {
+	return Effect.fn("Fleet.observeRenewal")(function* (stored: Versioned<FleetRecord>, worker: Attempt, receipt: SessionReceipt) {
+		const observation = yield* sessions
+			.observe(receipt)
+			.pipe(Effect.mapError(() => new Forbidden({ message: "Existing worker observation is unavailable; reconcile ownership before renewal" })));
+		if (observation.receipt.sessionId !== receipt.sessionId || observation.receipt.turnId !== receipt.turnId) {
+			return yield* Effect.fail(
+				new Forbidden({ message: "Existing worker observation changed the exact receipt; reconcile ownership before renewal" }),
+			);
+		}
+		const attempts = stored.value.attempts.map((attempt) =>
+			attempt.operationId === worker.operationId ? { ...attempt, output: observation.output, status: observation.execution } : attempt,
+		);
+		const observed = yield* save(stored, { ...stored.value, attempts });
+		if (observation.execution === "accepted" || observation.execution === "running") {
+			return yield* Effect.fail(new Forbidden({ message: "Existing worker is not confirmed terminal; reconcile before renewal" }));
+		}
+		return { observation, observed };
+	});
+}
+export const priorBoardWork = Effect.fn("Fleet.priorBoardWork")(function* (record: FleetRecord, work: BoardWork) {
+	const context = record.boardContext;
+	const sourcePath = record.boardSourcePath;
+	if (context === undefined || sourcePath === undefined) {
+		return yield* Effect.fail(new Forbidden({ message: "Prior Board context is unavailable; reconcile existing result ownership before renewal" }));
+	}
+	return { ...work, context, revision: record.boardRevision, sourcePath };
+});

package/src/engine/observedAttempt.ts

@@ -0,0 +1,17 @@
+import type { Attempt } from "#model.ts";
+import type { SessionObservation } from "#session/schema.ts";
+
+export function observedAttempt(attempt: Attempt, observation: SessionObservation, now: number): Attempt {
+	const signature = observation.progress === undefined ? undefined : JSON.stringify(observation.progress);
+	const progress = signature === undefined || signature === attempt.progress?.signature ? attempt.progress : { at: now, signature };
+	return {
+		...attempt,
+		missingSince: observation.turnMissing ? (attempt.missingSince ?? now) : undefined,
+		observationRetries: observation.turnMissing ? attempt.observationRetries : undefined,
+		output: observation.output,
+		progress,
+		readRetry: undefined,
+		receipt: observation.receipt,
+		status: observation.execution,
+	};
+}

package/src/engine/obtainReview.ts

@@ -0,0 +1,148 @@
+import { Effect, Result } from "effect";
+import { admit } from "#admit.ts";
+import { workRevision } from "#board/workRevision.ts";
+import { validateReview } from "#completion.ts";
+import { launchObservationRetries } from "#engine/launchObservationRetries.ts";
+import type { EngineState } from "#engine/makeState.ts";
+import { reconcileAttempt } from "#engine/reconcileAttempt.ts";
+import { submissionFailure } from "#engine/submissionFailure.ts";
+import type { Attempt, FleetRecord } from "#model.ts";
+import type { BoardWork, WorkResult } from "#policy.ts";
+import { policyGuidance } from "#policyGuidance.ts";
+import { readReviewerVerdict, reviewerPrompt } from "#prompt/reviewer.ts";
+import type { Versioned } from "#storage/model.ts";
+
+export function obtainReview(state: EngineState) {
+	const { store, policy, sessions, save, board } = state;
+	return Effect.fn("Fleet.obtainReview")(function* (
+		stored: Versioned<FleetRecord>,
+		work: BoardWork,
+		result: WorkResult,
+		retry?: {
+			readonly prompt: string;
+			readonly sessionId: string;
+			readonly stallRecovery: Attempt["stallRecovery"];
+			readonly observationRetries?: number;
+		},
+	) {
+		if (stored.value.review?.head === result.head) {
+			return stored.value.review.receipt;
+		}
+		const previous = stored.value.attempts.at(-1);
+		const continuation = retry ?? stalledReviewRetry(previous, policy.now());
+		const previousHead = reviewAttemptHead(stored.value, previous);
+		const unusable = yield* invalidPriorReview(stored.value, previous, result.head);
+		if (reusableReview(previous, work, result.head, previousHead, unusable)) {
+			return previous.receipt ?? (yield* reconcileAttempt(state)(stored, previous));
+		}
+		const reviewerGuidance = yield* policyGuidance(policy, "reviewer");
+		const prompt =
+			continuation?.prompt
+			?? reviewerPrompt({
+				result,
+				...(reviewerGuidance === undefined ? {} : { reviewerGuidance }),
+				...(policy.sharedEnvironment === undefined ? {} : { sharedEnvironment: policy.sharedEnvironment }),
+				task: work.context,
+			});
+
+		const settings = { ...policy.launch };
+		const attempt: Attempt = {
+			observationRetries: launchObservationRetries(stored.value, retry?.observationRetries),
+			operationId: policy.operationId(),
+			prompt,
+			providerFailures: stored.value.launchRetry?.rejections,
+			reviewHead: result.head,
+			reviewRevision: workRevision(work.revision, work.context),
+			role: "reviewer",
+			sessionId: continuation?.sessionId,
+			settings,
+			stallRecovery: continuation?.stallRecovery,
+			status: "submitting",
+			submittedAt: policy.now(),
+		};
+		const quota = yield* policy.refreshQuota === undefined ? Effect.succeed(policy.quota) : policy.refreshQuota();
+		yield* admit(
+			work,
+			(yield* store.list()).map(({ value }) => value),
+			{ ...policy, quota },
+			board.get,
+		);
+		yield* save(
+			stored,
+			{
+				...stored.value,
+				attempts: [...stored.value.attempts, attempt],
+				launchRetry: undefined,
+				mergeAreasReleased: undefined,
+				mergeReadyAt: undefined,
+				mergeReadyHead: undefined,
+			},
+			{ quota, role: "reviewer" },
+		);
+		const input = {
+			access: "read-only",
+			cwd: stored.value.cwd,
+			operationId: attempt.operationId,
+			prompt,
+			settings,
+		} as const;
+		return yield* (continuation === undefined ? sessions.start(input) : sessions.continue({ ...input, sessionId: continuation.sessionId })).pipe(
+			Effect.tapError((error) =>
+				submissionFailure(state, stored.value.workId, attempt.operationId, error, "Restore provider access and retry this review"),
+			),
+		);
+	});
+}
+
+function reviewAttemptHead(record: FleetRecord, attempt: Attempt | undefined) {
+	const review = record.review;
+	const reviewedHead =
+		review !== undefined && review.receipt.sessionId === attempt?.receipt?.sessionId && review.receipt.turnId === attempt?.receipt?.turnId
+			? review.head
+			: undefined;
+	return attempt?.reviewHead ?? reviewedHead;
+}
+
+const invalidPriorReview = Effect.fn("Fleet.invalidPriorReview")(function* (record: FleetRecord, previous: Attempt | undefined, head: string) {
+	if (
+		record.responses?.at(-1)?.action !== "retry"
+		|| previous?.status !== "completed"
+		|| previous.role !== "reviewer"
+		|| previous.receipt === undefined
+	) {
+		return false;
+	}
+	const parsed = yield* readReviewerVerdict(previous.output ?? "", previous.receipt).pipe(
+		Effect.tap((review) => validateReview(record, review, head)),
+		Effect.result,
+	);
+	return Result.isFailure(parsed);
+});
+
+export function reviewMatchesBrief(attempt: Attempt | undefined, work: BoardWork): boolean {
+	return attempt?.reviewRevision === undefined || attempt.reviewRevision === workRevision(work.revision, work.context);
+}
+
+function reusableReview(
+	previous: Attempt | undefined,
+	work: BoardWork,
+	head: string,
+	previousHead: string | undefined,
+	unusable: boolean,
+): previous is Attempt {
+	return (
+		previous?.role === "reviewer"
+		&& !(unusable || ["failed", "interrupted"].includes(previous.status))
+		&& (previous.status !== "completed" || reviewMatchesBrief(previous, work))
+		&& (previousHead === undefined || previousHead === head)
+	);
+}
+
+function stalledReviewRetry(previous: Attempt | undefined, now: number) {
+	return previous?.role === "reviewer"
+		&& previous.status === "interrupted"
+		&& previous.stallRecovery?.interruptRequestedAt !== undefined
+		&& previous.receipt !== undefined
+		? { prompt: previous.prompt ?? "Continue the review", sessionId: previous.receipt.sessionId, stallRecovery: { count: 2, lastActionAt: now } }
+		: undefined;
+}