@shivaedev/work-fleet 0.0.0 → 0.1.1

package/src/policy.ts

@@ -0,0 +1,131 @@
+import { Context, type Effect, Schema } from "effect";
+import { AttentionOwner } from "#attention.ts";
+import {
+	type BoardAcknowledgementStale,
+	BoardDecision,
+	type BoardDecisionAcknowledgement,
+	type BoardDecisionReading,
+	type BoardReport,
+} from "#board/schema.ts";
+import { DecisionCode } from "#DecisionCode.ts";
+import type { FleetError } from "#errors.ts";
+import type { MainObservation, Preparation } from "#preparation/schema.ts";
+import type { SessionObservation } from "#session/schema.ts";
+import { type LaunchSettings, SessionReceipt } from "#session/schema.ts";
+
+export const BoardWork = Schema.Struct({
+	approved: Schema.Boolean,
+	areas: Schema.optional(Schema.Array(Schema.String)),
+	context: Schema.String,
+	deliverable: Schema.optional(Schema.Literal("report")),
+	dependsOn: Schema.Array(Schema.String),
+	revision: Schema.String,
+	sourcePath: Schema.String,
+	status: Schema.optional(Schema.String),
+	workId: Schema.String,
+});
+export type BoardWork = typeof BoardWork.Type;
+export const Decision = Schema.Struct({
+	attentionOwner: Schema.optional(AttentionOwner),
+	boardAcknowledgementDisposition: Schema.optional(Schema.Literal("superseded")),
+	code: Schema.optional(DecisionCode),
+	id: Schema.String,
+	links: Schema.Array(Schema.String),
+	publicationWork: Schema.optional(BoardWork),
+	published: Schema.optional(BoardDecision),
+	reason: Schema.String,
+	recommendation: Schema.String,
+	worker: Schema.optional(SessionReceipt),
+});
+export type Decision = typeof Decision.Type;
+export const SupersededDecision = Schema.Struct({
+	boardAcknowledged: Schema.optional(Schema.Boolean),
+	boardAcknowledgementDisposition: Schema.optional(Schema.Literal("superseded")),
+	published: BoardDecision,
+	reassignedTo: Schema.optional(Schema.Struct({ attentionOwner: AttentionOwner, decisionId: Schema.String })),
+	supersededAt: Schema.Number,
+});
+export const DecisionResponse = Schema.Struct({
+	action: Schema.optional(Schema.Literals(["retry", "release", "continue"])),
+	boardAcknowledged: Schema.optional(Schema.Boolean),
+	boardAcknowledgementDisposition: Schema.optional(Schema.Literal("superseded")),
+	decisionId: Schema.String,
+	processedAt: Schema.Number,
+	published: Schema.optional(BoardDecision),
+	questionId: Schema.String,
+	questionRevision: Schema.String,
+	responseId: Schema.String,
+	type: Schema.Literals(["answer", "clarify", "not_now"]),
+});
+export type DecisionResponse = typeof DecisionResponse.Type;
+export class BoardFailure extends Schema.TaggedError<BoardFailure>()("BoardFailure", {
+	code: Schema.optional(DecisionCode),
+	message: Schema.String,
+}) {}
+export class BoardGateway extends Context.Service<
+	BoardGateway,
+	{
+		readonly acknowledgeDecision: (input: BoardDecisionAcknowledgement) => Effect.Effect<void, BoardFailure | BoardAcknowledgementStale>;
+		readonly complete?: (workId: string, sourcePath: string, nextAction: string) => Effect.Effect<void, BoardFailure>;
+		readonly get: (workId: string, options?: { readonly fresh?: boolean }) => Effect.Effect<BoardWork, BoardFailure>;
+		readonly decision: (workId: string, decision: Decision, original?: BoardWork) => Effect.Effect<BoardDecision, BoardFailure>;
+		readonly readDecision: (decision: BoardDecision) => Effect.Effect<BoardDecisionReading, BoardFailure>;
+		readonly report: (work: BoardWork, observation: SessionObservation) => Effect.Effect<BoardReport, BoardFailure>;
+	}
+>()("@shivaedev/work-fleet/BoardGateway") {}
+export const ChangeResult = Schema.Struct({
+	head: Schema.String,
+	kind: Schema.Literal("change"),
+	paths: Schema.Array(Schema.String),
+	pr: Schema.String,
+	prNumber: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0))),
+});
+export const NoChangeResult = Schema.Struct({ evidence: Schema.Array(Schema.String), head: Schema.String, kind: Schema.Literal("no-change") });
+export const WorkResult = Schema.Union([ChangeResult, NoChangeResult]);
+export type WorkResult = typeof WorkResult.Type;
+export const Review = Schema.Struct({
+	evidence: Schema.Array(Schema.String),
+	findings: Schema.optional(Schema.Array(Schema.String)),
+	head: Schema.String,
+	receipt: SessionReceipt,
+	repairPrompt: Schema.String,
+	verdict: Schema.Literals(["approved", "changes"]),
+});
+export type Review = typeof Review.Type;
+export const Checks = Schema.Struct({
+	evidence: Schema.Array(Schema.String),
+	failedChecks: Schema.optional(Schema.Array(Schema.String)),
+	head: Schema.String,
+	passed: Schema.Boolean,
+	pending: Schema.optional(Schema.Boolean),
+	repairPrompt: Schema.optional(Schema.String),
+});
+export type Checks = typeof Checks.Type;
+export const Delivery = Schema.Struct({ head: Schema.String, revision: Schema.String, url: Schema.String });
+export type Delivery = typeof Delivery.Type;
+export interface FleetConfiguration {
+	readonly areaMergeWaitMs?: number;
+	readonly deliveryBacklog?: number;
+	readonly executionConcurrency?: number;
+	readonly launch?: LaunchSettings;
+	readonly localOnlyBoardPath?: string;
+	readonly now: () => number;
+	readonly operationId: () => string;
+	readonly quota: { readonly available?: number; readonly observedAt: number; readonly expiresAt: number };
+	readonly readGuidance?: (role: "worker" | "reviewer") => Effect.Effect<string | undefined, FleetError>;
+	readonly refreshQuota?: () => Effect.Effect<FleetConfiguration["quota"], FleetError>;
+	readonly reviewerGuidance?: string;
+	readonly sharedEnvironment?: string;
+	readonly stallMinutes?: number;
+	readonly workerGuidance?: string;
+}
+export class FleetPolicy extends Context.Service<FleetPolicy, FleetConfiguration>()("@shivaedev/work-fleet/FleetPolicy") {}
+export class FleetIntegrations extends Context.Service<
+	FleetIntegrations,
+	{
+		readonly main: (preparation: Preparation) => Effect.Effect<MainObservation, FleetError>;
+		readonly result: (work: BoardWork, observation: SessionObservation) => Effect.Effect<WorkResult, FleetError>;
+		readonly checks: (work: BoardWork, result: WorkResult) => Effect.Effect<Checks, FleetError>;
+		readonly delivery: (result: typeof ChangeResult.Type) => Effect.Effect<Delivery | undefined, FleetError>;
+	}
+>()("@shivaedev/work-fleet/FleetIntegrations") {}

package/src/policyGuidance.ts

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+import type { FleetConfiguration } from "#policy.ts";
+
+export function policyGuidance(policy: FleetConfiguration, role: "worker" | "reviewer") {
+	return policy.readGuidance?.(role) ?? Effect.succeed(role === "worker" ? policy.workerGuidance : policy.reviewerGuidance);
+}

package/src/preparation/compatibility.ts

@@ -0,0 +1,49 @@
+import { Effect } from "effect";
+import type { MainObservation, Preparation, PreparationAssessment } from "#preparation/schema.ts";
+
+export function pathsOverlap(left: string, right: string): boolean {
+	return left === "." || right === "." || left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+function keyOverlaps(left: string, right: string): boolean {
+	return left === right || left.startsWith(`${right}.`) || right.startsWith(`${left}.`);
+}
+
+function relevantPath(preparation: Preparation, observation: MainObservation, path: string): boolean {
+	if (preparation.ownedPaths.some((owned) => pathsOverlap(owned, path))) {
+		return true;
+	}
+	const coverage = preparation.configuration.find((entry) => entry.path === path);
+	if (coverage !== undefined) {
+		const changes = observation.configurationChanges.filter((entry) => entry.path === path);
+		if (changes.length !== 1 || changes[0]?.complete !== true) {
+			return true;
+		}
+		return changes[0].keys.some((changed) => coverage.relevantKeys.some((key) => keyOverlaps(key, changed)));
+	}
+	return [preparation.sourcePaths, preparation.setupPaths, preparation.dependencyPaths, preparation.qualityPaths, preparation.baselinePaths].some(
+		(paths) => paths.some((context) => pathsOverlap(context, path)),
+	);
+}
+
+export const assessPreparation = Effect.fn("Preparation.assessPreparation")(
+	(preparation: Preparation, observation: MainObservation): Effect.Effect<PreparationAssessment> => {
+		if (observation.fromRevision !== preparation.baseRevision || !observation.complete || observation.observedAt < preparation.observedAt) {
+			return Effect.succeed({ _tag: "Reprepare", code: "incomplete-observation", paths: observation.changedPaths, reason: "incomplete-observation" });
+		}
+		if (!observation.ancestor) {
+			return Effect.succeed({ _tag: "Reprepare", code: "not-ancestor", paths: observation.changedPaths, reason: "not-ancestor" });
+		}
+		if (observation.revision !== preparation.baseRevision && !preparation.contextComplete) {
+			return Effect.succeed({ _tag: "Reprepare", code: "incomplete-context", paths: observation.changedPaths, reason: "incomplete-context" });
+		}
+		const paths = observation.changedPaths.filter((path) => relevantPath(preparation, observation, path));
+		if (paths.length > 0) {
+			return Effect.succeed({ _tag: "Reprepare", code: "relevant-change", paths, reason: "relevant-change" });
+		}
+		return Effect.succeed({
+			_tag: "Compatible",
+			preparation: { ...preparation, baseRevision: observation.revision, observedAt: observation.observedAt },
+		});
+	},
+);

package/src/preparation/schema.ts

@@ -0,0 +1,55 @@
+import { Schema } from "effect";
+import { DecisionCode } from "#DecisionCode.ts";
+
+const Text = Schema.String.check(Schema.isMinLength(1));
+export const RepositoryPath = Text.check(
+	Schema.makeFilter(
+		(value) =>
+			value === "."
+			|| (!(value.startsWith("/") || value.includes("\\"))
+				&& value.split("/").every((segment) => segment !== "" && segment !== "." && segment !== ".."))
+			|| "Expected a normalized repository-relative path",
+	),
+);
+
+export const ValidationEvidence = Schema.Struct({ command: Text, revision: Text });
+export const ConfigurationCoverage = Schema.Struct({ path: RepositoryPath, relevantKeys: Schema.Array(Text) });
+export const Preparation = Schema.Struct({
+	baselinePaths: Schema.Array(RepositoryPath),
+	baseRevision: Text,
+	configuration: Schema.Array(ConfigurationCoverage),
+	contextComplete: Schema.Boolean,
+	dependencyPaths: Schema.Array(RepositoryPath),
+	observedAt: Schema.Number,
+	ownedPaths: Schema.Array(RepositoryPath).check(Schema.isMinLength(1)),
+	qualityPaths: Schema.Array(RepositoryPath),
+	setupPaths: Schema.Array(RepositoryPath),
+	sourcePaths: Schema.Array(RepositoryPath),
+	validation: Schema.Array(ValidationEvidence),
+});
+export type Preparation = typeof Preparation.Type;
+
+export const ConfigurationChange = Schema.Struct({ complete: Schema.Boolean, keys: Schema.Array(Text), path: RepositoryPath });
+export const MainObservation = Schema.Struct({
+	ancestor: Schema.Boolean,
+	changedPaths: Schema.Array(RepositoryPath),
+	complete: Schema.Boolean,
+	configurationChanges: Schema.Array(ConfigurationChange),
+	fromRevision: Text,
+	observedAt: Schema.Number,
+	revision: Text,
+});
+export type MainObservation = typeof MainObservation.Type;
+
+const ReprepareCode = DecisionCode.pick(["not-ancestor", "incomplete-observation", "incomplete-context", "relevant-change"]);
+
+export const PreparationAssessment = Schema.Union([
+	Schema.Struct({ _tag: Schema.Literal("Compatible"), preparation: Preparation }),
+	Schema.Struct({
+		_tag: Schema.Literal("Reprepare"),
+		code: Schema.optional(ReprepareCode),
+		paths: Schema.Array(RepositoryPath),
+		reason: ReprepareCode,
+	}),
+]);
+export type PreparationAssessment = typeof PreparationAssessment.Type;

package/src/prompt/reviewer.ts

@@ -0,0 +1,64 @@
+import { Effect, Schema } from "effect";
+import { BadRequest } from "@shivaedev/platform/errors/taxonomy.ts";
+import type { FleetError } from "#errors.ts";
+import type { Review, WorkResult } from "#policy.ts";
+import { cloudStartup } from "#prompt/worker.ts";
+import type { SessionReceipt } from "#session/schema.ts";
+
+export const REVIEW_MARKER = "FLEET_REVIEW:";
+const Text = Schema.String.check(Schema.isPattern(/\S/u));
+export const ReviewerVerdict = Schema.Struct({
+	evidence: Schema.Array(Text).check(Schema.isMinLength(1)),
+	findings: Schema.Array(Text),
+	head: Text,
+	verdict: Schema.Literals(["approve", "changes"]),
+});
+
+export function reviewerPrompt(input: {
+	readonly task: string;
+	readonly result: WorkResult;
+	readonly reviewerGuidance?: string;
+	readonly sharedEnvironment?: string;
+}) {
+	return [
+		"Independently review this task against its acceptance criteria.",
+		...(input.sharedEnvironment === undefined ? [] : ["", cloudStartup({ sharedEnvironment: input.sharedEnvironment }, "read-only")]),
+		"",
+		"Task and criteria:",
+		"---",
+		input.task.trim(),
+		"---",
+		"",
+		`Review target: ${JSON.stringify(input.result)}`,
+		"",
+		"Read root and package AGENTS.md. Inspect only the exact target head, using existing repository objects or read-only repository tools. The checkout may be a different revision; never review that revision in its place.",
+		"You have no worker conversation. Judge the implementation and acceptance evidence independently.",
+		"This session is read-only. Do not edit, commit, push, merge, publish comments or reviews, or launch workers. Do not request escalation. Shell network access is enabled for read-only inspection. Use `gh pr view`, `gh pr diff` and `gh api --method GET` to read the PR and exact-head CI results; verify the PR head before using its diff. Network writes are prohibited.",
+		"When you can inspect the diff at the exact target head and its check results, always end with a verdict: approve or request changes in the format below. Never approve from the task text or a worker's claims alone.",
+		"Passing required checks at that exact head are the CI evidence. Unavailable CI job logs or artifacts (including HTTP 403 from the Cloud GitHub token) alone must not withhold a verdict. Include the passing checks and the access limitation in your evidence list, then decide from the diff and available evidence.",
+		"`main` is protected by a merge queue that re-runs CI against the latest main before merging. A branch behind main without conflicts is not a reason to request changes, repeat review or re-run validation; judge the exact target head and its checks. Workers merge main only when GitHub reports a conflict or the change needs something that landed there.",
+		...(input.reviewerGuidance === undefined ? [] : ["Repository reviewer guidance:", input.reviewerGuidance]),
+		"If the exact head, diff or check results cannot be inspected, report that limitation. Request changes for concrete implementation or validation gaps; unavailable job logs or artifacts alone are not such a gap.",
+		"End with exactly one machine-readable line, with no Markdown fencing:",
+		`${REVIEW_MARKER} ${JSON.stringify({ evidence: ["Evidence you inspected"], findings: [], head: input.result.head, verdict: "approve" })}`,
+		'Use verdict "changes" with nonempty findings that give concrete repair guidance. Use "approve" only with no findings. Evidence must be nonempty for either verdict.',
+	].join("\n");
+}
+
+export const readReviewerVerdict = Effect.fn("Fleet.readReviewerVerdict")(function* (
+	output: string,
+	receipt: SessionReceipt,
+): Effect.fn.Return<Review, FleetError> {
+	const lines = output.split("\n").filter((entry) => entry.trim().startsWith(REVIEW_MARKER));
+	const line = lines.length === 1 ? lines[0] : undefined;
+	if (line === undefined || output.trim().split("\n").at(-1)?.trim() !== line.trim()) {
+		return yield* new BadRequest({ message: "Reviewer must end with one machine-readable verdict" });
+	}
+	const verdict = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(ReviewerVerdict))(line.trim().slice(REVIEW_MARKER.length).trim()).pipe(
+		Effect.mapError(() => new BadRequest({ message: "Reviewer verdict is malformed or lacks evidence" })),
+	);
+	if ((verdict.verdict === "changes") !== verdict.findings.length > 0) {
+		return yield* new BadRequest({ message: "Reviewer changes require findings; approval requires no findings" });
+	}
+	return { ...verdict, receipt, repairPrompt: verdict.findings.join("\n"), verdict: verdict.verdict === "approve" ? "approved" : "changes" };
+});

package/src/prompt/worker.ts

@@ -0,0 +1,132 @@
+import { REPORT_ATTACHMENT_DIRECTORY, REPORT_ATTACHMENT_MARKER } from "#reportAttachments.ts";
+
+export interface CloudStartup {
+	readonly sharedEnvironment: string;
+}
+export interface WorkerPrompt extends CloudStartup {
+	readonly branch: string;
+	readonly deliverable?: "report" | undefined;
+	readonly task: string;
+	readonly workId: string;
+}
+export const MAINTAINER_QUESTION_MARKER = "FLEET_MAINTAINER_QUESTION:";
+export const QUESTION_MARKER = "FLEET_QUESTION:";
+export const PULL_REQUEST_MARKER = "FLEET_PR:";
+const GUIDANCE_HEADING =
+	"Repository worker guidance: maintainer's standing answers to the repository's 'ask the maintainer first' rules; takes precedence for this task";
+const GUIDANCE_END = "End repository worker guidance.";
+const QUESTION_INSTRUCTIONS = [
+	"When you need a decision:",
+	"- Do not ask about anything covered by Repository worker guidance; follow its standing answers.",
+	`- Stop the turn with \`${QUESTION_MARKER} <question>\`, including the context and choices needed to answer. Do not report a PR or no-change outcome while waiting for an answer.`,
+	`- Questions go to the orchestrator by default. Only when a decision requires maintainer authority, use \`${MAINTAINER_QUESTION_MARKER} <question>\` instead.`,
+	"- Fleet publishes the question on the Board and continues this same thread with the recorded answer. Treat that answer as task input; repository rules and runtime authority still apply.",
+].join("\n");
+const REPORT_INSTRUCTIONS = [
+	"Report deliverable:",
+	"- Leave repository sources unchanged. Commit nothing, push nothing, and open no PR. Do not create a branch or launch other workers.",
+	`- Write report attachments as new uncommitted files under ${REPORT_ATTACHMENT_DIRECTORY}, using the file-edit/apply_patch tool for every add and update. Fleet reconstructs files from this turn's fileChange items; files created or changed by shell commands are not retrievable. Never publish attachments to git or GitHub.`,
+	`- Use UTF-8 text attachments. For binary evidence, write a base64 text file with the file-edit tool and describe its encoding. List every promised attachment in the final report on its own line: ${REPORT_ATTACHMENT_MARKER} <path relative to ${REPORT_ATTACHMENT_DIRECTORY}>. Do not reuse files from earlier turns.`,
+	"- Read the root and package AGENTS.md and use read-only research to answer the approved task.",
+	"- Return the whole report as your final message, with evidence for each acceptance criterion and any remaining uncertainty.",
+].join("\n");
+
+// Codex Cloud cannot run startup steps; without this block workers spend minutes probing a provisioning sandbox.
+export function cloudStartup({ sharedEnvironment }: CloudStartup, access?: "read-only") {
+	return [
+		"Cloud startup:",
+		"- Your workspace may still be provisioning when this message arrives. If the cloud-environment runtime skill offers wait_for_environment, call it and wait calmly until the environment is ready; this usually takes about 90 seconds. Do not explore the snapshot or retry commands while waiting. Your instructions below stay valid.",
+		`- Source ${sharedEnvironment} at the start of EVERY independent shell command when it exists. The pinned Node, pnpm and Bun, the proxy, CA trust, caches and database settings come from it.`,
+		...(access === "read-only"
+			? []
+			: [
+					"- Request escalation (require_escalated) from the FIRST network-dependent command, such as git fetch or dependency installation, instead of waiting for it to fail.",
+				]),
+	].join("\n");
+}
+
+export function workerPrompt(input: WorkerPrompt) {
+	if (input.deliverable === "report") {
+		return [`Work Board task: ${input.workId}`, "", cloudStartup(input), "", reportPrompt(input.task.trim())].join("\n");
+	}
+	return [
+		`Work Board task: ${input.workId}`,
+		"",
+		cloudStartup(input),
+		`- Fetch origin/main and create ${input.branch} from that exact current revision, not from the environment snapshot. Use the supplied checkout and leave unrelated state alone.`,
+		"",
+		"Implement this approved Board task:",
+		"---",
+		input.task.trim(),
+		"---",
+		"",
+		"Evidence rules:",
+		"- Read the root and package AGENTS.md before editing, and follow the repository's documentation and pull request skills.",
+		"- Run focused tests while working, then `pnpm ready` before handing off. Never bypass or skip hooks, and never raise the quality baseline.",
+		"- Open exactly ONE pull request for human review. Do not merge it and do not launch other workers.",
+		"- Keep Board IDs, environment IDs, prompts and other private identifiers out of source, docs and pull request metadata.",
+		"- After every push, watch your PR's CI until all checks finish. Fix failures on the same branch, push again and repeat.",
+		"- `main` is protected by a merge queue that re-runs CI against the latest main before merging. Merge main only when GitHub reports a conflict or your change needs something that landed there. A branch behind main without conflicts does not need a merge, fresh review or revalidation. Never wait for main to stop moving or request a merge freeze.",
+		"- If you merge main or otherwise change the head, run `pnpm ready`, push and watch CI again for the new head. Report once all checks are green for your exact head, or when genuinely blocked. If blocked, explain why and identify the failed or pending checks.",
+		"",
+		QUESTION_INSTRUCTIONS,
+		"",
+		"Final report:",
+		"- The pull request URL, its head SHA and base, the changed paths and the exact commands you ran with their results.",
+		"- A short result against each acceptance criterion, separating proven behavior from anything still pending.",
+		"- State the CI result for the exact head SHA you report, including any failed or pending checks and why you are blocked. Put the CI result before the final `FLEET_PR:` line.",
+		"- Before the final PR line, include one line `FLEET_HEAD: <sha>` with the full 40-character PR head SHA, or the exact checked main SHA when no change was needed.",
+		`- End with one line \`${PULL_REQUEST_MARKER} <url>\` naming the pull request, or \`${PULL_REQUEST_MARKER} none\` when no change was needed.`,
+	].join("\n");
+}
+
+export function reportPrompt(task: string): string {
+	return task.endsWith(REPORT_INSTRUCTIONS) ? task : [task, "", QUESTION_INSTRUCTIONS, "", REPORT_INSTRUCTIONS].join("\n");
+}
+
+export function withWorkerGuidance(prompt: string, guidance?: string): string {
+	if (guidance === undefined) {
+		return prompt;
+	}
+	const block = [GUIDANCE_HEADING, guidance, GUIDANCE_END].join("\n");
+	const task = prompt.replaceAll(new RegExp(`\\n\\n${GUIDANCE_HEADING}\\n[\\s\\S]*?\\nEnd repository worker guidance\\.`, "gu"), "");
+	const evidence = task.indexOf("\n\nEvidence rules:");
+	const boundary = evidence < 0 ? task.indexOf("\n\nWhen you need a decision:") : evidence;
+	return boundary < 0 ? [task, block].join("\n\n") : `${task.slice(0, boundary)}\n\n${block}${task.slice(boundary)}`;
+}
+
+export function reportedPullRequest(output: string) {
+	const lines = output
+		.trim()
+		.split(/\r?\n/u)
+		.map((line) => line.trim());
+	const markers = lines.filter((line) => line.startsWith(PULL_REQUEST_MARKER));
+	if (markers.length !== 1 || markers[0] !== lines.at(-1)) {
+		return undefined;
+	}
+	const value = markers[0]
+		?.slice(PULL_REQUEST_MARKER.length)
+		.trim()
+		.replace(/^`(?<value>[^`]*)`$/u, "$<value>")
+		.trim();
+	if (value === "none") {
+		return { kind: "none" } as const;
+	}
+	if (value === undefined || /^https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/[1-9]\d*$/u.exec(value) === null) {
+		return undefined;
+	}
+	return { kind: "url", url: value } as const;
+}
+
+export function reportedQuestion(output: string) {
+	const lines = output.split("\n");
+	const index = lines.findIndex((line) => [QUESTION_MARKER, MAINTAINER_QUESTION_MARKER].some((candidate) => line.trim().startsWith(candidate)));
+	if (index < 0) {
+		return undefined;
+	}
+	const first = lines[index]?.trim() ?? "";
+	const maintainer = first.startsWith(MAINTAINER_QUESTION_MARKER);
+	const marker = maintainer ? MAINTAINER_QUESTION_MARKER : QUESTION_MARKER;
+	const question = [first.slice(marker.length).trim(), ...lines.slice(index + 1)].join("\n").trim();
+	return question.length === 0 ? undefined : { attentionOwner: maintainer ? ("maintainer" as const) : ("orchestrator" as const), question };
+}

package/src/providers/capacity.ts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+import { ProviderCapacity } from "#session/schema.ts";
+
+const ErrorData = Schema.Struct({ data: Schema.Struct({ codexErrorInfo: ProviderCapacity }) });
+export function capacity(error: unknown) {
+	const decoded = Schema.decodeUnknownOption(ErrorData)(error);
+	return decoded._tag === "Some" ? decoded.value.data.codexErrorInfo : undefined;
+}

package/src/providers/codexAdapter.ts

@@ -0,0 +1,73 @@
+import { Effect } from "effect";
+import { ThreadResponse } from "#providers/codexProtocol.ts";
+import { decode, failure } from "#providers/codexRpc.ts";
+import { echoedSettings, settingsParams } from "#providers/codexSettings.ts";
+import { type CodexRequest, codexTurns } from "#providers/codexTurns.ts";
+import { observeCodexTurn } from "#providers/observeCodexTurn.ts";
+import { recoverTurn } from "#providers/recoverTurn.ts";
+import { startCodexTurn } from "#providers/startCodexTurn.ts";
+import type { ContinueSession, ReconcileSession, SessionFailure, SessionObservation, SessionReceipt, StartSession } from "#session/schema.ts";
+import type { SessionTransport } from "#session/service.ts";
+
+export interface CodexDialect {
+	readonly beforeTurn: (input: ContinueSession) => Effect.Effect<Record<string, unknown>, SessionFailure>;
+	readonly provisioning: SessionObservation["provisioning"];
+	readonly recoveryGraceMs?: number;
+	readonly sessionStarted?: (sessionId: string) => void;
+	readonly threadStart: (input: StartSession) => Record<string, unknown>;
+}
+export function codexAdapter(rpc: CodexRequest, dialect: CodexDialect): typeof SessionTransport.Service {
+	const turns = codexTurns(rpc);
+	const { findTurn, operationTurn, waitUntilIdle } = turns;
+	const submitTurn = startCodexTurn(rpc, waitUntilIdle);
+	const startTurn = Effect.fn("Codex.startTurn")(function* (input: ContinueSession) {
+		const extra = yield* dialect.beforeTurn(input);
+		const result = yield* submitTurn(input.sessionId, {
+			...extra,
+			...settingsParams(input.settings),
+			clientUserMessageId: input.operationId,
+			input: [{ text: input.prompt, "text_elements": [], type: "text" }],
+			threadId: input.sessionId,
+		});
+		return { sessionId: input.sessionId, turnId: result.turn.id };
+	});
+	const recover = recoverTurn(operationTurn, startTurn, dialect.recoveryGraceMs);
+	return {
+		interrupt: Effect.fn("Codex.interrupt")(function* (receipt: SessionReceipt) {
+			yield* rpc("turn/interrupt", { threadId: receipt.sessionId, turnId: receipt.turnId }, true);
+			return receipt;
+		}),
+		observe: observeCodexTurn(turns, dialect.provisioning),
+		reconcile: Effect.fn("Codex.reconcile")(function* (input: ReconcileSession) {
+			if (input.sessionId === undefined) {
+				return yield* Effect.fail(
+					failure("ambiguous", "Lost thread acknowledgement cannot be reconciled by this Codex protocol; retain reservation"),
+				);
+			}
+			if (input.turnId !== undefined) {
+				yield* findTurn(input.sessionId, input.turnId);
+				return { sessionId: input.sessionId, turnId: input.turnId };
+			}
+			return yield* recover({ ...input, sessionId: input.sessionId });
+		}),
+		startSession: Effect.fn("Codex.startSession")(function* (input) {
+			const result = yield* rpc("thread/start", dialect.threadStart(input), true).pipe(Effect.flatMap((value) => decode(ThreadResponse, value)));
+			dialect.sessionStarted?.(result.thread.id);
+			yield* echoedSettings(input.settings, result).pipe(
+				Effect.mapError((error) => failure("ambiguous", `${error.message}; retain the started session reservation`)),
+			);
+			return result.thread.id;
+		}),
+		startTurn,
+		steer: (receipt, prompt) =>
+			rpc(
+				"turn/steer",
+				{
+					expectedTurnId: receipt.turnId,
+					input: [{ text: prompt, "text_elements": [], type: "text" }],
+					threadId: receipt.sessionId,
+				},
+				true,
+			).pipe(Effect.asVoid),
+	};
+}

package/src/providers/codexCloud.ts

@@ -0,0 +1,112 @@
+import { Context, Effect, FileSystem, Layer, Schema } from "effect";
+import { ChildProcessSpawner } from "effect/process";
+import { defineService } from "@shivaedev/effect-service/define-service.ts";
+import { codexAdapter } from "#providers/codexAdapter.ts";
+import { codexCloudConnection } from "#providers/codexCloudConnection.ts";
+import { decode, failure } from "#providers/codexRpc.ts";
+import type { ContinueSession, StartSession } from "#session/schema.ts";
+import { SessionTransport } from "#session/service.ts";
+
+export const CODEX_CLOUD_ENDPOINT = "wss://codex-cloud-backend.chatgpt.com/";
+export const CodexCloudConfiguration = Schema.Struct({
+	archiveThreads: Schema.optional(Schema.Boolean),
+	authFile: Schema.optional(Schema.String),
+	cwd: Schema.String.check(Schema.isNonEmpty()),
+	endpoint: Schema.optional(Schema.String),
+	environmentId: Schema.String.check(Schema.isNonEmpty()),
+	projectId: Schema.optional(Schema.String.check(Schema.isNonEmpty())),
+	refreshCommand: Schema.optional(Schema.Struct({ args: Schema.Array(Schema.String), command: Schema.String })),
+	requestTimeoutMs: Schema.Finite.check(Schema.isGreaterThan(0)),
+	threadNamePrefix: Schema.optional(Schema.String.check(Schema.isNonEmpty())),
+	writableRoots: Schema.optional(Schema.Array(Schema.String)),
+});
+export type CodexCloudConfiguration = typeof CodexCloudConfiguration.Type;
+export class CodexCloudConfig extends Context.Service<CodexCloudConfig, CodexCloudConfiguration>()("@shivaedev/work-fleet/CodexCloudConfig") {}
+
+const CloudThread = Schema.Struct({
+	thread: Schema.Struct({
+		environments: Schema.NullOr(
+			Schema.Array(
+				Schema.Struct({ cwd: Schema.String, environmentConfigId: Schema.optional(Schema.String), environmentId: Schema.optional(Schema.String) }),
+			),
+		),
+	}),
+});
+function threadStart(config: CodexCloudConfiguration, input: StartSession) {
+	return {
+		config: {
+			"sandbox_mode": input.access === "read-only" ? "read-only" : "workspace-write",
+			...(input.access === "read-only" ? { "approval_policy": "never", "sandbox_read_only.network_access": true } : {}),
+			...(input.settings?.effort === undefined ? {} : { "model_reasoning_effort": input.settings.effort }),
+		},
+		deferredEnvironment: true,
+		environments: [{ cwd: config.cwd, environmentConfigId: config.environmentId }],
+		experimentalRawEvents: false,
+		pluginsMcp: { productSku: "codex" },
+		serviceName: "codex_cloud",
+		threadSource: "user",
+		...(config.projectId === undefined ? {} : { projectId: config.projectId }),
+		...(input.settings?.model === undefined ? {} : { model: input.settings.model }),
+		...(input.settings?.serviceTier === undefined ? {} : { serviceTier: input.settings.serviceTier }),
+	};
+}
+
+const CodexCloud = defineService({
+	id: "Fleet/CodexCloud",
+	initialize: Effect.gen(function* () {
+		const config = yield* Schema.decodeUnknownEffect(CodexCloudConfiguration)(yield* CodexCloudConfig).pipe(
+			Effect.mapError(() => failure("unavailable", "Codex Cloud configuration needs an environment, workspace cwd and positive timeout")),
+		);
+		const rpc = yield* codexCloudConnection(config.endpoint ?? CODEX_CLOUD_ENDPOINT, config, config.requestTimeoutMs);
+		const sandboxPolicy = {
+			excludeSlashTmp: false,
+			excludeTmpdirEnvVar: false,
+			networkAccess: true,
+			type: "workspaceWrite",
+			writableRoots: config.writableRoots ?? [config.cwd, "/tmp"],
+		};
+		const verifyEnvironment = Effect.fn("CodexCloud.verifyEnvironment")(function* (input: ContinueSession) {
+			const read = yield* rpc("thread/read", { includeTurns: false, threadId: input.sessionId }).pipe(
+				Effect.flatMap((value) => decode(CloudThread, value)),
+			);
+			const environments = read.thread.environments ?? [];
+			const [environment] = environments;
+			if (
+				environments.length !== 1
+				|| environment === undefined
+				|| (environment.environmentConfigId ?? environment.environmentId) !== config.environmentId
+				|| environment.cwd !== config.cwd
+			) {
+				return yield* Effect.fail(failure("protocol", "Codex Cloud did not confirm the configured environment and cwd; retain the session"));
+			}
+			return input.access === "read-only"
+				? { approvalPolicy: "never", sandboxPolicy: { networkAccess: true, type: "readOnly" } }
+				: { approvalPolicy: "on-request", approvalsReviewer: "auto_review", sandboxPolicy };
+		});
+		const adapter = codexAdapter(rpc, {
+			beforeTurn: verifyEnvironment,
+			provisioning: "unknown",
+			recoveryGraceMs: 5000,
+			threadStart: (input) => threadStart(config, input),
+		});
+		return {
+			...adapter,
+			archive: (sessionId: string) =>
+				config.archiveThreads === false ? Effect.void : rpc("thread/archive", { threadId: sessionId }, true).pipe(Effect.asVoid),
+			nameSession: (sessionId: string, name: string) =>
+				rpc("thread/name/set", { name: `${config.threadNamePrefix ?? "Fleet: "}${name}`, threadId: sessionId }, true).pipe(Effect.asVoid),
+			readSessionName: (sessionId: string) =>
+				rpc("thread/read", { includeTurns: false, threadId: sessionId }).pipe(
+					Effect.flatMap((value) => decode(Schema.Struct({ thread: Schema.Struct({ name: Schema.optional(Schema.NullOr(Schema.String)) }) }), value)),
+					Effect.map((value) => value.thread.name ?? undefined),
+				),
+			startSession: (input: StartSession) =>
+				input.cwd === config.cwd
+					? adapter.startSession(input)
+					: Effect.fail(failure("rejected", "Work cwd differs from the configured Codex Cloud workspace cwd")),
+		};
+	}),
+	methods: (adapter) => adapter,
+	requires: [CodexCloudConfig, FileSystem.FileSystem, ChildProcessSpawner.ChildProcessSpawner],
+});
+export const codexCloudLayer = Layer.effect(SessionTransport)(CodexCloud).pipe(Layer.provide(CodexCloud.layer));