voratiq 0.1.0-beta.21 → 0.1.0-beta.22

package/dist/commands/run/validation.js

@@ -1,86 +1,49 @@
-import { readFile } from "node:fs/promises";
-import { verifyAgentProviders } from "../../agents/runtime/auth.js";
-import { loadAgentCatalogDiagnostics } from "../../configs/agents/loader.js";
-import { EnvironmentConfigParseError, MissingEnvironmentConfigError, } from "../../configs/environment/errors.js";
-import { DEFAULT_ENVIRONMENT_FILE_DISPLAY, loadEnvironmentConfig, } from "../../configs/environment/loader.js";
-import { loadRepoSettings } from "../../configs/settings/loader.js";
 import { NoAgentsEnabledError, RunPreflightError, } from "../../domain/run/competition/errors.js";
 import { RunOptionValidationError } from "../../domain/run/model/errors.js";
-import { toErrorMessage } from "../../utils/errors.js";
+import { loadOperatorEnvironment } from "../../preflight/environment.js";
+import { prepareConfiguredOperatorReadiness } from "../../preflight/operator.js";
 import { getHeadRevision } from "../../utils/git.js";
-import { WorkspaceMissingEntryError } from "../../workspace/errors.js";
 import { resolveEffectiveMaxParallel } from "../shared/max-parallel.js";
+import { loadRunSpecInput } from "./spec-provenance.js";
 /**
  * Validate command parameters, load spec, and prepare execution prerequisites.
  */
 export async function validateAndPrepare(input) {
-    const { root, specAbsolutePath, resolvedAgentIds, maxParallel: requestedMaxParallel, } = input;
+    const { root, specAbsolutePath, specDisplayPath, specsFilePath, resolvedAgentIds, maxParallel: requestedMaxParallel, } = input;
     if (requestedMaxParallel !== undefined &&
         (!Number.isInteger(requestedMaxParallel) || requestedMaxParallel <= 0)) {
         throw new RunOptionValidationError("maxParallel", "must be a positive integer");
     }
-    const specContent = await readFile(specAbsolutePath, "utf8");
+    const { specContent, specTarget } = await loadRunSpecInput({
+        root,
+        specAbsolutePath,
+        specDisplayPath: specDisplayPath ?? specAbsolutePath,
+        specsFilePath,
+    });
     const baseRevisionSha = await getHeadRevision(root);
-    const preflightIssues = [];
-    let agents;
-    if (resolvedAgentIds) {
-        if (resolvedAgentIds.length === 0) {
-            throw new NoAgentsEnabledError();
-        }
-        const selectedAgentIds = new Set(resolvedAgentIds);
-        const agentDiagnostics = loadAgentCatalogDiagnostics({ root });
-        preflightIssues.push(...agentDiagnostics.issues.filter((issue) => selectedAgentIds.has(issue.agentId)));
-        const catalogById = new Map(agentDiagnostics.catalog.map((agent) => [agent.id, agent]));
-        agents = resolvedAgentIds.flatMap((agentId) => {
-            const agent = catalogById.get(agentId);
-            return agent ? [agent] : [];
-        });
-    }
-    else {
-        const agentDiagnostics = loadAgentCatalogDiagnostics({ root });
-        const enabledAgents = agentDiagnostics.enabledAgents;
-        if (enabledAgents.length === 0) {
-            throw new NoAgentsEnabledError();
-        }
-        preflightIssues.push(...agentDiagnostics.issues);
-        agents = agentDiagnostics.catalog;
-    }
-    try {
-        loadRepoSettings({ root });
-    }
-    catch (error) {
-        preflightIssues.push({
-            agentId: "settings",
-            message: toErrorMessage(error),
-        });
+    const preflight = await prepareConfiguredOperatorReadiness({
+        root,
+        resolvedAgentIds,
+        includeEnvironment: false,
+    });
+    if (preflight.noAgentsEnabled) {
+        throw new NoAgentsEnabledError();
     }
-    const preProviderIssueCount = preflightIssues.length;
-    const providerIssues = await verifyAgentProviders(agents.map((agent) => ({
-        id: agent.id,
-        provider: agent.provider,
-    })));
-    preflightIssues.push(...providerIssues);
-    if (preflightIssues.length > 0) {
-        throw new RunPreflightError(preflightIssues, preProviderIssueCount === 0 ? [] : undefined);
+    if (preflight.issues.length > 0) {
+        throw new RunPreflightError(preflight.issues, preflight.preProviderIssueCount);
     }
-    const environment = (() => {
-        try {
-            return loadEnvironmentConfig({ root });
-        }
-        catch (error) {
-            if (error instanceof MissingEnvironmentConfigError ||
-                error instanceof EnvironmentConfigParseError) {
-                throw new WorkspaceMissingEntryError(DEFAULT_ENVIRONMENT_FILE_DISPLAY);
-            }
-            throw error;
-        }
-    })();
+    const agents = preflight.agents;
+    const environment = loadOperatorEnvironment({
+        root,
+        errorMode: "workspace-missing",
+    });
     const effectiveMaxParallel = resolveEffectiveMaxParallel({
         competitorCount: agents.length,
         requestedMaxParallel,
     });
     return {
         specContent,
+        specTarget,
         baseRevisionSha,
         agents,
         effectiveMaxParallel,

package/dist/commands/spec/command.js

@@ -1,20 +1,21 @@
 import { executeCompetitionWithAdapter } from "../../competition/command-adapter.js";
 import { AgentNotFoundError } from "../../configs/agents/errors.js";
-import { loadEnvironmentConfig } from "../../configs/environment/loader.js";
 import { buildLifecycleStartFields, buildOperationLifecycleCompleteFields, } from "../../domain/shared/lifecycle.js";
 import { createSpecCompetitionAdapter, } from "../../domain/spec/competition/adapter.js";
 import { deriveSpecStatusFromAgents, } from "../../domain/spec/model/types.js";
 import { appendSpecRecord, finalizeSpecRecord, flushSpecRecordBuffer, rewriteSpecRecord, } from "../../domain/spec/persistence/adapter.js";
 import { buildPersistedExtraContextFields } from "../../extra-context/contract.js";
+import { loadOperatorEnvironment } from "../../preflight/environment.js";
+import { prepareConfiguredOperatorReadiness } from "../../preflight/operator.js";
 import { toErrorMessage } from "../../utils/errors.js";
 import { getHeadRevision } from "../../utils/git.js";
 import { resolveEffectiveMaxParallel } from "../shared/max-parallel.js";
 import { resolveStageCompetitors } from "../shared/resolve-stage-competitors.js";
 import { generateSessionId } from "../shared/session-id.js";
-import { SpecAgentNotFoundError, SpecGenerationFailedError } from "./errors.js";
+import { SpecAgentNotFoundError, SpecGenerationFailedError, SpecPreflightError, } from "./errors.js";
 export async function executeSpecCommand(input) {
     const { root, specsFilePath, description, agentIds: cliAgentIds, profileName, maxParallel: requestedMaxParallel, title: providedTitle, extraContextFiles = [], onStatus, renderer, } = input;
-    let competitors;
+    let resolvedAgentIds;
     try {
         const normalizedCliIds = cliAgentIds && cliAgentIds.length > 0 ? [...cliAgentIds] : undefined;
         const resolution = resolveStageCompetitors({
@@ -22,9 +23,10 @@ export async function executeSpecCommand(input) {
             stageId: "spec",
             cliAgentIds: normalizedCliIds,
             profileName,
+            includeDefinitions: false,
         });
-        competitors = resolution.competitors;
-        if (competitors.length === 0) {
+        resolvedAgentIds = resolution.agentIds;
+        if (resolvedAgentIds.length === 0) {
             throw new SpecGenerationFailedError(["Spec agent resolution failed."]);
         }
     }
@@ -34,7 +36,16 @@ export async function executeSpecCommand(input) {
         }
         throw error;
     }
-    const environment = loadEnvironmentConfig({ root });
+    const preflight = await prepareConfiguredOperatorReadiness({
+        root,
+        resolvedAgentIds,
+        includeEnvironment: false,
+    });
+    if (preflight.issues.length > 0) {
+        throw new SpecPreflightError(preflight.issues, preflight.preProviderIssueCount);
+    }
+    const competitors = preflight.agents;
+    const environment = loadOperatorEnvironment({ root });
     const effectiveMaxParallel = resolveEffectiveMaxParallel({
         competitorCount: competitors.length,
         requestedMaxParallel,
@@ -251,6 +262,7 @@ async function persistSpecAgentCompletion(options) {
                         ...completeFields,
                         outputPath: result.outputPath,
                         dataPath: result.dataPath,
+                        contentHash: result.contentHash,
                         tokenUsage: result.tokenUsage,
                         error: null,
                     };
@@ -317,6 +329,7 @@ function mapExecutionResultsToSpecAgents(executionResults, startedAt) {
                 status: "succeeded",
                 outputPath: result.outputPath,
                 dataPath: result.dataPath,
+                contentHash: result.contentHash,
                 tokenUsage: result.tokenUsage,
             };
         }

package/dist/commands/spec/errors.d.ts

@@ -1,4 +1,5 @@
 import { CliError } from "../../cli/errors.js";
+import type { PreflightIssue } from "../../competition/shared/preflight.js";
 export declare class SpecError extends CliError {
     constructor(headline: string, detailLines?: readonly string[], hintLines?: readonly string[]);
 }
@@ -9,3 +10,7 @@ export declare class SpecAgentNotFoundError extends SpecError {
 export declare class SpecGenerationFailedError extends SpecError {
     constructor(detailLines?: readonly string[]);
 }
+export declare class SpecPreflightError extends SpecError {
+    readonly issues: readonly PreflightIssue[];
+    constructor(issues: readonly PreflightIssue[], preProviderIssueCount: number);
+}

package/dist/commands/spec/errors.js

@@ -1,4 +1,5 @@
 import { CliError } from "../../cli/errors.js";
+import { formatOperatorPreflightIssueLines, resolveOperatorPreflightHintLines, } from "../../preflight/formatting.js";
 export class SpecError extends CliError {
     constructor(headline, detailLines = [], hintLines = []) {
         super(headline, detailLines, hintLines);
@@ -21,3 +22,11 @@ export class SpecGenerationFailedError extends SpecError {
         this.name = "SpecGenerationFailedError";
     }
 }
+export class SpecPreflightError extends SpecError {
+    issues;
+    constructor(issues, preProviderIssueCount) {
+        super("Preflight failed. Aborting specification generation.", formatOperatorPreflightIssueLines(issues), resolveOperatorPreflightHintLines(issues, preProviderIssueCount) ?? []);
+        this.issues = Array.from(issues);
+        this.name = "SpecPreflightError";
+    }
+}

package/dist/commands/verify/agents.d.ts

@@ -4,5 +4,7 @@ export declare function resolveVerificationAgents(options: {
     root: string;
     agentOverrideFlag?: string;
     profileName?: string;
-}): AgentDefinition[];
-export declare function assertVerifierPreflight(agents: readonly AgentDefinition[]): Promise<void>;
+}): {
+    readonly agentIds: readonly string[];
+    readonly competitors: readonly AgentDefinition[];
+};

package/dist/commands/verify/agents.js

@@ -1,29 +1,22 @@
-import { verifyAgentProviders } from "../../agents/runtime/auth.js";
 import { AgentNotFoundError } from "../../configs/agents/errors.js";
 import { resolveStageCompetitors } from "../shared/resolve-stage-competitors.js";
+import { VerifyAgentNotFoundError } from "./errors.js";
 export function resolveVerificationAgents(options) {
     const { agentIds, root, agentOverrideFlag, profileName } = options;
     try {
-        const resolution = resolveStageCompetitors({
+        return resolveStageCompetitors({
             root,
             stageId: "verify",
             cliAgentIds: agentIds,
             cliOverrideFlag: agentOverrideFlag,
             profileName,
+            includeDefinitions: false,
         });
-        return [...resolution.competitors];
     }
     catch (error) {
         if (error instanceof AgentNotFoundError) {
-            throw new Error(`Verifier agent not found: ${error.agentId}`);
+            throw new VerifyAgentNotFoundError(error.agentId);
         }
         throw error;
     }
 }
-export async function assertVerifierPreflight(agents) {
-    const providerIssues = await verifyAgentProviders(agents.map((agent) => ({ id: agent.id, provider: agent.provider })));
-    if (providerIssues.length > 0) {
-        const detail = providerIssues.map((issue) => issue.message).join("; ");
-        throw new Error(`Verifier preflight failed: ${detail}`);
-    }
-}

package/dist/commands/verify/command.js

@@ -1,6 +1,5 @@
 import { teardownSessionAuth } from "../../agents/runtime/registry.js";
 import { createTeardownController } from "../../competition/shared/teardown.js";
-import { loadEnvironmentConfig } from "../../configs/environment/loader.js";
 import { loadVerificationConfig } from "../../configs/verification/loader.js";
 import { buildBlindedAliasMap } from "../../domain/verify/competition/blinding.js";
 import { deriveVerificationStatusFromMethods, maybePersistSelectedSpecPath, } from "../../domain/verify/competition/finalize.js";
@@ -9,11 +8,14 @@ import { executeAndPersistRubricMethods } from "../../domain/verify/competition/
 import { createVerificationRecordMutators } from "../../domain/verify/model/mutators.js";
 import { appendVerificationRecord, flushVerificationRecordBuffer, } from "../../domain/verify/persistence/adapter.js";
 import { buildPersistedExtraContextFields } from "../../extra-context/contract.js";
+import { loadOperatorEnvironment } from "../../preflight/environment.js";
+import { prepareConfiguredOperatorReadiness } from "../../preflight/operator.js";
 import { toErrorMessage } from "../../utils/errors.js";
 import { normalizePathForDisplay, relativeToRoot } from "../../utils/path.js";
 import { resolveWorkspacePath, VORATIQ_VERIFICATION_SESSIONS_DIR, } from "../../workspace/structure.js";
 import { generateSessionId } from "../shared/session-id.js";
-import { assertVerifierPreflight, resolveVerificationAgents, } from "./agents.js";
+import { resolveVerificationAgents } from "./agents.js";
+import { VerifyPreflightError } from "./errors.js";
 import { finalizeActiveVerification, registerActiveVerification, } from "./lifecycle.js";
 import { resolveVerifyRubricMaxParallel } from "./max-parallel.js";
 import { resolveVerifyTarget } from "./targets.js";
@@ -29,14 +31,22 @@ export async function executeVerifyCommand(input) {
         target,
     });
     const verificationConfig = loadVerificationConfig({ root });
-    const verificationAgents = resolveVerificationAgents({
+    const verificationPlan = resolveVerificationAgents({
         agentIds,
         root,
         agentOverrideFlag,
         profileName,
     });
-    await assertVerifierPreflight(verificationAgents);
-    const environment = loadEnvironmentConfig({ root });
+    const preflight = await prepareConfiguredOperatorReadiness({
+        root,
+        resolvedAgentIds: verificationPlan.agentIds,
+        includeEnvironment: false,
+    });
+    if (preflight.issues.length > 0) {
+        throw new VerifyPreflightError(preflight.issues, preflight.preProviderIssueCount);
+    }
+    const verificationAgents = preflight.agents;
+    const environment = loadOperatorEnvironment({ root });
     const verificationId = generateSessionId();
     const createdAt = new Date().toISOString();
     const aliasMap = buildBlindedAliasMap(resolvedTarget);

package/dist/commands/verify/errors.d.ts

@@ -0,0 +1,12 @@
+import { CliError } from "../../cli/errors.js";
+import type { PreflightIssue } from "../../competition/shared/preflight.js";
+export declare class VerifyError extends CliError {
+    constructor(headline: string, detailLines?: readonly string[], hintLines?: readonly string[]);
+}
+export declare class VerifyAgentNotFoundError extends VerifyError {
+    constructor(agentId: string);
+}
+export declare class VerifyPreflightError extends VerifyError {
+    readonly issues: readonly PreflightIssue[];
+    constructor(issues: readonly PreflightIssue[], preProviderIssueCount: number);
+}

package/dist/commands/verify/errors.js

@@ -0,0 +1,22 @@
+import { CliError } from "../../cli/errors.js";
+import { formatOperatorPreflightIssueLines, resolveOperatorPreflightHintLines, } from "../../preflight/formatting.js";
+export class VerifyError extends CliError {
+    constructor(headline, detailLines = [], hintLines = []) {
+        super(headline, detailLines, hintLines);
+        this.name = "VerifyError";
+    }
+}
+export class VerifyAgentNotFoundError extends VerifyError {
+    constructor(agentId) {
+        super(`Verifier agent not found: ${agentId}`);
+        this.name = "VerifyAgentNotFoundError";
+    }
+}
+export class VerifyPreflightError extends VerifyError {
+    issues;
+    constructor(issues, preProviderIssueCount) {
+        super("Preflight failed. Aborting verification.", formatOperatorPreflightIssueLines(issues), resolveOperatorPreflightHintLines(issues, preProviderIssueCount) ?? []);
+        this.issues = Array.from(issues);
+        this.name = "VerifyPreflightError";
+    }
+}

package/dist/commands/verify/targets.js

@@ -1,4 +1,4 @@
-import { basename } from "node:path";
+import { basename, join } from "node:path";
 import { CliError, RunNotFoundCliError } from "../../cli/errors.js";
 import { TERMINAL_MESSAGE_STATUSES } from "../../domain/message/model/types.js";
 import { readMessageRecords } from "../../domain/message/persistence/adapter.js";
@@ -10,7 +10,10 @@ import { TERMINAL_SPEC_STATUSES } from "../../domain/spec/model/types.js";
 import { readSpecRecords } from "../../domain/spec/persistence/adapter.js";
 import { readVerificationRecords } from "../../domain/verify/persistence/adapter.js";
 import { TERMINAL_RUN_STATUSES } from "../../status/index.js";
-import { MESSAGE_RESPONSE_FILENAME } from "../../workspace/structure.js";
+import { pathExists } from "../../utils/fs.js";
+import { normalizePathForDisplay, resolvePath } from "../../utils/path.js";
+import { buildAgentWorkspacePaths } from "../../workspace/layout.js";
+import { DIFF_FILENAME, MESSAGE_RESPONSE_FILENAME, } from "../../workspace/structure.js";
 export async function resolveVerifyTarget(input) {
     const { target } = input;
     switch (target.kind) {
@@ -40,14 +43,31 @@ async function resolveSpecVerifyTarget(input) {
     if (!TERMINAL_SPEC_STATUSES.includes(record.status)) {
         throw new CliError(`Spec session \`${target.sessionId}\` is not complete.`, [`Status: \`${record.status}\`.`], ["Wait for the spec to finish before running `voratiq verify`."]);
     }
+    const competitiveCandidates = record.agents
+        .filter((agent) => agent.status === "succeeded" && agent.outputPath)
+        .map((agent) => ({
+        canonicalId: agent.agentId,
+        forbiddenIdentityTokens: [agent.agentId],
+    }));
+    if (competitiveCandidates.length === 0) {
+        throw new CliError(`Spec session \`${target.sessionId}\` has no verifiable drafts.`, [], [
+            "Re-run `voratiq spec` to generate at least one succeeded draft before running `voratiq verify`.",
+        ]);
+    }
+    const missingSpecArtifacts = await collectMissingSpecVerificationArtifacts({
+        root,
+        outputPaths: record.agents
+            .filter((agent) => agent.status === "succeeded" && typeof agent.outputPath === "string")
+            .map((agent) => agent.outputPath),
+    });
+    if (missingSpecArtifacts.length > 0) {
+        throw new CliError(`Spec session \`${target.sessionId}\` is missing required verification artifacts.`, missingSpecArtifacts.map((artifact) => `Missing: \`${artifact}\`.`), [
+            "Re-run `voratiq spec` to regenerate the retained artifacts before running `voratiq verify`.",
+        ]);
+    }
     return {
         baseRevisionSha: resolveSpecBaseRevisionSha(record),
-        competitiveCandidates: record.agents
-            .filter((agent) => agent.status === "succeeded" && agent.outputPath)
-            .map((agent) => ({
-            canonicalId: agent.agentId,
-            forbiddenIdentityTokens: [agent.agentId],
-        })),
+        competitiveCandidates,
         target: {
             kind: "spec",
             sessionId: record.sessionId,
@@ -81,6 +101,16 @@ async function resolveRunVerifyTarget(input) {
     if (candidateIds.length === 0) {
         throw new CliError(`Run \`${target.sessionId}\` has no candidate agents to verify.`, [], ["Re-run `voratiq run` to generate verifiable candidates."]);
     }
+    const missingRequiredArtifacts = await collectMissingRunVerificationArtifacts({
+        root,
+        record,
+        candidateIds,
+    });
+    if (missingRequiredArtifacts.length > 0) {
+        throw new CliError(`Run \`${target.sessionId}\` is missing required verification artifacts.`, missingRequiredArtifacts.map((artifact) => `Missing: \`${artifact}\`.`), [
+            "Re-run `voratiq run` to regenerate the retained artifacts before running `voratiq verify`.",
+        ]);
+    }
     return {
         baseRevisionSha: record.baseRevisionSha,
         competitiveCandidates: candidateIds.map((candidateId) => ({
@@ -117,16 +147,33 @@ async function resolveReductionVerifyTarget(input) {
     if (!TERMINAL_REDUCTION_STATUSES.includes(record.status)) {
         throw new CliError(`Reduction session \`${target.sessionId}\` is not complete.`, [`Status: \`${record.status}\`.`], ["Wait for the reduction to finish before running `voratiq verify`."]);
     }
-    const referenceRepo = await resolveReductionReferenceRepo({
-        ...input,
-        reductionRecord: record,
-    });
     const competitiveCandidates = record.reducers
         .filter((reducer) => reducer.status === "succeeded" && reducer.outputPath)
         .map((reducer) => ({
         canonicalId: reducer.agentId,
         forbiddenIdentityTokens: [reducer.agentId],
     }));
+    if (competitiveCandidates.length === 0) {
+        throw new CliError(`Reduction session \`${target.sessionId}\` has no verifiable reductions.`, [], [
+            "Re-run `voratiq reduce` to produce at least one succeeded reduction before running `voratiq verify`.",
+        ]);
+    }
+    const missingReductionArtifacts = await collectMissingRetainedVerificationArtifacts({
+        root,
+        relativePaths: record.reducers
+            .filter((reducer) => reducer.status === "succeeded" &&
+            typeof reducer.outputPath === "string")
+            .map((reducer) => reducer.outputPath),
+    });
+    if (missingReductionArtifacts.length > 0) {
+        throw new CliError(`Reduction session \`${target.sessionId}\` is missing required verification artifacts.`, missingReductionArtifacts.map((artifact) => `Missing: \`${artifact}\`.`), [
+            "Re-run `voratiq reduce` to regenerate the retained artifacts before running `voratiq verify`.",
+        ]);
+    }
+    const referenceRepo = await resolveReductionReferenceRepo({
+        ...input,
+        reductionRecord: record,
+    });
     if (referenceRepo.kind === "git") {
         return {
             baseRevisionSha: referenceRepo.baseRevisionSha,
@@ -177,6 +224,15 @@ async function resolveMessageVerifyTarget(input) {
             "Re-run `voratiq message` to capture at least one succeeded response before running `voratiq verify`.",
         ]);
     }
+    const missingMessageArtifacts = await collectMissingRetainedVerificationArtifacts({
+        root,
+        relativePaths: recipients.map((recipient) => recipient.outputPath),
+    });
+    if (missingMessageArtifacts.length > 0) {
+        throw new CliError(`Message session \`${target.sessionId}\` is missing required verification artifacts.`, missingMessageArtifacts.map((artifact) => `Missing: \`${artifact}\`.`), [
+            "Re-run `voratiq message` to regenerate the retained artifacts before running `voratiq verify`.",
+        ]);
+    }
     return {
         competitiveCandidates: recipients.map((recipient) => ({
             canonicalId: recipient.agentId,
@@ -189,6 +245,46 @@ async function resolveMessageVerifyTarget(input) {
         messageRecord: record,
     };
 }
+async function collectMissingSpecVerificationArtifacts(options) {
+    return collectMissingRetainedVerificationArtifacts({
+        root: options.root,
+        relativePaths: options.outputPaths,
+    });
+}
+async function collectMissingRunVerificationArtifacts(options) {
+    const { root, record, candidateIds } = options;
+    const missing = new Set();
+    const specAbsolute = resolvePath(root, record.spec.path);
+    if (!(await pathExists(specAbsolute))) {
+        missing.add(normalizePathForDisplay(record.spec.path));
+    }
+    for (const candidateId of candidateIds) {
+        const runAgentRecord = record.agents.find((agent) => agent.agentId === candidateId);
+        if (runAgentRecord?.artifacts?.diffCaptured !== true) {
+            continue;
+        }
+        const paths = buildAgentWorkspacePaths({
+            root,
+            runId: record.runId,
+            agentId: candidateId,
+        });
+        const diffAbsolute = join(paths.artifactsPath, DIFF_FILENAME);
+        if (!(await pathExists(diffAbsolute))) {
+            missing.add(normalizePathForDisplay(join(".voratiq", "run", "sessions", record.runId, candidateId, "artifacts", DIFF_FILENAME)));
+        }
+    }
+    return Array.from(missing).sort((left, right) => left.localeCompare(right));
+}
+async function collectMissingRetainedVerificationArtifacts(options) {
+    const { root, relativePaths } = options;
+    const missing = new Set();
+    for (const relativePath of relativePaths) {
+        if (!(await pathExists(resolvePath(root, relativePath)))) {
+            missing.add(normalizePathForDisplay(relativePath));
+        }
+    }
+    return Array.from(missing).sort((left, right) => left.localeCompare(right));
+}
 function collectRunCandidateIdentityTokens(options) {
     const { runRecord, candidateId } = options;
     const tokens = new Set();

package/dist/competition/shared/preflight.d.ts

@@ -7,5 +7,5 @@ export interface FormatPreflightIssueLinesOptions {
     readonly unlabeledAgentIds?: readonly string[];
 }
 export declare const PREFLIGHT_SUMMARY_MAX_CHARS: 120;
-export declare const PREFLIGHT_HINT: "Run `voratiq init` to configure the workspace.";
+export declare const PREFLIGHT_HINT: "Run `voratiq doctor --fix` to repair workspace setup.";
 export declare function formatPreflightIssueLines(issues: readonly PreflightIssue[], options?: FormatPreflightIssueLinesOptions): string[];

package/dist/competition/shared/preflight.js

@@ -1,5 +1,6 @@
 export const PREFLIGHT_SUMMARY_MAX_CHARS = 120;
-export const PREFLIGHT_HINT = "Run `voratiq init` to configure the workspace.";
+export const PREFLIGHT_HINT = "Run `voratiq doctor --fix` to repair workspace setup.";
+const SETTINGS_FILE_MESSAGE_PATTERN = /^Invalid settings file at (?:(?:.+\/)?(?:\.voratiq\/)?)settings\.yaml(?::\s*(.+))?$/u;
 export function formatPreflightIssueLines(issues, options = {}) {
     const { maxChars = PREFLIGHT_SUMMARY_MAX_CHARS, unlabeledAgentIds = [] } = options;
     const unlabeled = new Set(unlabeledAgentIds);
@@ -17,15 +18,27 @@ function formatIssueLine(agentId, message, unlabeledAgentIds) {
     if (unlabeledAgentIds.has(agentId)) {
         return `- ${message}`;
     }
-    return `- ${agentId}: ${message}`;
+    return `- \`${agentId}\`: ${message}`;
 }
 function normalizeIssueMessage(message) {
     const split = message
         .split(/\r?\n/u)
         .map((line) => line.replace(/\s+/gu, " ").trim())
+        .map(normalizeIssueText)
         .filter((line) => line.length > 0);
     return split.length > 0 ? split : ["unknown error"];
 }
+function normalizeIssueText(line) {
+    const settingsMatch = SETTINGS_FILE_MESSAGE_PATTERN.exec(line);
+    if (!settingsMatch) {
+        return line;
+    }
+    const detail = settingsMatch[1]?.trim();
+    if (!detail) {
+        return "Invalid `settings.yaml`.";
+    }
+    return `Invalid \`settings.yaml\`: ${detail}`;
+}
 function truncateLine(value, maxChars) {
     if (value.length <= maxChars) {
         return value;