@clemrig/factory 0.6.0 → 0.7.0

package/dist/app/workflows/implement.js

@@ -2,16 +2,18 @@ import { agent, code, defineWorkflow, END, gate, node, retry, schemaGate, step,
 import { isSlug } from "../../domain/issue.js";
 import { planCommitMessage, planOutput, planProblem, renderPlan, } from "../../domain/plan.js";
 import { DELIVERY } from "../../domain/delivery.js";
-import { pullRequestBody } from "../../domain/pull-request.js";
+import { descriptionOutput, descriptionProblems, maxScreenshotBytes, } from "../../domain/description.js";
+import { ghVersionProblem, maxBodyLength, mergeDangerLine, pullRequestBody, } from "../../domain/pull-request.js";
 import { implementationOutput, implementationProblem, largeChangeLines, reviewChanges, reviewOutput, reviewProblem, } from "../../domain/review.js";
 import { parseSpec } from "../../domain/spec.js";
-import { failureFeedback, seconds, } from "../../domain/verification.js";
+import { failureFeedback, seconds } from "../../domain/verification.js";
+import { closeBrowser, runBrowser } from "../../system/browser.js";
 import { runChecks } from "../../system/checks.js";
 import * as git from "../../system/git.js";
 import * as github from "../../system/github.js";
 import { withTreeLock } from "../../system/lock.js";
 import { artifactPath, hasArtifact, isIssue, readArtifact, writeArtifact, } from "../../system/issues.js";
-import { fileName, keepInRun } from "../../system/run-files.js";
+import { keepCheckOutputs, keepFailedCheck, keepInRun, screenshotProblems, screenshotsFolder, } from "../../system/run-files.js";
 function facts(state) {
     return state.data;
 }
@@ -27,6 +29,11 @@ function reviewSession(state) {
     const restarts = state.retries?.["review.modified"] ?? 0;
     return `review-${reviewRounds(state)}${restarts > 0 ? `-${restarts}` : ""}`;
 }
+/** One conversation for the description, a new one once it changed the repository. */
+function describeSession(state) {
+    const restarts = state.retries?.["describe.modified"] ?? 0;
+    return `describe${restarts > 0 ? `-${restarts}` : ""}`;
+}
 function short(commit) {
     return commit.slice(0, 7);
 }
@@ -42,21 +49,42 @@ function journalChecks(log, where = "") {
             log(`${check.name} passed in ${seconds(event.durationMs)}`);
     };
 }
-/** The dependencies of the spec that are not delivered: no plan.md on the main branch, which is checked out. */
-async function undeliveredDependencies(dir, slug, base, spec) {
+/** The dependencies that are not delivered: no plan.md on the main branch, which is checked out. */
+async function dependencyProblems(dir, slug, base, dependencies) {
     const problems = [];
-    for (const dependency of spec.dependencies) {
+    for (const dependency of dependencies) {
         if (await hasArtifact(dir, dependency, "plan"))
             continue;
-        if (!(await isIssue(dir, dependency)))
-            problems.push(`Issue ${slug} depends on ${dependency}, which is no issue of .factory/issues/: fix spec.md with the issue skill (/issue ${slug})`);
-        else
+        if (await isIssue(dir, dependency))
             problems.push(`Issue ${slug} depends on ${dependency}, which is not delivered (its plan.md is not on ${base}): deliver it first, or revise the dependency with the issue skill (/issue ${slug})`);
+        else
+            problems.push(`Issue ${slug} depends on ${dependency}, which is no issue of .factory/issues/: fix spec.md with the issue skill (/issue ${slug})`);
     }
     return problems;
 }
+const message = (error) => error instanceof Error ? error.message : String(error);
+/** The repository on GitHub, when gh is recent enough and logged in to open its pull request; otherwise why not. */
+async function gitHubProblems(dir) {
+    const problems = [];
+    const version = await github
+        .version(dir)
+        .then(ghVersionProblem, (error) => message(error));
+    if (version)
+        problems.push(version);
+    if (!(await github.isAuthenticated(dir))) {
+        problems.push("gh is not logged in: run gh auth login");
+        return { problems };
+    }
+    try {
+        return { repository: await github.repository(dir), problems };
+    }
+    catch (error) {
+        problems.push(`gh cannot read the repository on GitHub: ${message(error)}`);
+        return { problems };
+    }
+}
 /** Every reason not to start, found without changing anything; then the base must pass its checks. */
-async function prepare(definition, { dir, state, log }) {
+async function prepare(definition, { dir, state, log, runDir }) {
     const slug = String(state.input.issue);
     const base = await git.defaultBranch(dir);
     const problems = [];
@@ -78,18 +106,23 @@ async function prepare(definition, { dir, state, log }) {
     else if (!spec.ok)
         problems.push(...spec.problems.map((problem) => `spec.md: ${problem}`), `Fix spec.md with the issue skill (/issue ${slug}), then commit and push it`);
     else
-        problems.push(...(await undeliveredDependencies(dir, slug, base, spec.value)));
+        problems.push(...(await dependencyProblems(dir, slug, base, spec.value.dependencies)));
     if (await hasArtifact(dir, slug, "plan"))
         problems.push(`Issue ${slug} is already delivered (its plan.md is on ${base}): start a new issue`);
-    if (!(await github.isAuthenticated(dir)))
-        problems.push("gh is not logged in: run gh auth login");
-    if (problems.length > 0 || !spec?.ok || text === undefined)
+    const { repository, problems: gitHub } = await gitHubProblems(dir);
+    problems.push(...gitHub);
+    if (problems.length > 0 || !spec?.ok || text === undefined || !repository)
         throw new Error(["Cannot start:", ...problems.map((problem) => `- ${problem}`)].join("\n"));
     log(`Starting point valid: ${base} matches origin, spec with ${spec.value.criteria.length} criteria, gh logged in`);
     const baseCommit = await git.commitOf(dir, "HEAD");
-    const checks = await runChecks(dir, definition.verify, journalChecks(log, ` on ${base}`));
+    // Nothing changed on the base yet: the checks with `when` wait for a change.
+    const checks = await runChecks(dir, definition.verify, [], journalChecks(log, ` on ${base}`));
     if (!checks.ok)
         throw new Error(`${base} does not pass its own checks:\n${failureFeedback(checks.check, checks.cause, checks.output)}`);
+    // Kept in the run's folder, outside the repository: made before the run
+    // takes the tree, so that a failure leaves it on the main branch.
+    const browser = await runBrowser(dir, runDir);
+    const screenshotsDir = await screenshotsFolder(runDir);
     // One run at a time per working tree: another one started during the checks
     // may have moved it. Checking and taking the tree happen under one lock, so
     // that two runs never both find it free; the branch starts from the approved
@@ -106,87 +139,189 @@ async function prepare(definition, { dir, state, log }) {
         slug,
         title: spec.value.title,
         spec: text,
+        objective: spec.value.objective,
         criteria: spec.value.criteria,
+        repository,
+        ...(browser ? { browser } : {}),
+        screenshotsDir,
         base,
         baseCommit,
         specPath: artifactPath(slug, "spec"),
         planPath: artifactPath(slug, "plan"),
     };
 }
-/** The implementing agent may not commit, switch branches or touch .factory/: the run stops if it did. */
-async function guard({ dir, state }) {
+/** The agents work on the plan's commit, on the issue's branch: the run stops if one committed or switched branches. */
+async function ensureOnPlanCommit({ dir, state }, agentName) {
     const { slug, planCommit } = facts(state);
     if ((await git.commitOf(dir, "HEAD")) !== planCommit ||
         (await git.currentBranch(dir)) !== slug)
-        throw new Error("The implementing agent committed or switched branches: the run stops");
-    if (await git.hasChanges(dir, ".factory"))
+        throw new Error(`The ${agentName} agent committed or switched branches: the run stops`);
+}
+/** The implementing agent may not commit, switch branches or touch .factory/: the run stops if it did. */
+async function guard(context) {
+    await ensureOnPlanCommit(context, "implementing");
+    if (await git.hasChanges(context.dir, ".factory"))
         throw new Error("The implementing agent changed .factory/: the run stops");
 }
 /**
- * The reviewing agent, which may run commands but never change the repository.
- * The tree the diff stage gave it to read is put back before its call, in case
- * an earlier review stopped without putting back what it left, and after it:
- * what it changed is put back, and the review starts again. Committing or
- * switching branches stops the run.
+ * Closes the agents' browser once an agent's call is over, failed or not:
+ * Playwright CLI keeps it open after the agent that opened it. Every session
+ * of the run's workspace is closed, those a stopped call left included.
  */
-function review(profile) {
-    const call = agent({
-        profile,
-        schema: reviewOutput,
-        session: reviewSession,
-        context: ({ state }) => {
-            const { slug, spec, changes, checks } = facts(state);
-            return { issue: slug, spec, changes, checks };
-        },
-    });
+function closingBrowser(stage) {
     return {
-        ...call,
-        outcomes: ["ok", "modified"],
+        ...stage,
         async run(context) {
-            const { dir, state, log } = context;
-            const { slug, planCommit, reviewedTree } = facts(state);
-            const putBack = async () => {
-                if ((await git.commitOf(dir, "HEAD")) !== planCommit ||
-                    (await git.currentBranch(dir)) !== slug)
-                    throw new Error("The reviewing agent committed or switched branches: the run stops");
-                return git.putBack(dir, reviewedTree);
-            };
-            const modified = (changed, why) => {
-                log(`The review changed ${changed.join(", ")}${why}: put back`);
-                return {
-                    outcome: "modified",
-                    reason: `The review changed the repository (${changed.join(", ")})${why}: put back, the review starts again`,
-                    feedback: `A previous review changed ${changed.join(", ")}; the run put them back as they were. Review the change again, without modifying anything in the repository.`,
-                };
-            };
-            // Left by a review that stopped before putting it back: it counts as
-            // that review's change, so it starts again in a new conversation.
-            const left = await putBack();
-            if (left.length > 0)
-                return modified(left, " before the run could put it back");
-            let result;
-            let failure;
             try {
-                result = await call.run(context);
-            }
-            catch (error) {
-                failure = error;
+                return await stage.run(context);
             }
-            // What the agent changed is put back even when its call failed; a
-            // review that changed it starts again in a new conversation, the same
-            // way whether its call failed or not.
-            const changed = await putBack();
-            if (changed.length === 0) {
-                if (result)
-                    return result;
-                throw failure;
+            finally {
+                const { browser } = facts(context.state);
+                const problem = browser && (await closeBrowser(browser));
+                if (problem)
+                    context.log(`Could not close the agents' browser: ${problem}`);
             }
-            return modified(changed, result
-                ? ""
-                : ` and its call failed (${failure instanceof Error ? failure.message : String(failure)})`);
         },
     };
 }
+/** The agents that read the change without changing the repository: the review, then the description. */
+const readers = {
+    review: {
+        name: "review",
+        agent: "reviewing",
+        again: "Review the change again",
+    },
+    describe: {
+        name: "description",
+        agent: "describing",
+        again: "Describe the change again",
+    },
+};
+/** Puts back the tree the reader reads, as the diff stage recorded it; returns the paths it put back. */
+async function putBackReviewedTree(context, reader) {
+    await ensureOnPlanCommit(context, reader.agent);
+    return git.putBack(context.dir, facts(context.state).reviewedTree);
+}
+/** The reader changed the repository, which the run put back: it starts again in a new conversation. */
+function readerModified(log, reader, changed, why) {
+    const paths = changed.join(", ");
+    const after = why ? ` ${why}` : "";
+    log(`The ${reader.name} changed ${paths}${after}: put back`);
+    return {
+        outcome: "modified",
+        reason: `The ${reader.name} changed the repository (${paths})${after}: put back, the ${reader.name} starts again`,
+        feedback: `A previous ${reader.name} changed ${paths}; the run put them back as they were. ${reader.again}, without modifying anything in the repository.`,
+    };
+}
+/**
+ * An agent that may run commands but never change the repository. The tree
+ * it reads is put back before its call and after it, even when the call
+ * fails; what it changed makes it start again.
+ */
+function reading(reader, stage) {
+    return closingBrowser({
+        ...stage,
+        outcomes: ["ok", "modified"],
+        async run(context) {
+            // Left by a call that stopped before the run put it back: it counts
+            // as that call's change.
+            const left = await putBackReviewedTree(context, reader);
+            if (left.length > 0)
+                return readerModified(context.log, reader, left, "before the run could put it back");
+            const ended = await stage.run(context).then((result) => ({ result }), (error) => ({ error }));
+            const changed = await putBackReviewedTree(context, reader);
+            if (changed.length > 0)
+                return readerModified(context.log, reader, changed, "error" in ended
+                    ? `and its call failed (${message(ended.error)})`
+                    : undefined);
+            if ("error" in ended)
+                throw ended.error;
+            return ended.result;
+        },
+    });
+}
+/** The agents' browser, in the request of the agents that may use it. */
+function browserContext(state) {
+    const { browser } = facts(state);
+    return browser ? { browser } : {};
+}
+/**
+ * The reviewing agent: it judges the change against the spec, from the code
+ * and the checks alone. From the second round on, it first reviews the change
+ * knowing nothing of the earlier reviews, then, in the same conversation,
+ * checks what the previous one found against the code as it is now, and gives
+ * its whole review again: nothing found earlier is lost on the way.
+ */
+function review(profile) {
+    const call = (context) => agent({ profile, schema: reviewOutput, session: reviewSession, context });
+    const fresh = call(({ state }) => {
+        const { slug, spec, changes, checks } = facts(state);
+        return { issue: slug, spec, changes, checks, ...browserContext(state) };
+    });
+    const recheck = call(({ state }) => ({
+        previous: facts(state).reviews?.at(-1),
+    }));
+    return reading(readers.review, {
+        ...fresh,
+        async run(context) {
+            const first = await fresh.run(context);
+            if ((facts(context.state).reviews ?? []).length === 0)
+                return first;
+            return recheck.run(context);
+        },
+    });
+}
+/**
+ * The describing agent: once the change is approved, it explains it to a
+ * reader who forgot its issue, and takes its screenshots. It never reads the
+ * implementing agent's account of its own work.
+ */
+function describe(profile) {
+    return reading(readers.describe, agent({
+        profile,
+        schema: descriptionOutput,
+        session: describeSession,
+        context: ({ state }) => {
+            const f = facts(state);
+            return {
+                issue: f.slug,
+                spec: f.spec,
+                plan: f.plan,
+                changes: f.changes,
+                checks: f.checks,
+                review: f.review,
+                deviations: f.implementation.deviations,
+                repository: { public: f.repository.public },
+                screenshots: f.screenshotsDir,
+                ...browserContext(state),
+            };
+        },
+    }));
+}
+/** What the pull request shows, from the run's data; its screenshots `pending` until attached. */
+function pullRequestFacts(state, description, pending) {
+    const f = facts(state);
+    return {
+        objective: f.objective,
+        criteria: f.criteria,
+        deviations: f.implementation.deviations,
+        assumptions: f.plan.risks,
+        review: f.review,
+        acceptedReview: f.acceptedReview === true,
+        reviewRounds: reviewRounds(state),
+        resolved: (f.reviews ?? []).flatMap(({ resolved = [] }) => resolved),
+        checks: f.checks,
+        skippedChecks: f.skippedChecks,
+        files: f.changes.files,
+        description,
+        screenshotsPending: pending,
+        links: {
+            spec: `${f.repository.url}/blob/${f.baseCommit}/${f.specPath}`,
+            plan: `${f.repository.url}/blob/${f.planCommit}/${f.planPath}`,
+        },
+        runId: state.id,
+    };
+}
 /**
  * A failed run resumes on its branch, at the commit its stage started from,
  * with its changes in progress and none in .factory/ but the plan it may have
@@ -195,21 +330,25 @@ function review(profile) {
 async function resumeProblem({ dir, state, }) {
     if (state.stage === "prepare")
         return undefined;
+    // Its pull request is open: only its screenshots remain to attach, from the
+    // run's folder, whatever the repository is on.
+    if (state.stage === "attach")
+        return undefined;
     // Stopped once its last stage was done, such as by Ctrl-C.
     const { pullRequest } = state.data;
     if (typeof pullRequest === "string")
         return `the run already delivered its pull request ${pullRequest}`;
-    // An earlier factory kept neither skipped checks nor the review's changes:
-    // past its checks, such a run has data these stages cannot read.
-    if (["diff", "review", "reviewed", "deliver"].includes(state.stage) &&
-        !Array.isArray(state.data.skippedChecks))
-        return "the run's checks ran with an earlier version of the factory, whose data this one does not read: start a new run";
-    // The review starts from the tree it reads, which Git may have pruned meanwhile.
+    // An earlier factory read neither the repository on GitHub nor the spec's
+    // objective: the pull request this run would open needs them.
+    if (typeof state.data.repository !== "object")
+        return "the run started with an earlier version of the factory, whose data this one does not read: start a new run";
+    // The review and the description start from the tree the review reads,
+    // which Git may have pruned meanwhile.
     const { reviewedTree } = state.data;
-    if (state.stage === "review" &&
+    if ((state.stage === "review" || state.stage === "describe") &&
         typeof reviewedTree === "string" &&
         !(await git.hasObject(dir, reviewedTree)))
-        return "the tree the review reads is no longer in Git (removed by git gc): start a new run";
+        return `the tree the ${state.stage === "review" ? "review" : "description"} reads is no longer in Git (removed by git gc): start a new run`;
     const { slug, baseCommit, planPath } = facts(state);
     // Until the plan is committed, the branch is at the run's starting commit.
     const { planCommit } = state.data;
@@ -226,7 +365,7 @@ async function resumeProblem({ dir, state, }) {
         problems.push(".factory/ has changes in progress, which a run never delivers: discard them");
     return problems.length ? problems.join("; ") : undefined;
 }
-/** Plans, implements, checks and reviews an approved spec, then opens its pull request. */
+/** Plans, implements, checks and reviews an approved spec, then describes it in the pull request it opens. */
 export function implement(definition) {
     return defineWorkflow({
         name: DELIVERY,
@@ -244,7 +383,10 @@ export function implement(definition) {
             { name: "implement", stages: ["implement", "implemented"] },
             { name: "verify", stages: ["verify"] },
             { name: "review", stages: ["diff", "review", "reviewed"] },
-            { name: "deliver", stages: ["deliver"] },
+            {
+                name: "deliver",
+                stages: ["describe", "described", "deliver", "attach"],
+            },
         ],
         nodes: {
             prepare: node(step((context) => prepare(definition, context)), { ok: "plan" }),
@@ -270,14 +412,14 @@ export function implement(definition) {
                 log(`Committed plan.md (${plan.steps.length} steps) as ${short(planCommit)}`);
                 return { planCommit };
             }), { ok: "implement" }),
-            implement: node(agent({
+            implement: node(closingBrowser(agent({
                 profile: definition.profiles.implement,
                 schema: implementationOutput,
                 context: ({ state }) => {
                     const { slug, spec, plan } = facts(state);
-                    return { issue: slug, spec, plan };
+                    return { issue: slug, spec, plan, ...browserContext(state) };
                 },
-            }), { ok: "implemented" }),
+            })), { ok: "implemented" }),
             implemented: node(gate(["ok", "invalid"], async (context) => {
                 // First what the agent did, whatever it answered: a malformed
                 // response must not hide a change it may not make.
@@ -298,20 +440,20 @@ export function implement(definition) {
                 };
             }), { ok: "verify", invalid: retry("implement", 2) }),
             verify: node(code(["passed", "failed"], async ({ dir, state, log, runDir }) => {
-                const checks = await runChecks(dir, definition.verify, journalChecks(log), await git.changedFiles(dir, facts(state).planCommit));
+                const checks = await runChecks(dir, definition.verify, await git.changedFiles(dir, facts(state).planCommit), journalChecks(log));
                 if (checks.ok)
                     return {
                         outcome: "passed",
                         reason: "Every check passed",
                         data: {
                             // What each check wrote stays with the run, for the review.
-                            checks: await Promise.all(checks.passed.map(async ({ output, ...check }, index) => ({
-                                ...check,
-                                outputFile: await keepInRun(runDir, `checks/${index + 1}-${fileName(check.name)}.log`, output),
-                            }))),
+                            checks: await keepCheckOutputs(runDir, checks.passed),
                             skippedChecks: checks.skipped.map(({ name }) => name),
                         },
                     };
+                // All it wrote, the agent receives its end only.
+                const kept = await keepFailedCheck(runDir, checks.check.name, checks.output);
+                log(`${checks.check.name} failed: ${checks.cause}; its output is in ${kept}`);
                 return {
                     outcome: "failed",
                     reason: `${checks.check.name} failed: ${checks.cause}`,
@@ -320,31 +462,25 @@ export function implement(definition) {
             }), { passed: "diff", failed: retry("implement", 3) }),
             diff: node(step(async ({ dir, state, log, runDir }) => {
                 const { planCommit } = facts(state);
-                const diff = await git.stagedDiff(dir, planCommit);
+                const reviewedTree = await git.snapshot(dir);
+                const diff = await git.diff(dir, planCommit, reviewedTree);
                 if (diff.truncated)
                     throw new Error("The changes are too large to review (over 2 MiB of diff): the run stops");
-                const files = await git.stagedStat(dir, planCommit);
+                const files = await git.diffStat(dir, planCommit, reviewedTree);
                 const lines = diff.text.split("\n").length;
-                // What the review reads, and must leave as it found it.
-                const reviewedTree = await git.snapshot(dir);
                 log(`Changes since the plan: ${files.length} files, ${lines} diff lines`);
-                if (lines <= largeChangeLines)
-                    return {
-                        changes: {
-                            files,
-                            lines,
-                            large: false,
-                            diff: diff.text,
-                        },
-                        reviewedTree,
-                    };
                 // A large diff is read from a file, part by part.
-                const diffFile = await keepInRun(runDir, "diff.patch", diff.text);
-                log(`Large change: the review reads its diff from ${diffFile}`);
-                return {
-                    changes: { files, lines, large: true, diffFile },
-                    reviewedTree,
-                };
+                const changes = lines <= largeChangeLines
+                    ? { files, lines, large: false, diff: diff.text }
+                    : {
+                        files,
+                        lines,
+                        large: true,
+                        diffFile: await keepInRun(runDir, "diff.patch", diff.text),
+                    };
+                if (changes.large)
+                    log(`Large change: the review reads its diff from ${changes.diffFile}`);
+                return { changes, reviewedTree };
             }), { ok: "review" }),
             review: node(review(definition.profiles.review), {
                 ok: "reviewed",
@@ -361,63 +497,127 @@ export function implement(definition) {
                 if (problem)
                     return { outcome: "invalid", reason: problem };
                 const changes = reviewChanges(parsed.data);
+                // Each review judged is kept, the last one apart for the stages after.
+                const judged = {
+                    review: parsed.data,
+                    reviews: [...(facts(state).reviews ?? []), parsed.data],
+                };
+                // The operator resumed the run to deliver it as the review left it.
+                if (changes && state.data.acceptedReview === true)
+                    return {
+                        outcome: "approved",
+                        reason: "The operator accepted the review's unmet criteria and blocking findings",
+                        data: judged,
+                    };
                 if (changes)
                     return {
                         outcome: "changes",
                         reason: "The review requires changes",
                         feedback: changes,
-                        data: { review: parsed.data },
+                        data: judged,
                     };
                 return {
                     outcome: "approved",
                     reason: "Every criterion is met and nothing blocks",
-                    data: { review: parsed.data },
+                    data: judged,
                 };
             }), {
-                approved: "deliver",
+                approved: "describe",
                 changes: retry("implement", 2),
                 invalid: retry("review", 2),
             }),
-            deliver: node(step(async ({ dir, state, log }) => {
-                const { slug, base, plan, specPath, planPath, baseCommit, criteria, implementation, review, checks, skippedChecks, } = facts(state);
+            describe: node(describe(definition.profiles.describe ?? definition.profiles.review), { ok: "described", modified: retry("describe", 1) }),
+            described: node(gate(["ok", "invalid"], async ({ state }) => {
+                const parsed = descriptionOutput.safeParse(state.output);
+                if (!parsed.success)
+                    return {
+                        outcome: "invalid",
+                        reason: `Invalid structured output:\n${z.prettifyError(parsed.error)}`,
+                    };
+                const description = parsed.data;
+                const { changes, screenshotsDir } = facts(state);
+                const problems = [
+                    ...descriptionProblems(description, changes.files),
+                    ...(await screenshotProblems(screenshotsDir, description.screenshots.map(({ file }) => file), maxScreenshotBytes)),
+                ];
+                const length = pullRequestBody(pullRequestFacts(state, description, false)).length;
+                if (length > maxBodyLength)
+                    problems.push(`The pull request's body would have ${length} characters, over ${maxBodyLength}: shorten the description`);
+                if (problems.length > 0)
+                    return {
+                        outcome: "invalid",
+                        reason: [
+                            "Invalid description:",
+                            ...problems.map((problem) => `- ${problem}`),
+                        ].join("\n"),
+                    };
+                return {
+                    outcome: "ok",
+                    reason: "Structured output and invariants valid: description",
+                    data: { description },
+                };
+            }), { ok: "deliver", invalid: retry("describe", 2) }),
+            deliver: node(code(["done", "attach"], async ({ dir, state, log }) => {
+                const { slug, base, plan, specPath, description } = facts(state);
                 const commit = await git.commit(dir, `${plan.commit}\n\nSpec: ${specPath}`);
                 log(`Committed "${plan.commit}" as ${short(commit)}`);
                 await git.forcePush(dir, slug);
                 log(`Pushed ${slug}, replacing any earlier version of the branch`);
+                // Its screenshots are attached once it is open: a failed upload
+                // leaves the pull request recorded, and resuming attaches them.
+                const attach = description.screenshots.length > 0;
                 const pullRequest = await github.openPullRequest(dir, {
                     base,
                     head: slug,
                     title: plan.commit,
-                    body: pullRequestBody({
-                        criteria,
-                        implementation,
-                        review,
-                        checks,
-                        skippedChecks,
-                        reviewRounds: reviewRounds(state),
-                        specPath,
-                        planPath,
-                        baseCommit,
-                        runId: state.id,
-                    }),
+                    body: pullRequestBody(pullRequestFacts(state, description, attach)),
                 });
                 log(`Pull request: ${pullRequest}`);
                 await git.switchTo(dir, base);
                 log(`Back on ${base}`);
-                return { pullRequest };
+                return {
+                    outcome: attach ? "attach" : "done",
+                    reason: attach
+                        ? "Pull request open, its screenshots to attach"
+                        : "Pull request open",
+                    data: { pullRequest },
+                };
+            }), { done: END, attach: "attach" }),
+            attach: node(step(async ({ dir, state, log }) => {
+                const { pullRequest, description, screenshotsDir } = facts(state);
+                const files = description.screenshots.map(({ file }) => file);
+                try {
+                    await github.attachImages(screenshotsDir, pullRequest, pullRequestBody(pullRequestFacts(state, description, false)), files);
+                }
+                catch (error) {
+                    // gh writes the body even when only some uploads succeeded: the
+                    // pull request says again that its screenshots are coming.
+                    await github
+                        .editBody(dir, pullRequest, pullRequestBody(pullRequestFacts(state, description, true)))
+                        .catch((restore) => log(`Could not put back the pull request's body: ${message(restore)}`));
+                    throw error;
+                }
+                log(`Attached ${files.length} screenshot${files.length === 1 ? "" : "s"} to ${pullRequest}`);
             }), { ok: END }),
         },
         resumeProblem,
         // Also called for a failed run, which opened no pull request.
         presentResult: (state) => {
-            const { pullRequest, checks } = facts(state);
+            const { pullRequest, checks, description, acceptedReview } = facts(state);
             if (typeof pullRequest !== "string")
                 return [];
             const rounds = reviewRounds(state);
+            const after = rounds === 0
+                ? "at the first review"
+                : `after ${rounds} round${rounds === 1 ? "" : "s"} of changes`;
             return [
                 `Pull request: ${pullRequest}`,
-                `Review: approved ${rounds === 0 ? "at the first review" : `after ${rounds} round${rounds === 1 ? "" : "s"} of changes`}`,
+                acceptedReview
+                    ? `Review: delivered by the operator with open findings ${after}`
+                    : `Review: approved ${after}`,
                 `Checks passed: ${checks.map(({ name }) => name).join(", ")}`,
+                // Runs delivered by an earlier factory have no description.
+                ...(description ? [mergeDangerLine(description)] : []),
             ];
         },
     });