clinkx 0.2.3 → 1.0.0

package/clinkx-workflows/dist/dashboard/contracts.js

@@ -0,0 +1,1157 @@
+import { z } from "zod";
+import { PLAN_REVIEW_RESULT_RELPATH } from "../plan-review/publication.js";
+import { IdSchema } from "../schema.js";
+import { CONTEXT_BUILDER_EXECUTION_STATUSES, CONTEXT_BUILDER_FALLBACK_STATUSES, CONTEXT_BUILDER_LIFECYCLE_PHASES, CONTEXT_BUILDER_LIFECYCLE_REASON_CODES, CONTEXT_BUILDER_LIFECYCLE_STATUSES, CONTEXT_BUILDER_OPERATION_KINDS, ContextBuilderLifecycleStateV1Schema, isContextBuilderOperationId, } from "../context-builder-lifecycle-contract.js";
+import { ActivityIdSchema, ActivityKindSchema, ActivityOutcomeKindSchema, ActivityPhaseSchema, } from "./activity-contract.js";
+import { SESSION_LOG_V1_SCHEMA_VERSION, parseSessionLogEventV1, } from "./session-log-contract.js";
+import { PROGRESS_REPORT_SCHEMA_VERSION, BoundedIdSchema, BoundedMessageSchema, BoundedTitleSchema, NonnegativeSafeIntegerSchema, ProjectFolderPathSchema, ProgressReportSessionIdSchema, StrictRfc3339TimestampSchema, } from "./progress-report-contract.js";
+export const MAX_DASHBOARD_STAGE_CALL_RECORDS = 2_000;
+export const MAX_DASHBOARD_ID_CHARS = 128;
+export const MAX_DASHBOARD_PATH_CHARS = 4_096;
+export const MAX_DASHBOARD_RAW_TEXT_CHARS = 2 * 1_024 * 1_024;
+export const MAX_DASHBOARD_STATE_TEXT_CHARS = 64 * 1_024 * 1_024;
+export const MAX_DASHBOARD_WORKFLOW_INPUT_CHARS = 1_024 * 1_024;
+export const MAX_DASHBOARD_WORKFLOW_INPUT_PATHS = 2_048;
+export const MAX_DASHBOARD_ADAPTERS = 256;
+export const DashboardCanonicalHttpsOriginSchema = z.string().superRefine((value, context) => {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "must be a canonical absolute HTTPS origin",
+        });
+        return;
+    }
+    if (parsed.protocol !== "https:" ||
+        parsed.username !== "" ||
+        parsed.password !== "" ||
+        parsed.pathname !== "/" ||
+        parsed.search !== "" ||
+        parsed.hash !== "" ||
+        parsed.origin !== value) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "must be a canonical absolute HTTPS origin",
+        });
+    }
+});
+export const DashboardAgentInstanceIdSchema = z.string().regex(/^[A-Za-z0-9_-]{22}$/);
+export const DashboardBearerCapabilitySchema = z.string().regex(/^[A-Za-z0-9_-]{43}$/);
+export const DashboardRemoteAccessConfigSchema = z.object({
+    apiOrigin: DashboardCanonicalHttpsOriginSchema,
+    uiOrigin: DashboardCanonicalHttpsOriginSchema,
+}).strict();
+export const DashboardConnectionResponseSchema = z.object({
+    schemaVersion: z.literal("dashboard-connection-v1"),
+    agentInstanceId: DashboardAgentInstanceIdSchema,
+}).strict();
+export const DashboardRemoteFragmentInputSchema = z.object({
+    apiOrigin: DashboardCanonicalHttpsOriginSchema,
+    agentInstanceId: DashboardAgentInstanceIdSchema,
+    token: DashboardBearerCapabilitySchema,
+}).strict();
+export function formatDashboardRemoteFragment(input) {
+    const parsed = DashboardRemoteFragmentInputSchema.parse(input);
+    return [
+        "#v=1",
+        `apiOrigin=${encodeURIComponent(parsed.apiOrigin)}`,
+        `agentInstanceId=${parsed.agentInstanceId}`,
+        `token=${parsed.token}`,
+    ].join("&");
+}
+const RUN_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+const COMPLEXITY_ISSUE = "dashboard_stage_call_limit_exceeded";
+const RunIdSchema = z.string().max(64).regex(RUN_ID_PATTERN);
+const DashboardIdSchema = IdSchema.max(MAX_DASHBOARD_ID_CHARS);
+const TimestampSchema = z.string().max(64).datetime({ offset: true });
+const RelativePathSchema = z.string().min(1).max(MAX_DASHBOARD_PATH_CHARS);
+const DashboardCallStateSchema = z.enum([
+    "pending",
+    "running",
+    "succeeded",
+    "failed",
+    "cancelled",
+]);
+const DashboardFailureClassSchema = z.enum(["transient", "permanent"]);
+/**
+ * `heartbeat_live` is appended, never reordered: a producer on a foreign host
+ * refreshed its `run.lock` mtime within the declared staleness window. It is
+ * weaker evidence than `live` (a same-host PID probe) and is reported as a
+ * distinct value rather than folded into `live`.
+ */
+export const WorkerLockObservationSchema = z.enum([
+    "live",
+    "orphaned",
+    "unknown",
+    "heartbeat_live",
+]);
+/** Strict display contract for the exact persisted pre-dispatch Clink input. */
+export const DashboardWorkflowInputSchema = z.object({
+    prompt: z.string().max(MAX_DASHBOARD_WORKFLOW_INPUT_CHARS),
+    cli_name: z.string().min(1).max(MAX_DASHBOARD_ID_CHARS).optional(),
+    role: z.string().min(1).max(MAX_DASHBOARD_ID_CHARS).optional(),
+    absolute_file_paths: z
+        .array(z.string().min(1).max(MAX_DASHBOARD_PATH_CHARS))
+        .max(MAX_DASHBOARD_WORKFLOW_INPUT_PATHS)
+        .optional(),
+    images: z
+        .array(z.string().min(1).max(MAX_DASHBOARD_PATH_CHARS))
+        .max(MAX_DASHBOARD_WORKFLOW_INPUT_PATHS)
+        .optional(),
+    context: z.string().max(MAX_DASHBOARD_WORKFLOW_INPUT_CHARS).optional(),
+    continuation_id: z.string().min(1).max(256).optional(),
+    timeout_seconds: z.number().finite().positive().optional(),
+    max_response_chars: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+    expect_json: z.boolean().optional(),
+    debug: z.boolean().optional(),
+    debug_keep_artifacts: z.boolean().optional(),
+}).strict();
+const SortedUniqueStringsSchema = z
+    .array(z.string().min(1).max(MAX_DASHBOARD_ID_CHARS))
+    .max(256)
+    .refine((values) => values.every((value, index) => index === 0 || values[index - 1] < value), "must be sorted and unique");
+/** Positive allowlist for root-injected adapter metadata. */
+export const SafeAdapterDescriptorSchema = z.object({
+    name: z.string().min(1).max(MAX_DASHBOARD_ID_CHARS),
+    command: z
+        .string()
+        .min(1)
+        .max(256)
+        .refine((value) => !value.includes("/") && !value.includes("\\"), "command must be a basename"),
+    parser: z.enum(["text", "json_extract", "codex_jsonl", "claude_json", "claude_stream_json"]),
+    promptMode: z.enum(["stdin", "arg", "file"]),
+    timeoutSeconds: z.number().finite().positive(),
+    idleTimeoutSeconds: z.number().finite().min(0).optional(),
+    idleTimeoutStartupSeconds: z.number().finite().min(0).optional(),
+    roleNames: SortedUniqueStringsSchema,
+    environmentKeys: SortedUniqueStringsSchema,
+    supportsImages: z.boolean(),
+    resultContract: z.object({
+        enabled: z.boolean(),
+        filename: z.enum(["RESULT.md", "RESULT.json"]),
+    }).strict(),
+    backend: z.enum(["subprocess", "app_server"]),
+    workflowEligible: z.boolean().optional(),
+    usableVia: z.array(z.enum([
+        "clink",
+        "context_builder",
+        "run_workflow",
+        "clink_agent_run",
+        "clink_agent_manage",
+    ])).max(5).optional(),
+}).strict();
+export const MAX_DASHBOARD_PAGE_SIZE = 500;
+const OpaqueCursorSchema = z.string().min(1).max(1_024).regex(/^[A-Za-z0-9_-]+$/);
+const OpaqueGenerationSchema = z.string().min(16).max(128).regex(/^[A-Za-z0-9_-]+$/);
+const SingleCursorValuesSchema = z.array(OpaqueCursorSchema).length(1).transform(([value]) => value);
+const SingleGenerationValuesSchema = z
+    .array(OpaqueGenerationSchema)
+    .length(1)
+    .transform(([value]) => value);
+const SingleLimitValuesSchema = z
+    .array(z.string().regex(/^[1-9][0-9]{0,2}$/))
+    .length(1)
+    .transform(([value]) => Number(value))
+    .refine((value) => value <= MAX_DASHBOARD_PAGE_SIZE, `limit must be <= ${String(MAX_DASHBOARD_PAGE_SIZE)}`);
+/** Query contracts consume a multimap so duplicate security fields stay visible. */
+export const PaginationQuerySchema = z.object({
+    limit: SingleLimitValuesSchema.optional(),
+    before: SingleCursorValuesSchema.optional(),
+}).strict().transform((query) => ({
+    limit: query.limit ?? 100,
+    ...(query.before === undefined ? {} : { before: query.before }),
+}));
+export const GenerationQuerySchema = z.object({
+    generation: SingleGenerationValuesSchema,
+}).strict().transform((query) => ({ generation: query.generation }));
+const SingleSessionLogSequenceValuesSchema = z
+    .array(z.string().regex(/^(?:0|[1-9][0-9]{0,15})$/))
+    .length(1)
+    .transform(([value]) => Number(value))
+    .refine(Number.isSafeInteger, "sequence must be a safe integer");
+export const SessionLogLaneIndexQuerySchema = z.object({
+    generation: SingleGenerationValuesSchema,
+}).strict().transform((query) => ({ generation: query.generation }));
+export const SessionLogPageQuerySchema = z.object({
+    generation: SingleGenerationValuesSchema,
+    sequence: SingleSessionLogSequenceValuesSchema.optional(),
+    limit: SingleLimitValuesSchema.optional(),
+}).strict().transform((query) => ({
+    generation: query.generation,
+    sequence: query.sequence ?? 0,
+    limit: query.limit ?? 100,
+}));
+const SessionLogLaneDescriptorResponseSchema = z.object({
+    owner: z.record(z.unknown()),
+    lane: z.object({
+        laneId: z.string().min(1).max(160).regex(/^[A-Za-z0-9_:-]+$/),
+    }).strict(),
+    nextSequence: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+}).strict().superRefine((descriptor, context) => {
+    try {
+        parseSessionLogEventV1({
+            schemaVersion: SESSION_LOG_V1_SCHEMA_VERSION,
+            sequence: 0,
+            timestamp: "2000-01-01T00:00:00.000Z",
+            producerFamily: descriptor.owner.family,
+            owner: descriptor.owner,
+            lane: descriptor.lane,
+            authority: "observability_only",
+            redaction: { ran: true, status: "no_matches", count: 0 },
+            truncation: "none",
+            completeness: "complete",
+            parseWarnings: [],
+            event: { kind: "lifecycle", state: "pending" },
+        });
+    }
+    catch {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "invalid session-log lane descriptor",
+        });
+    }
+});
+export const SessionLogLaneIndexResponseSchema = z.object({
+    schemaVersion: z.literal("session-log-index-v1"),
+    availability: z.discriminatedUnion("availability", [
+        z.object({ availability: z.literal("available") }).strict(),
+        z.object({
+            availability: z.literal("not_retained"),
+            reason: z.literal("producer_did_not_retain"),
+        }).strict(),
+    ]),
+    lanes: z.array(SessionLogLaneDescriptorResponseSchema).max(2_000),
+}).strict().superRefine((response, context) => {
+    if ((response.availability.availability === "available") !==
+        (response.lanes.length > 0)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "session-log lane availability must match discovered lanes",
+            path: ["availability"],
+        });
+    }
+});
+export const StructuredDetailQuerySchema = z.object({
+    generation: SingleGenerationValuesSchema.optional(),
+}).strict().transform((query) => query.generation === undefined ? {} : { generation: query.generation });
+/** Detail routes resolve the current incarnation and admit no query fields. */
+export const EmptyQuerySchema = z.object({}).strict();
+export const ContextRunListQuerySchema = z.object({
+    limit: SingleLimitValuesSchema.optional(),
+}).strict().transform((query) => ({ limit: query.limit ?? 100 }));
+const ContextRunRouteIdSchema = z.string()
+    .max(64)
+    .regex(/^[A-Za-z0-9_-]{1,64}$/)
+    .refine((id) => !id.startsWith("wfctx") && !id.startsWith("wfpre"), "workflow-owned context records are not context runs");
+export const ContextRunRouteParamsSchema = z.object({
+    id: ContextRunRouteIdSchema,
+}).strict();
+/**
+ * Artifact keys servable via the bounded `/context-runs/:id/artifacts/:key`
+ * body endpoint. Mirrors the producer artifact filename map; the reader pins its
+ * own copy to the producer export via a parity test, so this enum and the
+ * reader's `CONTEXT_RUN_ARTIFACT_FILE_NAMES` cannot drift independently.
+ */
+export const ContextRunArtifactKeySchema = z.enum([
+    "manifest_json",
+    "bundle_md",
+    "selected_context_jsonl",
+    "tree_json",
+    "search_jsonl",
+    "slices_jsonl",
+    "codemap_jsonl",
+    "summary_json",
+]);
+export const ContextRunArtifactRouteParamsSchema = z.object({
+    id: ContextRunRouteIdSchema,
+    artifactKey: ContextRunArtifactKeySchema,
+}).strict();
+export const RunRouteParamsSchema = z.object({
+    runId: RunIdSchema,
+}).strict();
+export const ActivityRouteParamsSchema = z.object({
+    activityId: ActivityIdSchema,
+}).strict();
+export const CallRouteParamsSchema = z.object({
+    runId: RunIdSchema,
+    stageId: DashboardIdSchema,
+    callId: DashboardIdSchema,
+    contentKind: z.enum(["prompt", "output", "error", "artifact"]),
+}).strict();
+export const SessionLogWorkflowRouteParamsSchema = z.object({
+    runId: RunIdSchema,
+    stageId: DashboardIdSchema,
+    callId: DashboardIdSchema,
+}).strict();
+export const SessionLogLaneRouteParamsSchema = z.object({
+    laneId: z.string().min(1).max(160).regex(/^[A-Za-z0-9_:-]+$/),
+}).strict();
+const WorkflowVariableDescriptorSchema = z.object({
+    name: DashboardIdSchema,
+    type: z.enum(["string", "number", "boolean", "string[]"]),
+    required: z.boolean(),
+}).strict();
+export const WorkflowDescriptorSchema = z.object({
+    name: DashboardIdSchema,
+    version: z.string().min(1).max(128),
+    description: z.string().max(4_096),
+    stageCount: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    callCount: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    variables: z.array(WorkflowVariableDescriptorSchema).max(512),
+}).strict();
+const DashboardChildConfigSourceSchema = z.discriminatedUnion("source", [
+    z.object({
+        source: z.literal("explicit"),
+        configured: z.literal(true),
+        path: z.string().min(1).max(MAX_DASHBOARD_PATH_CHARS),
+    }).strict(),
+    z.object({
+        source: z.literal("ambient"),
+        configured: z.literal(false),
+    }).strict(),
+]);
+export const DashboardEnvironmentSchema = z.object({
+    stateDir: z.string().min(1).max(MAX_DASHBOARD_PATH_CHARS),
+    activitiesRoot: z.string().min(1).max(MAX_DASHBOARD_PATH_CHARS).optional(),
+    progressReportsRoot: z.string().min(1).max(MAX_DASHBOARD_PATH_CHARS).optional(),
+    runsRoot: z.string().min(1).max(MAX_DASHBOARD_PATH_CHARS),
+    workspaceRoot: z.string().min(1).max(MAX_DASHBOARD_PATH_CHARS),
+    workflowsPath: z.string().min(1).max(MAX_DASHBOARD_PATH_CHARS),
+    templatesPath: z.string().min(1).max(MAX_DASHBOARD_PATH_CHARS),
+    childConfig: DashboardChildConfigSourceSchema,
+}).strict();
+const RunIdentitySchema = z.object({
+    runId: RunIdSchema,
+    runGeneration: OpaqueGenerationSchema,
+    stateRevision: OpaqueGenerationSchema,
+});
+const DashboardStageMarkerSchema = z.object({
+    stageId: DashboardIdSchema,
+    state: DashboardCallStateSchema,
+}).strict();
+export const MAX_DASHBOARD_STAGE_MARKERS = 64;
+export const MAX_DASHBOARD_LIVE_RUNS = 500;
+/** Cap on projected `cb_roots` (mirrors the search-terms channel cap). */
+export const MAX_DASHBOARD_ROOTS = 20;
+export const MAX_DASHBOARD_AGGREGATE_RETRY_COUNT = MAX_DASHBOARD_STAGE_CALL_RECORDS * 1_000_000;
+const CompactStateCountsSchema = z.object({
+    pending: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    running: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    succeeded: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    failed: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    cancelled: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+}).strict();
+const HealthyRunListItemSchema = RunIdentitySchema.extend({
+    availability: z.literal("available"),
+    workflowName: DashboardIdSchema,
+    workflowVersion: z.string().min(1).max(128),
+    status: DashboardCallStateSchema,
+    orphaned: z.boolean(),
+    workerLockObservation: WorkerLockObservationSchema.optional(),
+    resumable: z.boolean(),
+    startedAt: TimestampSchema.optional(),
+    completedAt: TimestampSchema.optional(),
+    stateUpdatedAt: TimestampSchema,
+    failureClass: DashboardFailureClassSchema.optional(),
+    async: z.boolean(),
+    debugKeepArtifacts: z.boolean(),
+    retryCount: z.number().int().min(0).max(MAX_DASHBOARD_AGGREGATE_RETRY_COUNT),
+    reportedRunningCalls: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    stageCounts: CompactStateCountsSchema,
+    callCounts: CompactStateCountsSchema,
+    stageMarkers: z.array(DashboardStageMarkerSchema).max(MAX_DASHBOARD_STAGE_MARKERS),
+    additionalStageCount: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    /**
+     * Project folder(s) the run was created for, sourced from the persisted
+     * `variables.cb_roots`. Always present (empty when no roots were recorded) so
+     * the detail page can show a stable "project folder" row.
+     */
+    projectFolders: z.array(z.string()).max(MAX_DASHBOARD_ROOTS),
+}).strict();
+const UnavailableReasonSchema = z.enum([
+    "state_unreadable",
+    "state_invalid",
+    "too_large_for_dashboard",
+    "too_complex_for_dashboard",
+    "path_rejected",
+    "identity_mismatch",
+    "run_generation_race",
+]);
+const UnavailableRunSchema = RunIdentitySchema.extend({
+    availability: z.literal("unavailable"),
+    reason: UnavailableReasonSchema,
+    chronologyAt: TimestampSchema.optional(),
+}).strict();
+export const ActivityLeaseObservationSchema = z.enum([
+    "live",
+    "orphaned",
+    "unknown",
+]);
+function requireConsistentActivityLease(item, ctx) {
+    if (item.orphaned !== (item.leaseObservation === "orphaned")) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "orphaned must agree with leaseObservation",
+            path: ["orphaned"],
+        });
+    }
+    if (item.status !== "running") {
+        if (item.orphaned || item.leaseObservation !== "unknown") {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "terminal activities cannot carry a live or orphaned lease",
+                path: ["leaseObservation"],
+            });
+        }
+    }
+}
+function requireConsistentWorkerLockObservation(item, ctx) {
+    if (item.workerLockObservation !== undefined &&
+        item.orphaned !== (item.workerLockObservation === "orphaned")) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "orphaned must agree with workerLockObservation",
+            path: ["orphaned"],
+        });
+    }
+}
+const ConsistentHealthyRunListItemSchema = HealthyRunListItemSchema.superRefine(requireConsistentWorkerLockObservation);
+export const RunListItemSchema = z.discriminatedUnion("availability", [
+    HealthyRunListItemSchema,
+    UnavailableRunSchema,
+]).superRefine((item, ctx) => {
+    if (item.availability === "available")
+        requireConsistentWorkerLockObservation(item, ctx);
+});
+export const RunListResponseSchema = z.object({
+    live: z.array(ConsistentHealthyRunListItemSchema).max(MAX_DASHBOARD_LIVE_RUNS),
+    history: z.array(RunListItemSchema).max(MAX_DASHBOARD_PAGE_SIZE),
+    nextBefore: OpaqueCursorSchema.optional(),
+    serverNow: TimestampSchema,
+}).strict();
+export const RunsResponseSchema = RunListResponseSchema;
+const ActivityIdentitySchema = z.object({
+    activityId: ActivityIdSchema,
+    activityGeneration: OpaqueGenerationSchema,
+    stateRevision: OpaqueGenerationSchema,
+}).strict();
+const ActivityListItemObjectSchema = ActivityIdentitySchema.extend({
+    kind: ActivityKindSchema,
+    phase: ActivityPhaseSchema,
+    status: z.enum(["running", "succeeded", "failed", "cancelled"]),
+    adapter: DashboardIdSchema,
+    role: DashboardIdSchema,
+    startedAt: TimestampSchema,
+    stateUpdatedAt: TimestampSchema,
+    completedAt: TimestampSchema.optional(),
+    hasResult: z.boolean(),
+    projectFolders: z.array(z.string()).max(MAX_DASHBOARD_ROOTS),
+    orphaned: z.boolean(),
+    leaseObservation: ActivityLeaseObservationSchema,
+}).strict();
+export const ActivityListItemSchema = ActivityListItemObjectSchema
+    .superRefine(requireConsistentActivityLease);
+export const ActivityListResponseSchema = z.object({
+    activities: z.array(ActivityListItemSchema).max(MAX_DASHBOARD_PAGE_SIZE),
+    nextBefore: OpaqueCursorSchema.optional(),
+    serverNow: TimestampSchema,
+}).strict();
+export const ActivityDetailSchema = ActivityListItemObjectSchema.extend({
+    outcome: z.object({
+        kind: ActivityOutcomeKindSchema,
+    }).strict().optional(),
+    resultTruncated: z.boolean().optional(),
+}).strict().superRefine(requireConsistentActivityLease);
+const ContextRunCountSchema = z.number().int().min(0).max(250_000_000);
+export const ContextRunLifecycleProjectionSchema = z.object({
+    status: z.enum(CONTEXT_BUILDER_LIFECYCLE_STATUSES),
+    phase: z.enum(CONTEXT_BUILDER_LIFECYCLE_PHASES),
+    createdAt: TimestampSchema.nullable(),
+    updatedAt: TimestampSchema.nullable(),
+    startedAt: TimestampSchema.nullable(),
+    completedAt: TimestampSchema.nullable(),
+    durationMs: z.number().int().min(0).max(86_400_000).nullable(),
+    curator: z.object({
+        status: z.enum(CONTEXT_BUILDER_EXECUTION_STATUSES),
+        score: z.number().finite().min(0).max(10).nullable(),
+    }).strict(),
+    finalizer: z.object({
+        status: z.enum(CONTEXT_BUILDER_EXECUTION_STATUSES),
+        score: z.number().finite().min(0).max(10).nullable(),
+    }).strict(),
+    cache: z.object({
+        lookup: z.enum(["not_checked", "miss", "hit"]),
+        write: z.enum(["not_attempted", "skipped", "written"]),
+    }).strict(),
+    fallback: z.object({
+        status: z.enum(CONTEXT_BUILDER_FALLBACK_STATUSES),
+    }).strict(),
+    counts: z.object({
+        filesSeen: ContextRunCountSchema,
+        filesConsidered: ContextRunCountSchema,
+        filesSelected: ContextRunCountSchema,
+        filesOmitted: ContextRunCountSchema,
+        searchResults: ContextRunCountSchema,
+        bytesRead: ContextRunCountSchema,
+        bytesWritten: ContextRunCountSchema,
+    }).strict(),
+    coverage: z.object({
+        policy: z.literal("review_deep_v1").nullable(),
+        status: z.enum(["satisfied", "degraded", "not_evaluated"]),
+        required: ContextRunCountSchema,
+        selected: ContextRunCountSchema,
+        missing: ContextRunCountSchema,
+    }).strict(),
+    reasonCodes: z.array(z.enum(CONTEXT_BUILDER_LIFECYCLE_REASON_CODES))
+        .max(16)
+        .refine((codes) => new Set(codes).size === codes.length, "reason codes must be unique"),
+    artifactRunId: RunIdSchema.nullable(),
+}).strict();
+const CurrentDashboardContextPreflightSchema = ContextRunLifecycleProjectionSchema.extend({
+    availability: z.literal("current"),
+    profile: z.enum([
+        "handoff_small",
+        "implementation_medium",
+        "review_deep",
+    ]).nullable(),
+    effectiveMode: z.enum(["full", "deterministic", "off", "disabled"]).nullable(),
+    failurePolicy: z.enum(["fallback", "fail"]).nullable(),
+    // The ctxop_… operation id, present when a preflight session-log generation
+    // sidecar exists. Pairs with the sidecar under <runDir>/.context-preflight.
+    contextRunId: z.string().max(40).refine(isContextBuilderOperationId, "invalid context builder operation ID").optional(),
+}).strict();
+const LegacyDashboardContextPreflightSchema = z.object({
+    availability: z.literal("legacy_without_telemetry"),
+    status: z.enum(["succeeded", "partial"]),
+    profile: z.enum([
+        "handoff_small",
+        "implementation_medium",
+        "review_deep",
+    ]).nullable(),
+    effectiveMode: z.enum(["full", "deterministic", "off", "disabled"]).nullable(),
+    failurePolicy: z.enum(["fallback", "fail"]).nullable(),
+}).strict();
+const PolicyOnlyDashboardContextPreflightSchema = z.object({
+    profile: z.enum([
+        "handoff_small",
+        "implementation_medium",
+        "review_deep",
+    ]).nullable(),
+    effectiveMode: z.enum(["full", "deterministic", "off", "disabled"]),
+    failurePolicy: z.enum(["fallback", "fail"]).nullable(),
+}).strict();
+export const DashboardContextPreflightSchema = z.discriminatedUnion("availability", [
+    CurrentDashboardContextPreflightSchema,
+    LegacyDashboardContextPreflightSchema,
+    PolicyOnlyDashboardContextPreflightSchema.extend({
+        availability: z.literal("bypassed"),
+    }).strict(),
+    PolicyOnlyDashboardContextPreflightSchema.extend({
+        availability: z.literal("awaiting_telemetry"),
+    }).strict(),
+    PolicyOnlyDashboardContextPreflightSchema.extend({
+        availability: z.literal("telemetry_unavailable"),
+    }).strict(),
+    z.object({ availability: z.literal("absent") }).strict(),
+]);
+export const ContextRunLivenessSchema = z.enum([
+    "live",
+    "orphaned",
+    "unknown",
+]);
+function requireConsistentContextRunLiveness(row, ctx) {
+    if (row.orphaned !== (row.liveness === "orphaned")) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "orphaned must agree with liveness",
+            path: ["orphaned"],
+        });
+    }
+    const status = row.lifecycle?.status;
+    const active = status === "pending" || status === "running";
+    if (!active && (row.orphaned || row.liveness !== "unknown")) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "terminal or unsupported context runs cannot carry live or orphaned liveness",
+            path: ["liveness"],
+        });
+    }
+}
+export const ContextRunRowSchema = z.object({
+    id: ContextRunRouteIdSchema,
+    contextGeneration: OpaqueGenerationSchema,
+    source: z.enum(["journal", "historical_manifest"]),
+    compatibility: z.enum([
+        "current",
+        "legacy_synthesized",
+        "legacy_unsupported",
+    ]),
+    operationKind: z.enum(CONTEXT_BUILDER_OPERATION_KINDS),
+    lifecycle: ContextRunLifecycleProjectionSchema.nullable(),
+    /**
+     * Project folder(s) from the manifest `roots[].path`. Defaults to `[]` so the
+     * strict parse accepts both journal producers (no roots) and historical rows.
+     */
+    projectFolders: z.array(z.string()).max(MAX_DASHBOARD_ROOTS).default([]),
+    orphaned: z.boolean().default(false),
+    liveness: ContextRunLivenessSchema.default("unknown"),
+}).strict().superRefine((row, context) => {
+    if ((row.compatibility === "legacy_unsupported") !== (row.lifecycle === null)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "only legacy_unsupported context runs omit lifecycle detail",
+            path: ["lifecycle"],
+        });
+    }
+    requireConsistentContextRunLiveness(row, context);
+});
+export const ContextRunListResponseSchema = z.object({
+    contextRuns: z.array(ContextRunRowSchema).max(MAX_DASHBOARD_PAGE_SIZE),
+    serverNow: TimestampSchema,
+    truncated: z.boolean(),
+}).strict();
+const DashboardCallSummarySchema = z.object({
+    stageId: DashboardIdSchema,
+    callId: DashboardIdSchema,
+    state: DashboardCallStateSchema,
+    retryCount: z.number().int().min(0).max(1_000_000),
+    attemptsConsumed: z.number().int().min(0).max(1_000_000).optional(),
+    startedAt: TimestampSchema.optional(),
+    completedAt: TimestampSchema.optional(),
+    durationMs: z.number().finite().min(0).max(Number.MAX_SAFE_INTEGER).optional(),
+    failureClass: DashboardFailureClassSchema.optional(),
+    snapshotIdentity: z.object({
+        adapter: DashboardIdSchema,
+        role: DashboardIdSchema,
+    }).strict().optional(),
+    hasWorkflowInput: z.boolean(),
+    hasOutput: z.boolean(),
+    hasRawError: z.boolean(),
+    hasArtifactReference: z.boolean(),
+}).strict();
+const DashboardStageDetailSchema = z.object({
+    stageId: DashboardIdSchema,
+    state: DashboardCallStateSchema,
+    startedAt: TimestampSchema.optional(),
+    completedAt: TimestampSchema.optional(),
+    calls: z.array(DashboardCallSummarySchema).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+}).strict();
+const SnapshotEnrichmentSchema = z.discriminatedUnion("availability", [
+    z.object({
+        availability: z.literal("available"),
+        stages: z.array(z.object({
+            stageId: DashboardIdSchema,
+            label: z.string().min(1).max(256).optional(),
+            dependsOn: z.array(DashboardIdSchema).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+        }).strict()).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    }).strict(),
+    z.object({
+        availability: z.literal("unavailable"),
+        reason: z.enum(["missing", "not_loaded", "unreadable", "invalid", "too_large", "hash_mismatch"]),
+    }).strict(),
+]);
+const ResultAvailabilitySchema = z.discriminatedUnion("availability", [
+    z.object({
+        availability: z.literal("available"),
+        kind: z.enum(["text", "json", "plan_review"]),
+    }).strict(),
+    z.object({
+        availability: z.literal("unavailable"),
+        reason: z.enum([
+            "run_pending",
+            "run_running",
+            "run_failed",
+            "run_cancelled",
+            "not_persisted",
+            "missing",
+            "invalid",
+            "too_large",
+        ]),
+    }).strict(),
+]);
+const DecisiveFailureSchema = z.object({
+    stageId: DashboardIdSchema,
+    callId: DashboardIdSchema.optional(),
+    failureClass: DashboardFailureClassSchema,
+}).strict();
+const StateCountsSchema = z.object({
+    pending: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    running: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    succeeded: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    failed: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    cancelled: z.number().int().min(0).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+}).strict();
+const GenericDetailCardSchema = z.object({
+    kind: z.literal("generic"),
+    stageCounts: StateCountsSchema,
+    callCounts: StateCountsSchema,
+}).strict();
+const PlanReviewTransportCardSchema = z.object({
+    kind: z.literal("council-plan-review"),
+    executionStatus: z.enum(["complete", "partial"]),
+    seatCount: z.number().int().min(1).max(10),
+    completedSeats: z.number().int().min(0).max(10),
+    failedSeats: z.number().int().min(0).max(10),
+    missingSeats: z.number().int().min(0).max(10),
+    executionContractDigestPrefix: z.string().length(16).regex(/^[0-9a-f]{16}$/),
+    chairmanStatus: z.enum(["completed", "failed", "skipped"]),
+    contextStatus: z.enum(["succeeded", "partial", "absent"]),
+}).strict().superRefine((card, ctx) => {
+    if (card.completedSeats + card.failedSeats + card.missingSeats !== card.seatCount) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "plan-review seat counts must equal seatCount",
+            path: ["seatCount"],
+        });
+    }
+});
+const DashboardDetailCardSchema = z.union([
+    GenericDetailCardSchema,
+    PlanReviewTransportCardSchema,
+]);
+const HealthyRunDetailSchema = HealthyRunListItemSchema.extend({
+    snapshotEnrichment: SnapshotEnrichmentSchema,
+    result: ResultAvailabilitySchema,
+    decisiveFailure: DecisiveFailureSchema.optional(),
+    card: DashboardDetailCardSchema,
+    stages: z.array(DashboardStageDetailSchema).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    contextPreflight: DashboardContextPreflightSchema.optional(),
+}).strict();
+export const RunDetailSchema = z.discriminatedUnion("availability", [
+    HealthyRunDetailSchema,
+    UnavailableRunSchema,
+]).superRefine((detail, ctx) => {
+    if (detail.availability !== "available")
+        return;
+    requireConsistentWorkerLockObservation(detail, ctx);
+    const count = detail.stages.length + detail.stages.reduce((sum, stage) => sum + stage.calls.length, 0);
+    if (count > MAX_DASHBOARD_STAGE_CALL_RECORDS) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: COMPLEXITY_ISSUE,
+            path: ["stages"],
+        });
+    }
+    const detailStageIds = new Set(detail.stages.map((stage) => stage.stageId));
+    if (detail.snapshotEnrichment.availability === "available") {
+        const snapshotStageIds = new Set();
+        for (const [index, snapshotStage] of detail.snapshotEnrichment.stages.entries()) {
+            if (snapshotStageIds.has(snapshotStage.stageId)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "snapshot enrichment stage IDs must be unique",
+                    path: ["snapshotEnrichment", "stages", index, "stageId"],
+                });
+            }
+            snapshotStageIds.add(snapshotStage.stageId);
+            if (!detailStageIds.has(snapshotStage.stageId)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "snapshot enrichment stage must match persisted state",
+                    path: ["snapshotEnrichment", "stages", index, "stageId"],
+                });
+            }
+        }
+        if (snapshotStageIds.size !== detailStageIds.size) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "available snapshot enrichment must cover every persisted stage",
+                path: ["snapshotEnrichment", "stages"],
+            });
+        }
+        for (const [stageIndex, stage] of detail.stages.entries()) {
+            for (const [callIndex, call] of stage.calls.entries()) {
+                if (call.snapshotIdentity === undefined) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        message: "available snapshot enrichment must identify every persisted call",
+                        path: ["stages", stageIndex, "calls", callIndex, "snapshotIdentity"],
+                    });
+                }
+            }
+        }
+    }
+    else {
+        for (const [stageIndex, stage] of detail.stages.entries()) {
+            for (const [callIndex, call] of stage.calls.entries()) {
+                if (call.snapshotIdentity !== undefined) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        message: "unavailable snapshot enrichment cannot supply call identity",
+                        path: ["stages", stageIndex, "calls", callIndex, "snapshotIdentity"],
+                    });
+                }
+            }
+        }
+    }
+    if (detail.decisiveFailure !== undefined) {
+        const failureStage = detail.stages.find((stage) => stage.stageId === detail.decisiveFailure?.stageId);
+        if (failureStage === undefined || (detail.decisiveFailure.callId !== undefined &&
+            !failureStage.calls.some((call) => call.callId === detail.decisiveFailure?.callId))) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "decisive failure must identify a persisted stage/call",
+                path: ["decisiveFailure"],
+            });
+        }
+    }
+    // The transport-card kind literal "council-plan-review" is a wire-contract
+    // identifier, not the workflow name. Typed runs are named
+    // "plan-review-receipts" since the rename; legacy typed runs persist the
+    // pre-rename name "council-plan-review" (which now also names the generic
+    // plan-review council — its runs carry a generic card, never this one).
+    if (detail.card.kind === "council-plan-review" &&
+        detail.workflowName !== "plan-review-receipts" &&
+        detail.workflowName !== "council-plan-review") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "plan-review transport card requires the plan-review-receipts workflow",
+            path: ["card", "kind"],
+        });
+    }
+});
+export const RunDetailResponseSchema = RunDetailSchema;
+export const ArtifactReferenceSchema = RunIdentitySchema.extend({
+    stageId: DashboardIdSchema,
+    callId: DashboardIdSchema,
+    kind: z.literal("json"),
+    validation: z.literal("deferred"),
+}).strict();
+export const WorkflowsResponseSchema = z.object({
+    workflows: z.array(WorkflowDescriptorSchema).max(1_000),
+}).strict();
+export const AdaptersResponseSchema = z.object({
+    adapters: z.array(SafeAdapterDescriptorSchema).max(MAX_DASHBOARD_ADAPTERS),
+}).strict();
+export const ArtifactsResponseSchema = z.object({
+    artifacts: z.array(ArtifactReferenceSchema).max(MAX_DASHBOARD_PAGE_SIZE),
+    nextBefore: OpaqueCursorSchema.optional(),
+    serverNow: TimestampSchema,
+}).strict();
+export const EnvironmentResponseSchema = DashboardEnvironmentSchema;
+export const ApiErrorResponseSchema = z.object({
+    error: z.object({
+        code: z.enum([
+            "unauthorized",
+            "invalid_request",
+            "method_not_allowed",
+            "host_rejected",
+            "origin_rejected",
+            "not_found",
+            "dashboard_busy",
+            "run_directory_limit_exceeded",
+            "scan_byte_budget_exceeded",
+            "projection_cache_budget_exceeded",
+            "live_run_limit_exceeded",
+            "artifact_catalog_limit_exceeded",
+            "run_generation_changed",
+            "run_state_changed",
+            "activity_generation_changed",
+            "activity_state_changed",
+            "context_generation_changed",
+            "agent_instance_changed",
+            "content_too_large_for_dashboard",
+            "context_runs_unavailable",
+            "session_logs_unavailable",
+            "progress_report_malformed",
+            "progress_report_overrides_unavailable",
+            "internal_error",
+        ]),
+    }).strict(),
+}).strict();
+const DashboardCallStateEntrySchema = z.object({
+    callId: DashboardIdSchema,
+    stageId: DashboardIdSchema,
+    state: DashboardCallStateSchema,
+    retryCount: z.number().int().min(0).max(1_000_000),
+    attemptsConsumed: z.number().int().min(0).max(1_000_000).optional(),
+    startedAt: TimestampSchema.optional(),
+    completedAt: TimestampSchema.optional(),
+    durationMs: z.number().finite().min(0).max(Number.MAX_SAFE_INTEGER).optional(),
+    failureClass: DashboardFailureClassSchema.optional(),
+    errorMessage: z.string().max(MAX_DASHBOARD_STATE_TEXT_CHARS).optional(),
+    outputPath: RelativePathSchema.optional(),
+    outputInline: z.string().max(MAX_DASHBOARD_STATE_TEXT_CHARS).optional(),
+    materializedInputPath: RelativePathSchema.optional(),
+    artifactPath: RelativePathSchema.optional(),
+});
+const DashboardStageStateEntrySchema = z.object({
+    stageId: DashboardIdSchema,
+    state: DashboardCallStateSchema,
+    startedAt: TimestampSchema.optional(),
+    completedAt: TimestampSchema.optional(),
+    calls: z.array(DashboardCallStateEntrySchema).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+});
+const DashboardPlanReviewPublicationSchema = z.discriminatedUnion("committed", [
+    z.object({ committed: z.literal(false) }),
+    z.object({
+        committed: z.literal(true),
+        sidecar_relpath: z.literal(PLAN_REVIEW_RESULT_RELPATH),
+        sidecar_sha256: z.string().length(64).regex(SHA256_PATTERN),
+        bytes: z.number().int().min(0).max(MAX_DASHBOARD_STATE_TEXT_CHARS),
+    }),
+]);
+/**
+ * Consumed-field decoder for persisted engine state.
+ *
+ * Deliberately strips unknown producer fields: this is a dashboard read schema,
+ * not the execution engine's complete RunState authority.
+ */
+export const DashboardRunStateSchema = z.object({
+    state_version: z.literal(1),
+    runId: RunIdSchema,
+    workflowName: DashboardIdSchema,
+    workflowVersion: z.string().min(1).max(128),
+    status: DashboardCallStateSchema,
+    resumable: z.boolean(),
+    workflowSnapshotPath: z.literal("workflow.snapshot.json").optional(),
+    workflowSnapshotHash: z.string().length(64).regex(SHA256_PATTERN).optional(),
+    stages: z.array(DashboardStageStateEntrySchema).max(MAX_DASHBOARD_STAGE_CALL_RECORDS),
+    startedAt: TimestampSchema.optional(),
+    completedAt: TimestampSchema.optional(),
+    failureClass: DashboardFailureClassSchema.optional(),
+    debugKeepArtifacts: z.boolean().optional(),
+    async: z.boolean().optional(),
+    variables: z.object({
+        cb_profile: z.enum([
+            "handoff_small",
+            "implementation_medium",
+            "review_deep",
+        ]).optional(),
+        /**
+         * Context-builder source roots the run operated on — the project folder(s)
+         * the run was created for. Persisted by the workflow engine as a string
+         * array; surfaced on the run detail page as "project folder".
+         */
+        cb_roots: z.array(z.string()).optional(),
+    }).optional(),
+    initialContextPolicy: z.object({
+        effectiveMode: z.enum(["full", "deterministic", "off", "disabled"]),
+        effectiveDelegate: z.object({
+            failure_policy: z.enum(["fallback", "fail"]).optional(),
+        }).optional(),
+    }).optional(),
+    context_builder_lifecycle: ContextBuilderLifecycleStateV1Schema.refine((lifecycle) => lifecycle.operation_kind === "workflow_preflight", "dashboard workflow preflight lifecycle must have operation_kind workflow_preflight").optional(),
+    workflow_context: z.object({
+        context_builder: z.object({
+            status: z.enum(["succeeded", "partial"]),
+            context_mode: z.enum(["full", "deterministic", "off", "disabled"]).optional(),
+        }),
+    }).optional(),
+    plan_review_state: z.object({
+        publication: DashboardPlanReviewPublicationSchema.optional(),
+    }).optional(),
+}).superRefine((state, ctx) => {
+    const stageIds = new Set();
+    let recordCount = state.stages.length;
+    for (const [stageIndex, stage] of state.stages.entries()) {
+        if (stageIds.has(stage.stageId)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `duplicate stageId ${stage.stageId}`,
+                path: ["stages", stageIndex, "stageId"],
+            });
+        }
+        stageIds.add(stage.stageId);
+        const callIds = new Set();
+        recordCount += stage.calls.length;
+        for (const [callIndex, call] of stage.calls.entries()) {
+            const callPath = ["stages", stageIndex, "calls", callIndex];
+            if (callIds.has(call.callId)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `duplicate callId ${call.callId} in stage ${stage.stageId}`,
+                    path: [...callPath, "callId"],
+                });
+            }
+            callIds.add(call.callId);
+            if (call.stageId !== stage.stageId) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "call.stageId must equal its enclosing stageId",
+                    path: [...callPath, "stageId"],
+                });
+            }
+            const inputPath = `${stage.stageId}.${call.callId}.input.json`;
+            if (call.materializedInputPath !== undefined && call.materializedInputPath !== inputPath) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "materializedInputPath does not match its producer call",
+                    path: [...callPath, "materializedInputPath"],
+                });
+            }
+            const hasInline = call.outputInline !== undefined;
+            const hasPath = call.outputPath !== undefined;
+            if (hasInline && hasPath) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "outputInline and outputPath are mutually exclusive",
+                    path: callPath,
+                });
+            }
+            if (call.state === "succeeded" && !hasInline && !hasPath) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "succeeded call must have one persisted output representation",
+                    path: callPath,
+                });
+            }
+            const outputPath = `${stage.stageId}.${call.callId}.output.txt`;
+            if (hasPath && call.outputPath !== outputPath) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "outputPath does not match its producer call",
+                    path: [...callPath, "outputPath"],
+                });
+            }
+            const artifactPath = `artifacts/${stage.stageId}/${String(callIndex + 1).padStart(2, "0")}-${call.callId}.json`;
+            if (call.artifactPath !== undefined && call.artifactPath !== artifactPath) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "artifactPath does not match its producer call ordinal",
+                    path: [...callPath, "artifactPath"],
+                });
+            }
+        }
+    }
+    if (recordCount > MAX_DASHBOARD_STAGE_CALL_RECORDS) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: COMPLEXITY_ISSUE,
+            path: ["stages"],
+        });
+    }
+});
+export function parseDashboardRunState(raw, expectedRunId) {
+    if (!RunIdSchema.safeParse(expectedRunId).success) {
+        return { ok: false, reason: "state_invalid", issues: ["invalid expected runId"] };
+    }
+    const parsed = DashboardRunStateSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((issue) => issue.message);
+        return {
+            ok: false,
+            reason: issues.includes(COMPLEXITY_ISSUE)
+                ? "too_complex_for_dashboard"
+                : "state_invalid",
+            issues,
+        };
+    }
+    if (parsed.data.runId !== expectedRunId) {
+        return { ok: false, reason: "state_invalid", issues: ["persisted runId does not match directory runId"] };
+    }
+    return { ok: true, state: parsed.data };
+}
+// --- Progress report wire schemas ---------------------------------------
+/**
+ * Re-export of the producer-side schema version literal so dashboard
+ * consumers can import it from the single wire-contract module.
+ */
+export { PROGRESS_REPORT_SCHEMA_VERSION } from "./progress-report-contract.js";
+/**
+ * Timestamp validator shared across the progress-report wire schemas. Mirrors
+ * the producer contract's strict RFC3339 validator (calendar + offset bounds +
+ * finite epoch) so the wire layer never admits a timestamp the producer or
+ * reader would reject. Kept local to progress reports; the dashboard-wide
+ * `TimestampSchema` above is intentionally unchanged.
+ */
+const ProgressReportTimestampSchema = StrictRfc3339TimestampSchema;
+/**
+ * LIST wire row for a progress report session, camelCase.
+ * Derived by the reader from the producer document's `session` section.
+ */
+export const ProgressReportRowSchema = z.object({
+    id: ProgressReportSessionIdSchema,
+    title: BoundedTitleSchema,
+    status: z.enum(["running", "paused", "blocked", "done", "failed"]),
+    projectFolder: ProjectFolderPathSchema,
+    startedAt: ProgressReportTimestampSchema,
+    updatedAt: ProgressReportTimestampSchema,
+    agentCount: NonnegativeSafeIntegerSchema,
+    taskCounts: z.object({
+        total: NonnegativeSafeIntegerSchema,
+        done: NonnegativeSafeIntegerSchema,
+    }).optional(),
+    publishedStatus: z.enum(["running", "paused", "blocked", "done", "failed"]).optional(),
+}).strict();
+/**
+ * DETAIL wire document for a progress report, camelCase. One camelCase
+ * wire field for each producer field across all 8 sections. The `session`
+ * section is required; the other 7 sections are optional.
+ */
+export const ProgressReportWireDocumentSchema = z.object({
+    schemaVersion: z.literal(PROGRESS_REPORT_SCHEMA_VERSION),
+    session: z.object({
+        id: ProgressReportSessionIdSchema,
+        title: BoundedTitleSchema,
+        goal: BoundedTitleSchema,
+        status: z.enum(["running", "paused", "blocked", "done", "failed"]),
+        startedAt: ProgressReportTimestampSchema,
+        updatedAt: ProgressReportTimestampSchema,
+        projectFolder: ProjectFolderPathSchema,
+    }).strict(),
+    agents: z.array(z.object({
+        name: BoundedIdSchema,
+        role: BoundedIdSchema,
+        status: z.enum(["working", "idle", "blocked", "done"]),
+        activity: BoundedMessageSchema,
+        updatedAt: ProgressReportTimestampSchema,
+    }).strict()).max(50).optional(),
+    tasks: z.array(z.object({
+        id: BoundedIdSchema,
+        title: BoundedTitleSchema,
+        status: z.enum(["pending", "active", "done", "blocked", "failed"]),
+        agent: BoundedIdSchema.optional(),
+        note: BoundedMessageSchema.optional(),
+    }).strict()).max(200).optional(),
+    log: z.array(z.object({
+        t: ProgressReportTimestampSchema,
+        agent: BoundedIdSchema,
+        kind: z.enum(["info", "success", "warn", "error"]),
+        msg: BoundedMessageSchema,
+    }).strict()).max(200).optional(),
+    files: z.array(z.object({
+        path: BoundedIdSchema,
+        change: z.enum(["added", "modified", "deleted"]),
+        adds: NonnegativeSafeIntegerSchema,
+        dels: NonnegativeSafeIntegerSchema,
+    }).strict()).max(500).optional(),
+    tests: z.object({
+        passed: NonnegativeSafeIntegerSchema,
+        failed: NonnegativeSafeIntegerSchema,
+        skipped: NonnegativeSafeIntegerSchema,
+        failing: z.array(BoundedMessageSchema).max(100),
+        lastRun: ProgressReportTimestampSchema,
+    }).strict().optional(),
+    blockers: z.array(z.object({
+        msg: BoundedMessageSchema,
+        raisedBy: BoundedIdSchema,
+        needsHuman: z.boolean(),
+    }).strict()).max(50).optional(),
+    decisions: z.array(z.object({
+        t: ProgressReportTimestampSchema,
+        by: BoundedIdSchema,
+        msg: BoundedMessageSchema,
+    }).strict()).max(100).optional(),
+}).strict();
+/**
+ * Cap on projected progress-report rows surfaced by the list endpoint. The
+ * reader never reads more than this many candidate directories per request.
+ */
+export const MAX_DASHBOARD_PROGRESS_REPORTS = 200;
+export const ProgressReportListResponseSchema = z.object({
+    progressReports: z.array(ProgressReportRowSchema).max(MAX_DASHBOARD_PROGRESS_REPORTS),
+    serverNow: ProgressReportTimestampSchema,
+    truncated: z.boolean(),
+}).strict();
+export const ProgressReportDetailResponseSchema = z.object({
+    progressReport: ProgressReportWireDocumentSchema,
+    serverNow: ProgressReportTimestampSchema,
+    omittedSections: z.array(z.string()).max(16),
+    publishedSessionStatus: z.enum(["running", "paused", "blocked", "done", "failed"]).optional(),
+}).strict();
+//# sourceMappingURL=contracts.js.map