@xfey/tutti 0.1.41 → 0.1.43

package/dist/artifacts/process-boundary.d.ts

@@ -0,0 +1,33 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+export declare const MAX_ARTIFACT_DIAGNOSTIC_CHARS = 8000;
+export type ArtifactPreviewProcessPlan = {
+    command: "npm";
+    args: ["run", "artifact:preview"];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    port: number;
+};
+export type ArtifactProcessRuntime = {
+    root: string;
+    home: string;
+    temp: string;
+};
+export declare class ArtifactDiagnosticBuffer {
+    private raw;
+    append(source: "stdout" | "stderr", chunk: Buffer | string): void;
+    read(sensitiveValues?: readonly string[]): {
+        text: string;
+        truncated: boolean;
+    };
+}
+export declare function createArtifactProcessRuntime(): ArtifactProcessRuntime;
+export declare function cleanupArtifactProcessRuntime(runtime: ArtifactProcessRuntime): void;
+export declare function createArtifactPreviewEnv(options: {
+    sourceEnv: NodeJS.ProcessEnv;
+    port: number;
+    runtime: ArtifactProcessRuntime;
+}): NodeJS.ProcessEnv;
+export declare function spawnArtifactPreviewProcess(plan: ArtifactPreviewProcessPlan): ChildProcessWithoutNullStreams;
+export declare function allocateArtifactPreviewPort(): Promise<number>;
+export declare function terminateArtifactProcessTree(child: ChildProcessWithoutNullStreams): Promise<void>;
+//# sourceMappingURL=process-boundary.d.ts.map

package/dist/artifacts/process-boundary.js

@@ -0,0 +1,134 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { redactAndTruncateText } from "@tutti/shared/utils";
+export const MAX_ARTIFACT_DIAGNOSTIC_CHARS = 8_000;
+const MAX_RAW_DIAGNOSTIC_CHARS = MAX_ARTIFACT_DIAGNOSTIC_CHARS * 2;
+const SAFE_ENV_NAMES = new Set(["PATH", "LANG", "LC_ALL", "LC_CTYPE", "TEMP", "TMP"]);
+export class ArtifactDiagnosticBuffer {
+    raw = "";
+    append(source, chunk) {
+        const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        this.raw = `${this.raw}[${source}]\n${text}`.slice(-MAX_RAW_DIAGNOSTIC_CHARS);
+    }
+    read(sensitiveValues = []) {
+        let redacted = this.raw;
+        for (const value of sensitiveValues) {
+            if (value.length >= 4) {
+                redacted = redacted.replaceAll(value, "[REDACTED:runtime_value]");
+            }
+        }
+        const truncated = redacted.length > MAX_ARTIFACT_DIAGNOSTIC_CHARS;
+        return {
+            text: redactAndTruncateText(redacted, MAX_ARTIFACT_DIAGNOSTIC_CHARS),
+            truncated,
+        };
+    }
+}
+export function createArtifactProcessRuntime() {
+    const root = mkdtempSync(join(tmpdir(), "tutti-artifact-preview-"));
+    const home = join(root, "home");
+    const temp = join(root, "tmp");
+    mkdirSync(home, { recursive: true });
+    mkdirSync(temp, { recursive: true });
+    return { root, home, temp };
+}
+export function cleanupArtifactProcessRuntime(runtime) {
+    rmSync(runtime.root, { recursive: true, force: true });
+}
+export function createArtifactPreviewEnv(options) {
+    const env = {};
+    for (const name of SAFE_ENV_NAMES) {
+        const value = options.sourceEnv[name];
+        if (value !== undefined && value.trim() !== "") {
+            env[name] = value;
+        }
+    }
+    env.HOME = options.runtime.home;
+    env.TMPDIR = options.runtime.temp;
+    env.TEMP = options.runtime.temp;
+    env.TMP = options.runtime.temp;
+    env.HOST = "127.0.0.1";
+    env.PORT = String(options.port);
+    env.TUTTI_ARTIFACT_PREVIEW = "1";
+    env.npm_config_update_notifier = "false";
+    env.npm_config_fund = "false";
+    env.npm_config_audit = "false";
+    return env;
+}
+export function spawnArtifactPreviewProcess(plan) {
+    const child = spawn(plan.command, plan.args, {
+        cwd: plan.cwd,
+        env: plan.env,
+        shell: false,
+        detached: process.platform !== "win32",
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    child.stdin.end();
+    return child;
+}
+export async function allocateArtifactPreviewPort() {
+    return await new Promise((resolvePort, reject) => {
+        const server = createServer();
+        server.unref();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (address === null || typeof address === "string") {
+                server.close();
+                reject(new Error("Could not allocate an Artifact preview port"));
+                return;
+            }
+            server.close((error) => {
+                if (error === undefined) {
+                    resolvePort(address.port);
+                }
+                else {
+                    reject(error);
+                }
+            });
+        });
+    });
+}
+function sendProcessSignal(child, signal) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return;
+    }
+    if (process.platform !== "win32" && child.pid !== undefined) {
+        try {
+            process.kill(-child.pid, signal);
+            return;
+        }
+        catch {
+            // Fall back to the direct child when a process group is already gone.
+        }
+    }
+    child.kill(signal);
+}
+function waitForChildClose(child, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return Promise.resolve(true);
+    }
+    return new Promise((resolveClosed) => {
+        const timeout = setTimeout(() => {
+            child.off("close", onClose);
+            resolveClosed(false);
+        }, timeoutMs);
+        const onClose = () => {
+            clearTimeout(timeout);
+            resolveClosed(true);
+        };
+        child.once("close", onClose);
+    });
+}
+export async function terminateArtifactProcessTree(child) {
+    sendProcessSignal(child, "SIGTERM");
+    if (await waitForChildClose(child, 1_000)) {
+        return;
+    }
+    sendProcessSignal(child, "SIGKILL");
+    await waitForChildClose(child, 500);
+}
+//# sourceMappingURL=process-boundary.js.map

package/dist/control-plane/types.d.ts

@@ -84,10 +84,15 @@ export type RunCorrectionContext = {
     summary: string;
     reason_code: string;
     guidance: string;
-    promotion_failure?: {
+    diagnostic: {
+        source: string;
+        text: string;
+        truncated: boolean;
+    };
+    promotion_failure: {
         reason_code: string;
         summary: string;
-    };
+    } | null;
 };
 export type RunPipelineInput = {
     activity_ref: ActivityRef;

package/dist/prompt-templates/index.d.ts

@@ -1,4 +1,4 @@
-export type PromptTemplateKey = "procedures.project_context_bootstrap" | "procedures.context_sync" | "procedures.project_brief_refresh" | "procedures.scratchpad_refresh" | "procedures.task_compile" | "procedures.reference_file_summary" | "procedures.follow_up_check" | "runs.task_run" | "runs.task_continuation" | "runs.task_retry" | "chat.assistant" | "codex.no_write_smoke";
+export type PromptTemplateKey = "procedures.project_context_bootstrap" | "procedures.context_sync" | "procedures.project_brief_refresh" | "procedures.scratchpad_refresh" | "procedures.task_compile" | "procedures.reference_file_summary" | "procedures.follow_up_check" | "runs.task_run" | "runs.task_continuation" | "runs.task_retry" | "artifacts.applicability" | "chat.assistant" | "codex.no_write_smoke";
 export type RenderPromptTemplateOptions = {
     templateKey: PromptTemplateKey;
     variables?: Record<string, unknown>;

package/dist/prompt-templates/index.js

@@ -22,6 +22,7 @@ const TEMPLATE_REGISTRY = {
     "runs.task_run": "runs/task-run.md",
     "runs.task_continuation": "runs/task-continuation.md",
     "runs.task_retry": "runs/task-retry.md",
+    "artifacts.applicability": "artifacts/applicability.md",
     "chat.assistant": "chat-assistant.md",
     "codex.no_write_smoke": "codex/no-write-smoke.md",
 };

package/dist/provider-usage/index.js

@@ -10,6 +10,7 @@ const SOURCE_LABELS = {
     workspace_write_run: { label: "Implementation", category: "implementation" },
     follow_up_run: { label: "Follow-up run", category: "implementation" },
     pipeline_self_correction: { label: "Self-correction", category: "implementation" },
+    artifact_applicability: { label: "Artifact applicability", category: "planning" },
     task_compile: { label: "Worklist planning", category: "planning" },
     scratchpad_refresh: { label: "Scratchpad sync", category: "planning" },
     project_brief_refresh: { label: "Project brief", category: "context" },

package/dist/run-pipeline/artifact-applicability.d.ts

@@ -0,0 +1,49 @@
+import type { ActivityRef, TaskId } from "@tutti/shared/ids";
+import { type CandidateArtifactValidationFailure, type CandidateArtifactValidationResult, type ValidateCandidateArtifactOptions } from "../artifacts/index.js";
+import type { ProviderUsageRecorder } from "../provider-usage/index.js";
+import { type OpenAiStructuredOutputClient } from "../providers/openai/sdk-procedure-runner.js";
+import type { OpenAiProviderConfig } from "../providers/openai/provider-config.js";
+import type { RunDiffSummary } from "../workspace-ops/index.js";
+export type ArtifactApplicabilityDecision = {
+    decision: "artifact_required" | "not_applicable";
+    reason: string;
+};
+export type ArtifactApplicabilityJudgeInput = {
+    task: {
+        title: string;
+        goal: string;
+        scope: string[];
+    };
+    candidate: {
+        changed_paths: string[];
+        diff_facts: string;
+        repo_evidence: string[];
+    };
+};
+export type ArtifactApplicabilityJudge = (input: ArtifactApplicabilityJudgeInput) => Promise<ArtifactApplicabilityDecision>;
+export type ArtifactCandidateGateResult = {
+    status: "passed";
+    disposition: "validated" | "not_applicable";
+    reason: string;
+} | {
+    status: "failed";
+    correctable: boolean;
+    failure: CandidateArtifactValidationFailure;
+};
+export type RunArtifactCandidateGateOptions = {
+    repoRoot: string;
+    task: ArtifactApplicabilityJudgeInput["task"];
+    diff: RunDiffSummary;
+    config: OpenAiProviderConfig;
+    apiKey: string;
+    promptsRoot?: string;
+    baseEnv?: NodeJS.ProcessEnv;
+    client?: OpenAiStructuredOutputClient;
+    judge?: ArtifactApplicabilityJudge;
+    validateCandidate?: (options: ValidateCandidateArtifactOptions) => Promise<CandidateArtifactValidationResult>;
+    recordUsage?: ProviderUsageRecorder;
+    activityRef?: ActivityRef;
+    taskId?: TaskId;
+};
+export declare function runArtifactCandidateGate(options: RunArtifactCandidateGateOptions): Promise<ArtifactCandidateGateResult>;
+//# sourceMappingURL=artifact-applicability.d.ts.map

package/dist/run-pipeline/artifact-applicability.js

@@ -0,0 +1,281 @@
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { redactAndTruncateText } from "@tutti/shared/utils";
+import { ARTIFACT_MANIFEST_PATH, validateCandidateArtifact, } from "../artifacts/index.js";
+import { renderPromptTemplate } from "../prompt-templates/index.js";
+import { createOpenAiStructuredOutputClient, OpenAiStructuredOutputError, runOpenAiStructuredOutput, } from "../providers/openai/sdk-procedure-runner.js";
+const ARTIFACT_APPLICABILITY_OUTPUT_SCHEMA = {
+    type: "object",
+    required: ["decision", "reason"],
+    additionalProperties: false,
+    properties: {
+        decision: { type: "string", enum: ["artifact_required", "not_applicable"] },
+        reason: { type: "string", minLength: 1 },
+    },
+};
+const MAX_CHANGED_PATHS = 200;
+const MAX_DIFF_FACT_CHARS = 4_000;
+const MAX_EVIDENCE_ITEMS = 40;
+const MAX_DIAGNOSTIC_CHARS = 8_000;
+const VISUAL_TASK_PATTERN = /\b(page|website|web app|frontend|ui|dashboard|landing|preview|browser|spa|visuali[sz]ation|prototype)\b|页面|网站|网页|界面|预览|可视化|仪表盘|交互/iu;
+const BROWSER_CHANGED_PATH_PATTERN = /(^|\/)(index\.html?|vite\.config\.[^/]+|next\.config\.[^/]+|astro\.config\.[^/]+|src\/(app|main|index)\.[jt]sx?|app\/.*page\.[jt]sx?|pages\/.*\.[jt]sx?|public\/.*|web\/.*)$/iu;
+const DOC_EXTENSION_SET = new Set([".md", ".mdx"]);
+const WEB_DEPENDENCIES = new Set([
+    "@angular/core",
+    "@sveltejs/kit",
+    "@vitejs/plugin-react",
+    "astro",
+    "next",
+    "nuxt",
+    "react",
+    "react-dom",
+    "solid-js",
+    "svelte",
+    "vite",
+    "vue",
+]);
+function isArtifactApplicabilityDecision(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    return ((record.decision === "artifact_required" || record.decision === "not_applicable") &&
+        typeof record.reason === "string" &&
+        record.reason.trim().length > 0 &&
+        Object.keys(record).length === 2);
+}
+function boundedChangedPaths(changedPaths) {
+    return changedPaths.slice(0, MAX_CHANGED_PATHS).map((path) => redactAndTruncateText(path, 240));
+}
+function isDocsOnly(changedPaths) {
+    return (changedPaths.length > 0 &&
+        changedPaths.every((path) => {
+            const name = basename(path).toLowerCase();
+            return (name === "readme" || name.startsWith("readme.") || DOC_EXTENSION_SET.has(extname(name)));
+        }));
+}
+function packageEvidence(repoRoot) {
+    const path = join(repoRoot, "package.json");
+    if (!existsSync(path)) {
+        return [];
+    }
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.size > 1024 * 1024) {
+            return ["root package.json exists but is not readable as bounded JSON"];
+        }
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return ["root package.json is not a JSON object"];
+        }
+        const record = parsed;
+        const evidence = ["root package.json exists"];
+        if (record.bin !== undefined) {
+            evidence.push("root package.json declares a CLI bin entry");
+        }
+        const scriptNames = record.scripts !== null &&
+            typeof record.scripts === "object" &&
+            !Array.isArray(record.scripts)
+            ? Object.keys(record.scripts).slice(0, 20)
+            : [];
+        if (scriptNames.length > 0) {
+            evidence.push(`root package scripts: ${scriptNames.join(", ")}`);
+        }
+        const dependencyNames = [record.dependencies, record.devDependencies]
+            .flatMap((dependencies) => dependencies !== null && typeof dependencies === "object" && !Array.isArray(dependencies)
+            ? Object.keys(dependencies)
+            : [])
+            .filter((name) => WEB_DEPENDENCIES.has(name));
+        if (dependencyNames.length > 0) {
+            evidence.push(`browser framework dependencies: ${[...new Set(dependencyNames)].join(", ")}`);
+        }
+        return evidence;
+    }
+    catch {
+        return ["root package.json exists but could not be parsed"];
+    }
+}
+function repoEvidence(repoRoot) {
+    const evidence = packageEvidence(repoRoot);
+    for (const path of [
+        "index.html",
+        "vite.config.ts",
+        "vite.config.js",
+        "next.config.js",
+        "next.config.mjs",
+        "astro.config.mjs",
+        "src/App.tsx",
+        "src/App.jsx",
+        "src/main.tsx",
+        "src/main.jsx",
+    ]) {
+        if (existsSync(join(repoRoot, path))) {
+            evidence.push(`browser entry evidence: ${path}`);
+        }
+    }
+    return evidence.slice(0, MAX_EVIDENCE_ITEMS);
+}
+function deterministicApplicability(options) {
+    const taskText = [options.task.title, options.task.goal, ...options.task.scope].join("\n");
+    if (VISUAL_TASK_PATTERN.test(taskText) ||
+        options.changedPaths.some((path) => BROWSER_CHANGED_PATH_PATTERN.test(path))) {
+        return {
+            decision: "artifact_required",
+            reason: "The task or candidate paths contain explicit browser-viewable application evidence.",
+        };
+    }
+    if (isDocsOnly(options.changedPaths)) {
+        return {
+            decision: "not_applicable",
+            reason: "The candidate only changes documentation files.",
+        };
+    }
+    return null;
+}
+function createDefaultJudge(options) {
+    const client = options.client ??
+        createOpenAiStructuredOutputClient({
+            apiKey: options.apiKey,
+            ...(options.config.api_base_url === undefined
+                ? {}
+                : { apiBaseUrl: options.config.api_base_url }),
+            ...(options.config.organization_id === undefined
+                ? {}
+                : { organizationId: options.config.organization_id }),
+            ...(options.config.openai_project_id === undefined
+                ? {}
+                : { openAiProjectId: options.config.openai_project_id }),
+        });
+    return async (input) => {
+        const instructions = renderPromptTemplate({
+            templateKey: "artifacts.applicability",
+            ...(options.promptsRoot === undefined ? {} : { promptsRoot: options.promptsRoot }),
+            variables: { applicability_input_json: input },
+        });
+        const result = await runOpenAiStructuredOutput({
+            client,
+            model: options.config.default_model,
+            instructions,
+            input: "Decide Artifact applicability and return only structured JSON.",
+            schemaName: "artifact_applicability_output",
+            schemaDescription: "Transient Artifact applicability decision for a completed candidate.",
+            schema: ARTIFACT_APPLICABILITY_OUTPUT_SCHEMA,
+            maxAttempts: 1,
+            validate: isArtifactApplicabilityDecision,
+        });
+        if (result.usage !== undefined) {
+            options.recordUsage?.({
+                provider: "openai",
+                source: "artifact_applicability",
+                model: options.config.default_model,
+                usage: result.usage,
+                ...(options.activityRef === undefined ? {} : { activity_ref: options.activityRef }),
+                ...(options.taskId === undefined ? {} : { task_id: options.taskId }),
+            });
+        }
+        return result.output;
+    };
+}
+function retryableJudgeFailure(error) {
+    return ((error instanceof OpenAiStructuredOutputError && error.retryable) ||
+        (error !== null &&
+            typeof error === "object" &&
+            "retryable" in error &&
+            error.retryable === true));
+}
+async function judgeApplicability(judge, input) {
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+        try {
+            const result = await judge(input);
+            if (!isArtifactApplicabilityDecision(result)) {
+                throw new Error("Artifact applicability judge returned an invalid result");
+            }
+            return result;
+        }
+        catch (error) {
+            if (attempt < 2 && retryableJudgeFailure(error)) {
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw new Error("Artifact applicability judge did not return a decision");
+}
+function gateFailure(options) {
+    const redacted = redactAndTruncateText(options.detail, MAX_DIAGNOSTIC_CHARS);
+    return {
+        status: "failed",
+        correctable: options.correctable,
+        failure: {
+            reason_code: options.reasonCode,
+            summary: options.summary,
+            guidance: options.guidance,
+            diagnostic: {
+                source: options.source,
+                text: redacted,
+                truncated: redacted.length >= MAX_DIAGNOSTIC_CHARS,
+            },
+        },
+    };
+}
+export async function runArtifactCandidateGate(options) {
+    const validation = await (options.validateCandidate ?? validateCandidateArtifact)({
+        repoRoot: options.repoRoot,
+        ...(options.baseEnv === undefined ? {} : { baseEnv: options.baseEnv }),
+    });
+    if (validation.status === "valid") {
+        return {
+            status: "passed",
+            disposition: "validated",
+            reason: "The declared Artifact candidate passed validation.",
+        };
+    }
+    if (validation.status === "invalid") {
+        return { status: "failed", correctable: true, failure: validation.failure };
+    }
+    const deterministic = deterministicApplicability({
+        task: options.task,
+        changedPaths: options.diff.changed_paths,
+    });
+    const evidence = repoEvidence(options.repoRoot);
+    let applicability = deterministic;
+    if (applicability === null) {
+        const input = {
+            task: options.task,
+            candidate: {
+                changed_paths: boundedChangedPaths(options.diff.changed_paths),
+                diff_facts: redactAndTruncateText(options.diff.summary, MAX_DIFF_FACT_CHARS),
+                repo_evidence: evidence,
+            },
+        };
+        try {
+            applicability = await judgeApplicability(options.judge ?? createDefaultJudge(options), input);
+        }
+        catch (error) {
+            return gateFailure({
+                reasonCode: "artifact_applicability_failed",
+                summary: "Tutti could not determine whether this candidate requires an Artifact.",
+                guidance: "Retry when the Artifact applicability provider is available.",
+                source: "applicability_judge",
+                detail: error instanceof Error ? error.message : "Artifact applicability judge failed",
+                correctable: false,
+            });
+        }
+    }
+    if (applicability.decision === "not_applicable") {
+        return {
+            status: "passed",
+            disposition: "not_applicable",
+            reason: applicability.reason,
+        };
+    }
+    return gateFailure({
+        reasonCode: "artifact_manifest_missing",
+        summary: "This candidate requires a browser-viewable Artifact but does not declare one.",
+        guidance: "Create tutti.artifact.json using the strict static or server contract and make the preview usable.",
+        source: "manifest_parser",
+        detail: `Artifact applicability: ${applicability.reason}. ${ARTIFACT_MANIFEST_PATH} was not found in the candidate.`,
+        correctable: true,
+    });
+}
+//# sourceMappingURL=artifact-applicability.js.map

package/dist/run-pipeline/openai.d.ts

@@ -2,6 +2,9 @@ import type { ProjectId } from "@tutti/shared/ids";
 import type { ApprovalRequestManager } from "../approvals/index.js";
 import type { ControlPlaneLogger, RunPipelineResolution, RunPipelineRunner } from "../control-plane/index.js";
 import type { ProviderUsageRecorder } from "../provider-usage/index.js";
+import type { OpenAiStructuredOutputClient } from "../providers/openai/sdk-procedure-runner.js";
+import type { CandidateArtifactValidationResult, ValidateCandidateArtifactOptions } from "../artifacts/index.js";
+import { type ArtifactApplicabilityJudge } from "./artifact-applicability.js";
 import { type OpenAiProviderConfig } from "../providers/openai/provider-config.js";
 import type { CodexAppServerAgentContextRuntime } from "../providers/openai/app-server/skills.js";
 export { TASK_RUN_OUTPUT_SCHEMA } from "./task-run-output.js";
@@ -24,6 +27,9 @@ export type OpenAiRunPipelineRunnerOptions = {
     baseEnv?: NodeJS.ProcessEnv;
     logger?: ControlPlaneLogger | undefined;
     recordUsage?: ProviderUsageRecorder;
+    artifactApplicabilityClient?: OpenAiStructuredOutputClient;
+    artifactApplicabilityJudge?: ArtifactApplicabilityJudge;
+    validateArtifactCandidate?: (options: ValidateCandidateArtifactOptions) => Promise<CandidateArtifactValidationResult>;
 };
 export type ProjectOpenAiRunPipelineRunnerOptions = {
     tuttiHome: string;

package/dist/run-pipeline/openai.js

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { createNodeNpmCheckPlan, executeCheckPlan } from "../checks/index.js";
 import { candidateChangedAfterChecks } from "./candidate-diff.js";
+import { runArtifactCandidateGate, } from "./artifact-applicability.js";
 import { checkSkipFields, checkStatus, checksSummary, completedWithoutRepoChanges, docsStatusForChangedPaths, failedBeforeChecks, failedFinishedResult, promotionNotAttempted, promotionNotPromoted, successfulRunSummary, } from "./result-projections.js";
 import { runPromotionReconcile } from "./promotion-reconcile.js";
 import { runWorkspaceWriteTask } from "./task-run-invocation.js";
@@ -96,6 +97,8 @@ function stageProgressSummary(stage) {
             return "retrying Codex task after a transient provider failure.";
         case "candidate_diff_collect":
             return "collecting candidate changes.";
+        case "artifact_candidate_validate":
+            return "validating the candidate Artifact preview.";
         case "checks":
             return "running project checks.";
         case "post_checks_diff_collect":
@@ -208,6 +211,12 @@ function buildCorrectionContext(input) {
         summary: input.result.summary,
         reason_code: input.reasonCode,
         guidance: input.guidance,
+        diagnostic: input.diagnostic ?? {
+            source: "pipeline",
+            text: input.result.summary,
+            truncated: false,
+        },
+        promotion_failure: null,
     };
     const promotion = runPipelineResultPromotion(input.result);
     if (promotion?.status === "not_promoted") {
@@ -351,6 +360,54 @@ async function runTaskAttempt(options, input) {
                 guidance: "Produce a concrete candidate diff for the frozen task contract.",
             });
         }
+        const artifactGate = await loggedAsyncStage(options, input, "artifact_candidate_validate", () => runArtifactCandidateGate({
+            repoRoot: runHandle.repo_root,
+            task: {
+                title: input.task.title,
+                goal: input.task_detail.detail.contract.goal,
+                scope: input.task_detail.detail.contract.scope,
+            },
+            diff,
+            config: options.config,
+            apiKey: options.apiKey,
+            ...(options.promptsRoot === undefined ? {} : { promptsRoot: options.promptsRoot }),
+            ...(options.baseEnv === undefined ? {} : { baseEnv: options.baseEnv }),
+            ...(options.artifactApplicabilityClient === undefined
+                ? {}
+                : { client: options.artifactApplicabilityClient }),
+            ...(options.artifactApplicabilityJudge === undefined
+                ? {}
+                : { judge: options.artifactApplicabilityJudge }),
+            ...(options.validateArtifactCandidate === undefined
+                ? {}
+                : { validateCandidate: options.validateArtifactCandidate }),
+            ...(options.recordUsage === undefined ? {} : { recordUsage: options.recordUsage }),
+            activityRef: input.activity_ref,
+            taskId: input.task.id,
+        }), (result) => ({
+            artifact_gate_status: result.status,
+            ...(result.status === "passed"
+                ? { artifact_gate_disposition: result.disposition }
+                : { artifact_reason_code: result.failure.reason_code }),
+        }));
+        if (artifactGate.status === "failed") {
+            const artifactResult = failedBeforeChecks({
+                summary: artifactGate.failure.summary,
+                errorCode: artifactGate.failure.reason_code,
+                retryable: false,
+                changedPaths,
+                promotion: promotionNotAttempted(artifactGate.failure.reason_code, "Artifact candidate validation failed, so promotion was not attempted."),
+            });
+            if (!artifactGate.correctable) {
+                return artifactResult;
+            }
+            return requestSelfCorrection({
+                result: artifactResult,
+                reasonCode: artifactGate.failure.reason_code,
+                guidance: artifactGate.failure.guidance,
+                diagnostic: artifactGate.failure.diagnostic,
+            });
+        }
         let docs = docsStatusForChangedPaths(changedPaths);
         const checkPlan = createNodeNpmCheckPlan({ workspaceRoot: runHandle.repo_root });
         const checks = await loggedAsyncStage(options, input, "checks", () => executeCheckPlan({
@@ -399,14 +456,27 @@ async function runTaskAttempt(options, input) {
         }
         catch (error) {
             if (isMainlineMovedPromotionConflict(error)) {
-                const reconcileResult = await loggedAsyncStage(options, input, "promotion_reconcile", () => runPromotionReconcile({
+                const reconcileOutcome = await loggedAsyncStage(options, input, "promotion_reconcile", () => runPromotionReconcile({
                     options,
                     pipelineInput: input,
                     runHandle,
                     taskOutput,
                     sourceCommit: commit,
                     changedPaths: postChecksDiff.changed_paths,
-                }), runResultLogFields);
+                }), (outcome) => runResultLogFields(outcome.result));
+                const reconcileResult = reconcileOutcome.result;
+                if (reconcileOutcome.artifact_gate_failure !== undefined) {
+                    if (!reconcileOutcome.artifact_gate_failure.correctable) {
+                        return reconcileResult;
+                    }
+                    const artifactFailure = reconcileOutcome.artifact_gate_failure.failure;
+                    return requestSelfCorrection({
+                        result: reconcileResult,
+                        reasonCode: artifactFailure.reason_code,
+                        guidance: artifactFailure.guidance,
+                        diagnostic: artifactFailure.diagnostic,
+                    });
+                }
                 const reasonCode = reconcileSelfCorrectionReason(reconcileResult);
                 if (reasonCode !== undefined) {
                     return requestSelfCorrection({