@shivaedev/work-board 0.10.0 → 0.12.0

package/src/server/board.ts

@@ -0,0 +1,147 @@
+import { Context, Effect, FileSystem, Layer, Path, type PlatformError, type Scope } from "effect";
+import { HttpRouter, HttpServerRequest, type HttpServerResponse } from "effect/unstable/http";
+import type { InternalServerError } from "@shivaedev/platform/errors/taxonomy.ts";
+import { loopbackOnly } from "@shivaedev/platform/rpc-server/local.ts";
+import { Diagnostics, DiagnosticsSources } from "#diagnostics/source.ts";
+import type { RenderFailed } from "#render/failed.ts";
+import { boardServices } from "#server/boardServices.ts";
+import { daemonDiagnostics } from "#server/diagnostics/daemon.ts";
+import { diagnosticsPage } from "#server/diagnostics/page.ts";
+import { readDocument } from "#server/document/read.ts";
+import { watchChanges } from "#server/files/changes.ts";
+import { type HomeMissing, homeIn } from "#server/files/home.ts";
+import { handoffPage } from "#server/handoffs/page.ts";
+import type { HandoffsService } from "#server/handoffs/Service.ts";
+import { ASSET_HANDLERS, checkBrowserAssets, MERMAID_ROUTE, type MermaidMissing, mermaidFile, mermaidRoot } from "#server/http/assets.ts";
+import { attachment } from "#server/http/attachment.ts";
+import { changesPage } from "#server/http/changesPage.ts";
+import { identity } from "#server/http/identity.ts";
+import { inbox } from "#server/http/inbox.ts";
+import { overview } from "#server/http/overview.ts";
+import { page } from "#server/http/page.ts";
+import { readPage } from "#server/http/readPage.ts";
+import { start } from "#server/http/start.ts";
+import { work } from "#server/http/work.ts";
+import { Highlighter } from "#server/render/Highlighter.ts";
+import { responsePage } from "#server/responses/page.ts";
+import type { Responses } from "#server/responses/service.ts";
+import { resultPage } from "#server/results/page.ts";
+import { server } from "#server/rpc/transport.ts";
+import { searchSnapshot } from "#server/search/snapshot.ts";
+
+export interface BoardOptions {
+	readonly fleetPort?: number;
+	readonly home?: string | undefined;
+	readonly maintainer?: string | undefined;
+	readonly responses?: boolean;
+	readonly root: string;
+}
+
+type Services = Highlighter | Responses | HandoffsService | Diagnostics | FileSystem.FileSystem | Path.Path;
+type Handler<E> = (request: HttpServerRequest.HttpServerRequest) => Effect.Effect<HttpServerResponse.HttpServerResponse, E, Services | Scope.Scope>;
+
+function routes(options: BoardOptions) {
+	return HttpRouter.use((router) =>
+		Effect.gen(function* () {
+			const home = yield* homeIn(options.root, options.home);
+			const mermaid = yield* mermaidRoot();
+			yield* checkBrowserAssets();
+			const changes = yield* watchChanges(options.root);
+			const platform = (yield* Effect.context<Highlighter | FileSystem.FileSystem | Path.Path>()).pipe(
+				Context.pick(Highlighter, FileSystem.FileSystem, Path.Path),
+			);
+			const index = yield* searchSnapshot(options.root, home, changes, options.maintainer);
+			const provided = yield* Effect.serviceOption(DiagnosticsSources);
+			const services = yield* Layer.build(
+				boardServices(
+					{ changes, enabled: options.responses === true, index: Effect.provideContext(index, platform), root: options.root },
+					provided._tag === "Some" ? { _tag: "Sources", sources: provided.value } : { _tag: "Read", read: daemonDiagnostics(options.fleetPort) },
+				),
+			);
+			const context = Context.merge(platform, services);
+			function serve<E>(route: HttpRouter.PathInput, handler: Handler<E>, method: "GET" | "POST" = "GET") {
+				return router.add(
+					method,
+					route,
+					loopbackOnly((request) => Effect.provideContext(handler(request), context)),
+				);
+			}
+			yield* serve("/_board/attachment/*", attachment(options.root, changes.realRoot));
+			const healthPage = diagnosticsPage(
+				Effect.flatMap(Diagnostics, (service) => service.read()).pipe(Effect.provideContext(context)),
+				changes,
+				home,
+				index,
+			);
+			yield* serve("/_board/diagnostics", () => healthPage);
+			const inboxPage = inbox(index, changes, home);
+			yield* serve("/_board/inbox", inboxPage);
+			const startPage = start(changes, home, index);
+			yield* serve("/_board/start", startPage);
+			const workPage = work(index, changes, home);
+			const result = resultPage(index, changes, home);
+			yield* serve("/_board/result", result);
+			const overviewPage = overview(index, changes, home);
+			const historyPage = changesPage(changes, home, index);
+			yield* serve("/_board/work", workPage);
+			yield* serve("/_board/overview", overviewPage);
+			yield* serve("/_board/changes", historyPage);
+			for (const [route, asset] of ASSET_HANDLERS) {
+				yield* serve(route, asset);
+			}
+			yield* serve(MERMAID_ROUTE, mermaidFile(mermaid));
+			const replyPage = responsePage(changes, home, options.responses === true, index);
+			yield* serve("/_board/respond", replyPage);
+			const handoff = handoffPage(changes, home, options.responses === true, index);
+			yield* serve("/_board/handoff", handoff);
+			const pages = page({ home, root: options.root, writable: options.responses === true }, changes, index);
+			const items = identity(index, pages, changes, home);
+			yield* serve("/_board/item/*", items);
+			const reading = readPage<PlatformError.PlatformError, Services>(
+				{
+					"/_board/changes": () => historyPage(),
+					"/_board/diagnostics": () => healthPage,
+					"/_board/handoff": handoff,
+					"/_board/inbox": () => inboxPage(),
+					"/_board/overview": () => overviewPage(),
+					"/_board/respond": replyPage,
+					"/_board/result": result,
+					"/_board/start": () => startPage(),
+					"/_board/work": workPage,
+				},
+				(request) => (new URL(request.url, "http://127.0.0.1").pathname.startsWith("/_board/item/") ? items(request) : pages(request)),
+			);
+			const rpc = yield* server({
+				changes,
+				document: (url) =>
+					Effect.provideContext(
+						readDocument({
+							changes,
+							home,
+							index: Effect.provideContext(index, context),
+							root: options.root,
+							writable: options.responses === true,
+						})(url),
+						context,
+					),
+				home,
+				index: Effect.provideContext(index, context),
+				page: (url) => Effect.provideContext(reading(url), context),
+			}).pipe(Effect.provideContext(context));
+			yield* serve("/_board/rpc", (request) => rpc.pipe(Effect.provideService(HttpServerRequest.HttpServerRequest, request)), "POST");
+			yield* serve("/", pages);
+			yield* serve("/*", pages);
+		}),
+	);
+}
+
+type BoardError = InternalServerError | HomeMissing | MermaidMissing | PlatformError.PlatformError | RenderFailed;
+type BoardServices =
+	| FileSystem.FileSystem
+	| HttpRouter.HttpRouter
+	| Path.Path
+	| HttpRouter.Request<"Error", InternalServerError | PlatformError.PlatformError>;
+
+export function boardLayer(options: BoardOptions): Layer.Layer<never, BoardError, BoardServices> {
+	return routes(options).pipe(Layer.provide(Highlighter.layer));
+}

package/src/server/boardServices.ts

@@ -0,0 +1,10 @@
+import { type Context, Layer } from "effect";
+import { Diagnostics, DiagnosticsConfig } from "#diagnostics/source.ts";
+import { HandoffsService } from "#server/handoffs/Service.ts";
+import { ResponseConfig, type ResponseOptions, Responses } from "#server/responses/service.ts";
+
+export function boardServices(options: ResponseOptions, diagnostics: Context.Service.Shape<typeof DiagnosticsConfig>) {
+	return Layer.mergeAll(Responses.layer, HandoffsService.layer, Diagnostics.layer).pipe(
+		Layer.provide(Layer.merge(Layer.succeed(ResponseConfig, options), Layer.succeed(DiagnosticsConfig, diagnostics))),
+	);
+}

package/src/server/cli.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import process from "node:process";
+
+const action = process.argv[2];
+if (action === "wait" || action === "response" || action === "question") {
+	try {
+		const entry: typeof import("#server/responses/agent-cli.ts") = await import(new URL("../../assets/agent.js", import.meta.url).href);
+		await entry.runAgent(process.argv.slice(2));
+	} catch (error) {
+		process.stderr.write(`${String(error)}\n`);
+		process.exitCode ??= 1;
+	}
+} else {
+	const entry = await import("./serve-cli.ts");
+	entry.runServe();
+}

package/src/server/diagnostics/codexLimits.ts

@@ -0,0 +1,15 @@
+import { Effect, Schema } from "effect";
+import { CodexLimits, SourceFailure } from "#diagnostics/source.ts";
+import { codexRateLimits } from "./codexRateLimits.ts";
+
+const Response = Schema.Struct({ rateLimits: CodexLimits });
+
+export function codexLimits(read = codexRateLimits()) {
+	return read.pipe(
+		Effect.flatMap(Schema.decodeUnknownEffect(Response)),
+		Effect.map(({ rateLimits }) => rateLimits),
+		Effect.mapError((error) =>
+			error instanceof SourceFailure ? error : new SourceFailure({ kind: "error", message: "Codex returned invalid usage windows" }),
+		),
+	);
+}

package/src/server/diagnostics/codexProtocol.ts

@@ -0,0 +1,44 @@
+import { Schema } from "effect";
+import { SourceFailure } from "#diagnostics/source.ts";
+
+const Envelope = Schema.Struct({
+	error: Schema.optional(Schema.Struct({ message: Schema.String })),
+	id: Schema.optional(Schema.Union([Schema.String, Schema.Number])),
+	method: Schema.optional(Schema.String),
+	result: Schema.optional(Schema.Unknown),
+});
+const Account = Schema.Struct({ account: Schema.NullOr(Schema.Struct({ type: Schema.String })) });
+export type CodexReply = { readonly send: readonly unknown[] } | { readonly result: unknown } | { readonly failure: SourceFailure };
+
+export function codexReply(line: string): CodexReply {
+	try {
+		const message = Schema.decodeUnknownSync(Schema.fromJsonString(Envelope))(line);
+		if (message.method !== undefined && message.id !== undefined) {
+			return { send: [{ error: { code: -32_601, message: "Diagnostics reader approves nothing" }, id: message.id }] };
+		}
+		if (!["initialize", "account", "limits"].includes(String(message.id))) {
+			return { send: [] };
+		}
+		if (message.error !== undefined) {
+			return { failure: new SourceFailure({ kind: "error", message: `Codex ${message.id}: ${message.error.message.slice(0, 500)}` }) };
+		}
+		switch (message.id) {
+			case "initialize":
+				return { send: [{ method: "initialized" }, { id: "account", method: "account/read", params: { refreshToken: false } }] };
+			case "account": {
+				const account = Schema.decodeUnknownSync(Account)(message.result).account;
+				if (account?.type === "apiKey") {
+					return { failure: new SourceFailure({ kind: "not-configured", message: "Codex usage windows are not available for API-key accounts" }) };
+				}
+				if (account === null) {
+					return { failure: new SourceFailure({ kind: "not-configured", message: "Codex usage windows require an authenticated ChatGPT account" }) };
+				}
+				return { send: [{ id: "limits", method: "account/rateLimits/read", params: { excludeResetCreditDetails: true } }] };
+			}
+			default:
+				return { result: message.result };
+		}
+	} catch {
+		return { failure: new SourceFailure({ kind: "error", message: "Codex returned an invalid app-server response" }) };
+	}
+}

package/src/server/diagnostics/codexRateLimits.ts

@@ -0,0 +1,62 @@
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { Effect } from "effect";
+import { SourceFailure } from "#diagnostics/source.ts";
+import { codexReply } from "./codexProtocol.ts";
+
+export function codexRateLimits(
+	launch: () => ChildProcessWithoutNullStreams = () => spawn("codex", ["app-server", "--listen", "stdio://"], { stdio: "pipe" }),
+	timeoutMs = 30_000,
+) {
+	return Effect.callback<unknown, SourceFailure>((resume) => {
+		const child = launch();
+		const lines = createInterface({ input: child.stdout });
+		let settled = false;
+		function finish(result: Effect.Effect<unknown, SourceFailure>) {
+			if (settled) {
+				return;
+			}
+			settled = true;
+			clearTimeout(timer);
+			lines.close();
+			child.kill();
+			resume(result);
+		}
+		function fail(message: string, kind: SourceFailure["kind"] = "error") {
+			finish(Effect.fail(new SourceFailure({ kind, message })));
+		}
+		function send(value: unknown) {
+			child.stdin.write(`${JSON.stringify(value)}\n`);
+		}
+		const timer = setTimeout(() => fail("Codex rate limits timed out"), timeoutMs);
+		child.on("error", (error) =>
+			fail(`Codex app-server could not start: ${error.message}`, "code" in error && error.code === "ENOENT" ? "not-configured" : "error"),
+		);
+		child.on("exit", () => fail("Codex app-server exited before reporting rate limits"));
+		child.stdin.on("error", () => fail("Codex app-server input closed before reporting rate limits"));
+		child.stderr.resume();
+		lines.on("line", (line) => {
+			const reply = codexReply(line);
+			if ("send" in reply) {
+				for (const message of reply.send) {
+					send(message);
+				}
+			} else if ("failure" in reply) {
+				finish(Effect.fail(reply.failure));
+			} else {
+				finish(Effect.succeed(reply.result));
+			}
+		});
+		send({
+			id: "initialize",
+			method: "initialize",
+			params: { capabilities: { experimentalApi: true }, clientInfo: { name: "work-board", version: "0.0.0" } },
+		});
+		return Effect.sync(() => {
+			settled = true;
+			clearTimeout(timer);
+			lines.close();
+			child.kill();
+		});
+	});
+}

package/src/server/diagnostics/daemon.ts

@@ -0,0 +1,34 @@
+import { Clock, Effect, Layer } from "effect";
+import { FetchHttpClient } from "effect/unstable/http";
+import { RpcClient, RpcSerialization } from "effect/unstable/rpc";
+import { RpcClientError } from "effect/unstable/rpc/RpcClientError";
+import { DAEMON_PORT, DAEMON_RPC_PATH, DiagnosticsContract, type DiagnosticsSnapshot } from "#diagnostics/daemonContract.ts";
+
+const daemonUnavailable = Effect.fn("WorkBoard.daemonUnavailable")(function* (error: unknown, port: number) {
+	const stopped = error instanceof RpcClientError && error.reason._tag === "HttpError" && error.reason.kind === "TransportError";
+	const observation = {
+		cause: stopped
+			? `No Fleet daemon is running at 127.0.0.1:${port}; start work-fleet serve <board-dir> --port ${port}`
+			: `Fleet daemon communication failed at 127.0.0.1:${port}`,
+		observedAt: yield* Clock.currentTimeMillis,
+		state: "error" as const,
+	};
+	return { codex: observation, fleet: observation, github: observation } satisfies DiagnosticsSnapshot;
+});
+
+export function daemonDiagnostics(port = DAEMON_PORT) {
+	return Effect.scoped(
+		Effect.gen(function* () {
+			const client = yield* RpcClient.make(DiagnosticsContract, { flatten: true });
+			return yield* client("daemon.diagnostics", {});
+		}).pipe(
+			Effect.provide(
+				RpcClient.layerProtocolHttp({ url: `http://127.0.0.1:${port}${DAEMON_RPC_PATH}` }).pipe(
+					Layer.provide([FetchHttpClient.layer, RpcSerialization.layerNdjson]),
+				),
+			),
+			Effect.timeout("5 seconds"),
+			Effect.catch((error) => daemonUnavailable(error, port)),
+		),
+	);
+}

package/src/server/diagnostics/fleetHealth.ts

@@ -0,0 +1,69 @@
+import { constants } from "node:fs";
+import { type FileHandle, open, realpath } from "node:fs/promises";
+import { Effect, Schema } from "effect";
+import { FLEET_HEALTH_NAME, FleetHealth } from "#diagnostics/health.ts";
+import { SourceFailure } from "#diagnostics/source.ts";
+import { directoryPath, validateDirectory } from "#server/responses/publicationDirectory.ts";
+
+function readFailure(error: unknown): SourceFailure {
+	if (error instanceof SourceFailure) {
+		return error;
+	}
+	if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+		return new SourceFailure({ kind: "not-configured", message: "Fleet has not published a health snapshot" });
+	}
+	return new SourceFailure({
+		kind: "error",
+		message: `Fleet health snapshot could not be read: ${error instanceof Error ? error.message : "unknown error"}`.slice(0, 500),
+	});
+}
+async function readSnapshot(file: FileHandle): Promise<FleetHealth> {
+	const stat = await file.stat();
+	if (!stat.isFile() || stat.size > 64 * 1024) {
+		throw new SourceFailure({
+			kind: "error",
+			message: "Snapshot must be a regular file under 64 KiB. Ask Fleet to publish a supported health snapshot.",
+		});
+	}
+	const source = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown))(await file.readFile("utf8"));
+	const { version } = Schema.decodeUnknownSync(Schema.Struct({ version: Schema.Int }))(source);
+	if (version !== 2) {
+		throw new SourceFailure({
+			kind: "error",
+			message: `Fleet health snapshot version ${version} is not supported by this Board. Use compatible Board and Fleet versions.`,
+		});
+	}
+	return Schema.decodeUnknownSync(FleetHealth)(source);
+}
+
+export function fleetHealth(root: string) {
+	return Effect.tryPromise({
+		catch: readFailure,
+		try: async () => {
+			const realRoot = await realpath(root);
+			const directory = await open(realRoot, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+			try {
+				const base = directoryPath(directory, realRoot);
+				await validateDirectory(directory, base, realRoot);
+				const target = await open(`${base}/fleet`, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+				try {
+					const folder = directoryPath(target, `${realRoot}/fleet`);
+					await validateDirectory(target, folder, `${realRoot}/fleet`);
+					const file = await open(`${folder}/${FLEET_HEALTH_NAME}`, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+					try {
+						const snapshot = await readSnapshot(file);
+						await validateDirectory(directory, base, realRoot);
+						await validateDirectory(target, folder, `${realRoot}/fleet`);
+						return snapshot;
+					} finally {
+						await file.close();
+					}
+				} finally {
+					await target.close();
+				}
+			} finally {
+				await directory.close();
+			}
+		},
+	});
+}

package/src/server/diagnostics/githubLimits.ts

@@ -0,0 +1,15 @@
+import { Effect, Schema } from "effect";
+import { GithubLimits, SourceFailure } from "#diagnostics/source.ts";
+import { readCommand } from "./readCommand.ts";
+
+const Response = Schema.Struct({ resources: GithubLimits });
+
+export function githubLimits(read = readCommand("gh", ["api", "rate_limit"])) {
+	return read.pipe(
+		Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(Response))),
+		Effect.map(({ resources }) => resources),
+		Effect.mapError((error) =>
+			error instanceof SourceFailure ? error : new SourceFailure({ kind: "error", message: "GitHub returned invalid rate limits" }),
+		),
+	);
+}

package/src/server/diagnostics/html.ts

@@ -0,0 +1,93 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { FleetHealth } from "#diagnostics/health.ts";
+import { resetLabel } from "#diagnostics/resetLabel.ts";
+import type { CodexLimits, GithubLimits, Observation, UsageWindow } from "#diagnostics/source.ts";
+
+function time(milliseconds: number | null): string {
+	return milliseconds === null
+		? "Not reported"
+		: `<time datetime="${new Date(milliseconds).toISOString()}">${new Date(milliseconds)
+				.toISOString()
+				.replace("T", " ")
+				.replace(/\.\d{3}Z$/u, " UTC")}</time>`;
+}
+function observed(at: number): string {
+	return `<p class="diagnostics-freshness">Observed ${time(at)}</p>`;
+}
+function card<A>(name: string, source: Observation<A>, render: (value: A) => string, attention = false, stale = false): string {
+	let state: Observation<A>["state"] | "attention" | "stale" = source.state;
+	if (state === "ready" && attention) {
+		state = "attention";
+	}
+	if (source.state === "ready" && stale) {
+		state = "stale";
+	}
+	const label = { attention: "Needs attention", error: "Unavailable", "not-configured": "Not configured", ready: "Available", stale: "Stale" }[state];
+	return `<section class="diagnostics-card" data-source="${name.toLowerCase()}" data-state="${state}" aria-labelledby="diagnostics-${name.toLowerCase()}"><header><h2 id="diagnostics-${name.toLowerCase()}">${name}</h2><span class="diagnostics-status">${label}</span></header>${source.state === "ready" ? render(source.value) : `<p role="status">${escapeHtml(source.cause)}</p>`}${observed(source.observedAt)}</section>`;
+}
+function reset(at: number | null, now: number): string {
+	return at === null ? "Not reported" : `<time data-reset datetime="${new Date(at).toISOString()}">${resetLabel(at, now)}</time>`;
+}
+function windowLabel(name: string, minutes: number | null): string {
+	if (minutes === null) {
+		return `${name} — duration not reported`;
+	}
+	if (minutes === 10_080) {
+		return "Weekly";
+	}
+	for (const [duration, unit] of [
+		[1440, "day"],
+		[60, "hour"],
+	] as const) {
+		if (minutes % duration === 0) {
+			return `${minutes / duration}-${unit}`;
+		}
+	}
+	return `${minutes}-minute`;
+}
+function usage(name: string, window: UsageWindow | null, now: number): string {
+	if (window === null) {
+		return `<li><h3>${name}</h3><p>Window not reported</p></li>`;
+	}
+	const label = windowLabel(name, window.windowDurationMins);
+	return `<li><h3>${label}</h3><p><strong>${window.usedPercent}% used</strong></p><meter min="0" max="100" value="${Math.min(window.usedPercent, 100)}" aria-label="${label} percent used">${window.usedPercent}%</meter><p>Resets ${reset(window.resetsAt === null ? null : window.resetsAt * 1000, now)}</p></li>`;
+}
+function codex(value: CodexLimits, now: number): string {
+	return `<ul class="diagnostics-windows">${usage("Primary", value.primary, now)}${usage("Secondary", value.secondary, now)}</ul>`;
+}
+function github(value: GithubLimits, now: number): string {
+	return `<dl class="diagnostics-metrics">${(
+		[
+			["REST", value.core],
+			["GraphQL", value.graphql],
+		] as const
+	)
+		.map(
+			([name, window]) =>
+				`<div><dt>${name}</dt><dd><strong>${window.remaining} / ${window.limit}</strong> remaining</dd><dd>Resets ${reset(window.reset * 1000, now)}</dd></div>`,
+		)
+		.join("")}</dl><p class="diagnostics-freshness">Cached for one minute across all tabs.</p>`;
+}
+function fleet(value: FleetHealth, now: number): string {
+	let freshness = "Current snapshot";
+	if (now < value.observedAt) {
+		freshness = "Publisher clock is ahead";
+	} else if (now - value.observedAt > value.staleAfterMs) {
+		freshness = "Stale snapshot — Fleet has not refreshed its health";
+	}
+	return `<p class="diagnostics-freshness">${freshness}</p><dl class="diagnostics-metrics"><div><dt>Running / concurrency cap</dt><dd><strong>${value.running} / ${value.concurrency}</strong></dd></div><div><dt>Queued</dt><dd><strong>${value.queued}</strong></dd></div>${Object.entries(
+		value.waiting,
+	)
+		.map(([owner, count]) => `<div><dt>Waiting on ${owner}</dt><dd><strong>${count}</strong></dd></div>`)
+		.join(
+			"",
+		)}<div><dt>Last scheduler pass</dt><dd>${time(value.lastSchedulerPass)}</dd></div><div><dt>Last provider capacity rejection</dt><dd>${value.lastCapacityRejection === null ? "None observed" : `${escapeHtml(value.lastCapacityRejection.cause)}<br>${time(value.lastCapacityRejection.at)}`}</dd></div></dl>`;
+}
+
+export function diagnosticsHtml(
+	sources: { readonly codex: Observation<CodexLimits>; readonly github: Observation<GithubLimits>; readonly fleet: Observation<FleetHealth> },
+	now: number,
+): string {
+	const fleetSource = sources.fleet.state === "ready" ? { ...sources.fleet, observedAt: sources.fleet.value.observedAt } : sources.fleet;
+	return `<div class="diagnostics"><h1>Diagnostics</h1><p>Agent usage and Fleet health. Refreshes every 15 seconds while this view is visible; Pause updates holds the current view.</p><div class="diagnostics-grid">${card("Codex", sources.codex, (value) => codex(value, now), sources.codex.state === "ready" && [sources.codex.value.primary, sources.codex.value.secondary].some((window) => window !== null && window.usedPercent >= 90))}${card("GitHub", sources.github, (value) => github(value, now), sources.github.state === "ready" && [sources.github.value.core, sources.github.value.graphql].some((window) => window.remaining === 0))}${card("Fleet", fleetSource, (value) => fleet(value, now), fleetSource.state === "ready" && (fleetSource.value.running >= fleetSource.value.concurrency || Object.values(fleetSource.value.waiting).some((count) => count > 0) || now < fleetSource.value.observedAt), fleetSource.state === "ready" && now - fleetSource.value.observedAt > fleetSource.value.staleAfterMs)}</div></div>`;
+}

package/src/server/diagnostics/page.ts

@@ -0,0 +1,31 @@
+import { Clock, Effect } from "effect";
+import type { diagnostics } from "#diagnostics/source.ts";
+import type { Changes } from "#server/files/changes.ts";
+import { respond } from "#server/http/respond.ts";
+import { navHtml } from "#server/page/nav.ts";
+import { shell } from "#server/page/shell.ts";
+import type { searchSnapshot } from "#server/search/snapshot.ts";
+import { diagnosticsHtml } from "./html.ts";
+
+export const diagnosticsPage = Effect.fn("WorkBoard.diagnosticsPage")(function* (
+	read: Effect.Success<ReturnType<typeof diagnostics>>,
+	changes: Changes,
+	home: string | undefined,
+	index?: Effect.Success<ReturnType<typeof searchSnapshot>>,
+) {
+	const result = yield* read;
+	const snapshot = index ? yield* index : undefined;
+	return respond(
+		shell(
+			"Diagnostics",
+			navHtml(yield* changes.files, "", home, snapshot),
+			diagnosticsHtml(result, yield* Clock.currentTimeMillis),
+			changes.realRoot,
+			true,
+			undefined,
+			"diagnostics",
+			snapshot,
+		),
+		"text/html",
+	);
+});

package/src/server/diagnostics/readCommand.ts

@@ -0,0 +1,24 @@
+import { execFile } from "node:child_process";
+import { Effect } from "effect";
+import { SourceFailure } from "#diagnostics/source.ts";
+
+export function readCommand(command: string, args: readonly string[]) {
+	return Effect.callback<string, SourceFailure>((resume) => {
+		const child = execFile(command, args, { maxBuffer: 1024 * 1024, timeout: 30_000 }, (error, stdout, stderr) => {
+			if (error === null) {
+				resume(Effect.succeed(stdout));
+				return;
+			}
+			const missing = error.code === "ENOENT" || stderr.includes("gh auth login") || stderr.includes("GH_TOKEN environment variable");
+			resume(
+				Effect.fail(
+					new SourceFailure({
+						kind: missing ? "not-configured" : "error",
+						message: missing ? `${command} is not installed or authenticated` : (stderr.trim() || error.message).slice(0, 500),
+					}),
+				),
+			);
+		});
+		return Effect.sync(() => child.kill());
+	});
+}

package/src/server/diagnostics/style.ts

@@ -0,0 +1,19 @@
+export function diagnosticsStyle(): string {
+	return `
+.diagnostics { max-width: 1200px; margin: auto; padding: clamp(1rem, 3vw, 2rem); }
+.diagnostics-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 320px), 1fr)); gap: 1rem; align-items: start; }
+.diagnostics-card { min-width: 0; border: 1px solid var(--border); border-radius: 12px; padding: 1.25rem; background: var(--surface); overflow-wrap: anywhere; }
+.diagnostics-card header { display: flex; align-items: baseline; flex-wrap: wrap; gap: .5rem 1rem; justify-content: space-between; }
+.diagnostics-card h2 { margin: 0; }
+.diagnostics-status { font-size: .85rem; border: 1px solid var(--border); border-radius: 1rem; padding: .2rem .6rem; }
+.diagnostics-card[data-state=attention], .diagnostics-card[data-state=error] { border-color: var(--link); }
+.diagnostics-card[data-state=stale] .diagnostics-metrics strong { opacity: .55; }
+.diagnostics-freshness { font-size: .85rem; color: var(--muted); }
+.diagnostics-windows { list-style: none; padding: 0; }
+.diagnostics-windows li + li, .diagnostics-metrics > div + div { border-top: 1px solid var(--border); padding-top: .75rem; margin-top: .75rem; }
+.diagnostics-windows h3 { margin-bottom: .25rem; }
+.diagnostics-windows meter { width: 100%; height: .75rem; accent-color: var(--link); }
+.diagnostics-metrics dt { color: var(--muted); }
+.diagnostics-metrics dd { margin: .25rem 0 0; }
+`;
+}

package/src/server/document/body.ts

@@ -0,0 +1,8 @@
+import type { MetadataDocument } from "#server/metadata/model.ts";
+import { metadataParse } from "#server/metadata/parse.ts";
+import { questionFrom } from "#server/responses/records.ts";
+
+export function documentBody(document: MetadataDocument): string {
+	const question = questionFrom(document);
+	return question ? metadataParse(question.context).body : document.parsed.body;
+}