@wardby/cli 0.6.0 → 0.7.0

package/dist/providers/vcs/github.js

@@ -1,7 +1,13 @@
 import { createPrivateKey } from "node:crypto";
 import { importPKCS8, SignJWT } from "jose";
 import { isGitHubLogin } from "../../config/github-allowed-accounts.js";
-import { normalizeGitHubRepository, normalizeGitRef } from "../../coding/protocol.js";
+import { testSimulatorBase } from "../../config/test-simulators.js";
+import { ACCEPTED_ADVISORY_ID } from "../../coding/registry/allowlist.js";
+import { packageAuditRows, packageAuditWording, summarizePackageAudit, } from "../../coding/registry/audit-mode.js";
+import { refusalMeaning } from "../../coding/registry/refusal-hints.js";
+import { DEPENDENCY_CACHE_PATH, normalizeGitHubRepository, normalizeGitRef, truncateText, } from "../../coding/protocol.js";
+import { LATEST_RUN_MARKER_PREFIX, RELATED_SECTION_END, RELATED_SECTION_START, assessFinalMessage, descriptionAppliedComment, descriptionFallbackComment, descriptionSha256, extractRelatedBlock, findDescriptionComments, hasClosingKeyword, isUneditedDescription, supersededDescriptionComment, } from "./pr-description.js";
+export { RELATED_SECTION_END, RELATED_SECTION_START };
 const DEFAULT_API_BASE_URL = "https://api.github.com";
 const DEFAULT_API_VERSION = "2026-03-10";
 const RUN_MARKER_PREFIX = "<!-- wardby:";
@@ -40,6 +46,8 @@ export function isSafeGitHubInstallationToken(value) {
  * executor validates with the shared one.
  */
 export const PR_ISSUE_KEY = /^[A-Z][A-Z0-9_]{0,254}-[1-9]\d{0,9}$/;
+/** Same shape as GITHUB_ISSUE_KEY (issue-tracker/types.ts), duplicated likewise. Only the Related section shows one. */
+export const PR_GITHUB_ISSUE_KEY = /^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?\/[a-z0-9._-]{1,100}#[1-9]\d{0,9}$/;
 /** The issue key when it is well-formed; a malformed one is dropped everywhere it would be rendered. */
 function validIssueKey(input) {
     const key = input.issue?.key;
@@ -50,22 +58,29 @@ export function pullRequestTitle(input) {
     const key = validIssueKey(input);
     return key ? `[${key}] ${base}` : base;
 }
-/** Validated issue parts; the tracker prefix is "" or "<Name> ". */
-function issueParts(issue) {
+/**
+ * Validated issue parts; the tracker prefix is "" or "<Name> ". A GitHub issue
+ * key is accepted only with `orGitHub` (the Related section): the title and
+ * the body's issue line stay tracker-only.
+ */
+function issueParts(issue, orGitHub = false) {
     const key = issue?.key;
-    if (typeof key !== "string" || !PR_ISSUE_KEY.test(key))
+    if (typeof key !== "string" || !(PR_ISSUE_KEY.test(key) || (orGitHub && PR_GITHUB_ISSUE_KEY.test(key)))) {
         return undefined;
+    }
     const url = issue?.url;
     const safeUrl = typeof url === "string" && url.startsWith("https://") && !/[\s<>()]/.test(url) ? url : undefined;
     const name = issue?.trackerName;
     const tracker = typeof name === "string" && /^[A-Za-z][A-Za-z0-9 .-]{0,39}$/.test(name) ? `${name.trim()} ` : "";
     return { key, ...(safeUrl ? { url: safeUrl } : {}), tracker };
 }
+/** The body's issue line: a tracker issue's link, else the same-repository issue the run came from. */
 function issueLine(input) {
     const parts = issueParts(input.issue);
-    if (!parts?.url)
-        return undefined;
-    return `Resolves ${parts.tracker}issue [${parts.key}](${parts.url})`;
+    if (parts?.url)
+        return `Resolves ${parts.tracker}issue [${parts.key}](${parts.url})`;
+    const number = input.issueNumber;
+    return typeof number === "number" && Number.isSafeInteger(number) && number > 0 ? `From issue #${number}` : undefined;
 }
 /**
  * Package names/versions/reasons come from registry metadata, not from
@@ -78,8 +93,17 @@ function issueLine(input) {
 function isSafeMarkdownFragment(value) {
     return !value.includes("`") && !value.includes("\n") && !value.includes("\r");
 }
-export const RELATED_SECTION_START = "<!-- wardby-related:start -->";
-export const RELATED_SECTION_END = "<!-- wardby-related:end -->";
+/** Whether a comment was written by this GitHub App (its bot user, through this App's id). */
+function isThisAppsComment(comment, appId) {
+    const user = comment.user;
+    const app = comment.performed_via_github_app;
+    return (!!user &&
+        typeof user === "object" &&
+        user.type === "Bot" &&
+        !!app &&
+        typeof app === "object" &&
+        app.id === appId);
+}
 /** At most this many pull requests are listed; the rest are counted. */
 export const MAX_RELATED_PULL_REQUESTS = 20;
 /** GitHub rejects a pull request body longer than this. */
@@ -128,7 +152,7 @@ export function renderRelatedSection(input) {
     const valid = input.entries.filter((entry) => relatedLine(entry, "-") !== undefined);
     if (!valid.some((entry) => !entry.self))
         return undefined;
-    const issue = issueParts(input.issue);
+    const issue = issueParts(input.issue, true);
     const issueText = issue ? ` for ${issue.tracker}issue ${issue.url ? `[${issue.key}](${issue.url})` : issue.key}` : "";
     const open = valid.filter((entry) => !isDone(entry)).slice(0, MAX_RELATED_PULL_REQUESTS);
     const done = valid.filter(isDone).slice(0, MAX_RELATED_PULL_REQUESTS - open.length);
@@ -185,8 +209,8 @@ export function renderRelatedSection(input) {
         RELATED_SECTION_END,
     ].join("\n");
 }
-/** The run marker, then optionally blank lines and the "Resolves …" line: the section goes right after. */
-const BODY_HEAD = /^[^\S\n]*<!-- (?:wardby|reevo-run):\S+ -->[^\S\n]*(?:\n|$)(?:[^\S\n]*\n)*(?:Resolves [^\n]*(?:\n|$))?/;
+/** The run marker, then optionally blank lines and the issue line ("Resolves … issue …" or "From issue #N"): the section goes right after. */
+const BODY_HEAD = /^[^\S\n]*<!-- (?:wardby|reevo-run):\S+ -->[^\S\n]*(?:\n|$)(?:[^\S\n]*\n)*(?:(?:Resolves |From issue #\d)[^\n]*(?:\n|$))?/;
 /**
  * The body with `block` in place of the existing marked section, or inserted
  * after the run marker (and the issue line) when there is none. Null — do not
@@ -223,13 +247,16 @@ export const MAX_PR_PACKAGE_LINES = 100;
 /** A hard ceiling on each list's rendered size, whatever the entries
  *  contain, so the section can never push the body past GitHub's limit. */
 const MAX_PR_PACKAGE_LIST_CHARS = 16 * 1024;
-/** Renders at most MAX_PR_PACKAGE_LINES lines (and at most
- *  MAX_PR_PACKAGE_LIST_CHARS characters) of `lines`, then a count of the rest. */
-function cappedList(lines) {
+/** The accepted-advisories list's ceiling: smaller, so adding it keeps the
+ *  whole section's worst case well inside the body limit. */
+const MAX_PR_WAIVER_LIST_CHARS = 8 * 1024;
+/** Renders at most MAX_PR_PACKAGE_LINES lines (and at most `maxChars`
+ *  characters) of `lines`, then a count of the rest. */
+function cappedList(lines, maxChars = MAX_PR_PACKAGE_LIST_CHARS) {
     const shown = [];
     let chars = 0;
     for (const line of lines.slice(0, MAX_PR_PACKAGE_LINES)) {
-        if (chars + line.length + 1 > MAX_PR_PACKAGE_LIST_CHARS)
+        if (chars + line.length + 1 > maxChars)
             break;
         shown.push(line);
         chars += line.length + 1;
@@ -237,6 +264,14 @@ function cappedList(lines) {
     const more = lines.length - shown.length;
     return more > 0 ? [...shown, `- …and ${more} more — see get_run for the full list`] : shown;
 }
+const MAX_DEPENDENCY_CACHE_FOLDERS = 4;
+function dependencyCacheLine(folders) {
+    const shown = [...new Set(folders ?? [])]
+        .filter((folder) => DEPENDENCY_CACHE_PATH.test(folder))
+        .slice(0, MAX_DEPENDENCY_CACHE_FOLDERS)
+        .map((folder) => (folder === "." ? "the repo root" : `\`${folder}\``));
+    return shown.length > 0 ? `Dependency cache: restored \`node_modules\` for ${shown.join(", ")}.` : undefined;
+}
 function packagesSection(input) {
     const packages = [
         ...new Map((input.packages ?? [])
@@ -252,11 +287,23 @@ function packagesSection(input) {
             isSafeMarkdownFragment(refusal.reason))
             .map((refusal) => [`${refusal.ecosystem}\0${refusal.name}\0${refusal.reason}`, refusal])).values(),
     ];
+    const restored = dependencyCacheLine(input.restoredDependencies);
     if (packages.length === 0 && refusals.length === 0)
-        return undefined;
+        return restored;
+    // Only ids safe in a Markdown line; a package whose ids are all unsafe is
+    // not listed here (it is still listed as installed).
+    const waivers = packages.flatMap((pkg) => {
+        // Ids come from OSV (a waiver can match via alias), so keep only the
+        // policy id shape and render each in a code span.
+        const ids = (pkg.acceptedAdvisories ?? []).filter((id) => ACCEPTED_ADVISORY_ID.test(id));
+        return ids.length > 0 ? [`- \`${pkg.name}@${pkg.version}\`: ${ids.map((id) => `\`${id}\``).join(", ")}`] : [];
+    });
     return [
+        ...(restored ? [restored, ""] : []),
         "<details>",
-        `<summary>Packages installed during this run (${packages.length})</summary>`,
+        input.packagesScope === "pull_request"
+            ? `<summary>Packages installed by wardby's runs on this pull request (${packages.length})</summary>`
+            : `<summary>Packages installed during this run (${packages.length})</summary>`,
         "",
         ...cappedList(packages.map((pkg) => `- ${pkg.ecosystem} \`${pkg.name}@${pkg.version}\``)),
         ...(refusals.length > 0
@@ -266,6 +313,13 @@ function packagesSection(input) {
                 ...cappedList(refusals.map((refusal) => `- ${refusal.ecosystem} \`${refusal.name}\`: ${refusal.reason}`)),
             ]
             : []),
+        ...(waivers.length > 0
+            ? [
+                "",
+                "**Accepted advisories** (waived by this agent's package policy):",
+                ...cappedList(waivers, MAX_PR_WAIVER_LIST_CHARS),
+            ]
+            : []),
         "</details>",
     ].join("\n");
 }
@@ -282,15 +336,6 @@ const LOCKFILE_NAMES = new Set([
 export function isLockfilePath(path) {
     return LOCKFILE_NAMES.has(path.slice(path.lastIndexOf("/") + 1));
 }
-/** What each refusal code means to someone reading the PR, without the registry's internals. */
-const REFUSAL_MEANING = {
-    wardby_package_not_allowed: "not on the allowlist, or only reachable through a refused package",
-    wardby_version_filtered: "withheld: newer than the release-age limit, or a high-severity advisory",
-    wardby_graph_incomplete: "its dependencies could not be confirmed (usually transient)",
-    wardby_lockfile_integrity_mismatch: "the lock file's integrity does not match the registry's",
-    wardby_upstream_error: "the upstream registry failed (transient)",
-    wardby_audit_unavailable: "the advisory check was unavailable (transient)",
-};
 /** At most this many refused packages are named in the warning; the full list stays in the details. */
 const MAX_WARNING_NAMES = 8;
 /**
@@ -320,7 +365,7 @@ function refusalWarning(input) {
         const listed = [...names];
         const shown = listed.slice(0, MAX_WARNING_NAMES).join(", ");
         const more = listed.length > MAX_WARNING_NAMES ? ` and ${listed.length - MAX_WARNING_NAMES} more` : "";
-        const meaning = REFUSAL_MEANING[reason];
+        const meaning = refusalMeaning(reason);
         lines.push(`> - ${shown}${more}: \`${reason}\`${meaning ? ` (${meaning})` : ""}`);
     }
     const lockfiles = (input.changedLockfiles ?? []).filter(isSafeMarkdownFragment);
@@ -329,8 +374,51 @@ function refusalWarning(input) {
     }
     return lines.join("\n");
 }
+/** The banner when the audit report can't be rendered: fixed text, no record data. */
+const PACKAGE_AUDIT_FALLBACK_BANNER = "> [!CAUTION]\n> **Package audit mode was on for this run.** Wardby's registry may have installed packages outside this agent's allowlist; see `get_run` (`packageAudit`) before merging.";
+/**
+ * The package audit block: built only from registry records (names and
+ * versions through codeSpan, advisory ids by their policy shape), so neither
+ * the model nor a package's metadata can remove or soften it.
+ */
+function packageAuditSection(input) {
+    if (!input.packageAudit)
+        return undefined;
+    const summary = summarizePackageAudit(packageAuditRows(input.packageAudit.entries));
+    return packageAuditWording(input.packageAudit.mode, summary, { format: "pr" });
+}
+/**
+ * The pull request body, within GitHub's MAX_PULL_REQUEST_BODY_CHARS. When it
+ * would be longer, the informational Packages section goes first; if that is
+ * not enough, the agent's summary is truncated to fit (fitSummary keeps its
+ * closing-keyword line). The other sections are bounded and stay whole.
+ */
+export function pullRequestBody(input, options = {}) {
+    const body = buildPullRequestBody(input, options);
+    if (body.length <= MAX_PULL_REQUEST_BODY_CHARS)
+        return body;
+    const withoutPackages = options.omitPackages ? body : buildPullRequestBody(input, { omitPackages: true });
+    if (withoutPackages.length <= MAX_PULL_REQUEST_BODY_CHARS || !input.summary)
+        return withoutPackages;
+    const room = input.summary.length - (withoutPackages.length - MAX_PULL_REQUEST_BODY_CHARS);
+    return buildPullRequestBody({ ...input, summary: fitSummary(input.summary, room) }, { omitPackages: true });
+}
+/**
+ * `summary` cut to `max` characters. A last line with a closing keyword
+ * (`Resolves #12`) is kept after the cut, so merging still closes the issue.
+ */
+function fitSummary(summary, max) {
+    const measure = (value) => value.length;
+    const lines = summary.trimEnd().split("\n");
+    const last = lines[lines.length - 1];
+    if (lines.length > 1 && last.length <= 200 && hasClosingKeyword(last)) {
+        const kept = truncateText(lines.slice(0, -1).join("\n"), max - last.length - 2, measure);
+        return `${kept}\n\n${last}`;
+    }
+    return truncateText(summary, max, measure);
+}
 /** The hidden run marker stays first and unconditional: createOrFindDraftPullRequest's idempotent lookup depends on it. */
-export function pullRequestBody(input) {
+function buildPullRequestBody(input, options) {
     const sections = [`${RUN_MARKER_PREFIX}${input.runId} -->`];
     // Hidden marker stays first; the issue link is the first visible line.
     const issue = issueLine(input);
@@ -352,6 +440,17 @@ export function pullRequestBody(input) {
     catch {
         // omitted, like the packages section
     }
+    try {
+        const audit = packageAuditSection(input);
+        if (audit)
+            sections.push(audit);
+    }
+    catch {
+        // Unlike the packages section, the audit banner fails closed: a report
+        // that can't be rendered still says the mode was on.
+        if (input.packageAudit)
+            sections.push(PACKAGE_AUDIT_FALLBACK_BANNER);
+    }
     if (input.summary)
         sections.push(input.summary);
     if (input.tests?.length) {
@@ -360,13 +459,16 @@ export function pullRequestBody(input) {
     // The packages section is informational: a failure rendering it (e.g. a
     // malformed report) omits the section and never fails finalization.
     try {
-        const packages = packagesSection(input);
+        const packages = options.omitPackages ? undefined : packagesSection(input);
         if (packages)
             sections.push(packages);
     }
     catch {
         // omitted
     }
+    if (input.latestRunId && SAFE_RUN_ID.test(input.latestRunId)) {
+        sections.push(`${LATEST_RUN_MARKER_PREFIX}${input.latestRunId} -->`);
+    }
     return sections.join("\n\n");
 }
 /** The hidden marker stays first and unconditional: findStatusComment's lookup depends on it. */
@@ -404,7 +506,9 @@ export class GitHubAppClient {
             throw new Error("github_app_id_invalid");
         if (!config.privateKey.trim())
             throw new Error("github_app_private_key_invalid");
-        this.apiBaseUrl = normalizeApiBaseUrl(config.apiBaseUrl ?? DEFAULT_API_BASE_URL);
+        // WARDBY_TEST_SIMULATORS (test only, refused with production configuration): every call
+        // goes to the simulator instead, all or nothing.
+        this.apiBaseUrl = testSimulatorBase("github-api") ?? normalizeApiBaseUrl(config.apiBaseUrl ?? DEFAULT_API_BASE_URL);
         this.apiVersion = config.apiVersion ?? DEFAULT_API_VERSION;
         if (!/^\d{4}-\d{2}-\d{2}$/.test(this.apiVersion))
             throw new Error("github_api_version_invalid");
@@ -611,11 +715,14 @@ export class GitHubAppClient {
     }
     async completeContinuationCheckRun(input) {
         const repository = normalizeGitHubRepository(input.repository);
-        if (!SAFE_RUN_ID.test(input.runId) || !SAFE_COMMIT_SHA.test(input.headSha)) {
+        if (!SAFE_RUN_ID.test(input.runId) || (input.headSha !== undefined && !SAFE_COMMIT_SHA.test(input.headSha))) {
             throw new Error("github_check_run_input_invalid");
         }
+        const ref = input.headSha ?? (input.headRef === undefined ? undefined : normalizeGitRef(input.headRef));
+        if (!ref)
+            throw new Error("github_check_run_input_invalid");
         await this.withChecksToken(repository, async (token) => {
-            const existing = await this.findCheckRun(token, repository, input.headSha, input.runId);
+            const existing = await this.findCheckRun(token, repository, ref, input.runId);
             if (!existing)
                 return;
             const [owner, name] = repository.split("/");
@@ -653,8 +760,14 @@ export class GitHubAppClient {
                     draft: true,
                 }),
             }, [201, 422]);
-            if (response.status === 201)
-                return this.parsePullRequest(await response.json(), repository);
+            if (response.status === 201) {
+                const payload = record(await response.json());
+                const created = this.parsePullRequest(payload, repository);
+                // Hash what GitHub stored, not what was sent.
+                return typeof payload.body === "string"
+                    ? { ...created, descriptionSha256: descriptionSha256(payload.body) }
+                    : created;
+            }
             const raced = await this.findPullRequest(token, { ...input, repository, baseRef, headRef });
             if (raced)
                 return raced;
@@ -675,6 +788,270 @@ export class GitHubAppClient {
             throw new Error("github_pull_request_input_invalid");
         return this.withRepositoryToken(repository, (token) => this.findPullRequest(token, { runId: input.runId, repository, baseRef, headRef, acceptReadyForReview: true }));
     }
+    /** See GitHubRepositoryAccess.openPullRequestDraft: GitHub's own `draft` flag on the marked open PR. */
+    async openPullRequestDraft(input) {
+        const repository = normalizeGitHubRepository(input.repository);
+        const baseRef = normalizeGitRef(input.baseRef);
+        const headRef = normalizeGitRef(input.headRef);
+        if (!SAFE_RUN_ID.test(input.runId))
+            throw new Error("github_pull_request_input_invalid");
+        return this.withRepositoryToken(repository, async (token) => {
+            const found = await this.findMarkedPullRequest(token, {
+                runId: input.runId,
+                repository,
+                baseRef,
+                headRef,
+                acceptReadyForReview: true,
+            });
+            return found ? found.draft : null;
+        });
+    }
+    /** See GitHubRepositoryAccess.openPullRequestBase: the marked open PR's current base, same repository only. */
+    async openPullRequestBase(input) {
+        const repository = normalizeGitHubRepository(input.repository);
+        const baseRef = normalizeGitRef(input.baseRef);
+        const headRef = normalizeGitRef(input.headRef);
+        if (!SAFE_RUN_ID.test(input.runId))
+            throw new Error("github_pull_request_input_invalid");
+        return this.withRepositoryToken(repository, async (token) => {
+            const found = await this.findMarkedPullRequest(token, {
+                runId: input.runId,
+                repository,
+                baseRef,
+                headRef,
+                acceptReadyForReview: true,
+            });
+            if (!found)
+                return null;
+            const base = record(found.raw.base);
+            const head = record(found.raw.head);
+            const sameRepository = (side) => {
+                const name = side.repo && typeof side.repo === "object" ? side.repo.full_name : null;
+                return typeof name === "string" && name.toLowerCase() === repository.toLowerCase();
+            };
+            // A fork's branch is never fetched: wardby's own heads live in the PR's repository.
+            if (!sameRepository(base) || !sameRepository(head))
+                return null;
+            if (typeof base.ref !== "string")
+                throw new Error("github_api_invalid_response");
+            try {
+                return { number: found.pr.number, baseRef: normalizeGitRef(base.ref) };
+            }
+            catch (error) {
+                throw new Error("github_api_invalid_response", { cause: error });
+            }
+        });
+    }
+    /**
+     * A fix round's description update (see GitHubRepositoryAccess). One
+     * repository token; every failure becomes `skipped:error`.
+     */
+    async updatePullRequestDescription(input) {
+        try {
+            const target = this.descriptionTarget(input);
+            return await this.withRepositoryToken(target.repository, async (token) => {
+                const state = await this.descriptionState(token, input, target);
+                if (!state)
+                    return { kind: "skipped", reason: "not_open" };
+                const { pr, verdict, full, proposed } = state;
+                const { repository } = target;
+                if (!state.writable) {
+                    // The comment truncates a body too long for it, so the full one goes in.
+                    const commentPosted = await this.upsertDescriptionComment(token, repository, pr.number, input, full, state)
+                        .then(() => true)
+                        .catch(() => false);
+                    return { kind: "edited_by_hand", commentPosted };
+                }
+                if (proposed === undefined)
+                    return { kind: "skipped", reason: "too_long" };
+                const agentTextRunId = verdict.ok ? input.runId : input.baseline.agentTextRunId;
+                const outcome = verdict.ok
+                    ? { kind: "replaced" }
+                    : { kind: "refreshed", reason: verdict.reason };
+                const proposedSha256 = descriptionSha256(proposed);
+                if (proposedSha256 === input.baseline.recordedSha256) {
+                    return { kind: "unchanged", sha256: proposedSha256, agentTextRunId: input.baseline.agentTextRunId };
+                }
+                const [owner, name] = repository.split("/");
+                // Known, accepted race: a person editing between our read and this PATCH is overwritten (GitHub has no If-Match); the store's compare-and-set only covers wardby runs racing each other.
+                const response = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/pulls/${pr.number}`, token, { method: "PATCH", body: JSON.stringify({ body: proposed }) }, [200]);
+                const written = record(await response.json()).body;
+                if (typeof written !== "string")
+                    throw new Error("github_api_invalid_response");
+                // A proposal left from an earlier round is stale now; a failure here never undoes the write.
+                await this.markDescriptionCommentApplied(token, repository, pr.number, input.runId, state).catch(() => undefined);
+                return { ...outcome, sha256: descriptionSha256(written), agentTextRunId };
+            });
+        }
+        catch {
+            return { kind: "skipped", reason: "error" };
+        }
+    }
+    /** See GitHubRepositoryAccess.proposeDescriptionComment. */
+    async proposeDescriptionComment(input) {
+        try {
+            if (!input.headSha || !/^[0-9a-f]{40}$/.test(input.headSha))
+                return false;
+            const target = this.descriptionTarget(input);
+            return await this.withRepositoryToken(target.repository, async (token) => {
+                const state = await this.descriptionState(token, input, target);
+                if (!state || state.writable)
+                    return false;
+                await this.upsertDescriptionComment(token, target.repository, state.pr.number, input, state.full, state);
+                return true;
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+    /** The validated repository and refs; throws unless this is wardby's own pull request branch. */
+    descriptionTarget(input) {
+        const repository = normalizeGitHubRepository(input.repository);
+        const baseRef = normalizeGitRef(input.baseRef);
+        const headRef = normalizeGitRef(input.headRef);
+        if (!SAFE_RUN_ID.test(input.runId) ||
+            !SAFE_RUN_ID.test(input.rootRunId) ||
+            !SAFE_RUN_ID.test(input.baseline.agentTextRunId) ||
+            (input.headSha !== undefined && !/^[0-9a-f]{40}$/.test(input.headSha)) ||
+            // Only wardby's own pull request: its branch is the root run's.
+            headRef !== `wardby/run-${input.rootRunId}`) {
+            throw new Error("github_pull_request_description_input_invalid");
+        }
+        return { repository, baseRef, headRef };
+    }
+    /**
+     * The open pull request, the description this run proposes, and whether
+     * wardby may write it directly: it is unedited (recorded or rebuilt hash),
+     * or a person copied wardby's latest proposal in (taken back). Null when
+     * the pull request isn't open. `comments` is set when it was read.
+     */
+    async descriptionState(token, input, target) {
+        const { repository, baseRef, headRef } = target;
+        const found = await this.findMarkedPullRequest(token, {
+            runId: input.rootRunId,
+            repository,
+            baseRef,
+            headRef,
+            acceptReadyForReview: true,
+        });
+        if (!found)
+            return null;
+        const { pr, body: currentBody } = found;
+        const verdict = assessFinalMessage(input.summary, input.baseline.previousAgentText);
+        const summary = verdict.ok ? input.summary : input.baseline.previousAgentText;
+        const { full, proposed } = this.proposedDescription(input, repository, baseRef, headRef, summary, currentBody);
+        const unedited = isUneditedDescription({
+            currentBody,
+            rootRunId: input.rootRunId,
+            recordedSha256: input.baseline.recordedSha256,
+            ...(input.baseline.legacySha256 ? { legacySha256: input.baseline.legacySha256 } : {}),
+            previousAgentText: input.baseline.previousAgentText,
+        });
+        if (unedited)
+            return { pr, currentBody, verdict, full, proposed, writable: true };
+        const comments = await this.findDescriptionComments(token, repository, pr.number);
+        const latest = comments.newest?.parsed.proposed;
+        // The author copied wardby's latest proposal in: the description is wardby's again.
+        const takenBack = latest !== undefined &&
+            isUneditedDescription({
+                currentBody,
+                rootRunId: input.rootRunId,
+                recordedSha256: descriptionSha256(latest),
+            });
+        return { pr, currentBody, verdict, full, proposed, writable: takenBack, comments };
+    }
+    /**
+     * The rebuilt description: the generated sections from this run with
+     * `summary` as the agent text, the latest-run marker last, and the current
+     * body's Related block re-inserted verbatim. `proposed` drops the Packages
+     * section when `full` exceeds GitHub's limit, and is undefined when it still
+     * would.
+     */
+    proposedDescription(input, repository, baseRef, headRef, summary, currentBody) {
+        const related = extractRelatedBlock(currentBody.replace(/\r\n/g, "\n"));
+        const build = (omitPackages) => {
+            const body = pullRequestBody({
+                repository,
+                baseRef,
+                headRef,
+                runId: input.rootRunId,
+                latestRunId: input.runId,
+                summary,
+                tests: input.tests,
+                tag: input.tag,
+                packages: input.packages,
+                packagesScope: "pull_request",
+                packageRefusals: input.packageRefusals,
+                packageAudit: input.packageAudit,
+                restoredDependencies: input.restoredDependencies,
+                changedLockfiles: input.changedLockfiles,
+                issue: input.issue,
+                issueNumber: input.issueNumber,
+            }, { omitPackages });
+            return related ? (upsertRelatedSection(body, related) ?? body) : body;
+        };
+        const full = build(false);
+        if (full.length <= MAX_PULL_REQUEST_BODY_CHARS)
+            return { full, proposed: full };
+        const trimmed = build(true);
+        return { full, proposed: trimmed.length <= MAX_PULL_REQUEST_BODY_CHARS ? trimmed : undefined };
+    }
+    /**
+     * Creates the pull request's one description comment, or edits the newest
+     * one this App wrote (unchanged text is not re-sent); older duplicates are
+     * rewritten to point at it. A comment anyone else wrote is never edited.
+     */
+    async upsertDescriptionComment(token, repository, pullRequestNumber, input, proposedBody, state) {
+        const body = descriptionFallbackComment(input.runId, proposedBody, input.headSha);
+        const { newest, older } = state.comments ?? (await this.findDescriptionComments(token, repository, pullRequestNumber));
+        const [owner, name] = repository.split("/");
+        const commentPath = (id) => `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/issues/comments/${id}`;
+        let url = newest?.url;
+        if (newest) {
+            if (newest.body.replace(/\r\n/g, "\n") !== body) {
+                await this.requestJson(commentPath(newest.id), token, { method: "PATCH", body: JSON.stringify({ body }) }, [200]);
+            }
+        }
+        else {
+            const response = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/issues/${pullRequestNumber}/comments`, token, { method: "POST", body: JSON.stringify({ body }) }, [201]);
+            const created = record(await response.json()).html_url;
+            url = typeof created === "string" ? created : undefined;
+        }
+        await this.supersedeDescriptionComments(token, commentPath, older, url);
+    }
+    /** Once a run applied its description, a pending proposal in the description comment is marked applied. */
+    async markDescriptionCommentApplied(token, repository, pullRequestNumber, runId, state) {
+        const { newest, older } = state.comments ?? (await this.findDescriptionComments(token, repository, pullRequestNumber));
+        if (!newest)
+            return;
+        const [owner, name] = repository.split("/");
+        const commentPath = (id) => `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/issues/comments/${id}`;
+        if (!newest.parsed.applied) {
+            await this.requestJson(commentPath(newest.id), token, { method: "PATCH", body: JSON.stringify({ body: descriptionAppliedComment(runId) }) }, [200]);
+        }
+        await this.supersedeDescriptionComments(token, commentPath, older, newest.url);
+    }
+    /** Rewrites duplicate description comments to a pointer at the one in use. */
+    async supersedeDescriptionComments(token, commentPath, older, url) {
+        for (const duplicate of older) {
+            await this.requestJson(commentPath(duplicate.id), token, { method: "PATCH", body: JSON.stringify({ body: supersededDescriptionComment(url) }) }, [200]);
+        }
+    }
+    /** The description comments this App wrote (see findDescriptionComments; the reviewer reads them the same way). */
+    async findDescriptionComments(token, repository, pullRequestNumber) {
+        const { id: appId } = await this.appIdentity();
+        const [owner, name] = repository.split("/");
+        return findDescriptionComments(async (page) => {
+            const response = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/issues/${pullRequestNumber}/comments?per_page=100&page=${page}`, token);
+            const payload = await response.json();
+            if (!Array.isArray(payload))
+                throw new Error("github_api_invalid_response");
+            return payload;
+        }, 
+        // Only this App's own comments: never a person's, nor another App's or bot's.
+        (comment) => isThisAppsComment(comment, appId));
+    }
     async appJwt() {
         let keyObject;
         try {
@@ -740,11 +1117,19 @@ export class GitHubAppClient {
         await this.requestJson("/installation/token", token, { method: "DELETE" }, [204]);
     }
     async findPullRequest(token, input) {
+        return (await this.findMarkedPullRequest(token, input))?.pr ?? null;
+    }
+    /**
+     * findPullRequest, plus the matched pull request's raw body and payload. Not
+     * filtered by base: a person may retarget the PR, and the head branch plus the
+     * run marker already identify it. When several open PRs match, the one on
+     * `baseRef` wins.
+     */
+    async findMarkedPullRequest(token, input) {
         const [owner, name] = input.repository.split("/");
         const query = new URLSearchParams({
             state: "open",
             head: `${owner}:${input.headRef}`,
-            base: input.baseRef,
             per_page: "100",
         });
         const response = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/pulls?${query.toString()}`, token);
@@ -752,13 +1137,26 @@ export class GitHubAppClient {
         if (!Array.isArray(payload))
             throw new Error("github_api_invalid_response");
         const marker = `${RUN_MARKER_PREFIX}${input.runId} -->`;
+        let first;
         for (const item of payload) {
             const candidate = record(item);
-            if (typeof candidate.body === "string" && candidate.body.includes(marker)) {
-                return this.parsePullRequest(candidate, input.repository, input.acceptReadyForReview === true);
+            if (typeof candidate.body !== "string" || !candidate.body.includes(marker))
+                continue;
+            const base = candidate.base && typeof candidate.base === "object" ? candidate.base : {};
+            if (base.ref === input.baseRef) {
+                first = candidate;
+                break;
             }
+            first ??= candidate;
         }
-        return null;
+        if (!first)
+            return null;
+        return {
+            pr: this.parsePullRequest(first, input.repository, input.acceptReadyForReview === true),
+            body: first.body,
+            draft: first.draft === true,
+            raw: first,
+        };
     }
     parsePullRequest(value, repository, acceptReadyForReview = false) {
         const payload = record(value);
@@ -788,23 +1186,27 @@ export class GitHubAppClient {
         return { number, url: expectedUrl };
     }
     async findStatusComment(token, repository, pullRequestNumber, runId) {
+        const marker = `${STATUS_COMMENT_MARKER_PREFIX}${runId} -->`;
+        return this.findMarkedComment(token, repository, pullRequestNumber, (body) => body.includes(marker));
+    }
+    /** The first comment on the pull request (first page) whose body `matches`. */
+    async findMarkedComment(token, repository, pullRequestNumber, matches) {
         const [owner, name] = repository.split("/");
         const response = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/issues/${pullRequestNumber}/comments?per_page=100`, token);
         const payload = await response.json();
         if (!Array.isArray(payload))
             throw new Error("github_api_invalid_response");
-        const marker = `${STATUS_COMMENT_MARKER_PREFIX}${runId} -->`;
         for (const item of payload) {
             const candidate = record(item);
-            if (typeof candidate.body === "string" && candidate.body.includes(marker)) {
-                return { id: positiveInteger(candidate.id) };
-            }
+            if (typeof candidate.body !== "string" || !matches(candidate.body))
+                continue;
+            return { id: positiveInteger(candidate.id), body: candidate.body };
         }
         return null;
     }
-    async findCheckRun(token, repository, headSha, runId) {
+    async findCheckRun(token, repository, ref, runId) {
         const [owner, name] = repository.split("/");
-        const response = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/commits/${headSha}/check-runs?per_page=100`, token);
+        const response = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/commits/${encodeURIComponent(ref)}/check-runs?per_page=100`, token);
         const payload = record(await response.json());
         const checkRuns = Array.isArray(payload.check_runs) ? payload.check_runs.map(record) : [];
         for (const candidate of checkRuns) {