clinkx 0.2.3 → 1.0.0

package/clinkx-workflows/dist/dashboard/api-routes.js

@@ -0,0 +1,1047 @@
+import { randomBytes } from "node:crypto";
+import { dirname, join } from "node:path";
+import { listWorkflows } from "../loader.js";
+import { logger } from "../logger.js";
+import { CONTEXT_BUILDER_LIFECYCLE_DIRECTORY } from "../context-builder-lifecycle-contract.js";
+import { AdaptersResponseSchema, ActivityDetailSchema, ActivityListResponseSchema, ActivityRouteParamsSchema, CallRouteParamsSchema, ContextRunArtifactRouteParamsSchema, ContextRunListQuerySchema, ContextRunListResponseSchema, ContextRunRouteParamsSchema, ContextRunRowSchema, DashboardAgentInstanceIdSchema, DashboardConnectionResponseSchema, EnvironmentResponseSchema, EmptyQuerySchema, GenerationQuerySchema, PaginationQuerySchema, ProgressReportDetailResponseSchema, ProgressReportListResponseSchema, RunRouteParamsSchema, SessionLogLaneIndexQuerySchema, SessionLogLaneIndexResponseSchema, SessionLogLaneRouteParamsSchema, SessionLogPageQuerySchema, SessionLogWorkflowRouteParamsSchema, StructuredDetailQuerySchema, WorkflowDescriptorSchema, WorkflowsResponseSchema, MAX_DASHBOARD_ADAPTERS, SafeAdapterDescriptorSchema, } from "./contracts.js";
+import { DashboardInvalidCursorError } from "./artifact-index.js";
+import { createDashboardRunScanner, DashboardReadModelError, } from "./scanner.js";
+import { createDashboardActivityReader, } from "./activity-reader.js";
+import { ContextRunSourceUnavailableError, createContextRunReader, } from "./context-run-reader.js";
+import { createSessionLogReader, } from "./session-log-reader.js";
+import { readSessionLogGeneration } from "./session-log-identity.js";
+import { ProgressReportSessionIdSchema } from "./progress-report-contract.js";
+import { createDashboardProgressReportReader, } from "./progress-report-reader.js";
+import { isProgressReportStatusOverrideSegments, ProgressReportStatusOverrideRequestSchema, } from "./progress-report-status-overlay.js";
+import { createProgressReportStatusOverrideStore, } from "./progress-report-status-store.js";
+function queryMultimap(query) {
+    const values = Object.create(null);
+    for (const [key, value] of query) {
+        (values[key] ??= []).push(value);
+    }
+    return values;
+}
+function parseSessionLogRouteQuery(query, page) {
+    if (page) {
+        const parsed = SessionLogPageQuerySchema.safeParse(query);
+        return parsed.success
+            ? {
+                generation: parsed.data.generation,
+                pageQuery: {
+                    sequence: parsed.data.sequence,
+                    limit: parsed.data.limit,
+                },
+            }
+            : undefined;
+    }
+    const parsed = SessionLogLaneIndexQuerySchema.safeParse(query);
+    return parsed.success ? { generation: parsed.data.generation } : undefined;
+}
+/**
+ * Content-Type for a served context-run artifact body. JSON variants are served
+ * as `application/json`; newline-delimited JSONL as `application/x-ndjson`;
+ * the bundle as `text/markdown`. All include an explicit charset.
+ */
+function artifactContentType(artifactKey) {
+    switch (artifactKey) {
+        case "manifest_json":
+        case "summary_json":
+        case "tree_json":
+            return "application/json; charset=utf-8";
+        case "selected_context_jsonl":
+        case "search_jsonl":
+        case "slices_jsonl":
+        case "codemap_jsonl":
+            return "application/x-ndjson; charset=utf-8";
+        case "bundle_md":
+            return "text/markdown; charset=utf-8";
+    }
+}
+function sendBytes(request, response, status, contentType, bytes, headers = {}) {
+    response.writeHead(status, {
+        "Cache-Control": "no-store",
+        "Content-Length": bytes.byteLength,
+        "Content-Type": contentType,
+        ...headers,
+    });
+    response.end(request.method === "HEAD" ? undefined : bytes);
+}
+function sendJson(request, response, status, value, headers = {}) {
+    sendBytes(request, response, status, "application/json; charset=utf-8", Buffer.from(`${JSON.stringify(value)}\n`, "utf8"), headers);
+}
+function sendError(request, response, status, code, headers = {}) {
+    sendJson(request, response, status, { error: { code } }, headers);
+}
+const PROGRESS_REPORT_STATUS_OVERRIDE_BODY_MAX_BYTES = 4 * 1024;
+class ProgressReportStatusOverrideBodyError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(code);
+        this.name = "ProgressReportStatusOverrideBodyError";
+        this.status = status;
+        this.code = code;
+    }
+}
+function singleDistinctHeader(request, name) {
+    const values = request.headersDistinct[name];
+    return values?.length === 1 ? values[0] : undefined;
+}
+function parseProgressReportStatusOverrideContentLength(request) {
+    const values = request.headersDistinct["content-length"];
+    if (values != null && values.length !== 1) {
+        throw new ProgressReportStatusOverrideBodyError(400, "invalid_request");
+    }
+    const raw = values?.[0];
+    if (raw == null)
+        return;
+    if (!/^(0|[1-9]\d*)$/.test(raw)) {
+        throw new ProgressReportStatusOverrideBodyError(400, "invalid_request");
+    }
+    const length = Number(raw);
+    if (!Number.isSafeInteger(length)) {
+        throw new ProgressReportStatusOverrideBodyError(400, "invalid_request");
+    }
+    if (length > PROGRESS_REPORT_STATUS_OVERRIDE_BODY_MAX_BYTES) {
+        throw new ProgressReportStatusOverrideBodyError(413, "content_too_large_for_dashboard");
+    }
+}
+async function readProgressReportStatusOverrideJsonBody(request) {
+    const contentType = singleDistinctHeader(request, "content-type");
+    if (contentType == null || contentType.toLowerCase() !== "application/json") {
+        throw new ProgressReportStatusOverrideBodyError(400, "invalid_request");
+    }
+    parseProgressReportStatusOverrideContentLength(request);
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of request) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += bytes.byteLength;
+        if (total > PROGRESS_REPORT_STATUS_OVERRIDE_BODY_MAX_BYTES) {
+            request.resume();
+            throw new ProgressReportStatusOverrideBodyError(413, "content_too_large_for_dashboard");
+        }
+        chunks.push(bytes);
+    }
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+    }
+    catch {
+        throw new ProgressReportStatusOverrideBodyError(400, "invalid_request");
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new ProgressReportStatusOverrideBodyError(400, "invalid_request");
+    }
+    const parsed = ProgressReportStatusOverrideRequestSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new ProgressReportStatusOverrideBodyError(400, "invalid_request");
+    }
+    return parsed.data;
+}
+function serializeContextRunList(rows, truncated) {
+    const serverNow = new Date().toISOString();
+    const parsed = ContextRunListResponseSchema.safeParse({
+        contextRuns: rows,
+        serverNow,
+        truncated,
+    });
+    if (parsed.success)
+        return parsed.data;
+    logger.error({ issues: parsed.error.issues.slice(0, 8) }, "context run list schema rejected; dropping invalid rows");
+    const kept = [];
+    for (const row of rows) {
+        const one = ContextRunRowSchema.safeParse(row);
+        if (one.success) {
+            kept.push(one.data);
+            continue;
+        }
+        logger.warn({
+            id: typeof row === "object" && row !== null && "id" in row
+                ? row.id
+                : undefined,
+            issues: one.error.issues.slice(0, 4),
+        }, "dropped invalid context run row");
+    }
+    return ContextRunListResponseSchema.parse({
+        contextRuns: kept,
+        serverNow,
+        truncated: true,
+    });
+}
+function projectWorkflow(definition) {
+    const descriptor = {
+        name: definition.name,
+        version: definition.version,
+        description: definition.description.slice(0, 4_096),
+        stageCount: definition.stages.length,
+        callCount: definition.stages.reduce((count, stage) => count + stage.calls.length, 0),
+        variables: Object.entries(definition.variables)
+            .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+            .map(([name, variable]) => ({
+            name,
+            type: variable.type,
+            required: variable.required,
+        })),
+    };
+    return WorkflowDescriptorSchema.parse(descriptor);
+}
+function createWorkflowResponse(workflowsPath, loader) {
+    const workflows = [...loader(workflowsPath).values()]
+        .map(projectWorkflow)
+        .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)
+        .map((workflow) => Object.freeze(workflow));
+    WorkflowsResponseSchema.parse({ workflows });
+    return Object.freeze({
+        workflows: Object.freeze(workflows),
+    });
+}
+function quoteEtag(stateRevision) {
+    return `"${stateRevision}"`;
+}
+function handleLazyResult(request, response, result) {
+    if (result.kind === "run_generation_changed") {
+        sendError(request, response, 409, "run_generation_changed");
+        return;
+    }
+    if (result.kind === "run_state_changed") {
+        sendError(request, response, 409, "run_state_changed");
+        return;
+    }
+    if (result.kind === "unavailable") {
+        if (result.reason === "content_too_large_for_dashboard") {
+            sendError(request, response, 413, "content_too_large_for_dashboard");
+        }
+        else {
+            sendError(request, response, 404, "not_found");
+        }
+        return;
+    }
+    sendBytes(request, response, 200, result.mediaType, Buffer.from(result.content, "utf8"), {
+        ETag: quoteEtag(result.stateRevision),
+        ...(result.validatorSchemaId === undefined
+            ? {}
+            : { "X-ClinkX-Validator-Schema-Id": result.validatorSchemaId }),
+    });
+}
+function handleActivityResult(request, response, result) {
+    if (result.kind === "activity_generation_changed") {
+        sendError(request, response, 409, "activity_generation_changed");
+        return;
+    }
+    if (result.kind === "activity_state_changed") {
+        sendError(request, response, 409, "activity_state_changed");
+        return;
+    }
+    if (result.kind === "unavailable") {
+        sendError(request, response, result.reason === "too_large" ? 413 : 404, result.reason === "too_large"
+            ? "content_too_large_for_dashboard"
+            : "not_found");
+        return;
+    }
+    sendBytes(request, response, 200, result.mediaType, Buffer.from(result.content, "utf8"), { ETag: quoteEtag(result.stateRevision) });
+}
+/**
+ * Build the authenticated dashboard route module from immutable launch-time
+ * configuration and one long-lived Phase 1 scanner/generation authority.
+ */
+export function createDashboardApiHandler(adapterCatalog, options) {
+    const agentInstanceId = DashboardAgentInstanceIdSchema.parse(options.agentInstanceId ?? randomBytes(16).toString("base64url"));
+    const scanner = options.scanner ?? createDashboardRunScanner({
+        maxStateBytes: options.maxStateBytes,
+    });
+    const activityReader = options.activityReader ?? createDashboardActivityReader();
+    const activitiesRoot = options.activitiesRoot ?? join(dirname(options.runsRoot), "activities");
+    const contextRunsRoot = options.contextRunsRoot;
+    const contextRunReader = options.contextRunReader ?? createContextRunReader();
+    const sessionLogsRoot = options.sessionLogsRoot ?? join(dirname(options.runsRoot), "session-logs");
+    const sessionLogReader = options.sessionLogReader ?? createSessionLogReader({
+        rootDir: sessionLogsRoot,
+    });
+    const progressReportsRoot = options.progressReportsRoot ?? join(dirname(options.runsRoot), "progress-reports");
+    const progressReportOverrideStore = options.progressReportOverrideStore ?? createProgressReportStatusOverrideStore();
+    const progressReportReader = options.progressReportReader ??
+        createDashboardProgressReportReader({
+            overrideStore: progressReportOverrideStore,
+        });
+    const safeAdapters = [];
+    for (const adapter of adapterCatalog) {
+        const result = SafeAdapterDescriptorSchema.safeParse(adapter);
+        if (!result.success)
+            continue;
+        Object.freeze(result.data.roleNames);
+        Object.freeze(result.data.environmentKeys);
+        Object.freeze(result.data.resultContract);
+        if (result.data.usableVia !== undefined)
+            Object.freeze(result.data.usableVia);
+        safeAdapters.push(Object.freeze(result.data));
+        if (safeAdapters.length === MAX_DASHBOARD_ADAPTERS)
+            break;
+    }
+    const boundedAdapters = Object.freeze(safeAdapters);
+    AdaptersResponseSchema.parse({ adapters: boundedAdapters });
+    const adaptersResponse = Object.freeze({ adapters: boundedAdapters });
+    const environmentResponse = Object.freeze(EnvironmentResponseSchema.parse(options.environment));
+    const workflowsResponse = createWorkflowResponse(options.workflowsPath, options.loadWorkflows ??
+        ((workflowsPath) => listWorkflows(workflowsPath, {
+            failOnInvalidExternal: true,
+            templatesRoot: options.environment.templatesPath,
+        })));
+    async function handleSessionLogRead(request, response, scope, laneId, pageQuery) {
+        if (laneId === undefined) {
+            const result = await sessionLogReader.listLanes(scope);
+            if (result.kind === "unavailable") {
+                sendError(request, response, 503, "session_logs_unavailable");
+                return;
+            }
+            sendJson(request, response, 200, SessionLogLaneIndexResponseSchema.parse({
+                schemaVersion: "session-log-index-v1",
+                availability: result.kind === "not_retained"
+                    ? {
+                        availability: "not_retained",
+                        reason: "producer_did_not_retain",
+                    }
+                    : { availability: "available" },
+                lanes: result.kind === "available" ? result.lanes : [],
+            }));
+            return;
+        }
+        const result = await sessionLogReader.readPage(scope, laneId, pageQuery);
+        if (result.kind === "unavailable") {
+            sendError(request, response, 503, "session_logs_unavailable");
+            return;
+        }
+        if (result.kind === "missing") {
+            sendError(request, response, 404, "not_found");
+            return;
+        }
+        sendJson(request, response, 200, result.page);
+    }
+    async function dispatch(request, response, target) {
+        const segments = target.segments;
+        const query = queryMultimap(target.query);
+        if (segments.length === 2 && segments[1] === "connection") {
+            if (!EmptyQuerySchema.safeParse(query).success) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            sendJson(request, response, 200, DashboardConnectionResponseSchema.parse({
+                schemaVersion: "dashboard-connection-v1",
+                agentInstanceId,
+            }));
+            return;
+        }
+        if (segments.length === 2 && segments[1] === "context-runs") {
+            const parsed = ContextRunListQuerySchema.safeParse(query);
+            if (!parsed.success) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            const result = contextRunsRoot === undefined
+                ? { rows: [], truncated: false }
+                : await contextRunReader.list({
+                    runsDir: contextRunsRoot,
+                    maxRows: parsed.data.limit,
+                });
+            sendJson(request, response, 200, serializeContextRunList(result.rows, result.truncated));
+            return;
+        }
+        if (segments[1] === "context-runs" &&
+            (segments.length === 4 || segments.length === 5) &&
+            segments[3] === "session-logs") {
+            const route = ContextRunRouteParamsSchema.safeParse({ id: segments[2] });
+            const lane = segments.length === 5
+                ? SessionLogLaneRouteParamsSchema.safeParse({ laneId: segments[4] })
+                : undefined;
+            const parsedQuery = parseSessionLogRouteQuery(query, segments.length === 5);
+            if (!route.success) {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (parsedQuery === undefined || (lane !== undefined && !lane.success)) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            if (contextRunsRoot === undefined) {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            const authority = await contextRunReader.readDetail({ runsDir: contextRunsRoot }, route.data.id, parsedQuery.generation);
+            if (authority.kind === "context_generation_changed") {
+                sendError(request, response, 409, "context_generation_changed");
+                return;
+            }
+            if (authority.kind === "missing") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (authority.kind === "unavailable") {
+                sendError(request, response, 503, "context_runs_unavailable");
+                return;
+            }
+            const contextRunDir = authority.row.source === "journal"
+                ? join(contextRunsRoot, CONTEXT_BUILDER_LIFECYCLE_DIRECTORY, route.data.id)
+                : join(contextRunsRoot, route.data.id);
+            const identity = await readSessionLogGeneration(contextRunDir);
+            if (identity.kind === "unavailable") {
+                sendError(request, response, 503, "session_logs_unavailable");
+                return;
+            }
+            const confirmedAuthority = await contextRunReader.readDetail({ runsDir: contextRunsRoot }, route.data.id, parsedQuery.generation);
+            if (confirmedAuthority.kind === "context_generation_changed") {
+                sendError(request, response, 409, "context_generation_changed");
+                return;
+            }
+            if (confirmedAuthority.kind === "missing") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (confirmedAuthority.kind === "unavailable") {
+                sendError(request, response, 503, "context_runs_unavailable");
+                return;
+            }
+            await handleSessionLogRead(request, response, {
+                family: "context",
+                contextRunId: route.data.id,
+                contextGeneration: identity.kind === "available"
+                    ? identity.sessionLogGeneration
+                    : parsedQuery.generation,
+            }, lane?.success === true ? lane.data.laneId : undefined, parsedQuery.pageQuery);
+            return;
+        }
+        if (segments[1] === "context-runs" &&
+            segments.length === 5 &&
+            segments[3] === "artifacts") {
+            // Bounded single-artifact body endpoint. Mirrors the session-logs
+            // authority pattern: readDetail resolves the run, readArtifact serves the
+            // body from the resolved artifact directory (the journal row's linked
+            // artifactRunId, NOT the operation id), then readDetail re-confirms to
+            // close a journal-state-swap TOCTOU. Param-parse failure → 404 (matches
+            // the established "reject malformed route IDs" convention).
+            const detailQuery = StructuredDetailQuerySchema.safeParse(query);
+            if (!detailQuery.success) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            const route = ContextRunArtifactRouteParamsSchema.safeParse({
+                id: segments[2],
+                artifactKey: segments[4],
+            });
+            if (!route.success) {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (contextRunsRoot === undefined) {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            const firstRead = await contextRunReader.readDetail({ runsDir: contextRunsRoot }, route.data.id, detailQuery.data.generation);
+            if (firstRead.kind === "context_generation_changed") {
+                sendError(request, response, 409, "context_generation_changed");
+                return;
+            }
+            if (firstRead.kind === "missing") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (firstRead.kind === "unavailable") {
+                sendError(request, response, 503, "context_runs_unavailable");
+                return;
+            }
+            const result = await contextRunReader.readArtifact({ runsDir: contextRunsRoot }, route.data.id, route.data.artifactKey, detailQuery.data.generation);
+            if (result.kind === "content_too_large") {
+                sendError(request, response, 413, "content_too_large_for_dashboard");
+                return;
+            }
+            if (result.kind === "context_generation_changed") {
+                sendError(request, response, 409, "context_generation_changed");
+                return;
+            }
+            if (result.kind === "missing") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (result.kind === "unavailable") {
+                sendError(request, response, 503, "context_runs_unavailable");
+                return;
+            }
+            // Re-confirm authority: for a journal row, artifactRunId is sourced from
+            // .context-runs/<id>/state.json, and readArtifact's generation check pins
+            // the artifact dir, not the journal dir. A state swap mid-request could
+            // otherwise serve an artifact for an artifactRunId the current state no
+            // longer points to. Every non-available outcome — including the run
+            // disappearing entirely (missing) or being recycled to a shape with no
+            // resolvable artifactRunId (lifecycle null) — must bail rather than fall
+            // through to a stale 200.
+            const confirmedRead = await contextRunReader.readDetail({ runsDir: contextRunsRoot }, route.data.id, detailQuery.data.generation);
+            if (confirmedRead.kind === "missing") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (confirmedRead.kind === "context_generation_changed") {
+                sendError(request, response, 409, "context_generation_changed");
+                return;
+            }
+            if (confirmedRead.kind === "unavailable") {
+                sendError(request, response, 503, "context_runs_unavailable");
+                return;
+            }
+            if (confirmedRead.row.lifecycle === null) {
+                sendError(request, response, 409, "context_generation_changed");
+                return;
+            }
+            const currentArtifactRunId = confirmedRead.row.source === "journal"
+                ? confirmedRead.row.lifecycle.artifactRunId
+                : confirmedRead.row.id;
+            if (currentArtifactRunId !== result.artifactRunId) {
+                sendError(request, response, 409, "context_generation_changed");
+                return;
+            }
+            const contentType = artifactContentType(route.data.artifactKey);
+            sendBytes(request, response, 200, contentType, Buffer.from(result.content, "utf8"));
+            return;
+        }
+        if (segments[1] === "context-runs" && segments.length === 3) {
+            const detailQuery = StructuredDetailQuerySchema.safeParse(query);
+            if (!detailQuery.success) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            const route = ContextRunRouteParamsSchema.safeParse({ id: segments[2] });
+            if (!route.success) {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (contextRunsRoot === undefined) {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            const result = await contextRunReader.readDetail({ runsDir: contextRunsRoot }, route.data.id, detailQuery.data.generation);
+            if (result.kind === "missing") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (result.kind === "context_generation_changed") {
+                sendError(request, response, 409, "context_generation_changed");
+                return;
+            }
+            if (result.kind === "unavailable") {
+                sendError(request, response, 503, "context_runs_unavailable");
+                return;
+            }
+            const detail = ContextRunRowSchema.safeParse(result.row);
+            if (!detail.success) {
+                logger.error({ issues: detail.error.issues.slice(0, 8), id: result.row.id }, "context run detail schema rejected");
+                sendError(request, response, 500, "internal_error");
+                return;
+            }
+            sendJson(request, response, 200, detail.data);
+            return;
+        }
+        if (segments.length === 2 && segments[1] === "activities") {
+            const parsed = PaginationQuerySchema.safeParse(query);
+            if (!parsed.success) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            const result = await activityReader.list(activitiesRoot, parsed.data);
+            sendJson(request, response, 200, ActivityListResponseSchema.parse(result));
+            return;
+        }
+        if (segments.length === 2 && segments[1] === "progress-reports") {
+            if (!EmptyQuerySchema.safeParse(query).success) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            // Absent root → 200 with empty list (reader maps ENOENT to empty).
+            const result = await progressReportReader.list(progressReportsRoot);
+            sendJson(request, response, 200, ProgressReportListResponseSchema.parse({
+                progressReports: result.rows,
+                serverNow: new Date().toISOString(),
+                truncated: result.truncated,
+            }));
+            return;
+        }
+        if (segments[1] === "progress-reports" &&
+            segments.length === 4 &&
+            segments[3] === "data") {
+            if (!EmptyQuerySchema.safeParse(query).success) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            const sessionId = segments[2];
+            if (sessionId === undefined || !ProgressReportSessionIdSchema.safeParse(sessionId).success) {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            const result = await progressReportReader.readDetail(progressReportsRoot, sessionId);
+            if (result.kind === "absent") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (result.kind === "malformed") {
+                sendError(request, response, 404, "progress_report_malformed");
+                return;
+            }
+            if (result.kind === "oversized") {
+                sendError(request, response, 413, "content_too_large_for_dashboard");
+                return;
+            }
+            sendJson(request, response, 200, ProgressReportDetailResponseSchema.parse({
+                progressReport: result.document,
+                serverNow: new Date().toISOString(),
+                omittedSections: result.omittedSections,
+                ...(result.publishedSessionStatus === undefined
+                    ? {}
+                    : { publishedSessionStatus: result.publishedSessionStatus }),
+            }));
+            return;
+        }
+        if (isProgressReportStatusOverrideSegments(segments)) {
+            if (request.method !== "POST") {
+                sendError(request, response, 405, "method_not_allowed", { Allow: "POST" });
+                return;
+            }
+            if (!EmptyQuerySchema.safeParse(query).success) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            const sessionId = segments[2];
+            if (sessionId === undefined) {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            let overrideRequest;
+            try {
+                overrideRequest = await readProgressReportStatusOverrideJsonBody(request);
+            }
+            catch (error) {
+                if (error instanceof ProgressReportStatusOverrideBodyError) {
+                    sendError(request, response, error.status, error.code);
+                    return;
+                }
+                throw error;
+            }
+            const detail = await progressReportReader.readDetail(progressReportsRoot, sessionId);
+            if (detail.kind === "absent") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (detail.kind === "malformed") {
+                sendError(request, response, 404, "progress_report_malformed");
+                return;
+            }
+            if (detail.kind === "oversized") {
+                sendError(request, response, 413, "content_too_large_for_dashboard");
+                return;
+            }
+            const session = detail.document.session;
+            const outcome = await progressReportOverrideStore.write(progressReportsRoot, sessionId, overrideRequest, {
+                status: detail.publishedSessionStatus ?? session.status,
+                startedAt: session.startedAt,
+                updatedAt: session.updatedAt,
+            });
+            if (outcome.kind === "unwritable") {
+                sendError(request, response, 503, "progress_report_overrides_unavailable");
+                return;
+            }
+            if (outcome.kind === "too_large") {
+                sendError(request, response, 413, "content_too_large_for_dashboard");
+                return;
+            }
+            response.writeHead(204, { "Cache-Control": "no-store" });
+            response.end();
+            return;
+        }
+        if (segments.length === 2 && segments[1] === "runs") {
+            const parsed = PaginationQuerySchema.safeParse(query);
+            if (!parsed.success) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            sendJson(request, response, 200, await scanner.scan(options.runsRoot, parsed.data));
+            return;
+        }
+        if (segments.length === 2 && segments[1] === "artifacts") {
+            const parsed = PaginationQuerySchema.safeParse(query);
+            if (!parsed.success) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            sendJson(request, response, 200, await scanner.listArtifacts(options.runsRoot, parsed.data));
+            return;
+        }
+        if (segments.length === 2 && ["adapters", "env", "workflows"].includes(segments[1] ?? "")) {
+            if (Object.keys(query).length !== 0) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            if (segments[1] === "adapters")
+                sendJson(request, response, 200, adaptersResponse);
+            if (segments[1] === "env")
+                sendJson(request, response, 200, environmentResponse);
+            if (segments[1] === "workflows")
+                sendJson(request, response, 200, workflowsResponse);
+            return;
+        }
+        if (segments[1] === "activities") {
+            const activity = ActivityRouteParamsSchema.safeParse({
+                activityId: segments[2],
+            });
+            if (!activity.success) {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if ((segments.length === 4 || segments.length === 5) &&
+                segments[3] === "session-logs") {
+                const lane = segments.length === 5
+                    ? SessionLogLaneRouteParamsSchema.safeParse({ laneId: segments[4] })
+                    : undefined;
+                const parsedQuery = parseSessionLogRouteQuery(query, segments.length === 5);
+                if (parsedQuery === undefined || (lane !== undefined && !lane.success)) {
+                    sendError(request, response, 400, "invalid_request");
+                    return;
+                }
+                const authority = await activityReader.readDetail(activitiesRoot, activity.data.activityId, parsedQuery.generation);
+                if (authority.kind === "activity_generation_changed") {
+                    sendError(request, response, 409, "activity_generation_changed");
+                    return;
+                }
+                if (authority.kind === "activity_state_changed") {
+                    sendError(request, response, 409, "activity_state_changed");
+                    return;
+                }
+                if (authority.kind === "unavailable") {
+                    sendError(request, response, 404, "not_found");
+                    return;
+                }
+                const identity = await readSessionLogGeneration(join(activitiesRoot, activity.data.activityId));
+                if (identity.kind === "unavailable") {
+                    sendError(request, response, 503, "session_logs_unavailable");
+                    return;
+                }
+                const confirmedAuthority = await activityReader.readDetail(activitiesRoot, activity.data.activityId, parsedQuery.generation);
+                if (confirmedAuthority.kind === "activity_generation_changed") {
+                    sendError(request, response, 409, "activity_generation_changed");
+                    return;
+                }
+                if (confirmedAuthority.kind === "activity_state_changed") {
+                    sendError(request, response, 409, "activity_state_changed");
+                    return;
+                }
+                if (confirmedAuthority.kind === "unavailable") {
+                    sendError(request, response, 404, "not_found");
+                    return;
+                }
+                await handleSessionLogRead(request, response, {
+                    family: "activity",
+                    activityId: activity.data.activityId,
+                    activityGeneration: identity.kind === "available"
+                        ? identity.sessionLogGeneration
+                        : parsedQuery.generation,
+                }, lane?.success === true ? lane.data.laneId : undefined, parsedQuery.pageQuery);
+                return;
+            }
+            if (segments.length === 3) {
+                const detailQuery = StructuredDetailQuerySchema.safeParse(query);
+                if (!detailQuery.success) {
+                    sendError(request, response, 400, "invalid_request");
+                    return;
+                }
+                let activityGeneration = detailQuery.data.generation;
+                if (activityGeneration === undefined) {
+                    const current = await activityReader.resolveCurrent(activitiesRoot, activity.data.activityId);
+                    if (current.kind === "missing") {
+                        sendError(request, response, 404, "not_found");
+                        return;
+                    }
+                    activityGeneration = current.activityGeneration;
+                }
+                const result = await activityReader.readDetail(activitiesRoot, activity.data.activityId, activityGeneration);
+                if (result.kind === "unavailable") {
+                    sendError(request, response, 404, "not_found");
+                }
+                if (result.kind === "activity_generation_changed") {
+                    sendError(request, response, 409, "activity_generation_changed");
+                }
+                if (result.kind === "activity_state_changed") {
+                    sendError(request, response, 409, "activity_state_changed");
+                }
+                if (result.kind === "available") {
+                    sendJson(request, response, 200, ActivityDetailSchema.parse(result.detail));
+                }
+                return;
+            }
+            if (segments.length === 4 && segments[3] === "result") {
+                const generation = GenerationQuerySchema.safeParse(query);
+                if (!generation.success) {
+                    sendError(request, response, 400, "invalid_request");
+                    return;
+                }
+                handleActivityResult(request, response, await activityReader.readResult({
+                    activitiesRoot,
+                    activityId: activity.data.activityId,
+                    activityGeneration: generation.data.generation,
+                }));
+                return;
+            }
+            sendError(request, response, 404, "not_found");
+            return;
+        }
+        const run = RunRouteParamsSchema.safeParse({ runId: segments[2] });
+        if (!run.success) {
+            sendError(request, response, 404, "not_found");
+            return;
+        }
+        if (segments.length === 3) {
+            const detailQuery = StructuredDetailQuerySchema.safeParse(query);
+            if (!detailQuery.success) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            let runGeneration = detailQuery.data.generation;
+            if (runGeneration === undefined) {
+                const current = await scanner.resolveCurrent(options.runsRoot, run.data.runId);
+                if (current.kind === "missing" || current.kind === "unavailable") {
+                    sendError(request, response, 404, "not_found");
+                    return;
+                }
+                runGeneration = current.runGeneration;
+            }
+            const result = await scanner.readDetail(options.runsRoot, run.data.runId, runGeneration);
+            if (result.kind === "missing")
+                sendError(request, response, 404, "not_found");
+            if (result.kind === "run_generation_changed") {
+                sendError(request, response, 409, "run_generation_changed");
+            }
+            if (result.kind === "run_state_changed") {
+                sendError(request, response, 409, "run_state_changed");
+            }
+            if (result.kind === "available")
+                sendJson(request, response, 200, result.detail);
+            return;
+        }
+        if (segments.length === 4 && segments[3] === "result") {
+            const generation = GenerationQuerySchema.safeParse(query);
+            if (!generation.success) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            handleLazyResult(request, response, await scanner.readResult({
+                runsRoot: options.runsRoot,
+                runId: run.data.runId,
+                runGeneration: generation.data.generation,
+            }));
+            return;
+        }
+        if ((segments.length === 8 || segments.length === 9) &&
+            segments[3] === "stages" &&
+            segments[5] === "calls" &&
+            segments[7] === "session-logs") {
+            const route = SessionLogWorkflowRouteParamsSchema.safeParse({
+                runId: segments[2],
+                stageId: segments[4],
+                callId: segments[6],
+            });
+            const lane = segments.length === 9
+                ? SessionLogLaneRouteParamsSchema.safeParse({ laneId: segments[8] })
+                : undefined;
+            const parsedQuery = parseSessionLogRouteQuery(query, segments.length === 9);
+            if (!route.success) {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (parsedQuery === undefined || (lane !== undefined && !lane.success)) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            const authority = await scanner.readDetail(options.runsRoot, route.data.runId, parsedQuery.generation);
+            if (authority.kind === "run_generation_changed") {
+                sendError(request, response, 409, "run_generation_changed");
+                return;
+            }
+            if (authority.kind === "run_state_changed") {
+                sendError(request, response, 409, "run_state_changed");
+                return;
+            }
+            if (authority.kind === "missing") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (authority.kind !== "available") {
+                sendError(request, response, 503, "session_logs_unavailable");
+                return;
+            }
+            const identity = await readSessionLogGeneration(join(options.runsRoot, route.data.runId));
+            if (identity.kind === "unavailable") {
+                sendError(request, response, 503, "session_logs_unavailable");
+                return;
+            }
+            // Close the sidecar-read race against same-ID parent replacement. The
+            // URL generation remains the sole parent authority; the portable token
+            // is used only after that authority is re-confirmed.
+            const confirmedAuthority = await scanner.readDetail(options.runsRoot, route.data.runId, parsedQuery.generation);
+            if (confirmedAuthority.kind === "run_generation_changed") {
+                sendError(request, response, 409, "run_generation_changed");
+                return;
+            }
+            if (confirmedAuthority.kind === "run_state_changed") {
+                sendError(request, response, 409, "run_state_changed");
+                return;
+            }
+            if (confirmedAuthority.kind === "missing") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (confirmedAuthority.kind !== "available") {
+                sendError(request, response, 503, "session_logs_unavailable");
+                return;
+            }
+            await handleSessionLogRead(request, response, {
+                family: "workflow",
+                runId: route.data.runId,
+                runGeneration: identity.kind === "available"
+                    ? identity.sessionLogGeneration
+                    : parsedQuery.generation,
+                stageId: route.data.stageId,
+                callId: route.data.callId,
+            }, lane?.success === true ? lane.data.laneId : undefined, parsedQuery.pageQuery);
+            return;
+        }
+        // Preflight (curator/finalizer) session logs: the workflow-embedded context
+        // preflight's delegate calls emit context-family session logs. Authority is
+        // the run generation (workflow scanner), and the context-generation sidecar
+        // lives under <runDir>/.context-preflight (resolved here, not on the client).
+        if ((segments.length === 5 || segments.length === 6) &&
+            segments[3] === "context-preflight" &&
+            segments[4] === "session-logs") {
+            const route = RunRouteParamsSchema.safeParse({ runId: segments[2] });
+            const lane = segments.length === 6
+                ? SessionLogLaneRouteParamsSchema.safeParse({ laneId: segments[5] })
+                : undefined;
+            const parsedQuery = parseSessionLogRouteQuery(query, segments.length === 6);
+            if (!route.success) {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (parsedQuery === undefined || (lane !== undefined && !lane.success)) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            const authority = await scanner.readDetail(options.runsRoot, route.data.runId, parsedQuery.generation);
+            if (authority.kind === "run_generation_changed") {
+                sendError(request, response, 409, "run_generation_changed");
+                return;
+            }
+            if (authority.kind === "run_state_changed") {
+                sendError(request, response, 409, "run_state_changed");
+                return;
+            }
+            if (authority.kind === "missing") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (authority.kind !== "available") {
+                sendError(request, response, 503, "session_logs_unavailable");
+                return;
+            }
+            if (authority.detail.availability !== "available") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            const preflight = authority.detail.contextPreflight;
+            if (preflight === undefined || preflight.availability !== "current") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            const contextRunId = preflight.contextRunId;
+            if (contextRunId === undefined) {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            const identity = await readSessionLogGeneration(join(options.runsRoot, route.data.runId, ".context-preflight"));
+            if (identity.kind === "unavailable" || identity.kind === "legacy") {
+                sendError(request, response, 503, "session_logs_unavailable");
+                return;
+            }
+            // Re-confirm run authority after the sidecar read (TOCTOU guard).
+            const confirmedAuthority = await scanner.readDetail(options.runsRoot, route.data.runId, parsedQuery.generation);
+            if (confirmedAuthority.kind === "run_generation_changed") {
+                sendError(request, response, 409, "run_generation_changed");
+                return;
+            }
+            if (confirmedAuthority.kind === "run_state_changed") {
+                sendError(request, response, 409, "run_state_changed");
+                return;
+            }
+            if (confirmedAuthority.kind === "missing") {
+                sendError(request, response, 404, "not_found");
+                return;
+            }
+            if (confirmedAuthority.kind !== "available") {
+                sendError(request, response, 503, "session_logs_unavailable");
+                return;
+            }
+            await handleSessionLogRead(request, response, {
+                family: "context",
+                contextRunId,
+                contextGeneration: identity.sessionLogGeneration,
+            }, lane?.success === true ? lane.data.laneId : undefined, parsedQuery.pageQuery);
+            return;
+        }
+        const call = CallRouteParamsSchema.safeParse({
+            runId: segments[2],
+            stageId: segments[4],
+            callId: segments[6],
+            contentKind: segments[7],
+        });
+        if (!call.success) {
+            sendError(request, response, 404, "not_found");
+            return;
+        }
+        const generation = GenerationQuerySchema.safeParse(query);
+        if (!generation.success) {
+            sendError(request, response, 400, "invalid_request");
+            return;
+        }
+        handleLazyResult(request, response, await scanner.readCallContent({
+            runsRoot: options.runsRoot,
+            runId: call.data.runId,
+            runGeneration: generation.data.generation,
+            stageId: call.data.stageId,
+            callId: call.data.callId,
+            kind: call.data.contentKind,
+        }));
+    }
+    return (request, response, target) => {
+        void dispatch(request, response, target).catch((error) => {
+            if (!(error instanceof DashboardReadModelError) &&
+                !(error instanceof DashboardInvalidCursorError) &&
+                !(error instanceof ContextRunSourceUnavailableError)) {
+                logger.error({ err: error }, "dashboard API request failed");
+            }
+            if (response.headersSent) {
+                response.destroy(error instanceof Error ? error : undefined);
+                return;
+            }
+            if (error instanceof DashboardReadModelError) {
+                sendError(request, response, error.status, error.code);
+                return;
+            }
+            if (error instanceof DashboardInvalidCursorError) {
+                sendError(request, response, 400, "invalid_request");
+                return;
+            }
+            if (error instanceof ContextRunSourceUnavailableError) {
+                sendError(request, response, 503, "context_runs_unavailable");
+                return;
+            }
+            sendError(request, response, 500, "internal_error");
+        });
+    };
+}
+//# sourceMappingURL=api-routes.js.map