@shivaedev/work-fleet 0.0.0 → 0.1.1

package/src/engine/boardBrief.ts

@@ -0,0 +1,84 @@
+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 function briefChanged(record: Pick<FleetRecord, "boardRevision" | "boardContext">, work: BoardWork): boolean {
+	return workRevision(record.boardRevision, record.boardContext) !== workRevision(work.revision, work.context);
+}
+
+export function briefApproved(work: BoardWork): boolean {
+	return work.approved;
+}
+
+export const authorizeBrief = Effect.fn("Fleet.authorizeBrief")(function* (work: BoardWork) {
+	if (!briefApproved(work)) {
+		return yield* withFailureContext(new Forbidden({ message: "Work is no longer approved" }), {
+			attentionOwner: "maintainer",
+			code: "approval-required",
+		});
+	}
+});
+
+export const authorizeBriefContext = Effect.fn("Fleet.authorizeBriefContext")(function* (
+	record: Pick<FleetRecord, "boardRevision" | "boardContext">,
+	work: BoardWork,
+) {
+	yield* authorizeBrief(work);
+	if (briefChanged(record, work)) {
+		return yield* withFailureContext(new Conflict({ message: CHANGED_BRIEF_REASON }), { attentionOwner: "maintainer", code: "fleet-stale" });
+	}
+});
+
+export function stopChangedBrief(state: EngineState) {
+	return Effect.fn("Fleet.stopChangedBrief")(function* (stored: Versioned<FleetRecord>) {
+		const work = yield* state.board.get(stored.value.workId);
+		if (
+			isChangedBriefDecision(stored.value)
+			&& stored.value.decision?.publicationWork !== undefined
+			&& !briefChanged(
+				{
+					boardContext: stored.value.decision.publicationWork.context,
+					boardRevision: stored.value.decision.publicationWork.revision,
+				},
+				work,
+			)
+		) {
+			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)));
+	});
+}
+
+export function isChangedBriefDecision(record: FleetRecord): boolean {
+	return record.decision?.code === "fleet-stale" && record.decision.reason === CHANGED_BRIEF_REASON;
+}

package/src/engine/capacityRetry.ts

@@ -0,0 +1,72 @@
+import { Effect } from "effect";
+import { failureCode } from "#engine/failureCode.ts";
+import type { EngineState } from "#engine/makeState.ts";
+import { restartableReview } from "#engine/restartableReview.ts";
+import { retryPrompt } from "#engine/retryPrompt.ts";
+import type { Attempt, FleetRecord } from "#model.ts";
+import { SessionFailure } from "#session/schema.ts";
+import { busyThread, transientFailure } from "#session/transientFailure.ts";
+
+const retryStages: Readonly<Record<Attempt["role"], FleetRecord["stage"]>> = { repair: "repairing", reviewer: "reviewing", worker: "prepared" };
+
+export const retryLostReview = Effect.fn("Fleet.retryLostReview")(function* (state: EngineState, record: FleetRecord, error: unknown) {
+	const attempt = record.attempts.at(-1);
+	return attempt !== undefined && restartableReview(record, error) ? yield* capacityRetry(state, record, attempt.operationId, error) : false;
+});
+
+export const retryMissingReview = Effect.fn("Fleet.retryMissingReview")(function* (state: EngineState, record: FleetRecord, error: unknown) {
+	return error instanceof SessionFailure && error.code === "session-turn-missing" && (yield* retryLostReview(state, record, error))
+		? yield* state.load(record.workId)
+		: undefined;
+});
+
+export const capacityRetry = Effect.fn("Fleet.capacityRetry")(function* (
+	state: EngineState,
+	previous: FleetRecord,
+	operationId: string,
+	error: SessionFailure,
+) {
+	const restartReview = restartableReview(previous, error);
+	if (!(transientFailure(error) || restartReview)) {
+		return false;
+	}
+	const current = yield* state.load(previous.workId);
+	if (restartReview && (current.value.attempts.at(-1)?.operationId !== operationId || !restartableReview(current.value, error))) {
+		return false;
+	}
+	const rejected = current.value.attempts.find((item) => item.operationId === operationId);
+	if (rejected === undefined || (rejected.receipt !== undefined && rejected.status !== "failed")) {
+		return false;
+	}
+	const rejectedAt = state.policy.now();
+	const rejections = (previous.launchRetry?.rejections ?? rejected.providerFailures ?? 0) + 1;
+	const delay = Math.min(300_000, 30_000 * 2 ** Math.min(rejections - 1, 4));
+	const freshThread = busyThread(error);
+	const saved = yield* state.save(current, {
+		...current.value,
+		attempts: current.value.attempts.map((attempt) =>
+			attempt.operationId === operationId
+				? {
+						...attempt,
+						output: error.message,
+						readRetry: undefined,
+						...(restartReview ? { sessionUnusable: true } : {}),
+						...(freshThread ? { prompt: retryPrompt(previous, attempt), sessionUnusable: true } : {}),
+						status: "failed" as const,
+					}
+				: attempt,
+		),
+		blocker: undefined,
+		launchRetry: rejections < 5 ? { rejectedAt, rejections, retryAt: rejectedAt + delay } : undefined,
+		stage: previous.decision?.code === "worker-question" ? "repairing" : retryStages[rejected.role],
+	});
+	if (rejections >= 5) {
+		yield* state.decision(
+			saved,
+			failureCode(error),
+			`${error.message}; provider failure after ${rejections} attempts (${rejections - 1} automatic retries)`,
+			"Inspect the provider failure and retry or safely release",
+		);
+	}
+	return true;
+});

package/src/engine/closeDecisions.ts

@@ -0,0 +1,92 @@
+import { Effect, Result } from "effect";
+import { BoardAcknowledgementStale, type BoardDecisionAcknowledgement } from "#board/schema.ts";
+import type { EngineState } from "#engine/makeState.ts";
+import { pendingAcknowledgements } from "#engine/pendingAcknowledgements.ts";
+import type { FleetCycleSnapshot, FleetRecord } from "#model.ts";
+import type { Versioned } from "#storage/model.ts";
+
+const ACKNOWLEDGEMENT_PREFIX = "Board request acknowledgement pending: ";
+export function closeDecisions(state: EngineState) {
+	return Effect.fn("Fleet.closeDecisions")(function* (initial: Versioned<FleetRecord>) {
+		let stored = initial;
+		const failures: string[] = [];
+		for (const pending of pendingAcknowledgements(initial.value)) {
+			const result = yield* closeAcknowledgement(state, pending.input).pipe(Effect.result);
+			if (Result.isFailure(result)) {
+				failures.push(`${pending.input.decision.questionId}: ${result.failure.message}`);
+				continue;
+			}
+			stored = yield* state.save(stored, markedRecord(stored.value, pending, result.success));
+		}
+		if (failures.length > 0) {
+			return yield* state.save(stored, { ...stored.value, blocker: `${ACKNOWLEDGEMENT_PREFIX}${failures.join("; ")}` });
+		}
+		if (stored.value.blocker?.startsWith(ACKNOWLEDGEMENT_PREFIX)) {
+			return yield* state.save(stored, { ...stored.value, blocker: undefined });
+		}
+		return stored;
+	});
+}
+
+interface Closure {
+	readonly boardAcknowledged?: boolean;
+	readonly boardAcknowledgementDisposition?: "superseded";
+}
+
+const closeAcknowledgement = Effect.fn("Fleet.closeAcknowledgement")(function* (state: EngineState, input: BoardDecisionAcknowledgement) {
+	const applied = yield* state.board.acknowledgeDecision(input).pipe(Effect.result);
+	if (Result.isSuccess(applied)) {
+		return { boardAcknowledged: true };
+	}
+	if (!(applied.failure instanceof BoardAcknowledgementStale)) {
+		return yield* Effect.fail(applied.failure);
+	}
+	const superseded =
+		input.disposition === "superseded"
+			? applied
+			: yield* state.board.acknowledgeDecision({ ...input, disposition: "superseded", responseId: undefined }).pipe(Effect.result);
+	if (Result.isFailure(superseded) && !(superseded.failure instanceof BoardAcknowledgementStale)) {
+		return yield* Effect.fail(superseded.failure);
+	}
+	return Result.isSuccess(superseded)
+		? { boardAcknowledged: true, boardAcknowledgementDisposition: "superseded" as const }
+		: { boardAcknowledgementDisposition: "superseded" as const };
+});
+
+function markedRecord(record: FleetRecord, pending: ReturnType<typeof pendingAcknowledgements>[number], closure: Closure): FleetRecord {
+	const previous = record.history ?? [];
+	function mark<T extends FleetRecord | FleetCycleSnapshot>(value: T) {
+		return marked(value, pending.response, pending.superseded, closure);
+	}
+	return {
+		...(pending.cycle === previous.length ? mark(record) : record),
+		history: previous.map((cycle, index) => (index === pending.cycle ? mark(cycle) : cycle)),
+	};
+}
+
+function marked<T extends FleetRecord | FleetCycleSnapshot>(
+	cycle: T,
+	responseIndex: number | undefined,
+	supersededIndex: number | undefined,
+	closure: Closure,
+): T {
+	if (supersededIndex !== undefined) {
+		return {
+			...cycle,
+			supersededDecisions: cycle.supersededDecisions?.map((receipt, index) => (index === supersededIndex ? { ...receipt, ...closure } : receipt)),
+		};
+	}
+	return responseIndex === undefined
+		? {
+				...cycle,
+				decision:
+					closure.boardAcknowledgementDisposition === undefined || cycle.decision === undefined
+						? cycle.decision
+						: { ...cycle.decision, boardAcknowledgementDisposition: closure.boardAcknowledgementDisposition },
+				decisionAcknowledged: closure.boardAcknowledged ?? cycle.decisionAcknowledged,
+			}
+		: {
+				...cycle,
+				responses: cycle.responses?.map((response, index) => (index === responseIndex ? { ...response, ...closure } : response)),
+			};
+}

package/src/engine/completeBoardWork.ts

@@ -0,0 +1,33 @@
+import { Effect } from "effect";
+import type { EngineState } from "#engine/makeState.ts";
+import type { FleetRecord } from "#model.ts";
+import type { Versioned } from "#storage/model.ts";
+
+export function boardCompletionAction(record: FleetRecord) {
+	if (record.stage === "completed" && record.report !== undefined) {
+		return "Done; report recorded.";
+	}
+	if (record.stage === "completed" && record.result?.kind === "no-change") {
+		return "Done; no change needed.";
+	}
+	if (record.stage !== "completed" && !(record.stage === "released" && /^PR #\d+ merged by a human /u.test(record.releaseReason ?? ""))) {
+		return;
+	}
+	if (record.result?.kind !== "change") {
+		return;
+	}
+	const number = record.result.prNumber ?? /\/(?<number>\d+)\/?$/u.exec(record.result.pr)?.groups?.number;
+	return number === undefined ? undefined : `Done; PR #${number} merged.`;
+}
+
+export function completeBoardWork(state: EngineState) {
+	return Effect.fn("Fleet.completeBoardWork")(function* (stored: Versioned<FleetRecord>) {
+		const action = boardCompletionAction(stored.value);
+		if (action !== undefined && stored.value.boardSourcePath !== undefined && state.board.complete !== undefined) {
+			yield* state.board
+				.complete(stored.value.workId, stored.value.boardSourcePath, action)
+				.pipe(Effect.catchTag("BoardFailure", (error) => Effect.logWarning(error.message)));
+		}
+		return stored;
+	});
+}

package/src/engine/completeReport.ts

@@ -0,0 +1,24 @@
+import { Effect, Option } from "effect";
+import { BadRequest } from "@shivaedev/platform/errors/taxonomy.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";
+
+export function completeReport({ board, save, decision, reportInspection }: EngineState) {
+	return Effect.fn("Fleet.completeReport")(function* (stored: Versioned<FleetRecord>, work: BoardWork) {
+		const latest = stored.value.attempts.at(-1);
+		if (latest?.receipt === undefined || latest.status !== "completed") {
+			return yield* Effect.fail(new BadRequest({ message: "Report execution lacks a completed receipt" }));
+		}
+		if (Option.isSome(reportInspection)) {
+			yield* reportInspection.value.check(work);
+		}
+		const output = latest.output ?? "";
+		if (!output.trim()) {
+			return yield* decision(stored, "empty-report", "Report worker returned empty output", "Retry the report worker or safely release this work");
+		}
+		const report = yield* board.report(work, { execution: "completed", output, provisioning: "unknown", receipt: latest.receipt });
+		return yield* save(stored, { ...stored.value, outcome: { evidence: [report.sourcePath] }, report, stage: "completed" });
+	});
+}

package/src/engine/continueCommand.ts

@@ -0,0 +1,30 @@
+import { Effect } from "effect";
+import { BadRequest, Forbidden } from "@shivaedev/platform/errors/taxonomy.ts";
+import { ensurePublication } from "#engine/ensurePublication.ts";
+import type { makeLaunch } from "#engine/makeLaunch.ts";
+import type { EngineState } from "#engine/makeState.ts";
+import { allAttempts, executing } from "#model.ts";
+
+export function continueCommand(state: EngineState, launch: ReturnType<typeof makeLaunch>) {
+	return Effect.fn("Fleet.continue")(function* (workId: string, message: string) {
+		let stored = yield* state.load(workId);
+		if (!message.trim()) {
+			return yield* Effect.fail(new BadRequest({ message: "Continuation needs a message" }));
+		}
+		if (!["needs-human", "completed"].includes(stored.value.stage) || executing(stored.value)) {
+			return yield* Effect.fail(new Forbidden({ message: "Continue requires terminal needs-human or completed work" }));
+		}
+		const latest = stored.value.attempts.findLast((attempt) => attempt.role !== "reviewer");
+		const sessionId = latest?.receipt?.sessionId ?? latest?.sessionId;
+		const worker = allAttempts(stored.value).findLast((attempt) => attempt.role !== "reviewer" && attempt.receipt?.sessionId === sessionId);
+		if (worker?.receipt === undefined) {
+			return yield* Effect.fail(new Forbidden({ message: "Continue requires an existing worker receipt" }));
+		}
+		const observation = yield* state.sessions.observe(worker.receipt);
+		if (["accepted", "running"].includes(observation.execution)) {
+			return yield* Effect.fail(new Forbidden({ message: "The existing worker turn is still running" }));
+		}
+		stored = yield* ensurePublication(state)(stored);
+		return yield* launch(stored, "repair", message);
+	});
+}

package/src/engine/continueWorker.ts

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+import { Forbidden } from "@shivaedev/platform/errors/taxonomy.ts";
+import { makeLaunch } from "#engine/makeLaunch.ts";
+import type { EngineState } from "#engine/makeState.ts";
+import { executing, type FleetRecord } from "#model.ts";
+import type { DecisionResponse } from "#policy.ts";
+import type { Versioned } from "#storage/model.ts";
+
+export function continueWorker(state: EngineState) {
+	return Effect.fn("Fleet.continueWorker")(function* (stored: Versioned<FleetRecord>, responses: readonly DecisionResponse[], prompt: string) {
+		const worker = stored.value.decision?.worker;
+		const latest = stored.value.attempts.at(-1);
+		if (
+			worker === undefined
+			|| latest?.receipt?.sessionId !== worker.sessionId
+			|| latest.receipt.turnId !== worker.turnId
+			|| latest.role === "reviewer"
+			|| latest.status !== "completed"
+			|| executing(stored.value)
+		) {
+			return yield* Effect.fail(new Forbidden({ message: "Confirm the exact question turn is terminal before continuing" }));
+		}
+		return yield* makeLaunch(state)(stored, latest.role, prompt, { responses, sessionId: worker.sessionId });
+	});
+}

package/src/engine/continuedRecord.ts

@@ -0,0 +1,24 @@
+import type { FleetRecord } from "#model.ts";
+
+export function continuedRecord(record: FleetRecord, archivedAt: number): FleetRecord {
+	const { workId: _workId, history: _history, ...cycle } = record;
+	return {
+		...record,
+		attempts: [],
+		attentionOwner: undefined,
+		blocker: undefined,
+		checks: undefined,
+		conflictRepairs: undefined,
+		decision: undefined,
+		decisionAcknowledged: undefined,
+		decisionPublished: undefined,
+		history: [...(record.history ?? []), { ...cycle, archivedAt }],
+		outcome: undefined,
+		report: undefined,
+		responses: [],
+		result: record.result?.kind === "change" && record.outcome === undefined ? record.result : undefined,
+		resultObservations: [],
+		review: undefined,
+		supersededDecisions: undefined,
+	};
+}

package/src/engine/deliverPendingAnswers.ts

@@ -0,0 +1,30 @@
+import { Effect } from "effect";
+import { makeDeliver } from "#engine/makeDeliver.ts";
+import type { makeLaunch } from "#engine/makeLaunch.ts";
+import type { EngineState } from "#engine/makeState.ts";
+import { reconcileBrief } from "#engine/refreshBrief.ts";
+import { executing, type FleetRecord } from "#model.ts";
+import type { Versioned } from "#storage/model.ts";
+
+export const deliverPendingAnswers = Effect.fn("Fleet.deliverPendingAnswers")(function* (
+	state: EngineState,
+	launch: ReturnType<typeof makeLaunch>,
+	stored: Versioned<FleetRecord>,
+) {
+	if ((stored.value.pendingAnswers?.length ?? 0) === 0 || executing(stored.value) || ["completed", "released"].includes(stored.value.stage)) {
+		return undefined;
+	}
+	const delivered = yield* makeDeliver(state)(stored);
+	if (["completed", "released"].includes(delivered.value.stage)) {
+		return delivered;
+	}
+	const current = yield* reconcileBrief(state, delivered);
+	return yield* launch(current, "repair", deliveryPrompt(current.value, current.value.boardRevision !== delivered.value.boardRevision));
+});
+
+function deliveryPrompt(record: FleetRecord, briefChanged: boolean) {
+	if (record.stage === "repairing") {
+		return record.checks?.repairPrompt ?? record.review?.repairPrompt ?? record.prompt;
+	}
+	return briefChanged ? record.prompt : "Apply the following human guidance to the existing work.";
+}

package/src/engine/deliveryFailure.ts

@@ -0,0 +1,13 @@
+import { Conflict } from "@shivaedev/platform/errors/taxonomy.ts";
+import { withFailureContext } from "./failureContext.ts";
+
+export const MOVED_PR_HEAD_REASON = "PR head differs from the reviewed head; review the current revision before accepting delivery";
+export const CONFLICTING_PR_REASON = "PR conflicts with main; inspect the conflict repair before retrying or releasing this work";
+
+export function movedPrHead(head: string) {
+	return withFailureContext(new Conflict({ message: MOVED_PR_HEAD_REASON }), { code: "pr-head-moved", head });
+}
+
+export function conflictingPr(mainRevision: string) {
+	return withFailureContext(new Conflict({ message: CONFLICTING_PR_REASON }), { code: "pr-conflicting", mainRevision });
+}

package/src/engine/dispatchCommand.ts

@@ -0,0 +1,88 @@
+import { Effect, Result } from "effect";
+import { Forbidden } from "@shivaedev/platform/errors/taxonomy.ts";
+import { approveDispatchedBrief } from "#engine/approveBrief.ts";
+import { authorizeBriefContext } from "#engine/boardBrief.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 { refreshBrief } from "#engine/refreshBrief.ts";
+import { releaseClosedPreparation } from "#engine/releaseClosedPreparation.ts";
+import { assessPreparation } from "#preparation/compatibility.ts";
+export function dispatchCommand(state: EngineState, launch: ReturnType<typeof makeLaunch>) {
+	const { board, load, save, decision, integrations, policy } = state;
+	const dispatchPrepared = Effect.fn("Fleet.dispatchPrepared")(function* (workId: string, prompt?: string) {
+		let stored = yield* load(workId);
+		const work = yield* board.get(workId);
+		stored = yield* refreshBrief(state, stored, work);
+		stored = yield* approveDispatchedBrief(state, stored, work, prompt);
+		if (stored.value.stage !== "prepared") {
+			return stored;
+		}
+		const released = yield* releaseClosedPreparation(state, stored, work);
+		if (released !== undefined) {
+			return released;
+		}
+		const authorized = yield* authorizeBriefContext(stored.value, work).pipe(Effect.result);
+		if (Result.isFailure(authorized)) {
+			return yield* decision(
+				stored,
+				failureCode(authorized.failure),
+				authorized.failure.message,
+				"Restore approval for work that is still needed, or release it",
+				undefined,
+				"maintainer",
+			);
+		}
+		if (stored.value.launchRetry !== undefined && policy.now() < stored.value.launchRetry.retryAt) {
+			return stored;
+		}
+		const assessment = yield* assessPreparation(stored.value.preparation, yield* integrations.main(stored.value.preparation));
+		if (assessment._tag === "Reprepare") {
+			return yield* decision(stored, assessment.code ?? "fleet-invalid", assessment.reason, "Prepare the affected scope again before dispatch");
+		}
+		if (
+			assessment.preparation.baseRevision !== stored.value.preparation.baseRevision
+			|| assessment.preparation.observedAt !== stored.value.preparation.observedAt
+		) {
+			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;
+					}
+					yield* save(current, {
+						...current.value,
+						admissionReady: !(error instanceof Forbidden),
+						attentionOwner: failureOwner(error),
+						blocker: failureMessage(error),
+					});
+					return yield* Effect.fail(error);
+				}),
+			),
+		);
+	});
+	return Effect.fn("Fleet.dispatch")(function* (workId: string, prompt?: string) {
+		const current = yield* load(workId);
+		if (retryPending(state, current.value)) {
+			return current;
+		}
+		if (current.value.integrationRetry !== undefined) {
+			yield* save(current, { ...current.value, attentionOwner: undefined, blocker: undefined });
+		}
+		return yield* dispatchPrepared(workId, prompt).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;
+				}),
+			),
+		);
+	});
+}

package/src/engine/ensureDecisionOwner.ts

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+import type { EngineState } from "#engine/makeState.ts";
+import { reassignCommand } from "#engine/reassignCommand.ts";
+import type { FleetRecord } from "#model.ts";
+import type { Versioned } from "#storage/model.ts";
+
+export function ensureDecisionOwner(state: EngineState) {
+	return Effect.fn("Fleet.ensureDecisionOwner")(function* (stored: Versioned<FleetRecord>) {
+		const decision = stored.value.decision;
+		const owner = stored.value.attentionOwner ?? decision?.attentionOwner ?? "orchestrator";
+		if (stored.value.stage !== "needs-human" || decision === undefined || decision.attentionOwner === owner) {
+			return stored;
+		}
+		return yield* reassignCommand(state)(stored.value.workId, decision.id, owner);
+	});
+}

package/src/engine/ensurePublication.ts

@@ -0,0 +1,32 @@
+import { Effect } from "effect";
+import { Forbidden } from "@shivaedev/platform/errors/taxonomy.ts";
+import type { EngineState } from "#engine/makeState.ts";
+import { originalWork } from "#engine/originalWork.ts";
+import type { FleetRecord } from "#model.ts";
+import type { Versioned } from "#storage/model.ts";
+
+export function ensurePublication({ board, save }: EngineState) {
+	return Effect.fn("Fleet.ensurePublication")(function* (stored: Versioned<FleetRecord>, refresh = false) {
+		const decision = stored.value.decision;
+		if (decision === undefined || (decision.published !== undefined && !refresh)) {
+			return stored;
+		}
+		const work = decision.publicationWork ?? originalWork(stored.value);
+		if (work === undefined) {
+			return yield* Effect.fail(
+				new Forbidden({ message: "Original Board context is unavailable; reconcile the decision publication receipt before renewal" }),
+			);
+		}
+		const original = { ...decision, attentionOwner: decision.attentionOwner ?? ("maintainer" as const) };
+		const published = yield* board.decision(stored.value.workId, original, work);
+		if (published.workId !== work.workId || published.workRevision !== work.revision || published.request !== decision.id) {
+			return yield* Effect.fail(
+				new Forbidden({ message: "Decision publication does not match the original Board context; renewal retains its ownership" }),
+			);
+		}
+		if (published.questionId === decision.published?.questionId) {
+			return stored;
+		}
+		return yield* save(stored, { ...stored.value, decision: { ...original, published }, decisionPublished: true });
+	});
+}

package/src/engine/exhaustedCheckRepairs.ts

@@ -0,0 +1,11 @@
+import type { FleetRecord } from "#model.ts";
+
+export function exhaustedCheckRepairs(record: FleetRecord, failures: readonly string[]): readonly string[] {
+	const repairs = record.attempts
+		.filter((attempt) => attempt.role !== "reviewer" && !(attempt.role === "repair" && attempt.status === "failed" && attempt.receipt === undefined))
+		.slice(-3);
+	if (repairs.length < 3 || repairs.some((attempt) => attempt.role !== "repair" || attempt.status !== "completed")) {
+		return [];
+	}
+	return failures.filter((name) => repairs.every((attempt) => attempt.checkFailures?.includes(name)));
+}

package/src/engine/failureCode.ts

@@ -0,0 +1,30 @@
+import type { DecisionCode } from "#DecisionCode.ts";
+import { failureContext } from "#engine/failureContext.ts";
+import { type FleetError, isFleetError } from "#errors.ts";
+import { BoardFailure } from "#policy.ts";
+import { SessionFailure } from "#session/schema.ts";
+
+const platformCodes: Readonly<Record<FleetError["_tag"], DecisionCode>> = {
+	BadRequest: "fleet-invalid",
+	Conflict: "fleet-stale",
+	Forbidden: "fleet-denied",
+	NotFound: "fleet-missing",
+	ServiceUnavailable: "fleet-integration",
+};
+
+export function failureCode(error: unknown): DecisionCode {
+	const code = failureContext(error).code;
+	if (code !== undefined) {
+		return code;
+	}
+	if (isFleetError(error)) {
+		return platformCodes[error._tag];
+	}
+	if (error instanceof SessionFailure) {
+		return error.code ?? `session-${error.reason}`;
+	}
+	if (error instanceof BoardFailure) {
+		return error.code ?? "board-failure";
+	}
+	return "integration-failure";
+}

package/src/engine/failureContext.ts

@@ -0,0 +1,22 @@
+import type { AttentionOwner } from "#attention.ts";
+import type { DecisionCode } from "#DecisionCode.ts";
+import type { FleetError } from "#errors.ts";
+
+interface FailureContext {
+	readonly attentionOwner?: AttentionOwner | undefined;
+	readonly code?: DecisionCode | undefined;
+	readonly head?: string;
+	readonly mainRevision?: string;
+	readonly retryable?: boolean;
+}
+
+const contexts = new WeakMap<object, FailureContext>();
+
+export function withFailureContext<E extends FleetError>(error: E, context: FailureContext): E {
+	contexts.set(error, context);
+	return error;
+}
+
+export function failureContext(error: unknown): FailureContext {
+	return typeof error === "object" && error !== null ? (contexts.get(error) ?? {}) : {};
+}

package/src/engine/failureMessage.ts

@@ -0,0 +1,19 @@
+import { isFleetError } from "#errors.ts";
+import { BoardFailure } from "#policy.ts";
+import { SessionFailure } from "#session/schema.ts";
+import { StorageAdmission, StorageCapacity, StorageConflict, StorageQuota } from "#storage/errors.ts";
+export function failureMessage(error: unknown): string {
+	if (error instanceof StorageAdmission || isFleetError(error) || error instanceof SessionFailure || error instanceof BoardFailure) {
+		return error.message;
+	}
+	if (error instanceof StorageQuota) {
+		return "Fresh available provider quota is required";
+	}
+	if (error instanceof StorageCapacity) {
+		return `${error.kind} capacity is occupied (limit ${error.limit})`;
+	}
+	if (error instanceof StorageConflict) {
+		return "Work changed during this observation; load the current record";
+	}
+	return "The integration is unavailable; inspect runtime diagnostics";
+}