feat(ql3): expose copilot diagnosis read model

packages/ql3-cluster-control/package.json

@@ -50,6 +50,11 @@
       "require": "./dist/copilot/failure-diagnosis/failureDiagnosisRoute.js",
       "default": "./dist/copilot/failure-diagnosis/failureDiagnosisRoute.js"
     },
+    "./copilot-read-routes": {
+      "types": "./dist/copilot/failure-diagnosis/failureDiagnosisReadRoutes.d.ts",
+      "require": "./dist/copilot/failure-diagnosis/failureDiagnosisReadRoutes.js",
+      "default": "./dist/copilot/failure-diagnosis/failureDiagnosisReadRoutes.js"
+    },
     "./http": {
       "types": "./dist/transport/httpSurface.d.ts",
       "require": "./dist/transport/httpSurface.js",

packages/ql3-cluster-control/src/application-runtime/aiProductionApplication.ts

@@ -31,6 +31,10 @@ import {
   type ClusterCopilotFailureDiagnosisProjection,
   type CreateProductionClusterCopilotFailureDiagnosisOptions,
 } from './copilot/failureDiagnosisComposition';
+import {
+  createProductionClusterCopilotFailureDiagnosisReadService,
+  type CreateProductionClusterCopilotFailureDiagnosisReadServiceOptions,
+} from './copilot/failureDiagnosisReadComposition';
 
 export interface EnabledProductionClusterAiConfig {
   readonly enabled: true;
@@ -54,6 +58,11 @@ export interface ProductionClusterAiControlApplicationOptions {
   readonly createCopilot?: (
     options: CreateProductionClusterCopilotFailureDiagnosisOptions,
   ) => Promise<Readonly<CopilotFailureDiagnosisApplicationService>>;
+  readonly createCopilotRead?: (
+    options: CreateProductionClusterCopilotFailureDiagnosisReadServiceOptions,
+  ) => ReturnType<
+    typeof createProductionClusterCopilotFailureDiagnosisReadService
+  >;
   readonly openAiDatabase?: ReturnType<typeof createPostgresDatabaseOpener>;
 }
 
@@ -241,7 +250,9 @@ export async function startProductionClusterAiControlApplication(
     Array.isArray(options) ||
     typeof options.audit !== 'function'
   ) {
-    throw new TypeError('Production Cluster AI application options are invalid');
+    throw new TypeError(
+      'Production Cluster AI application options are invalid',
+    );
   }
   const startControl =
     options.startControl ?? startProductionClusterControlApplication;
@@ -249,14 +260,20 @@ export async function startProductionClusterAiControlApplication(
     options.bootstrapPrompt ?? bootstrapPostgresPluginPackagePromptApplication;
   const createCopilot =
     options.createCopilot ?? createProductionClusterCopilotFailureDiagnosis;
+  const createCopilotRead =
+    options.createCopilotRead ??
+    createProductionClusterCopilotFailureDiagnosisReadService;
   if (
     typeof startControl !== 'function' ||
     typeof bootstrapPrompt !== 'function' ||
     typeof createCopilot !== 'function' ||
+    typeof createCopilotRead !== 'function' ||
     (options.openAiDatabase !== undefined &&
       typeof options.openAiDatabase !== 'function')
   ) {
-    throw new TypeError('Production Cluster AI application factories are invalid');
+    throw new TypeError(
+      'Production Cluster AI application factories are invalid',
+    );
   }
   const copilotArtifactStore = options.control.workerIngress?.artifactStore;
   if (
@@ -303,18 +320,27 @@ export async function startProductionClusterAiControlApplication(
   let copilotApplication:
     | Readonly<CopilotFailureDiagnosisApplicationService>
     | undefined;
+  let copilotReadApplication:
+    | ReturnType<
+        typeof createProductionClusterCopilotFailureDiagnosisReadService
+      >
+    | undefined;
   let copilotSuccessfulCompletion:
     | CopilotFailureDiagnosisModelCompletionCoordinator
     | undefined;
   let stopPromise: Promise<ClusterControlStopResult> | undefined;
   let promptOutputPolicy: ProjectPolicyEngine | undefined;
   const promptOutputReadAuthorizer = Object.freeze({
-    async authorize(request: Readonly<{
-      principal: Parameters<ProjectPolicyEngine['authorize']>[0];
-      projectId: string;
-    }>) {
+    async authorize(
+      request: Readonly<{
+        principal: Parameters<ProjectPolicyEngine['authorize']>[0];
+        projectId: string;
+      }>,
+    ) {
       if (!aiDatabase) {
-        throw new Error('Cluster AI database is unavailable during output read');
+        throw new Error(
+          'Cluster AI database is unavailable during output read',
+        );
       }
       promptOutputPolicy ??= new ProjectPolicyEngine(
         new PostgresProjectPolicyRepository(aiDatabase.pool),
@@ -361,7 +387,9 @@ export async function startProductionClusterAiControlApplication(
       },
       async loadProviders() {
         if (!aiDatabase) {
-          throw new Error('Cluster AI database is unavailable during provider load');
+          throw new Error(
+            'Cluster AI database is unavailable during provider load',
+          );
         }
         const credentialStorage = new PostgresModelProviderCredentialReader(
           aiDatabase.pool,
@@ -409,7 +437,11 @@ export async function startProductionClusterAiControlApplication(
       throw new Error('Cluster AI Prompt application did not activate');
     }
     if (preparedCopilot !== undefined) {
-      if (!copilotSuccessfulCompletion || !aiDatabase || !copilotArtifactStore) {
+      if (
+        !copilotSuccessfulCompletion ||
+        !aiDatabase ||
+        !copilotArtifactStore
+      ) {
         throw new Error('Cluster Copilot shared authorities did not activate');
       }
       copilotApplication = await createCopilot({
@@ -419,6 +451,10 @@ export async function startProductionClusterAiControlApplication(
         successfulCompletion: copilotSuccessfulCompletion,
         artifactStore: copilotArtifactStore,
       });
+      copilotReadApplication = createCopilotRead({
+        pool: aiDatabase.pool,
+        prepared: preparedCopilot,
+      });
     }
     controlApplication = await startControl({
       ...options.control,
@@ -445,11 +481,13 @@ export async function startProductionClusterAiControlApplication(
               capability: promptApplication.promptExecutionOutputs,
             },
           }),
-      ...(copilotApplication === undefined
+      ...(copilotApplication === undefined ||
+      copilotReadApplication === undefined
         ? {}
         : {
             copilotFailureDiagnosis: {
               capability: copilotApplication,
+              readCapability: copilotReadApplication,
             },
           }),
     });

packages/ql3-cluster-control/src/application-runtime/copilot/failureDiagnosisReadComposition.ts

@@ -0,0 +1,57 @@
+import { CopilotFailureDiagnosisReadService } from '@qinglong/ai/failure-diagnosis-read-model';
+import { PostgresCopilotFailureDiagnosisAdmissionRepository } from '@qinglong/ai/postgres-failure-diagnosis-admission-storage';
+import { PostgresCopilotFailureDiagnosisModelRepository } from '@qinglong/ai/postgres-failure-diagnosis-model-execution-storage';
+import { PostgresCopilotFailureDiagnosisPreModelTerminalizationRepository } from '@qinglong/ai/failure-diagnosis-pre-model-terminalization';
+import {
+  PostgresProjectPolicyRepository,
+  type QingLongPostgresPool,
+} from '@qinglong/cluster-postgres/runtime';
+import { ProjectPolicyEngine } from '@qinglong/runtime-core/project-policy';
+
+import type { PreparedClusterCopilotFailureDiagnosisProjection } from './failureDiagnosisComposition';
+
+export interface CreateProductionClusterCopilotFailureDiagnosisReadServiceOptions {
+  readonly pool: QingLongPostgresPool;
+  readonly prepared: PreparedClusterCopilotFailureDiagnosisProjection;
+}
+
+/**
+ * Reuses the execution Pool, durable repositories and projected output keys;
+ * creating this service owns no connection, listener or background lifecycle.
+ */
+export function createProductionClusterCopilotFailureDiagnosisReadService(
+  options: CreateProductionClusterCopilotFailureDiagnosisReadServiceOptions,
+): Readonly<CopilotFailureDiagnosisReadService> {
+  if (
+    !options ||
+    typeof options !== 'object' ||
+    Array.isArray(options) ||
+    typeof options.pool?.query !== 'function' ||
+    typeof options.pool?.connect !== 'function' ||
+    typeof options.prepared?.outputKeys?.resolve !== 'function'
+  ) {
+    throw new TypeError(
+      'Production Cluster Copilot failure diagnosis read dependencies are invalid',
+    );
+  }
+  const admissions = new PostgresCopilotFailureDiagnosisAdmissionRepository(
+    options.pool,
+  );
+  const models = new PostgresCopilotFailureDiagnosisModelRepository(
+    options.pool,
+  );
+  const terminalizations =
+    new PostgresCopilotFailureDiagnosisPreModelTerminalizationRepository(
+      options.pool,
+    );
+  return new CopilotFailureDiagnosisReadService({
+    admissions,
+    terminalizations,
+    finalizations: models,
+    models,
+    authorizer: new ProjectPolicyEngine(
+      new PostgresProjectPolicyRepository(options.pool),
+    ),
+    keys: options.prepared.outputKeys,
+  });
+}

packages/ql3-cluster-control/src/application-runtime/productionApplication.ts

@@ -65,6 +65,12 @@ import {
   createClusterControlCopilotFailureDiagnosisRoute,
   type ClusterCopilotFailureDiagnosisCapability,
 } from '../copilot/failure-diagnosis/failureDiagnosisRoute';
+import {
+  createClusterControlCopilotFailureDiagnosisInspectionRoute,
+  createClusterControlCopilotFailureDiagnosisOutputReadRoute,
+  type ClusterCopilotFailureDiagnosisInspectionCapability,
+  type ClusterCopilotFailureDiagnosisOutputReadCapability,
+} from '../copilot/failure-diagnosis/failureDiagnosisReadRoutes';
 
 export const PRODUCTION_CLUSTER_CONTROL_ROUTE_OPERATIONS = Object.freeze([
   'task.get',
@@ -92,8 +98,14 @@ export const PRODUCTION_CLUSTER_CONTROL_OPTIONAL_ROUTE_OPERATIONS =
     'prompt.execution.output.read',
     'prompt.output.read',
     'copilot.failure_diagnosis.execute',
+    'copilot.failure_diagnosis.read',
+    'copilot.failure_diagnosis.output.read',
   ] as const);
 
+export interface ClusterCopilotFailureDiagnosisReadCapability
+  extends ClusterCopilotFailureDiagnosisInspectionCapability,
+    ClusterCopilotFailureDiagnosisOutputReadCapability {}
+
 export interface ProductionClusterControlAssemblyOptions {
   readonly createEventId?: ClusterRunCancellationEventIdFactory;
   readonly promptCatalog?: Readonly<{
@@ -116,6 +128,7 @@ export interface ProductionClusterControlAssemblyOptions {
   }>;
   readonly copilotFailureDiagnosis?: Readonly<{
     readonly capability: ClusterCopilotFailureDiagnosisCapability;
+    readonly readCapability?: ClusterCopilotFailureDiagnosisReadCapability;
   }>;
   readonly workerIngress?: Readonly<{
     readonly config: EnabledClusterWorkerIngressConfig;
@@ -164,6 +177,7 @@ export interface ProductionClusterControlApplicationOptions
   }>;
   readonly copilotFailureDiagnosis?: Readonly<{
     readonly capability: ClusterCopilotFailureDiagnosisCapability;
+    readonly readCapability?: ClusterCopilotFailureDiagnosisReadCapability;
   }>;
   readonly workerIngress?: ProductionClusterWorkerIngressOptions;
 }
@@ -279,6 +293,16 @@ export function createProductionClusterControlApplicationStack(
             options.copilotFailureDiagnosis.capability,
           ),
         ]),
+    ...(options.copilotFailureDiagnosis?.readCapability === undefined
+      ? []
+      : [
+          createClusterControlCopilotFailureDiagnosisInspectionRoute(
+            options.copilotFailureDiagnosis.readCapability,
+          ),
+          createClusterControlCopilotFailureDiagnosisOutputReadRoute(
+            options.copilotFailureDiagnosis.readCapability,
+          ),
+        ]),
   ];
   const routes = createClusterControlRouteRegistry(routeDefinitions);
   const expectedRouteCount =
@@ -288,7 +312,8 @@ export function createProductionClusterControlApplicationStack(
     (options.promptExecutionInspection === undefined ? 0 : 1) +
     (options.promptOutputRead === undefined ? 0 : 1) +
     (options.promptExecutionOutputRead === undefined ? 0 : 1) +
-    (options.copilotFailureDiagnosis === undefined ? 0 : 1);
+    (options.copilotFailureDiagnosis === undefined ? 0 : 1) +
+    (options.copilotFailureDiagnosis?.readCapability === undefined ? 0 : 2);
   if (routes.size !== expectedRouteCount) {
     throw new Error('Production cluster-control route allowlist is incomplete');
   }

packages/ql3-cluster-control/src/copilot/failure-diagnosis/failureDiagnosisReadRoutes.ts

@@ -0,0 +1,436 @@
+// Cluster Copilot exposes separate low-sensitive status and protected output reads.
+import type { SecurityPrincipal } from '@qinglong/runtime-core/security';
+
+import type { ClusterControlAdmissionResponse } from '../../transport/httpSurface';
+import type {
+  ClusterControlAuthorizedOperationRequest,
+  ClusterControlRouteDefinition,
+  ClusterControlRouteParameters,
+} from '../../transport/routeRegistry';
+
+export const CLUSTER_COPILOT_FAILURE_DIAGNOSIS_INSPECTION_RESPONSE_SCHEMA =
+  'qinglong/cluster-copilot-failure-diagnosis-inspection-response@v1' as const;
+export const CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_READ_RESPONSE_SCHEMA =
+  'qinglong/cluster-copilot-failure-diagnosis-output-read-response@v1' as const;
+
+export const CLUSTER_CONTROL_COPILOT_FAILURE_DIAGNOSIS_INSPECTION_ROUTE =
+  Object.freeze({
+    method: 'GET' as const,
+    path: '/api/v3/projects/{projectId}/runs/{runId}/copilot/failure-diagnoses/{requestId}',
+    operationId: 'copilot.failure_diagnosis.read',
+    permission: 'run.read',
+    projectParameter: 'projectId',
+  });
+
+export const CLUSTER_CONTROL_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_READ_ROUTE =
+  Object.freeze({
+    method: 'GET' as const,
+    path: '/api/v3/projects/{projectId}/runs/{runId}/copilot/failure-diagnoses/{requestId}/output',
+    operationId: 'copilot.failure_diagnosis.output.read',
+    permission: 'artifact.read',
+    projectParameter: 'projectId',
+  });
+
+interface ClusterCopilotFailureDiagnosisReadCommand {
+  readonly principal: Readonly<SecurityPrincipal>;
+  readonly projectId: string;
+  readonly sourceRunId: string;
+  readonly requestId: string;
+}
+
+export interface ClusterCopilotFailureDiagnosisInspectionCapability {
+  inspect(
+    command: Readonly<ClusterCopilotFailureDiagnosisReadCommand>,
+  ): Promise<unknown>;
+}
+
+export interface ClusterCopilotFailureDiagnosisOutputReadCapability {
+  readOutput(
+    command: Readonly<ClusterCopilotFailureDiagnosisReadCommand>,
+  ): Promise<unknown>;
+}
+
+const IDENTITY = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,35}$/;
+const DIGEST = /^[0-9a-f]{64}$/;
+const FINISH_REASONS = new Set([
+  'stop',
+  'length',
+  'content_filter',
+  'tool_call',
+  'unknown',
+]);
+const OUTCOMES = new Set(['succeeded', 'failed', 'timed_out', 'cancelled']);
+const STAGES = new Set(['model', 'tool', 'log', 'deadline', 'cancellation']);
+const REASONS = new Set([
+  'tool_failed',
+  'tool_timed_out',
+  'log_not_found',
+  'log_pending',
+  'log_missing',
+  'log_retired',
+  'tool_budget_exhausted',
+  'deadline_exceeded',
+  'cancellation_requested',
+]);
+
+function response(
+  statusCode: number,
+  body: Readonly<Record<string, unknown>>,
+): ClusterControlAdmissionResponse {
+  return Object.freeze({ statusCode, body: Object.freeze(body) });
+}
+
+function exactRecord(
+  value: unknown,
+  required: readonly string[],
+  optional: readonly string[] = [],
+): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const actual = Object.keys(record).sort();
+  const expected = [
+    ...required,
+    ...optional.filter((key) => key in record),
+  ].sort();
+  return actual.length === expected.length &&
+    actual.every((key, index) => key === expected[index])
+    ? record
+    : null;
+}
+
+function nonNegativeInteger(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) >= 0;
+}
+
+function target(
+  authorized: ClusterControlAuthorizedOperationRequest,
+  parameters: ClusterControlRouteParameters,
+): Readonly<ClusterCopilotFailureDiagnosisReadCommand> | null {
+  if (
+    authorized.request.body !== null ||
+    authorized.projectId === null ||
+    typeof parameters.runId !== 'string' ||
+    !RUN_ID.test(parameters.runId) ||
+    typeof parameters.requestId !== 'string' ||
+    !IDENTITY.test(parameters.requestId)
+  ) {
+    return null;
+  }
+  return Object.freeze({
+    principal: authorized.principal,
+    projectId: authorized.projectId,
+    sourceRunId: parameters.runId,
+    requestId: parameters.requestId,
+  });
+}
+
+function exactTarget(
+  value: Record<string, unknown>,
+  expected: Readonly<ClusterCopilotFailureDiagnosisReadCommand>,
+): boolean {
+  return (
+    value.projectId === expected.projectId &&
+    value.sourceRunId === expected.sourceRunId &&
+    value.requestId === expected.requestId
+  );
+}
+
+function notFound(
+  value: unknown,
+  expected: Readonly<ClusterCopilotFailureDiagnosisReadCommand>,
+  schema: string,
+): boolean {
+  const candidate = exactRecord(value, [
+    'projectId',
+    'requestId',
+    'schema',
+    'sourceRunId',
+    'status',
+  ]);
+  return (
+    !!candidate &&
+    candidate.schema === schema &&
+    candidate.status === 'not_found' &&
+    exactTarget(candidate, expected)
+  );
+}
+
+function usageView(value: unknown): Readonly<Record<string, unknown>> | null {
+  const usage = exactRecord(value, [
+    'costMicros',
+    'currency',
+    'inputTokens',
+    'outputTokens',
+    'totalTokens',
+  ]);
+  if (
+    !usage ||
+    !nonNegativeInteger(usage.inputTokens) ||
+    !nonNegativeInteger(usage.outputTokens) ||
+    !nonNegativeInteger(usage.totalTokens) ||
+    usage.totalTokens !== usage.inputTokens + usage.outputTokens ||
+    !(
+      (usage.currency === null && usage.costMicros === null) ||
+      (usage.currency === 'USD' && nonNegativeInteger(usage.costMicros))
+    )
+  ) {
+    return null;
+  }
+  return Object.freeze({ ...usage });
+}
+
+function inspectionView(
+  value: unknown,
+  expected: Readonly<ClusterCopilotFailureDiagnosisReadCommand>,
+): Readonly<Record<string, unknown>> | null {
+  const candidate = exactRecord(value, [
+    'admittedAtMs',
+    'diagnosisRunId',
+    'finalizedAtMs',
+    'outcome',
+    'outputAvailable',
+    'projectId',
+    'reason',
+    'requestId',
+    'schema',
+    'sourceRunId',
+    'stage',
+    'status',
+    'usage',
+  ]);
+  if (
+    !candidate ||
+    candidate.schema !==
+      'qinglong/copilot-failure-diagnosis-inspection-result@v1' ||
+    !exactTarget(candidate, expected) ||
+    typeof candidate.diagnosisRunId !== 'string' ||
+    !RUN_ID.test(candidate.diagnosisRunId) ||
+    !nonNegativeInteger(candidate.admittedAtMs) ||
+    typeof candidate.outputAvailable !== 'boolean'
+  ) {
+    return null;
+  }
+  if (candidate.status === 'running') {
+    if (
+      candidate.outcome !== null ||
+      candidate.stage !== null ||
+      candidate.reason !== null ||
+      candidate.outputAvailable !== false ||
+      candidate.finalizedAtMs !== null ||
+      candidate.usage !== null
+    ) {
+      return null;
+    }
+  } else if (candidate.status === 'terminal') {
+    if (
+      typeof candidate.outcome !== 'string' ||
+      !OUTCOMES.has(candidate.outcome) ||
+      typeof candidate.stage !== 'string' ||
+      !STAGES.has(candidate.stage) ||
+      !nonNegativeInteger(candidate.finalizedAtMs) ||
+      candidate.finalizedAtMs < candidate.admittedAtMs ||
+      (candidate.stage === 'model') !== (candidate.reason === null) ||
+      (candidate.reason !== null &&
+        (typeof candidate.reason !== 'string' ||
+          !REASONS.has(candidate.reason))) ||
+      candidate.outputAvailable !==
+        (candidate.stage === 'model' && candidate.outcome === 'succeeded')
+    ) {
+      return null;
+    }
+    if (candidate.usage !== null && !usageView(candidate.usage)) return null;
+  } else {
+    return null;
+  }
+  return Object.freeze({
+    schema: CLUSTER_COPILOT_FAILURE_DIAGNOSIS_INSPECTION_RESPONSE_SCHEMA,
+    status: candidate.status,
+    projectId: expected.projectId,
+    sourceRunId: expected.sourceRunId,
+    requestId: expected.requestId,
+    diagnosisRunId: candidate.diagnosisRunId,
+    outcome: candidate.outcome,
+    stage: candidate.stage,
+    reason: candidate.reason,
+    outputAvailable: candidate.outputAvailable,
+    admittedAtMs: candidate.admittedAtMs,
+    finalizedAtMs: candidate.finalizedAtMs,
+    usage: candidate.usage === null ? null : usageView(candidate.usage),
+  });
+}
+
+function outputView(
+  value: unknown,
+  expected: Readonly<ClusterCopilotFailureDiagnosisReadCommand>,
+): Readonly<Record<string, unknown>> | null {
+  const candidate = exactRecord(value, [
+    'diagnosisRunId',
+    'projectId',
+    'reference',
+    'requestId',
+    'result',
+    'schema',
+    'sourceRunId',
+    'status',
+  ]);
+  const reference = candidate
+    ? exactRecord(candidate.reference, [
+        'artifactDigest',
+        'artifactId',
+        'contentDigest',
+        'outputBytes',
+        'sealedAtMs',
+      ])
+    : null;
+  const result = candidate
+    ? exactRecord(candidate.result, ['finishReason', 'text', 'usage'])
+    : null;
+  const usage = result
+    ? exactRecord(
+        result.usage,
+        ['inputTokens', 'outputTokens', 'totalTokens'],
+        ['costMicros'],
+      )
+    : null;
+  if (
+    !candidate ||
+    !reference ||
+    !result ||
+    !usage ||
+    candidate.schema !==
+      'qinglong/copilot-failure-diagnosis-output-read-result@v1' ||
+    candidate.status !== 'available' ||
+    !exactTarget(candidate, expected) ||
+    typeof candidate.diagnosisRunId !== 'string' ||
+    !RUN_ID.test(candidate.diagnosisRunId) ||
+    typeof reference.artifactId !== 'string' ||
+    !IDENTITY.test(reference.artifactId) ||
+    typeof reference.artifactDigest !== 'string' ||
+    !DIGEST.test(reference.artifactDigest) ||
+    typeof reference.contentDigest !== 'string' ||
+    !DIGEST.test(reference.contentDigest) ||
+    !nonNegativeInteger(reference.outputBytes) ||
+    reference.outputBytes > 1024 * 1024 ||
+    !nonNegativeInteger(reference.sealedAtMs) ||
+    typeof result.text !== 'string' ||
+    Buffer.byteLength(result.text, 'utf8') !== reference.outputBytes ||
+    typeof result.finishReason !== 'string' ||
+    !FINISH_REASONS.has(result.finishReason) ||
+    !nonNegativeInteger(usage.inputTokens) ||
+    !nonNegativeInteger(usage.outputTokens) ||
+    !nonNegativeInteger(usage.totalTokens) ||
+    usage.totalTokens !== usage.inputTokens + usage.outputTokens ||
+    (usage.costMicros !== undefined && !nonNegativeInteger(usage.costMicros))
+  ) {
+    return null;
+  }
+  return Object.freeze({
+    schema: CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_READ_RESPONSE_SCHEMA,
+    status: 'available',
+    projectId: expected.projectId,
+    sourceRunId: expected.sourceRunId,
+    requestId: expected.requestId,
+    diagnosisRunId: candidate.diagnosisRunId,
+    reference: Object.freeze({ ...reference }),
+    result: Object.freeze({
+      text: result.text,
+      finishReason: result.finishReason,
+      usage: Object.freeze({ ...usage }),
+    }),
+  });
+}
+
+export function createClusterControlCopilotFailureDiagnosisInspectionRoute(
+  capability: ClusterCopilotFailureDiagnosisInspectionCapability,
+): Readonly<ClusterControlRouteDefinition> {
+  if (!capability || typeof capability.inspect !== 'function') {
+    throw new TypeError(
+      'Cluster-control Copilot diagnosis inspection capability is invalid',
+    );
+  }
+  return Object.freeze({
+    ...CLUSTER_CONTROL_COPILOT_FAILURE_DIAGNOSIS_INSPECTION_ROUTE,
+    async handle(
+      authorized: ClusterControlAuthorizedOperationRequest,
+      parameters: ClusterControlRouteParameters,
+    ) {
+      const command = target(authorized, parameters);
+      if (!command) {
+        return response(400, {
+          code: 'invalid_copilot_failure_diagnosis_read_request',
+        });
+      }
+      try {
+        const result = await capability.inspect(command);
+        if (
+          notFound(
+            result,
+            command,
+            'qinglong/copilot-failure-diagnosis-inspection-result@v1',
+          )
+        ) {
+          return response(404, { code: 'copilot_failure_diagnosis_not_found' });
+        }
+        const view = inspectionView(result, command);
+        return view
+          ? response(200, view)
+          : response(503, {
+              code: 'copilot_failure_diagnosis_read_unavailable',
+            });
+      } catch {
+        return response(503, {
+          code: 'copilot_failure_diagnosis_read_unavailable',
+        });
+      }
+    },
+  });
+}
+
+export function createClusterControlCopilotFailureDiagnosisOutputReadRoute(
+  capability: ClusterCopilotFailureDiagnosisOutputReadCapability,
+): Readonly<ClusterControlRouteDefinition> {
+  if (!capability || typeof capability.readOutput !== 'function') {
+    throw new TypeError(
+      'Cluster-control Copilot diagnosis output read capability is invalid',
+    );
+  }
+  return Object.freeze({
+    ...CLUSTER_CONTROL_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_READ_ROUTE,
+    async handle(
+      authorized: ClusterControlAuthorizedOperationRequest,
+      parameters: ClusterControlRouteParameters,
+    ) {
+      const command = target(authorized, parameters);
+      if (!command) {
+        return response(400, {
+          code: 'invalid_copilot_failure_diagnosis_output_read_request',
+        });
+      }
+      try {
+        const result = await capability.readOutput(command);
+        if (
+          notFound(
+            result,
+            command,
+            'qinglong/copilot-failure-diagnosis-output-read-result@v1',
+          )
+        ) {
+          return response(404, {
+            code: 'copilot_failure_diagnosis_output_not_found',
+          });
+        }
+        const view = outputView(result, command);
+        return view
+          ? response(200, view)
+          : response(503, {
+              code: 'copilot_failure_diagnosis_output_read_unavailable',
+            });
+      } catch {
+        return response(503, {
+          code: 'copilot_failure_diagnosis_output_read_unavailable',
+        });
+      }
+    },
+  });
+}

packages/ql3-cluster-control/test/aiProductionApplication.test.cjs

@@ -29,7 +29,8 @@ const {
 function enabledEnvironment(overrides = {}) {
   return {
     QL3_CLUSTER_AI_ENABLED: 'true',
-    QL3_CLUSTER_AI_PROVIDER_AUTHORITY_FILE: '/var/run/qinglong/ai/providers.json',
+    QL3_CLUSTER_AI_PROVIDER_AUTHORITY_FILE:
+      '/var/run/qinglong/ai/providers.json',
     QL3_CLUSTER_AI_SECRET_ROOT: '/var/run/qinglong/ai/provider-secrets',
     ...overrides,
   };
@@ -120,26 +121,30 @@ async function projectedFile(root, name, bytes) {
 test('Copilot composition is explicit, shares the Prompt gateway and injects one route capability', async () => {
   const secretRoot = await mkdtemp(join(tmpdir(), 'ql3-cluster-ai-secret-'));
   const configRoot = await mkdtemp(join(tmpdir(), 'ql3-copilot-config-'));
-  const invocationRoot = await mkdtemp(join(tmpdir(), 'ql3-copilot-invocation-'));
+  const invocationRoot = await mkdtemp(
+    join(tmpdir(), 'ql3-copilot-invocation-'),
+  );
   const resultRoot = await mkdtemp(join(tmpdir(), 'ql3-copilot-result-'));
   const outputRoot = await mkdtemp(join(tmpdir(), 'ql3-copilot-output-'));
   const key = Buffer.alloc(32, 0x55).toString('base64url');
-  const config = Buffer.from(`${JSON.stringify({
-    schema: 'qinglong/cluster-copilot-failure-diagnosis-config@v1',
-    provider: 'provider-primary',
-    model: 'model-diagnosis',
-    modelBoundary: 'external',
-    responseLanguage: 'zh-CN',
-    maxOutputTokens: 512,
-    executionTimeoutMs: 60_000,
-    egressPolicy: {
-      schema: 'qinglong/copilot-model-egress-policy@v1',
-      revision: 'cluster-copilot-v1',
-      potentiallySensitiveDataBoundaries: ['external'],
-      maxInputBytes: 64 * 1024,
-      maxOutputTokens: 1024,
-    },
-  })}\n`);
+  const config = Buffer.from(
+    `${JSON.stringify({
+      schema: 'qinglong/cluster-copilot-failure-diagnosis-config@v1',
+      provider: 'provider-primary',
+      model: 'model-diagnosis',
+      modelBoundary: 'external',
+      responseLanguage: 'zh-CN',
+      maxOutputTokens: 512,
+      executionTimeoutMs: 60_000,
+      egressPolicy: {
+        schema: 'qinglong/copilot-model-egress-policy@v1',
+        revision: 'cluster-copilot-v1',
+        potentiallySensitiveDataBoundaries: ['external'],
+        maxInputBytes: 64 * 1024,
+        maxOutputTokens: 1024,
+      },
+    })}\n`,
+  );
   const invocation = canonicalClusterToolInvocationKeyringManifest({
     schema: CLUSTER_TOOL_INVOCATION_KEYRING_MANIFEST_SCHEMA,
     activeKeyId: 'invocation-key-1',
@@ -163,8 +168,10 @@ test('Copilot composition is explicit, shares the Prompt gateway and injects one
   const fakePool = { query() {}, connect() {} };
   const artifactStore = { put() {}, inspect() {}, readLogRange() {} };
   const copilot = Object.freeze({ execute() {} });
+  const copilotRead = Object.freeze({ inspect() {}, readOutput() {} });
   let registeredSink;
   let created;
+  let createdRead;
   let controlOptions;
   try {
     await Promise.all([
@@ -205,22 +212,41 @@ test('Copilot composition is explicit, shares the Prompt gateway and injects one
           async recordWithAtomicSuccess() {},
         });
         return {
-          status: 'active', profile: 'cluster', readiness: {}, capability: gateway,
-          prompts: {}, promptCatalog: {}, promptExecutions: {},
-          promptExecutionInspections: {}, async stop() { return 'stopped'; },
+          status: 'active',
+          profile: 'cluster',
+          readiness: {},
+          capability: gateway,
+          prompts: {},
+          promptCatalog: {},
+          promptExecutions: {},
+          promptExecutionInspections: {},
+          async stop() {
+            return 'stopped';
+          },
         };
       },
       async createCopilot(options) {
         created = options;
         return copilot;
       },
+      createCopilotRead(options) {
+        createdRead = options;
+        return copilotRead;
+      },
       async startControl(options) {
         controlOptions = options;
         return {
-          status: 'active', address: { host: '127.0.0.1', port: 5800 },
-          evidence: {}, recovery: { safe: true, remaining: 0, failed: 0 },
-          unavailable: new Promise(() => {}), availabilityStatus() { return 'ready'; },
-          async stop() { return 'stopped'; },
+          status: 'active',
+          address: { host: '127.0.0.1', port: 5800 },
+          evidence: {},
+          recovery: { safe: true, remaining: 0, failed: 0 },
+          unavailable: new Promise(() => {}),
+          availabilityStatus() {
+            return 'ready';
+          },
+          async stop() {
+            return 'stopped';
+          },
         };
       },
     });
@@ -229,10 +255,19 @@ test('Copilot composition is explicit, shares the Prompt gateway and injects one
     assert.equal(created.gateway, gateway);
     assert.equal(created.successfulCompletion, registeredSink);
     assert.equal(created.artifactStore, artifactStore);
+    assert.equal(createdRead.pool, fakePool);
+    assert.equal(typeof createdRead.prepared.outputKeys.resolve, 'function');
     assert.equal(controlOptions.copilotFailureDiagnosis.capability, copilot);
+    assert.equal(
+      controlOptions.copilotFailureDiagnosis.readCapability,
+      copilotRead,
+    );
     assert.equal(await application.stop(), 'stopped');
   } finally {
-    config.fill(0); invocation.fill(0); result.fill(0); output.fill(0);
+    config.fill(0);
+    invocation.fill(0);
+    result.fill(0);
+    output.fill(0);
     await Promise.all([
       rm(secretRoot, { recursive: true, force: true }),
       rm(configRoot, { recursive: true, force: true }),
@@ -362,7 +397,9 @@ test('output-enabled AI composition wires exact and request-keyed protected read
           promptExecutionInspections: { inspectAuthorized() {} },
           promptOutputs,
           promptExecutionOutputs,
-          async stop() { return 'stopped'; },
+          async stop() {
+            return 'stopped';
+          },
         };
       },
       async startControl(options) {
@@ -373,8 +410,12 @@ test('output-enabled AI composition wires exact and request-keyed protected read
           evidence: {},
           recovery: { safe: true, remaining: 0, failed: 0 },
           unavailable: new Promise(() => {}),
-          availabilityStatus() { return 'ready'; },
-          async stop() { return 'stopped'; },
+          availabilityStatus() {
+            return 'ready';
+          },
+          async stop() {
+            return 'stopped';
+          },
         };
       },
     });

packages/ql3-cluster-control/test/copilotFailureDiagnosisReadRoutes.test.cjs

@@ -0,0 +1,288 @@
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+
+const {
+  CLUSTER_COPILOT_FAILURE_DIAGNOSIS_INSPECTION_RESPONSE_SCHEMA,
+  CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_READ_RESPONSE_SCHEMA,
+  CLUSTER_CONTROL_COPILOT_FAILURE_DIAGNOSIS_INSPECTION_ROUTE,
+  CLUSTER_CONTROL_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_READ_ROUTE,
+  createClusterControlCopilotFailureDiagnosisInspectionRoute,
+  createClusterControlCopilotFailureDiagnosisOutputReadRoute,
+} = require('@qinglong/cluster-control/copilot-read-routes');
+
+function authorized(path, body = null) {
+  return {
+    request: {
+      requestId: 'transport-request-1',
+      method: 'GET',
+      path,
+      query: {},
+      headers: {},
+      signal: new AbortController().signal,
+      body,
+    },
+    principal: {
+      subject: { type: 'api_app', id: 'app-1' },
+      authenticationId: 'credential-1',
+      authenticatedAtMs: 1,
+      expiresAtMs: 10_000,
+      assurance: 'service',
+    },
+    operationId: 'copilot.failure_diagnosis.read',
+    permission: 'run.read',
+    projectId: 'project-1',
+    policyFence: { projectVersion: 3, bindingVersion: 7 },
+  };
+}
+
+const parameters = {
+  projectId: 'project-1',
+  runId: 'source-run-1',
+  requestId: 'diagnosis-request-1',
+};
+
+function running(overrides = {}) {
+  return {
+    schema: 'qinglong/copilot-failure-diagnosis-inspection-result@v1',
+    status: 'running',
+    projectId: 'project-1',
+    sourceRunId: 'source-run-1',
+    requestId: 'diagnosis-request-1',
+    diagnosisRunId: 'diagnosis-run-1',
+    outcome: null,
+    stage: null,
+    reason: null,
+    outputAvailable: false,
+    admittedAtMs: 100,
+    finalizedAtMs: null,
+    usage: null,
+    ...overrides,
+  };
+}
+
+test('defines separate run.read inspection and artifact.read output routes', () => {
+  assert.deepEqual(CLUSTER_CONTROL_COPILOT_FAILURE_DIAGNOSIS_INSPECTION_ROUTE, {
+    method: 'GET',
+    path: '/api/v3/projects/{projectId}/runs/{runId}/copilot/failure-diagnoses/{requestId}',
+    operationId: 'copilot.failure_diagnosis.read',
+    permission: 'run.read',
+    projectParameter: 'projectId',
+  });
+  assert.deepEqual(
+    CLUSTER_CONTROL_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_READ_ROUTE,
+    {
+      method: 'GET',
+      path: '/api/v3/projects/{projectId}/runs/{runId}/copilot/failure-diagnoses/{requestId}/output',
+      operationId: 'copilot.failure_diagnosis.output.read',
+      permission: 'artifact.read',
+      projectParameter: 'projectId',
+    },
+  );
+});
+
+test('projects a request-keyed running inspection and passes only trusted target facts', async () => {
+  let command;
+  const route = createClusterControlCopilotFailureDiagnosisInspectionRoute({
+    async inspect(value) {
+      command = value;
+      return running();
+    },
+  });
+  const request = authorized(
+    '/api/v3/projects/project-1/runs/source-run-1/copilot/failure-diagnoses/diagnosis-request-1',
+  );
+  const result = await route.handle(request, parameters);
+  assert.deepEqual(command, {
+    principal: request.principal,
+    projectId: 'project-1',
+    sourceRunId: 'source-run-1',
+    requestId: 'diagnosis-request-1',
+  });
+  assert.deepEqual(result, {
+    statusCode: 200,
+    body: {
+      schema: CLUSTER_COPILOT_FAILURE_DIAGNOSIS_INSPECTION_RESPONSE_SCHEMA,
+      status: 'running',
+      projectId: 'project-1',
+      sourceRunId: 'source-run-1',
+      requestId: 'diagnosis-request-1',
+      diagnosisRunId: 'diagnosis-run-1',
+      outcome: null,
+      stage: null,
+      reason: null,
+      outputAvailable: false,
+      admittedAtMs: 100,
+      finalizedAtMs: null,
+      usage: null,
+    },
+  });
+});
+
+test('projects terminal cancellation and settled Model usage without private fields', async () => {
+  for (const [value, expected] of [
+    [
+      running({
+        status: 'terminal',
+        outcome: 'cancelled',
+        stage: 'cancellation',
+        reason: 'cancellation_requested',
+        finalizedAtMs: 200,
+        usage: {
+          inputTokens: 0,
+          outputTokens: 0,
+          totalTokens: 0,
+          currency: 'USD',
+          costMicros: 0,
+        },
+      }),
+      'cancellation',
+    ],
+    [
+      running({
+        status: 'terminal',
+        outcome: 'succeeded',
+        stage: 'model',
+        reason: null,
+        outputAvailable: true,
+        finalizedAtMs: 200,
+        usage: {
+          inputTokens: 11,
+          outputTokens: 7,
+          totalTokens: 18,
+          currency: 'USD',
+          costMicros: 29,
+        },
+      }),
+      'model',
+    ],
+  ]) {
+    const route = createClusterControlCopilotFailureDiagnosisInspectionRoute({
+      async inspect() {
+        return value;
+      },
+    });
+    const result = await route.handle(authorized('/read'), parameters);
+    assert.equal(result.statusCode, 200);
+    assert.equal(result.body.stage, expected);
+    assert.equal(JSON.stringify(result).includes('provider'), false);
+    assert.equal(JSON.stringify(result).includes('modelId'), false);
+  }
+});
+
+test('masks absent reads and fails closed on invalid input or widened results', async () => {
+  let calls = 0;
+  const route = createClusterControlCopilotFailureDiagnosisInspectionRoute({
+    async inspect() {
+      calls += 1;
+      return {
+        schema: 'qinglong/copilot-failure-diagnosis-inspection-result@v1',
+        status: 'not_found',
+        projectId: 'project-1',
+        sourceRunId: 'source-run-1',
+        requestId: 'diagnosis-request-1',
+      };
+    },
+  });
+  assert.equal(
+    (await route.handle(authorized('/read'), parameters)).statusCode,
+    404,
+  );
+  assert.equal(
+    (await route.handle(authorized('/read', {}), parameters)).statusCode,
+    400,
+  );
+  assert.equal(
+    (
+      await route.handle(authorized('/read'), {
+        ...parameters,
+        requestId: '../private',
+      })
+    ).statusCode,
+    400,
+  );
+  assert.equal(calls, 1);
+
+  const widened = createClusterControlCopilotFailureDiagnosisInspectionRoute({
+    async inspect() {
+      return running({ privateModel: 'must not cross' });
+    },
+  });
+  assert.equal(
+    (await widened.handle(authorized('/read'), parameters)).statusCode,
+    503,
+  );
+});
+
+test('returns only decrypted diagnosis content and low-sensitive Artifact metadata', async () => {
+  let command;
+  const route = createClusterControlCopilotFailureDiagnosisOutputReadRoute({
+    async readOutput(value) {
+      command = value;
+      return {
+        schema: 'qinglong/copilot-failure-diagnosis-output-read-result@v1',
+        status: 'available',
+        projectId: value.projectId,
+        sourceRunId: value.sourceRunId,
+        requestId: value.requestId,
+        diagnosisRunId: 'diagnosis-run-1',
+        reference: {
+          artifactId: 'cdo:artifact-1',
+          artifactDigest: 'a'.repeat(64),
+          contentDigest: 'b'.repeat(64),
+          outputBytes: Buffer.byteLength('diagnosis'),
+          sealedAtMs: 200,
+        },
+        result: {
+          text: 'diagnosis',
+          finishReason: 'stop',
+          usage: { inputTokens: 3, outputTokens: 2, totalTokens: 5 },
+        },
+      };
+    },
+  });
+  const request = authorized('/output');
+  request.operationId = 'copilot.failure_diagnosis.output.read';
+  request.permission = 'artifact.read';
+  const result = await route.handle(request, parameters);
+  assert.equal(result.statusCode, 200);
+  assert.equal(
+    result.body.schema,
+    CLUSTER_COPILOT_FAILURE_DIAGNOSIS_OUTPUT_READ_RESPONSE_SCHEMA,
+  );
+  assert.equal(result.body.result.text, 'diagnosis');
+  assert.equal('provider' in result.body.result, false);
+  assert.equal('model' in result.body.result, false);
+  assert.equal(command.principal, request.principal);
+});
+
+test('masks absent output and maps dependency/cipher failures to one 503 code', async () => {
+  const absent = createClusterControlCopilotFailureDiagnosisOutputReadRoute({
+    async readOutput(value) {
+      return {
+        schema: 'qinglong/copilot-failure-diagnosis-output-read-result@v1',
+        status: 'not_found',
+        projectId: value.projectId,
+        sourceRunId: value.sourceRunId,
+        requestId: value.requestId,
+      };
+    },
+  });
+  assert.equal(
+    (await absent.handle(authorized('/output'), parameters)).statusCode,
+    404,
+  );
+
+  const unavailable =
+    createClusterControlCopilotFailureDiagnosisOutputReadRoute({
+      async readOutput() {
+        throw new Error('private key failure');
+      },
+    });
+  assert.deepEqual(
+    await unavailable.handle(authorized('/output'), parameters),
+    {
+      statusCode: 503,
+      body: { code: 'copilot_failure_diagnosis_output_read_unavailable' },
+    },
+  );
+});

packages/ql3-cluster-control/test/productionApplication.test.cjs

@@ -730,6 +730,8 @@ test('optionally exposes Prompt execution behind shared admission and policy', a
     'prompt.execution.output.read',
     'prompt.output.read',
     'copilot.failure_diagnosis.execute',
+    'copilot.failure_diagnosis.read',
+    'copilot.failure_diagnosis.output.read',
   ]);
   const response = await invoke(
     stack,
@@ -783,9 +785,30 @@ test('optionally exposes Copilot diagnosis behind shared authentication, Policy
         terminalizationRequired: false,
       };
     },
+    async inspect(value) {
+      return {
+        schema: 'qinglong/copilot-failure-diagnosis-inspection-result@v1',
+        status: 'not_found',
+        projectId: value.projectId,
+        sourceRunId: value.sourceRunId,
+        requestId: value.requestId,
+      };
+    },
+    async readOutput(value) {
+      return {
+        schema: 'qinglong/copilot-failure-diagnosis-output-read-result@v1',
+        status: 'not_found',
+        projectId: value.projectId,
+        sourceRunId: value.sourceRunId,
+        requestId: value.requestId,
+      };
+    },
   };
   const stack = createProductionClusterControlApplicationStack(input, {
-    copilotFailureDiagnosis: { capability },
+    copilotFailureDiagnosis: {
+      capability,
+      readCapability: capability,
+    },
   });
   const result = await invoke(
     stack,
@@ -811,6 +834,29 @@ test('optionally exposes Copilot diagnosis behind shared authentication, Policy
     'audit:copilot.failure_diagnosis.execute:allowed',
     'diagnose:run-1',
   ]);
+
+  const inspection = await invoke(
+    stack,
+    metadata(
+      '/api/v3/projects/project-1/runs/run-1/copilot/failure-diagnoses/diagnosis-request-1',
+    ),
+  );
+  const output = await invoke(
+    stack,
+    metadata(
+      '/api/v3/projects/project-1/runs/run-1/copilot/failure-diagnoses/diagnosis-request-1/output',
+    ),
+  );
+  assert.equal(inspection.statusCode, 404);
+  assert.equal(output.statusCode, 404);
+  assert.equal(
+    events.includes('audit:copilot.failure_diagnosis.read:allowed'),
+    true,
+  );
+  assert.equal(
+    events.includes('audit:copilot.failure_diagnosis.output.read:allowed'),
+    true,
+  );
 });
 
 test('keeps the Copilot route absent by default and never invokes it after Policy denial', async () => {
@@ -830,6 +876,15 @@ test('keeps the Copilot route absent by default and never invokes it after Polic
     defaultStack.admission.prepare(request),
     (error) => error?.statusCode === 404 && error?.code === 'route_not_found',
   );
+  for (const path of [
+    '/api/v3/projects/project-1/runs/run-1/copilot/failure-diagnoses/diagnosis-request-1',
+    '/api/v3/projects/project-1/runs/run-1/copilot/failure-diagnoses/diagnosis-request-1/output',
+  ]) {
+    await assert.rejects(
+      defaultStack.admission.prepare(metadata(path)),
+      (error) => error?.statusCode === 404 && error?.code === 'route_not_found',
+    );
+  }
 
   let calls = 0;
   const deniedFixture = fixture({