@mingchuno/agent-workflows 0.1.0 → 0.3.0

package/dist/src/config.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { defaultStageTimeoutMs, defaultValidationTimeoutMs, } from "./defaults.js";
 export const profileSchema = z.strictObject({
     provider: z.enum(["codex", "copilot"]),
     model: z.string().min(1).optional(),
@@ -10,12 +11,24 @@ export const profileSchema = z.strictObject({
     })
         .optional(),
 });
-export const stageSchema = z.strictObject({
+export const stageSchema = z
+    .strictObject({
     profile: profileSchema.partial().optional(),
-    prompt: z.string().default(""),
-    skills: z.array(z.string()).default([]),
-    timeoutMs: z.number().int().positive().default(1_800_000),
-});
+    prompt: z
+        .string()
+        .refine((text) => text.trim().length > 0, "Prompt must be nonblank")
+        .optional(),
+    promptFile: z
+        .string()
+        .refine((text) => text.trim().length > 0, "Prompt file path must be nonblank")
+        .optional(),
+    timeoutMs: z.number().int().positive().default(defaultStageTimeoutMs),
+}, {
+    error: (issue) => issue.code === "unrecognized_keys" && issue.keys.includes("skills")
+        ? "Stage skills was removed; configure skills in your agent runtime and request them in prompt"
+        : undefined,
+})
+    .refine((stage) => stage.prompt === undefined || stage.promptFile === undefined, "Specify either prompt or promptFile, never both");
 export const projectSchema = z.strictObject({
     id: z.string().regex(/^[a-zA-Z0-9_-]+$/),
     checkout: z.string().min(1),
@@ -40,34 +53,26 @@ export const projectSchema = z.strictObject({
         .array(z.strictObject({
         command: z.string().min(1),
         args: z.array(z.string()).default([]),
-        timeoutMs: z.number().int().positive().default(300_000),
+        timeoutMs: z
+            .number()
+            .int()
+            .positive()
+            .default(defaultValidationTimeoutMs),
     }))
         .default([]),
-    gitIdentity: z.strictObject({ name: z.string().min(1), email: z.email() }),
+    includeAgentCoAuthors: z.boolean().default(true),
     agent: profileSchema,
     stages: z
         .strictObject({
-        implementation: stageSchema.default(() => ({
-            prompt: "",
-            skills: [],
-            timeoutMs: 1_800_000,
-        })),
-        writing: stageSchema.default(() => ({
-            prompt: "",
-            skills: [],
-            timeoutMs: 1_800_000,
-        })),
-        review: stageSchema.default(() => ({
-            prompt: "",
-            skills: [],
-            timeoutMs: 1_800_000,
-        })),
+        implementation: stageSchema.prefault({}),
+        publication: stageSchema.prefault({}),
+        review: stageSchema.prefault({}),
+    }, {
+        error: (issue) => issue.code === "unrecognized_keys" && issue.keys.includes("writing")
+            ? "Stage writing was renamed to publication; update projects.stages.writing"
+            : undefined,
     })
-        .default(() => ({
-        implementation: { prompt: "", skills: [], timeoutMs: 1_800_000 },
-        writing: { prompt: "", skills: [], timeoutMs: 1_800_000 },
-        review: { prompt: "", skills: [], timeoutMs: 1_800_000 },
-    })),
+        .prefault({}),
 });
 export const configSchema = z.strictObject({
     id: z.string().regex(/^[a-zA-Z0-9_-]+$/),

package/dist/src/defaults.d.ts

@@ -0,0 +1,2 @@
+export declare const defaultStageTimeoutMs = 1800000;
+export declare const defaultValidationTimeoutMs = 300000;

package/dist/src/defaults.js

@@ -0,0 +1,2 @@
+export const defaultStageTimeoutMs = 1_800_000;
+export const defaultValidationTimeoutMs = 300_000;

package/dist/src/domain.d.ts

@@ -21,14 +21,16 @@ export declare const publicationSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type Publication = z.infer<typeof publicationSchema>;
 export declare const reviewSchema: z.ZodObject<{
+    complete: z.ZodBoolean;
+    limitations: z.ZodArray<z.ZodString>;
     summary: z.ZodString;
     findings: z.ZodArray<z.ZodObject<{
         body: z.ZodString;
-        path: z.ZodOptional<z.ZodString>;
-        line: z.ZodOptional<z.ZodNumber>;
+        path: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        line: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
-export type Review = z.infer<typeof reviewSchema>;
+export type Review = z.input<typeof reviewSchema>;
 export interface ValidationResult {
     command: string;
     args: string[];
@@ -45,6 +47,11 @@ export interface Snapshot {
     paths: string[];
     files: Record<string, string | null>;
 }
+export interface ContributionCandidate {
+    provider: string;
+    beforeFiles: Record<string, string | null>;
+    afterFiles: Record<string, string | null>;
+}
 export interface Workspace {
     check(project: Project): Promise<void>;
     prepare(project: Project, branch: string, signal?: AbortSignal): Promise<Snapshot>;
@@ -84,7 +91,7 @@ export interface AgentInvocation {
     cwd: string;
     prompt: string;
     profile: AgentProfile;
-    skills: string[];
+    outputSchema?: unknown;
     processFile?: string;
     readOnly: boolean;
     signal: AbortSignal;
@@ -104,6 +111,22 @@ export interface AgentAdapter {
     invoke(invocation: AgentInvocation): Promise<string>;
 }
 export type Outcome = "queued" | "running" | "completed" | "failed" | "blocked" | "cancelled" | "no-change" | "ineligible";
+export interface ExecutionRecord {
+    /** DBOS workflow identity; publication markers continue to use the run ID. */
+    id: string;
+    recoveryOf?: string;
+    startStep?: number;
+    reusedSteps?: string[];
+    fingerprint: string;
+    recoverySupported: boolean;
+    createdAt: string;
+    startedAt?: string;
+    finishedAt?: string;
+    outcome: Outcome;
+    phase: string;
+    failedStep?: number;
+    error?: string;
+}
 export interface RunRecord {
     id: string;
     projectId: string;
@@ -122,10 +145,14 @@ export interface RunRecord {
     snapshot?: Snapshot;
     validation?: ValidationResult[];
     publication?: Publication;
+    contributionCandidates?: ContributionCandidate[];
+    contributingProviders?: string[];
     change?: ChangeRequest;
     review?: Review;
     reviewHead?: string;
     error?: string;
+    failedStep?: number;
+    executions?: ExecutionRecord[];
 }
 export declare class BlockedError extends Error {
     constructor(message: string);

package/dist/src/domain.js

@@ -4,13 +4,20 @@ export const publicationSchema = z.strictObject({
     title: z.string().trim().min(1).max(240),
     description: z.string().trim().min(1).max(60000),
 });
-export const reviewSchema = z.strictObject({
+export const reviewSchema = z
+    .strictObject({
+    complete: z.boolean(),
+    limitations: z.array(z.string().trim().min(1)),
     summary: z.string().min(1),
     findings: z.array(z.strictObject({
         body: z.string().min(1),
-        path: z.string().optional(),
-        line: z.number().int().positive().optional(),
+        path: z.string().nullable().default(null),
+        line: z.number().int().positive().nullable().default(null),
     })),
+})
+    .refine((review) => review.complete || review.limitations.length > 0, {
+    message: "Incomplete review requires at least one inspection limitation",
+    path: ["limitations"],
 });
 export class BlockedError extends Error {
     constructor(message) {

package/dist/src/evidence.d.ts

@@ -0,0 +1,54 @@
+import type { Project } from "./config.js";
+import { type Snapshot } from "./domain.js";
+export declare const evidenceLimits: {
+    readonly chunkBytes: number;
+    readonly totalBytes: number;
+};
+interface Artifact {
+    path: string;
+    sha256: string;
+    bytes: number;
+}
+export interface ChangeEvidence {
+    index: string;
+    identity: string;
+    files: Artifact[];
+    changedPaths: number;
+    base: string;
+    head?: string;
+    snapshot?: string;
+}
+/** Split even single long lines, preserving UTF-8 and exact reconstruction. */
+export declare function chunkText(text: string): string[];
+export declare class EvidenceWriter {
+    readonly directory: string;
+    readonly files: Artifact[];
+    private bytes;
+    constructor(directory: string);
+    write(name: string, content: string): Promise<Artifact>;
+    index(contents: string, metadata: Record<string, unknown>): Promise<Artifact>;
+    chunks(prefix: string, content: string): Promise<{
+        path: string;
+        sha256: string;
+        bytes: number;
+        ordinal: number;
+        byteOffset: number;
+        startLine: number;
+    }[]>;
+}
+interface CaptureOptions {
+    project: Project;
+    directory: string;
+    snapshot: Snapshot;
+    revisions?: {
+        base: string;
+        head: string;
+    };
+    signal?: AbortSignal;
+}
+export declare function captureEvidence(options: CaptureOptions): Promise<ChangeEvidence>;
+export declare function verifyEvidence(evidence: ChangeEvidence): Promise<void>;
+export declare function evidenceContext(evidence: ChangeEvidence): string;
+/** Resolve through existing ancestors, rejecting source-tree writes before mkdir. */
+export declare function assertEvidenceDirectory(checkout: string, requested: string): Promise<string>;
+export {};

package/dist/src/evidence.js

@@ -0,0 +1,214 @@
+import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { BlockedError } from "./domain.js";
+import { sha256 } from "./prompts.js";
+import { command, maxCapturedOutputBytes } from "./runtime/process.js";
+export const evidenceLimits = {
+    chunkBytes: 64 * 1024,
+    totalBytes: maxCapturedOutputBytes,
+};
+/** Split even single long lines, preserving UTF-8 and exact reconstruction. */
+export function chunkText(text) {
+    const buffer = Buffer.from(text);
+    const chunks = [];
+    for (let start = 0; start < buffer.length;) {
+        let end = Math.min(start + evidenceLimits.chunkBytes, buffer.length);
+        while (end < buffer.length && (buffer[end] & 0xc0) === 0x80)
+            end--;
+        chunks.push(buffer.subarray(start, end).toString("utf8"));
+        start = end;
+    }
+    return chunks;
+}
+export class EvidenceWriter {
+    directory;
+    files = [];
+    bytes = 0;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    async write(name, content) {
+        const bytes = Buffer.byteLength(content);
+        const total = this.bytes + bytes;
+        if (total > evidenceLimits.totalBytes)
+            throw new BlockedError(`Change evidence size ${total} bytes exceeds limit ${evidenceLimits.totalBytes} bytes`);
+        if (bytes > evidenceLimits.chunkBytes)
+            throw new BlockedError(`Evidence chunk size ${bytes} exceeds limit ${evidenceLimits.chunkBytes}`);
+        const artifact = {
+            path: resolve(this.directory, name),
+            sha256: sha256(content),
+            bytes,
+        };
+        await writeFile(artifact.path, content, { mode: 0o600, flag: "wx" });
+        this.bytes = total;
+        this.files.push(artifact);
+        return artifact;
+    }
+    async index(contents, metadata) {
+        let pages = await this.chunks("index", contents);
+        let depth = 0;
+        const serialize = () => JSON.stringify({
+            version: 1,
+            ...metadata,
+            indexDepth: depth,
+            instructions: "At depth 0, concatenate pages as JSONL change entries. At greater depth, concatenate pages as a JSON array of page references and descend one level. Read ordered patch chunks; hunk headers carry original line numbers. Untracked content starts at line 1. Report incomplete inspection explicitly.",
+            pages,
+        });
+        while (Buffer.byteLength(serialize()) > evidenceLimits.chunkBytes) {
+            depth++;
+            pages = await this.chunks(`catalog-${depth}`, JSON.stringify(pages));
+        }
+        return this.write("index.json", serialize());
+    }
+    async chunks(prefix, content) {
+        const result = [];
+        let byteOffset = 0, line = 1;
+        for (const [ordinal, part] of chunkText(content).entries()) {
+            result.push({
+                ...(await this.write(`${prefix}-${ordinal}.txt`, part)),
+                ordinal,
+                byteOffset,
+                startLine: line,
+            });
+            byteOffset += Buffer.byteLength(part);
+            line += part.split("\n").length - 1;
+        }
+        return result;
+    }
+}
+export async function captureEvidence(options) {
+    const { project, snapshot, revisions, signal } = options;
+    const checkout = await realpath(project.checkout);
+    const directory = await assertEvidenceDirectory(checkout, options.directory);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const writer = new EvidenceWriter(directory);
+    const git = async (...args) => (await command("git", args, { cwd: checkout, signal, strictUtf8: true }))
+        .stdout;
+    const diff = (...args) => git("--literal-pathspecs", "diff", "--no-ext-diff", "--no-textconv", "--no-renames", "--full-index", ...args);
+    const split = (text) => text.split("\0").filter(Boolean);
+    const untracked = revisions
+        ? []
+        : split(await git("ls-files", "--others", "--exclude-standard", "-z"));
+    const paths = revisions
+        ? split(await diff("--name-only", "-z", revisions.base, revisions.head))
+        : [
+            ...new Set([
+                ...snapshot.paths,
+                ...split(await diff("--cached", "--name-only", "-z")),
+                ...split(await diff("--name-only", "-z")),
+                ...untracked,
+            ]),
+        ].sort();
+    const entries = [];
+    for (const [number, path] of paths.entries()) {
+        signal?.throwIfAborted();
+        if (untracked.includes(path)) {
+            const content = await readFile(resolve(checkout, path));
+            let text;
+            try {
+                if (!content.includes(0))
+                    text = new TextDecoder("utf-8", {
+                        fatal: true,
+                        ignoreBOM: true,
+                    }).decode(content);
+            }
+            catch {
+                /* Binary metadata is intentional. */
+            }
+            entries.push({
+                path,
+                kind: "untracked",
+                change: "added",
+                sha256: sha256(content),
+                bytes: content.length,
+                binary: text === undefined,
+                reason: text === undefined
+                    ? "Binary or non-UTF-8 content; metadata only"
+                    : undefined,
+                chunks: text === undefined ? [] : await writer.chunks(`file-${number}`, text),
+            });
+        }
+        const ranges = revisions
+            ? [{ kind: "published", args: [revisions.base, revisions.head] }]
+            : [
+                { kind: "staged", args: ["--cached", snapshot.head] },
+                { kind: "unstaged", args: [] },
+            ];
+        for (const range of ranges) {
+            const patch = await diff(...range.args, "--", path);
+            if (!patch)
+                continue;
+            const blobs = /^index ([0-9a-f]+)\.\.([0-9a-f]+)/m.exec(patch);
+            entries.push({
+                path,
+                kind: range.kind,
+                change: /^new file mode /m.test(patch)
+                    ? "added"
+                    : /^deleted file mode /m.test(patch)
+                        ? "deleted"
+                        : "modified",
+                blobs: blobs ? { before: blobs[1], after: blobs[2] } : undefined,
+                sha256: sha256(patch),
+                binary: /^Binary files /m.test(patch),
+                reason: /^Binary files /m.test(patch)
+                    ? "Git binary change; metadata only"
+                    : undefined,
+                // Patch headers/hunks preserve original old/new line numbers. Offsets support split long lines.
+                chunks: await writer.chunks(`patch-${number}-${range.kind}`, patch),
+            });
+        }
+    }
+    const identity = {
+        base: revisions?.base ?? snapshot.head,
+        ...(revisions
+            ? { head: revisions.head }
+            : { snapshot: snapshot.fingerprint }),
+    };
+    const index = await writer.index(entries.map((entry) => JSON.stringify(entry)).join("\n") + "\n", { ...identity, changedPaths: paths.length });
+    const evidence = {
+        ...identity,
+        index: index.path,
+        identity: index.sha256,
+        files: writer.files,
+        changedPaths: paths.length,
+    };
+    await verifyEvidence(evidence);
+    return evidence;
+}
+export async function verifyEvidence(evidence) {
+    for (const file of evidence.files) {
+        const content = await readFile(file.path).catch((cause) => {
+            throw new BlockedError(`Required change evidence unavailable: ${file.path}: ${String(cause)}`);
+        });
+        if (content.length !== file.bytes || sha256(content) !== file.sha256)
+            throw new BlockedError(`Change evidence changed: ${file.path}`);
+    }
+}
+export function evidenceContext(evidence) {
+    return `Change evidence index: ${evidence.index}\nIdentity: ${evidence.identity}\nBase: ${evidence.base}\nHead: ${evidence.head ?? "verified dirty snapshot"}\nChanged paths: ${evidence.changedPaths}\nRead the index and its ordered artifacts incrementally. Use read-only tools and do not edit files. Required evidence must be readable; never infer missing content. Binary content is metadata-only.`;
+}
+/** Resolve through existing ancestors, rejecting source-tree writes before mkdir. */
+export async function assertEvidenceDirectory(checkout, requested) {
+    const canonicalCheckout = await realpath(checkout);
+    let ancestor = resolve(requested);
+    const suffix = [];
+    while (true) {
+        try {
+            const canonical = await realpath(ancestor);
+            const destination = resolve(canonical, ...suffix);
+            const location = relative(canonicalCheckout, destination);
+            if (!location ||
+                (!isAbsolute(location) &&
+                    location !== ".." &&
+                    !location.startsWith(`..${sep}`)))
+                throw new BlockedError("State directory for change evidence must be outside the managed checkout");
+            return destination;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            suffix.unshift(relative(dirname(ancestor), ancestor));
+            ancestor = dirname(ancestor);
+        }
+    }
+}

package/dist/src/index.d.ts

@@ -3,6 +3,7 @@ export * from "./adapters/hosting.js";
 export * from "./config.js";
 export * from "./domain.js";
 export * from "./operations.js";
+export * from "./prompts.js";
 export * from "./runner.js";
 export * from "./store.js";
 export * from "./workspace.js";

package/dist/src/index.js

@@ -3,6 +3,7 @@ export * from "./adapters/hosting.js";
 export * from "./config.js";
 export * from "./domain.js";
 export * from "./operations.js";
+export * from "./prompts.js";
 export * from "./runner.js";
 export * from "./store.js";
 export * from "./workspace.js";

package/dist/src/invocation.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { type Stage } from "./config.js";
+import { type ContributionCandidate, type RunRecord, type Snapshot } from "./domain.js";
+import { type ChangeEvidence } from "./evidence.js";
+import type { OperationDependencies } from "./operations.js";
+export interface InvocationTask {
+    defaultPrompt: string;
+    context?: (run: RunRecord) => string;
+    readOnly?: boolean;
+    outputContract?: z.ZodType;
+    evidence?: ChangeEvidence;
+}
+interface StageExecution {
+    run: RunRecord;
+    name: string;
+    stage: Stage;
+    task: InvocationTask;
+    stepId: number;
+    dependencies: OperationDependencies;
+    saveImplementationSnapshot: (runId: string, snapshot: Snapshot, provider: string) => Promise<ContributionCandidate | undefined>;
+    acceptContribution: (runId: string, candidate: ContributionCandidate) => Promise<void>;
+}
+/** One logical stage; only returned format errors admit a second response attempt. */
+export declare function invokeStage({ run, name, stage, task, stepId, dependencies, saveImplementationSnapshot, acceptContribution, }: StageExecution): Promise<string>;
+export {};

package/dist/src/invocation.js

@@ -0,0 +1,166 @@
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { resolveProfile } from "./config.js";
+import { BlockedError, } from "./domain.js";
+import { verifyEvidence } from "./evidence.js";
+import { resolveStagePrompt, sha256 } from "./prompts.js";
+const maxInvocationAttempts = 2;
+/** One logical stage; only returned format errors admit a second response attempt. */
+export async function invokeStage({ run, name, stage, task, stepId, dependencies, saveImplementationSnapshot, acceptContribution, }) {
+    const { store, project, agents, signal, workspace, redact } = dependencies;
+    const previous = (await store.invocations(run.id)).filter((item) => item.stepId === stepId);
+    if (previous.length) {
+        for (const record of previous) {
+            if (record.outcome !== "running")
+                continue;
+            record.outcome = "interrupted";
+            record.finishedAt = new Date().toISOString();
+            if (!record.sessionId)
+                record.sessionState = "unavailable";
+            await store.saveInvocation(record);
+        }
+        throw new BlockedError(`Interrupted agent stage ${name}; inspect existing sessions before explicit retry`);
+    }
+    if (!run.snapshot)
+        throw new BlockedError("Missing workspace snapshot");
+    await workspace.verify(project, run.snapshot);
+    if (task.evidence)
+        await verifyEvidence(task.evidence);
+    const resolved = resolveStagePrompt(stage, task.defaultPrompt, dependencies.promptBaseDirectory);
+    const outputSchema = task.outputContract
+        ? z.toJSONSchema(task.outputContract)
+        : undefined;
+    const contract = outputSchema
+        ? `Return ONLY JSON satisfying this application-owned schema:\n${JSON.stringify(outputSchema)}`
+        : "";
+    const fullPrompt = [
+        resolved.content,
+        `Run context:\n${task.context?.(run) ?? ""}`,
+        task.readOnly
+            ? "Inspection only. Do not modify files, commit, push, or publish."
+            : "Do not commit, push, or publish.",
+        contract,
+    ].join("\n\n");
+    const profile = resolveProfile(project.agent, stage.profile);
+    const adapter = agents[profile.provider];
+    if (!adapter)
+        throw new Error(`Missing agent adapter ${profile.provider}`);
+    const deadline = Date.now() + stage.timeoutMs;
+    const invocationSignal = AbortSignal.any([
+        signal,
+        AbortSignal.timeout(stage.timeoutMs),
+    ]);
+    const effective = await adapter.validate(profile, invocationSignal);
+    const directory = join(dependencies.artifacts, run.id);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    let correction = "";
+    let pendingContribution;
+    for (let attempt = 1; attempt <= maxInvocationAttempts; attempt++) {
+        invocationSignal.throwIfAborted();
+        const expected = (await store.run(run.id)).snapshot;
+        await workspace.verify(project, expected);
+        if (task.evidence)
+            await verifyEvidence(task.evidence);
+        const id = randomUUID();
+        const prompt = fullPrompt + correction;
+        const readOnly = task.readOnly === true || attempt === maxInvocationAttempts;
+        const record = {
+            id,
+            runId: run.id,
+            projectId: project.id,
+            step: name,
+            stepId,
+            attempt,
+            provider: profile.provider,
+            sessionId: null,
+            sessionState: "pending",
+            requested: profile,
+            effective,
+            prompt: redact(prompt),
+            taskPrompt: { ...resolved, content: redact(resolved.content) },
+            outputContract: outputSchema
+                ? sha256(JSON.stringify(outputSchema))
+                : undefined,
+            evidence: task.evidence,
+            outcome: "running",
+            startedAt: new Date().toISOString(),
+            log: join(directory, `${id}.jsonl`),
+        };
+        await store.saveInvocation(record);
+        try {
+            invocationSignal.throwIfAborted();
+            const output = await adapter.invoke({
+                id,
+                runId: run.id,
+                step: name,
+                cwd: project.checkout,
+                prompt,
+                profile,
+                outputSchema,
+                processFile: record.log + ".process.json",
+                readOnly,
+                signal: invocationSignal,
+                timeoutMs: Math.max(1, deadline - Date.now()),
+                session: async (sessionId) => {
+                    record.sessionId = sessionId;
+                    record.sessionState = "available";
+                    await store.saveInvocation(record);
+                },
+                event: async (event) => {
+                    await appendFile(record.log, redact(JSON.stringify(event)) + "\n", {
+                        mode: 0o600,
+                    });
+                },
+            });
+            await appendFile(record.log, "", { mode: 0o600 });
+            invocationSignal.throwIfAborted();
+            if (readOnly)
+                await workspace.verify(project, expected);
+            else
+                pendingContribution = await saveImplementationSnapshot(run.id, expected, profile.provider);
+            if (task.evidence)
+                await verifyEvidence(task.evidence);
+            invocationSignal.throwIfAborted();
+            // Only returned output validation failures qualify for correction.
+            let parsed;
+            try {
+                parsed = task.outputContract
+                    ? task.outputContract.parse(JSON.parse(output))
+                    : undefined;
+            }
+            catch (error) {
+                if (!(error instanceof SyntaxError) && !(error instanceof z.ZodError))
+                    throw error;
+                record.outcome = "invalid-output";
+                record.validationError = redact(String(error));
+                await appendFile(record.log, redact(JSON.stringify({
+                    type: "invalid-output",
+                    output,
+                    error: String(error),
+                })) + "\n");
+                if (attempt === maxInvocationAttempts)
+                    throw new Error(`Invalid output after one correction: ${String(error)}`);
+                correction = `\n\nCorrect the prior response format in this fresh inspection-only session. Do not modify files.\nPrior invalid response:\n${output}\nValidation errors:\n${String(error)}`;
+                continue;
+            }
+            if (pendingContribution)
+                await acceptContribution(run.id, pendingContribution);
+            record.outcome = "completed";
+            return redact(task.outputContract ? JSON.stringify(parsed) : output);
+        }
+        catch (error) {
+            if (record.outcome === "running")
+                record.outcome = "failed";
+            throw error;
+        }
+        finally {
+            record.finishedAt = new Date().toISOString();
+            if (!record.sessionId)
+                record.sessionState = "unavailable";
+            await store.saveInvocation(record);
+        }
+    }
+    throw new Error("Format correction exhausted");
+}