@shivaedev/work-fleet 0.5.0 → 0.7.0

package/src/engine/dispatchCommand.ts

@@ -1,14 +1,11 @@
 import { Effect, Result } from "effect";
-import { Forbidden } from "@shivaedev/platform/errors/taxonomy.ts";
-import { waitingOwner } from "#attention.ts";
 import { approveDispatchedBrief } from "#engine/approveBrief.ts";
 import { authorizeBriefContext } from "#engine/boardBrief.ts";
+import { dispatchFailure } from "#engine/dispatchFailure.ts";
 import { failureCode } from "#engine/failureCode.ts";
-import { failureMessage } from "#engine/failureMessage.ts";
-import { failureOwner } from "#engine/failureOwner.ts";
 import type { makeLaunch } from "#engine/makeLaunch.ts";
 import type { EngineState } from "#engine/makeState.ts";
-import { clearIntegrationRetry, readRetry, retryPending } from "#engine/readRetry.ts";
+import { clearIntegrationRetry, retryPending } from "#engine/readRetry.ts";
 import { refreshBrief } from "#engine/refreshBrief.ts";
 import { releaseClosedPreparation } from "#engine/releaseClosedPreparation.ts";
 import type { DispatchNow, FleetRecord } from "#model.ts";
@@ -57,26 +54,7 @@ export function dispatchCommand(state: EngineState, launch: ReturnType<typeof ma
 		) {
 			stored = yield* save(stored, { ...stored.value, preparation: assessment.preparation });
 		}
-		return yield* launch(stored, "worker", stored.value.prompt).pipe(
-			Effect.catch((error) =>
-				Effect.gen(function* () {
-					const current = yield* load(workId);
-					if (current.value.stage !== "prepared") {
-						return current;
-					}
-					const waiting = {
-						...current.value,
-						admissionReady: !(error instanceof Forbidden),
-						attentionOwner: failureOwner(error),
-						blocker: failureMessage(error),
-					};
-					if (!sameWait(current.value, waiting)) {
-						yield* save(current, waiting);
-					}
-					return yield* Effect.fail(error);
-				}),
-			),
-		);
+		return yield* launch(stored, "worker", stored.value.prompt);
 	});
 	return Effect.fn("Fleet.dispatch")(function* (workId: string, prompt?: string, now?: DispatchNow) {
 		const current = yield* load(workId);
@@ -88,12 +66,7 @@ export function dispatchCommand(state: EngineState, launch: ReturnType<typeof ma
 		}
 		return yield* dispatchPrepared(workId, prompt, now).pipe(
 			Effect.flatMap((updated) => clearIntegrationRetry(state, updated)),
-			Effect.catch((error) =>
-				Effect.gen(function* () {
-					const retrying = yield* readRetry(state, yield* load(workId), error);
-					return retrying === undefined ? yield* Effect.fail(error) : retrying;
-				}),
-			),
+			Effect.catch((error) => dispatchFailure(state, workId, error)),
 		);
 	});
 }
@@ -105,8 +78,3 @@ function requestedNow(record: FleetRecord, now: DispatchNow | undefined): FleetR
 	}
 	return { ...record, dispatchNow: now };
 }
-
-// Every scheduler pass retries waiting work, so rewriting an unchanged wait would make each pass write and notify once per waiter.
-function sameWait(current: FleetRecord, waiting: FleetRecord) {
-	return current.blocker === waiting.blocker && current.admissionReady === waiting.admissionReady && current.attentionOwner === waitingOwner(waiting);
-}

package/src/engine/dispatchFailure.ts

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+import { waitingOwner } from "#attention.ts";
+import { failureMessage } from "#engine/failureMessage.ts";
+import { failureOwner } from "#engine/failureOwner.ts";
+import type { EngineState } from "#engine/makeState.ts";
+import { releaseMissingBoardWork } from "#engine/missingBoardWork.ts";
+import { readRetry } from "#engine/readRetry.ts";
+
+export const dispatchFailure = Effect.fn("Fleet.dispatchFailure")(function* <E>(state: EngineState, workId: string, error: E) {
+	const current = yield* state.load(workId);
+	const released = yield* releaseMissingBoardWork(state, current, error);
+	if (released !== undefined) {
+		return released;
+	}
+	const retrying = yield* readRetry(state, current, error);
+	if (retrying !== undefined) {
+		return retrying;
+	}
+	const waiting = { ...current.value, attentionOwner: failureOwner(error), blocker: failureMessage(error) };
+	// Unchanged waits must not write and wake every subscriber on every scheduler pass.
+	if (current.value.stage === "prepared" && (current.value.blocker !== waiting.blocker || current.value.attentionOwner !== waitingOwner(waiting))) {
+		yield* state.save(current, waiting);
+	}
+	return yield* Effect.fail(error);
+});

package/src/engine/failureCode.ts

@@ -24,7 +24,7 @@ export function failureCode(error: unknown): DecisionCode {
 		return error.code ?? `session-${error.reason}`;
 	}
 	if (error instanceof BoardFailure) {
-		return error.code ?? "board-failure";
+		return error.code === "board-item-missing" ? "board-failure" : (error.code ?? "board-failure");
 	}
 	return "integration-failure";
 }

package/src/engine/health.ts

@@ -1,5 +1,5 @@
 import { Clock, Context, Effect, Ref } from "effect";
-import type { CapacityRejection, FleetHealth, SourceFailure } from "@shivaedev/work-board/integration/diagnostics.ts";
+import type { CapacityRejection, FleetHealth, SourceFailure } from "@shivaedev/work-board/server/integration/diagnostics.ts";
 import type { SessionObservation } from "#session/schema.ts";
 
 export interface HealthState {

package/src/engine/makeDeliver.ts

@@ -2,6 +2,7 @@ import { Effect, Result } from "effect";
 import { validateChecks, validateReview } from "#completion.ts";
 import { authorizeBriefContext } from "#engine/boardBrief.ts";
 import { failureCode } from "#engine/failureCode.ts";
+import { failureOwner } from "#engine/failureOwner.ts";
 import type { EngineState } from "#engine/makeState.ts";
 import { awaitHumanMerge, expireMergeAreas } from "#engine/mergeReadiness.ts";
 import { observeDeliveryFailure } from "#engine/observeDeliveryFailure.ts";
@@ -54,7 +55,7 @@ function deniedDelivery(state: EngineState, stored: Versioned<FleetRecord>, work
 						error.message,
 						"Restore approval for work that is still needed, or release it",
 						undefined,
-						"maintainer",
+						failureOwner(error),
 					)
 				: state.save(stored, { ...stored.value, blocker: error.message, mergeReadyAt: undefined, mergeReadyHead: undefined }),
 		),
@@ -72,6 +73,9 @@ const observeDelivery = Effect.fn("Fleet.observeDelivery")(function* (
 ) {
 	const record = stored.value;
 	const observed = yield* state.integrations.delivery(result).pipe(Effect.result);
+	if (Result.isFailure(observed) && failureCode(observed.failure) === "pr-closed") {
+		yield* state.store.releaseForeign(result.pr);
+	}
 	if (Result.isSuccess(observed) && observed.success !== undefined && !executing(record)) {
 		return yield* settleMergedDelivery(state, stored, result, observed.success, deliveryPending(record));
 	}

package/src/engine/makeState.ts

@@ -2,16 +2,18 @@ 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 { closeDecisions } from "#engine/closeDecisions.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, type FleetConfiguration, FleetIntegrations, FleetPolicy } from "#policy.ts";
+import { type BoardFailure, BoardGateway, type BoardWork, type Decision, type FleetConfiguration, 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 { AdmissionLimits, Versioned } from "#storage/model.ts";
 export interface LaunchAdmission {
+	readonly areaWaiters: readonly string[];
 	readonly ignoreAreas?: boolean;
 	readonly implementer?: boolean;
 	readonly overLimit?: boolean;
@@ -52,7 +54,7 @@ export const makeState = Effect.gen(function* () {
 		worker?: SessionReceipt,
 		attentionOwner: AttentionOwner = "orchestrator",
 		publicationWork?: BoardWork,
-	) {
+	): Effect.fn.Return<Versioned<FleetRecord>, Effect.Error<ReturnType<typeof save>> | BoardFailure> {
 		const value: Decision = {
 			attentionOwner,
 			code,
@@ -63,6 +65,8 @@ export const makeState = Effect.gen(function* () {
 			recommendation,
 			...(worker === undefined ? {} : { worker }),
 		};
+		const previous = stored.value.decision?.published;
+		const superseded = stored.value.supersededDecisions ?? [];
 		const updated = yield* save(stored, {
 			...stored.value,
 			attentionOwner,
@@ -71,18 +75,33 @@ export const makeState = Effect.gen(function* () {
 			decisionPublished: false,
 			launchRetry: undefined,
 			stage: "needs-human",
+			supersededDecisions:
+				previous === undefined || superseded.some((receipt) => receipt.published.questionId === previous.questionId)
+					? stored.value.supersededDecisions
+					: [...superseded, { published: previous, supersededAt: policy.now() }],
 		});
 		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 yield* save(updated, { ...updated.value, decision: { ...value, published }, decisionPublished: true }).pipe(
+			Effect.flatMap(closeDecisions(state)),
+		);
 	});
-	return { board, current, decision, integrations, launching, launchScope, load, policy, reportInspection, save, sessions, store };
+	const state = { board, current, decision, integrations, launching, launchScope, load, policy, reportInspection, save, sessions, store };
+	return state;
 });
 export type EngineState = Effect.Success<typeof makeState>;
 
 function launchLimits(policy: FleetConfiguration, admission: LaunchAdmission): AdmissionLimits {
 	const concurrency = admission.overLimit ? undefined : policy.executionConcurrency;
 	return {
-		...(admission.ignoreAreas ? {} : { scheduling: { areaMergeWaitMs: policy.areaMergeWaitMs ?? DEFAULT_AREA_MERGE_WAIT_MS, now: policy.now() } }),
+		...(admission.ignoreAreas
+			? {}
+			: {
+					scheduling: {
+						areaMergeWaitMs: policy.areaMergeWaitMs ?? DEFAULT_AREA_MERGE_WAIT_MS,
+						now: policy.now(),
+						waiters: admission.areaWaiters,
+					},
+				}),
 		...(admission.quota.available === undefined ? {} : { quota: { available: admission.quota.available, observedAt: admission.quota.observedAt } }),
 		...(concurrency === undefined ? {} : { maxExecuting: concurrency }),
 		...(admission.role !== "worker" || admission.overLimit || policy.deliveryBacklog === undefined ? {} : { maxBacklog: policy.deliveryBacklog }),

package/src/engine/mergeReadiness.ts

@@ -31,8 +31,6 @@ export const awaitHumanMerge = Effect.fn("Fleet.awaitHumanMerge")(function* (
 		"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",
 	);
 });
 

package/src/engine/missingBoardWork.ts

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import type { EngineState } from "#engine/makeState.ts";
+import { releaseFinishedWork } from "#engine/releaseFinishedWork.ts";
+import { executing, type FleetRecord } from "#model.ts";
+import { BoardFailure } from "#policy.ts";
+import type { Versioned } from "#storage/model.ts";
+
+export function missingBoardItem(error: unknown, workId?: string): boolean {
+	return error instanceof BoardFailure && error.code === "board-item-missing" && (workId === undefined || error.workId === workId);
+}
+
+export const releaseMissingBoardWork = Effect.fn("Fleet.releaseMissingBoardWork")(function* (
+	state: EngineState,
+	stored: Versioned<FleetRecord>,
+	error: unknown,
+) {
+	const record = stored.value;
+	if (!missingBoardItem(error, record.workId) || ["completed", "released"].includes(record.stage) || executing(record)) {
+		return undefined;
+	}
+	const released = yield* releaseFinishedWork(state, stored, `Board item no longer exists: ${record.workId}`);
+	yield* Effect.logInfo("Fleet released missing Board item").pipe(Effect.annotateLogs({ workId: record.workId }));
+	return released;
+});

package/src/engine/obtainReview.ts

@@ -78,7 +78,7 @@ export function obtainReview(state: EngineState) {
 				mergeReadyAt: undefined,
 				mergeReadyHead: undefined,
 			},
-			{ quota, role: "reviewer" },
+			{ areaWaiters: [], quota, role: "reviewer" },
 		);
 		const input = {
 			access: "read-only",

package/src/engine/pendingAcknowledgements.ts

@@ -9,8 +9,15 @@ export function pendingAcknowledgements(record: FleetRecord) {
 		readonly input: BoardDecisionAcknowledgement;
 	}[] = [];
 	const cycles = [...(record.history ?? []), record];
+	const answered = new Set(
+		cycles.flatMap((value) =>
+			(value.responses ?? []).flatMap((response) =>
+				response.action !== undefined && response.published !== undefined ? [response.published.questionId] : [],
+			),
+		),
+	);
 	for (const [cycle, value] of cycles.entries()) {
-		pending.push(...supersededAcknowledgements(value, cycle));
+		pending.push(...supersededAcknowledgements(value, cycle).filter((entry) => !answered.has(entry.input.decision.questionId)));
 		for (const [response, receipt] of (value.responses ?? []).entries()) {
 			if (
 				receipt.action !== undefined
@@ -28,6 +35,7 @@ export function pendingAcknowledgements(record: FleetRecord) {
 		if (
 			"archivedAt" in value
 			&& value.decision?.published !== undefined
+			&& !answered.has(value.decision.published.questionId)
 			&& !value.decisionAcknowledged
 			&& value.decision.boardAcknowledgementDisposition === undefined
 		) {

package/src/engine/readOrContinueReview.ts

@@ -66,7 +66,7 @@ function continueReview(state: EngineState) {
 			{ ...policy, quota },
 			board.get,
 		);
-		yield* save(stored, { ...stored.value, attempts: [...stored.value.attempts, attempt] }, { quota, role: "reviewer" });
+		yield* save(stored, { ...stored.value, attempts: [...stored.value.attempts, attempt] }, { areaWaiters: [], quota, role: "reviewer" });
 		yield* sessions
 			.continue({ access: "read-only", operationId: attempt.operationId, prompt, sessionId: receipt.sessionId, settings })
 			.pipe(

package/src/engine/readResolution.ts

@@ -1,7 +1,7 @@
 import { Effect } from "effect";
 import { BadRequest, Conflict } from "@shivaedev/platform/errors/taxonomy.ts";
-import type { RecordedResponse } from "@shivaedev/work-board/integration/responses.ts";
-import { releaseOnly } from "#engine/releaseOnly.ts";
+import type { RecordedResponse } from "@shivaedev/work-board/server/integration/responses.ts";
+import { releaseOnly } from "#engine/decisionCopy.ts";
 import type { BoardGateway, Decision } from "#policy.ts";
 
 export const readResolution = Effect.fn("Fleet.readResolution")(function* (

package/src/engine/reconcileCommand.ts

@@ -6,6 +6,7 @@ import { failureMessage } from "#engine/failureMessage.ts";
 import { failureOwner } from "#engine/failureOwner.ts";
 import type { makeAdvance } from "#engine/makeAdvance.ts";
 import type { EngineState } from "#engine/makeState.ts";
+import { releaseMissingBoardWork } from "#engine/missingBoardWork.ts";
 import { persistTerminalReceipts } from "#engine/persistTerminalReceipts.ts";
 import { clearIntegrationRetry, readRetry, retryPending } from "#engine/readRetry.ts";
 import { refreshBrief } from "#engine/refreshBrief.ts";
@@ -67,7 +68,12 @@ export function reconcileCommand(state: EngineState, advance: ReturnType<typeof
 		}
 		return yield* advance(workId).pipe(
 			Effect.flatMap((updated) => clearIntegrationRetry(state, updated)),
-			Effect.catch((error) => handleFailure(workId, error)),
+			Effect.catch((error) =>
+				load(workId).pipe(
+					Effect.flatMap((stored) => releaseMissingBoardWork(state, stored, error)),
+					Effect.flatMap((released) => (released === undefined ? handleFailure(workId, error) : Effect.succeed(released))),
+				),
+			),
 			Effect.flatMap(completeBoardWork(state)),
 		);
 	});

package/src/engine/releaseFinishedWork.ts

@@ -10,7 +10,6 @@ export function releaseFinishedWork(state: EngineState, stored: Versioned<FleetR
 	return state
 		.save(stored, {
 			...record,
-			admissionReady: false,
 			attentionOwner: undefined,
 			blocker: undefined,
 			decision: undefined,

package/src/engine/repository.ts

@@ -1,6 +1,6 @@
 import { Context, Effect, Layer } from "effect";
 import { SqlClient } from "effect/sql";
-import { defineService } from "@shivaedev/effect-service/define-service.ts";
+import { defineService } from "@shivaedev/effect-service/defineService.ts";
 import { operationRecord } from "#engine/operationRecord.ts";
 import { threadName } from "#engine/threadNames.ts";
 import { type Attempt, allAttempts, backlog, executing, FleetRecord } from "#model.ts";

package/src/engine/saveLaunch.ts

@@ -1,13 +1,15 @@
 import { Effect } from "effect";
 import type { EngineState, LaunchAdmission } from "#engine/makeState.ts";
+import { missingBoardItem } from "#engine/missingBoardWork.ts";
 import type { Attempt, FleetRecord } from "#model.ts";
 import type { BoardWork } from "#policy.ts";
+import { qualifyDependencies } from "#qualifyDependencies.ts";
+import { DEFAULT_AREA_MERGE_WAIT_MS, holdsAreas } from "#scheduling/areas.ts";
 import type { Versioned } from "#storage/model.ts";
 
 function launched(record: FleetRecord, attempt: Attempt): FleetRecord {
 	return {
 		...record,
-		admissionReady: true,
 		attempts: [...record.attempts, attempt],
 		blocker: undefined,
 		launchRetry: undefined,
@@ -28,8 +30,10 @@ export const saveLaunch = Effect.fn("Fleet.saveLaunch")(function* (
 	launch: Pick<LaunchAdmission, "quota" | "role"> & { readonly priority: BoardWork["priority"] },
 ) {
 	const implementer = stored.value.stage === "prepared";
+	const ignoreAreas = implementer && stored.value.dispatchNow?.ignoreAreas === true;
 	const admission: LaunchAdmission = {
-		ignoreAreas: implementer && stored.value.dispatchNow?.ignoreAreas === true,
+		areaWaiters: ignoreAreas || !stored.value.areas?.length ? [] : yield* areaWaiters(state, stored.value),
+		ignoreAreas,
 		implementer,
 		quota: launch.quota,
 		role: launch.role,
@@ -43,3 +47,24 @@ export const saveLaunch = Effect.fn("Fleet.saveLaunch")(function* (
 			),
 		);
 });
+
+const areaWaiters = Effect.fn("Fleet.areaWaiters")(function* (state: EngineState, record: FleetRecord) {
+	const policy = yield* state.current;
+	if (holdsAreas(record, policy.now(), policy.areaMergeWaitMs ?? DEFAULT_AREA_MERGE_WAIT_MS)) {
+		return [];
+	}
+	const records = (yield* state.store.list()).map(({ value }) => value);
+	const index = records.findIndex((entry) => entry.workId === record.workId);
+	const waiting = records.slice(0, index).filter((entry) => entry.stage === "prepared" && entry.areas?.some((area) => record.areas?.includes(area)));
+	return yield* Effect.filter(waiting, (entry) =>
+		state.board.get(entry.workId).pipe(
+			Effect.flatMap((work) =>
+				qualifyDependencies(work.dependsOn, records, state.board.get).pipe(
+					Effect.as(work.approved),
+					Effect.catchTag("Forbidden", () => Effect.succeed(false)),
+				),
+			),
+			Effect.catchTag("BoardFailure", (error) => (missingBoardItem(error) ? Effect.succeed(false) : Effect.fail(error))),
+		),
+	).pipe(Effect.map((entries) => entries.map((entry) => entry.workId)));
+});

package/src/engine/scheduler.ts

@@ -1,4 +1,4 @@
-import { Effect, Result } from "effect";
+import { Cause, Effect, Result } from "effect";
 import { inBoardReadPass, withBoardReadPass } from "#board/readPass.ts";
 import { boardCompletionAction } from "#engine/completeBoardWork.ts";
 import { schedulerPassed } from "#engine/health.ts";
@@ -15,6 +15,9 @@ const dispatchRecords = Effect.fn("Fleet.dispatchRecords")(function* (records: r
 	for (const { value } of prepared) {
 		const result = yield* fleet.dispatch(value.workId).pipe(Effect.result);
 		dispatched.push(result);
+		if (Result.isFailure(result)) {
+			yield* Effect.logWarning("Fleet dispatch failed", Cause.fail(result.failure)).pipe(Effect.annotateLogs({ workId: value.workId }));
+		}
 		if ((Result.isSuccess(result) && result.success.value.launchRetry !== undefined) || (yield* fleet.hasLaunchRetry())) {
 			break;
 		}

package/src/engine/situations/choices.ts

@@ -0,0 +1,36 @@
+export interface Choice {
+	readonly label: string;
+	readonly outcome: string;
+}
+
+export interface Situation {
+	readonly details?: boolean;
+	readonly happened: string;
+	readonly question?: string;
+	readonly recommendation: string;
+	readonly release?: Choice;
+	readonly retry?: Choice;
+}
+
+export const RELEASE: Choice = {
+	label: "Stop and hand back",
+	outcome: "Fleet stops working on this task and hands it back to you. An open PR stays open.",
+};
+export const TRY_AGAIN: Choice = { label: "Try again", outcome: "Fleet repeats the step that stopped and continues the same work." };
+export const RUN_AGAIN: Choice = { label: "Run the step again", outcome: "Fleet starts the step again and continues the same work." };
+export const FRESH_WORKER: Choice = {
+	label: "Start a fresh worker",
+	outcome: "Fleet starts a new worker session with the same task. An existing branch and PR stay in use.",
+};
+export const CORRECT_REPORT: Choice = {
+	label: "Ask for a corrected report",
+	outcome: "Fleet asks the same worker to send its final report again in the expected format.",
+};
+
+export function blocked(happened: string, recommendation: string): Situation {
+	return { details: true, happened, recommendation, retry: TRY_AGAIN };
+}
+
+export function stopOnly(happened: string, recommendation: string): Situation {
+	return { happened, recommendation };
+}

package/src/engine/situations/service.ts

@@ -0,0 +1,82 @@
+import type { DecisionCode } from "#DecisionCode.ts";
+import { blocked, FRESH_WORKER, RUN_AGAIN, type Situation, TRY_AGAIN } from "#engine/situations/choices.ts";
+
+export const serviceSituations = {
+	"board-failure": blocked(
+		"Fleet could not read or update the Board.",
+		"Fleet needs the Board files readable again. Fix the cause in the details, then let Fleet try again.",
+	),
+	"fleet-denied": blocked(
+		"Fleet is not allowed to take the next step.",
+		"Fleet needs the blocker in the details resolved. Then let Fleet try again, or stop here.",
+	),
+	"fleet-integration": blocked(
+		"A service Fleet depends on is unavailable or not set up.",
+		"Fleet needs that service working. Fix it, then let Fleet try again, or stop here.",
+	),
+	"fleet-invalid": blocked("Fleet received data it cannot use.", "Fix the problem in the details, then let Fleet try again, or stop here."),
+	"fleet-missing": blocked(
+		"Fleet could not find something this work needs.",
+		"Restore what the details name, then let Fleet try again, or stop here.",
+	),
+	"fleet-stale": blocked(
+		"Something changed while Fleet was working on this task.",
+		"Fleet recommends trying again from the current state. Stop here if the task should not go on.",
+	),
+	"integration-failure": blocked(
+		"Fleet hit an unexpected error.",
+		"Check the details. If the cause is fixed, let Fleet try again. Otherwise stop here.",
+	),
+	"provider-quota-unavailable": {
+		happened: "The worker service has no usage quota left for Fleet.",
+		recommendation: "Fleet needs fresh quota to start workers. Try again once quota is available.",
+		retry: { label: "Try again", outcome: "Fleet checks the quota again and starts the work once quota is available." },
+	},
+	"session-active-turn": {
+		happened: "The worker was still busy with an earlier step, so Fleet could not send the next one.",
+		recommendation: "Fleet recommends trying again once the worker is free.",
+		retry: { label: "Try again", outcome: "Fleet sends the step to the same worker again." },
+	},
+	"session-active-turn-exhausted": {
+		happened: "The worker stayed busy with an earlier step through several attempts.",
+		recommendation: "Fleet recommends starting over with a fresh worker.",
+		retry: FRESH_WORKER,
+	},
+	"session-ambiguous": {
+		details: true,
+		happened: "Fleet lost contact with the worker service and cannot tell whether the last step started.",
+		recommendation: "Fleet recommends trying again once the worker service is reachable. Fleet checks what already ran before it sends anything.",
+		retry: { label: "Try again", outcome: "Fleet checks what the worker already did and continues from there." },
+	},
+	"session-persistence": blocked(
+		"Fleet could not save the state of the worker's run.",
+		"Fleet needs its database working. Fix the cause in the details, then let Fleet try again.",
+	),
+	"session-protocol": blocked(
+		"The worker service sent an answer Fleet does not understand.",
+		"Check the details. Let Fleet try again once the cause is fixed, or stop here.",
+	),
+	"session-queue-full": {
+		happened: "The worker service is too busy to accept new work.",
+		recommendation: "Fleet recommends trying again later.",
+		retry: TRY_AGAIN,
+	},
+	"session-rejected": blocked(
+		"The worker service rejected Fleet's request.",
+		"Check the details. Let Fleet try again once the cause is fixed, or stop here.",
+	),
+	"session-stalled": {
+		happened: "The worker stopped making progress, and nudging and interrupting it did not help.",
+		recommendation: "Fleet recommends starting over with a fresh worker.",
+		retry: FRESH_WORKER,
+	},
+	"session-turn-missing": {
+		happened: "The worker's run can no longer be found, even after Fleet resumed it once.",
+		recommendation: "Fleet recommends running the step again.",
+		retry: RUN_AGAIN,
+	},
+	"session-unavailable": blocked(
+		"Fleet could not reach the worker service.",
+		"Fleet needs the worker service reachable. Let Fleet try again once it is back, or stop here.",
+	),
+} satisfies Partial<Record<DecisionCode, Situation>>;

package/src/engine/situations/stop.ts

@@ -0,0 +1,60 @@
+import type { DecisionCode } from "#DecisionCode.ts";
+import { type Situation, stopOnly } from "#engine/situations/choices.ts";
+
+export const stopSituations = {
+	"checks-result-invalid": stopOnly(
+		"Fleet could not read check results because this work has no valid PR or commit.",
+		"Trying again cannot fix this. Stop here so the task can be prepared again with a valid PR.",
+	),
+	"delivery-pr-required": stopOnly(
+		"Fleet has no valid GitHub PR for this work.",
+		"Trying again cannot fix this. Stop here, check who owns the branch, and prepare the task again.",
+	),
+	"duplicate-turns": stopOnly(
+		"The worker service shows several runs for the same step, so Fleet cannot tell which result is right.",
+		"Fleet cannot pick a result itself. Stop here once every one of those runs has finished.",
+	),
+	"foreign-pr": stopOnly(
+		"The reported PR belongs to another repository.",
+		"Fleet cannot move a PR between repositories. Stop here so the task can be prepared again in the right repository.",
+	),
+	"incomplete-context": {
+		details: true,
+		happened: "The task needs information the worker cannot reach.",
+		recommendation:
+			"Trying again cannot fill in the missing information. Stop here, change the task to use data from the repository, and prepare it again.",
+	},
+	"incomplete-observation": {
+		details: true,
+		happened: "Fleet could not get a complete view of the Board or the repository.",
+		recommendation: "Fleet cannot continue from an incomplete view. Stop here so the task can be prepared again.",
+	},
+	"no-change-checks-unconfigured": stopOnly(
+		"The worker changed nothing, and this Fleet setup cannot check a result without changes.",
+		"Trying again cannot verify this result here. Stop here so the task can run where such results can be checked.",
+	),
+	"not-ancestor": stopOnly(
+		"The main branch no longer contains the commit this work was prepared on.",
+		"Fleet cannot move the work onto the new history. Stop here so the task can be prepared again on the current main branch.",
+	),
+	"relevant-change": stopOnly(
+		"Files this work depends on changed on the main branch after it was prepared.",
+		"Fleet cannot refresh the preparation itself. Stop here so the task can be prepared again on the current main branch.",
+	),
+	"report-published": stopOnly(
+		"The report worker published to GitHub, which a report task must not do.",
+		"Fleet cannot undo the publication. Stop here and check what was published.",
+	),
+	"report-too-large": stopOnly(
+		"The worker's report is too large for the Board.",
+		"Fleet cannot shorten a finished report. Stop here so a worker can write a shorter report.",
+	),
+	"result-identity-changed": stopOnly(
+		"The PR or branch for this work was replaced during review.",
+		"Fleet cannot take over a different result. Stop here and check the replacement before preparing the task again.",
+	),
+	"worker-receipt-missing": stopOnly(
+		"Fleet lost the record of which worker run produced this result.",
+		"Fleet cannot prove who owns this result. Stop here and check the branch before preparing the task again.",
+	),
+} satisfies Partial<Record<DecisionCode, Situation>>;