@shivaedev/work-fleet 0.6.0 → 0.7.0

package/src/cli.ts

@@ -11,7 +11,7 @@ import * as Flag from "effect/cli/Flag";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import { answerCommand, continueCommand, nameThreadsCommand, reassignCommand, releaseCommand } from "#host/actionCommands.ts";
-import { board, config, host, port } from "#host/cliOptions.ts";
+import { board, clientPort, config, host, port } from "#host/cliOptions.ts";
 import { waitCommand, watchCommand } from "#host/followCommands.ts";
 import { VERSION } from "#packageInfo.ts";
 
@@ -20,7 +20,7 @@ const serveCommand = Command.make(
 	{ board: Argument.Directory("board-dir"), config, port },
 	Effect.fn("WorkFleetCli.serve")(function* (input) {
 		const { serveFleet } = yield* Effect.promise(() => import("#host/daemon.ts"));
-		yield* serveFleet(yield* host(input.board, input.config), undefined, input.port);
+		yield* serveFleet(yield* host(input.board, input.config), undefined, Option.getOrUndefined(input.port));
 	}),
 ).pipe(Command.withDescription("Serve the local Fleet HTTP RPC daemon and schedule approved Board work"));
 
@@ -40,7 +40,7 @@ const dispatchCommand = Command.make(
 	Effect.fn("WorkFleetCli.dispatch")(function* (input) {
 		const { daemonRequest } = yield* Effect.promise(() => import("#host/daemonClient.ts"));
 		const value = yield* daemonRequest(
-			input.port,
+			yield* clientPort(input),
 			(client) => client("daemon.dispatch", { ignoreAreas: input.ignoreAreas, now: input.now, workId: input.workId }),
 			`dispatch ${input.workId}`,
 		);
@@ -62,12 +62,20 @@ const statusCommand = Command.make(
 			Promise.all([import("#host/daemonClient.ts"), import("#host/renderStatus.ts")]),
 		);
 		const workId = Option.getOrUndefined(input.workId);
+		const daemonPort = yield* clientPort(input);
 		const current = yield* daemonRequest(
-			input.port,
+			daemonPort,
 			(client) => client("daemon.status", workId === undefined ? {} : { workId }),
 			workId === undefined ? "status" : `status ${workId}`,
 		);
-		yield* Console.log(input.json ? JSON.stringify(current) : renderStatus(current, input.port));
+		yield* Console.log(
+			input.json
+				? JSON.stringify(current)
+				: renderStatus(current, {
+						board: input.board,
+						...Option.match(input.port, { onNone: () => ({}), onSome: (value) => ({ port: value }) }),
+					}),
+		);
 	}),
 ).pipe(Command.withDescription("Show active and completed Fleet work, and waiting work grouped by owner"));
 

package/src/engine/authorizeResolution.ts

@@ -17,7 +17,7 @@ export const authorizeResolution = Effect.fn("Fleet.authorizeResolution")(functi
 	if (executing(record)) {
 		return yield* Effect.fail(new Forbidden({ message: "Confirm terminal execution before releasing ownership" }));
 	}
-	if (record.result?.kind === "change") {
+	if (record.result?.kind === "change" && record.decision?.code !== "pr-closed") {
 		yield* state.store.reserveForeign(record.result.pr, { backlog: true, executing: false });
 	}
 });

package/src/engine/boardBrief.ts

@@ -1,14 +1,13 @@
 import { Effect } from "effect";
 import { Conflict, Forbidden } from "@shivaedev/platform/errors/taxonomy.ts";
 import { workRevision } from "#board/workRevision.ts";
-import { closeDecisions } from "#engine/closeDecisions.ts";
 import { withFailureContext } from "#engine/failureContext.ts";
 import type { EngineState } from "#engine/makeState.ts";
 import type { FleetRecord } from "#model.ts";
 import type { BoardWork } from "#policy.ts";
 import type { Versioned } from "#storage/model.ts";
 
-const CHANGED_BRIEF_REASON = "Board context changed";
+export const CHANGED_BRIEF_REASON = "Board context changed";
 
 export function briefChanged(record: Pick<FleetRecord, "boardRevision" | "boardContext">, work: BoardWork): boolean {
 	return workRevision(record.boardRevision, record.boardContext) !== workRevision(work.revision, work.context);
@@ -33,7 +32,7 @@ export const authorizeBriefContext = Effect.fn("Fleet.authorizeBriefContext")(fu
 ) {
 	yield* authorizeBrief(work);
 	if (briefChanged(record, work)) {
-		return yield* withFailureContext(new Conflict({ message: CHANGED_BRIEF_REASON }), { attentionOwner: "maintainer", code: "fleet-stale" });
+		return yield* withFailureContext(new Conflict({ message: CHANGED_BRIEF_REASON }), { code: "fleet-stale" });
 	}
 });
 
@@ -53,29 +52,22 @@ export function stopChangedBrief(state: EngineState) {
 		) {
 			return stored;
 		}
-		const published = stored.value.decision?.published;
 		const stopped = yield* state.save(stored, {
 			...stored.value,
 			checks: undefined,
 			mergeReadyAt: undefined,
 			mergeReadyHead: undefined,
 			review: undefined,
-			supersededDecisions:
-				published === undefined
-					? stored.value.supersededDecisions
-					: [...(stored.value.supersededDecisions ?? []), { published, supersededAt: state.policy.now() }],
 		});
-		return yield* state
-			.decision(
-				stopped,
-				"fleet-stale",
-				CHANGED_BRIEF_REASON,
-				"Dispatch to approve the current brief in place, retry this decision, or safely release this work",
-				undefined,
-				"maintainer",
-				work,
-			)
-			.pipe(Effect.flatMap(closeDecisions(state)));
+		return yield* state.decision(
+			stopped,
+			"fleet-stale",
+			CHANGED_BRIEF_REASON,
+			"Dispatch to approve the current brief in place, retry this decision, or safely release this work",
+			undefined,
+			undefined,
+			work,
+		);
 	});
 }
 

package/src/engine/decisionCopy.ts

@@ -0,0 +1,63 @@
+import type { DecisionCode } from "#DecisionCode.ts";
+import { CHANGED_BRIEF_REASON } from "#engine/boardBrief.ts";
+import { blocked, type Choice, RELEASE, type Situation } from "#engine/situations/choices.ts";
+import { serviceSituations } from "#engine/situations/service.ts";
+import { stopSituations } from "#engine/situations/stop.ts";
+import { workSituations } from "#engine/situations/work.ts";
+import type { Decision } from "#policy.ts";
+
+export interface DecisionCopy {
+	readonly question?: {
+		readonly title: string;
+		readonly retry?: Choice;
+		readonly release: Choice;
+	};
+	readonly reason: string;
+	readonly recommendation: string;
+}
+
+const situations: Readonly<Record<DecisionCode, Situation>> = { ...serviceSituations, ...stopSituations, ...workSituations };
+
+const changedBrief: Situation = {
+	happened: "The task was edited on the Board while this work was waiting.",
+	question: "Continue with the edited task?",
+	recommendation: "Fleet needs to know whether the edited task still fits the work done so far. If it does, continue. Otherwise stop here.",
+	retry: {
+		label: "Continue on the updated task",
+		outcome: "Fleet accepts the edited task and continues the same work with it, on the same branch and PR.",
+	},
+};
+
+const uncoded = blocked("Fleet stopped and needs your decision.", "Check the details, then let Fleet try again, or stop here.");
+
+const WORKER =
+	"The worker needs your answer to keep going. Write it on this card. Fleet passes it to the same worker, which continues where it stopped.";
+
+export function decisionCopy(decision: Pick<Decision, "code" | "publicationWork" | "reason" | "worker">): DecisionCopy {
+	if (decision.worker !== undefined) {
+		return { reason: decision.reason, recommendation: WORKER };
+	}
+	const situation = situationOf(decision);
+	const detailed = situation.details === true && decision.reason.trim() !== "" && decision.reason !== decision.code;
+	return {
+		question: {
+			release: situation.release ?? RELEASE,
+			title: situation.question ?? "What should Fleet do next?",
+			...(situation.retry === undefined ? {} : { retry: situation.retry }),
+		},
+		reason: detailed ? `${situation.happened}\n\nDetails: ${decision.reason}` : situation.happened,
+		recommendation: situation.recommendation,
+	};
+}
+
+export function releaseOnly(code: DecisionCode | undefined) {
+	const situation = code === undefined ? undefined : situations[code];
+	return situation?.retry === undefined ? situation?.recommendation : undefined;
+}
+
+function situationOf(decision: Pick<Decision, "code" | "publicationWork" | "reason">) {
+	if (decision.code === "fleet-stale" && decision.reason === CHANGED_BRIEF_REASON && decision.publicationWork !== undefined) {
+		return changedBrief;
+	}
+	return decision.code === undefined ? uncoded : situations[decision.code];
+}

package/src/engine/dispatchCommand.ts

@@ -1,13 +1,11 @@
 import { Effect, Result } from "effect";
-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";
@@ -56,25 +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,
-						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);
@@ -86,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)),
 		);
 	});
 }
@@ -103,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.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,11 +2,12 @@ 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";
@@ -53,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,
@@ -64,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,
@@ -72,11 +75,18 @@ 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>;
 

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/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/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,5 +1,6 @@
 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";
@@ -63,6 +64,7 @@ const areaWaiters = Effect.fn("Fleet.areaWaiters")(function* (state: EngineState
 					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>>;