@wardby/cli 0.6.0 → 0.7.0

package/dist/providers/vcs/index.js

@@ -7,6 +7,7 @@ import { GitHubRemote } from "./github-remote.js";
 import { LocalRemote } from "./local-remote.js";
 import { RoutingVcsProvider } from "./routing.js";
 import { logger } from "../../core/logger.js";
+import { testSimulatorBase } from "../../config/test-simulators.js";
 const vcsLog = logger.child({ module: "vcs" });
 export * from "./types.js";
 export { GitHubAppClient } from "./github.js";
@@ -33,7 +34,13 @@ export function buildVcsProvider(providerConfig, config, env = process.env, opti
             privateKey: config.privateKey,
             apiVersion: config.apiVersion,
         });
-        github = new GitVcsProvider({ rootDir, remote: new GitHubRemote({ github: client }), ...limits });
+        // WARDBY_TEST_SIMULATORS (test only): clone from and push to the simulator's git server.
+        const simulatorGit = testSimulatorBase("github-git", env);
+        const remote = new GitHubRemote({
+            github: client,
+            ...(simulatorGit ? { cloneUrlForRepository: (repository) => `${simulatorGit}/${repository}.git` } : {}),
+        });
+        github = new GitVcsProvider({ rootDir, remote, ...limits });
     }
     let local = null;
     if (loadLocalRepoRoots(env).roots.length > 0) {

package/dist/providers/vcs/pr-description.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The pull request description wardby writes, as pure functions: the hash it
+ * records, whether a fix round's final message is good enough to replace it,
+ * whether a person has edited it since, and the comment that carries a
+ * proposed description when wardby must not overwrite one.
+ *
+ * Depends on nothing else in providers/vcs, so github.ts can import it.
+ */
+/** Marks the Related pull requests section; replaced in place by later runs. */
+export declare const RELATED_SECTION_START = "<!-- wardby-related:start -->";
+export declare const RELATED_SECTION_END = "<!-- wardby-related:end -->";
+/** The last line of a description a fix round rewrote: `<!-- wardby-latest:<runId> -->`. */
+export declare const LATEST_RUN_MARKER_PREFIX = "<!-- wardby-latest:";
+/**
+ * The first line of the one description comment per pull request (edited in
+ * place on later runs). Pull-request level, never per run. A proposal is
+ * stamped with the head commit it describes: `<!-- wardby-description head=<sha> -->`.
+ */
+export declare const DESCRIPTION_COMMENT_MARKER = "<!-- wardby-description -->";
+/** The second line of the description comment once a later run applied its description directly. */
+export declare const DESCRIPTION_COMMENT_APPLIED_MARKER = "<!-- wardby-description-applied -->";
+/** The first line of a duplicate description comment, rewritten to point at the one in use. */
+export declare const DESCRIPTION_COMMENT_SUPERSEDED_MARKER = "<!-- wardby-description-superseded -->";
+/** The description comment is searched for on at most this many pages of 100 comments. */
+export declare const MAX_DESCRIPTION_COMMENT_PAGES = 10;
+/** A final message with fewer non-whitespace characters can't replace the description. */
+export declare const MIN_PR_BODY_CHARS = 80;
+/** The fallback comment stays under this many characters (GitHub's limit is 65,536). */
+export declare const MAX_DESCRIPTION_COMMENT_CHARS = 60000;
+/** The marked Related block, START through END inclusive; undefined when absent or malformed (missing, reversed, repeated). */
+export declare function extractRelatedBlock(body: string): string | undefined;
+/**
+ * The body as hashed: LF line endings, the Related block removed (it is
+ * rewritten as other runs finish, which is not an edit), trailing whitespace
+ * trimmed per line and at the end, and runs of blank lines collapsed to one.
+ */
+export declare function normalizeDescriptionForHash(body: string): string;
+/** SHA-256 of the normalized body, lowercase hex. */
+export declare function descriptionSha256(body: string): string;
+/** Whether the text contains a GitHub closing keyword and issue reference (`Fixes #3`, `resolves owner/repo#3`). */
+export declare function hasClosingKeyword(text: string): boolean;
+/**
+ * The issue number of the first closing keyword in `text` that points at an
+ * issue in `repository` (`Resolves #12`, `fixes owner/repo#12` naming this
+ * repository, case-insensitively); undefined when there is none.
+ */
+export declare function closingIssueNumber(text: string | undefined, repository: string): number | undefined;
+export type FinalMessageVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "empty" | "too_short" | "missing_closing_keyword";
+};
+/**
+ * Whether `next` (a fix round's final message) can replace the description
+ * whose agent-written text was `previous`: not empty, at least
+ * MIN_PR_BODY_CHARS non-whitespace characters, and keeping a closing keyword
+ * when the previous text had one.
+ */
+export declare function assessFinalMessage(next: string | undefined, previous: string | undefined): FinalMessageVerdict;
+/**
+ * Whether the PR description is still what wardby last wrote. It must start
+ * with the root run's marker, and its normalized hash must match the recorded
+ * one. Without a recorded hash (a description written before hashes were
+ * recorded), it must match `legacySha256`, the hash of the body wardby would
+ * have written for the root run, rebuilt from stored records; without that
+ * either it counts as edited, so a person's text is never overwritten.
+ * `previousAgentText` does not decide edit status; it is carried for callers.
+ */
+export declare function isUneditedDescription(input: {
+    currentBody: string;
+    rootRunId: string;
+    recordedSha256: string | null;
+    legacySha256?: string;
+    previousAgentText?: string | undefined;
+}): boolean;
+export interface ParsedDescriptionComment {
+    /** The head commit the proposal describes; absent on an unstamped or applied comment. */
+    headSha?: string;
+    /** A later run applied its description directly: no proposal is pending. */
+    applied: boolean;
+    /** The run that proposed it, when named. */
+    runId?: string;
+    /** The proposed description; absent when the comment holds none. */
+    proposed?: string;
+}
+/**
+ * wardby's description comment, parsed; undefined for any other comment.
+ * Only the first line (the marker) and second line (the applied marker) are
+ * structural, so text inside a proposal can't change its state.
+ */
+export declare function parseDescriptionComment(body: string): ParsedDescriptionComment | undefined;
+export interface DescriptionCommentRecord {
+    id: number;
+    body: string;
+    url?: string;
+    parsed: ParsedDescriptionComment;
+}
+/**
+ * wardby's description comments on a pull request, read the same way by the
+ * writer and the reviewer: up to MAX_DESCRIPTION_COMMENT_PAGES pages of 100
+ * (oldest first), only comments `isOurs` accepts that start with the
+ * pull-request-level marker. `newest` is the one in use; `older` are
+ * duplicates (oldest first).
+ */
+export declare function findDescriptionComments(fetchPage: (page: number) => Promise<unknown[]>, isOurs: (comment: Record<string, unknown>) => boolean): Promise<{
+    newest: DescriptionCommentRecord | null;
+    older: DescriptionCommentRecord[];
+}>;
+/** What a duplicate description comment becomes: a pointer to the one in use. */
+export declare function supersededDescriptionComment(url: string | undefined): string;
+/**
+ * The pull request's description comment, carrying the description wardby's
+ * latest run proposed when it could not apply it (it couldn't confirm the
+ * description is still its own text). There is one per pull request,
+ * edited in place by later runs, its marker stamped with `headSha`, the head
+ * commit the proposal describes. Holds the body in a collapsed fenced block,
+ * and stays under MAX_DESCRIPTION_COMMENT_CHARS (a long body is truncated).
+ * Throws on a run id or head that isn't safe to quote.
+ */
+export declare function descriptionFallbackComment(runId: string, proposedBody: string, headSha?: string): string;
+/**
+ * What the description comment becomes once a later run applied its
+ * description directly: no proposal is pending, so nobody (a person or a
+ * reviewer) acts on a stale one.
+ */
+export declare function descriptionAppliedComment(runId: string): string;

package/dist/providers/vcs/pr-description.js

@@ -0,0 +1,270 @@
+import { createHash } from "node:crypto";
+/**
+ * The pull request description wardby writes, as pure functions: the hash it
+ * records, whether a fix round's final message is good enough to replace it,
+ * whether a person has edited it since, and the comment that carries a
+ * proposed description when wardby must not overwrite one.
+ *
+ * Depends on nothing else in providers/vcs, so github.ts can import it.
+ */
+/** Marks the Related pull requests section; replaced in place by later runs. */
+export const RELATED_SECTION_START = "<!-- wardby-related:start -->";
+export const RELATED_SECTION_END = "<!-- wardby-related:end -->";
+/** The last line of a description a fix round rewrote: `<!-- wardby-latest:<runId> -->`. */
+export const LATEST_RUN_MARKER_PREFIX = "<!-- wardby-latest:";
+/**
+ * The first line of the one description comment per pull request (edited in
+ * place on later runs). Pull-request level, never per run. A proposal is
+ * stamped with the head commit it describes: `<!-- wardby-description head=<sha> -->`.
+ */
+export const DESCRIPTION_COMMENT_MARKER = "<!-- wardby-description -->";
+/** The marker line, plain or stamped with a head; anchored to the whole first line. */
+const DESCRIPTION_COMMENT_MARKER_LINE = /^<!-- wardby-description(?: head=([0-9a-f]{40}))? -->$/;
+/** The second line of the description comment once a later run applied its description directly. */
+export const DESCRIPTION_COMMENT_APPLIED_MARKER = "<!-- wardby-description-applied -->";
+/** The first line of a duplicate description comment, rewritten to point at the one in use. */
+export const DESCRIPTION_COMMENT_SUPERSEDED_MARKER = "<!-- wardby-description-superseded -->";
+/** The description comment is searched for on at most this many pages of 100 comments. */
+export const MAX_DESCRIPTION_COMMENT_PAGES = 10;
+const HEAD_SHA = /^[0-9a-f]{40}$/;
+const PROPOSAL_SUMMARY = "<details><summary>Proposed description</summary>";
+/** A final message with fewer non-whitespace characters can't replace the description. */
+export const MIN_PR_BODY_CHARS = 80;
+/** The fallback comment stays under this many characters (GitHub's limit is 65,536). */
+export const MAX_DESCRIPTION_COMMENT_CHARS = 60_000;
+const RUN_MARKER_PREFIX = "<!-- wardby:";
+/** Mirrors the runId shape validated in github.ts and coding/protocol.ts. */
+const SAFE_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+/** GitHub's closing keywords, then `#N` or `owner/repo#N`. */
+const CLOSING_KEYWORD = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\b:?\s+(?:[\w.-]+\/[\w.-]+)?#\d+\b/i;
+/** The marked Related block, START through END inclusive; undefined when absent or malformed (missing, reversed, repeated). */
+export function extractRelatedBlock(body) {
+    const start = body.indexOf(RELATED_SECTION_START);
+    const end = body.indexOf(RELATED_SECTION_END);
+    if (start === -1 || end === -1 || end < start)
+        return undefined;
+    if (body.indexOf(RELATED_SECTION_START, start + 1) !== -1 || body.indexOf(RELATED_SECTION_END, end + 1) !== -1) {
+        return undefined;
+    }
+    return body.slice(start, end + RELATED_SECTION_END.length);
+}
+/**
+ * The body as hashed: LF line endings, the Related block removed (it is
+ * rewritten as other runs finish, which is not an edit), trailing whitespace
+ * trimmed per line and at the end, and runs of blank lines collapsed to one.
+ */
+export function normalizeDescriptionForHash(body) {
+    let text = body.replace(/\r\n/g, "\n");
+    const related = extractRelatedBlock(text);
+    if (related)
+        text = text.replace(related, "");
+    return text
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trimEnd();
+}
+/** SHA-256 of the normalized body, lowercase hex. */
+export function descriptionSha256(body) {
+    return createHash("sha256").update(normalizeDescriptionForHash(body), "utf8").digest("hex");
+}
+/** Whether the text contains a GitHub closing keyword and issue reference (`Fixes #3`, `resolves owner/repo#3`). */
+export function hasClosingKeyword(text) {
+    return CLOSING_KEYWORD.test(text);
+}
+const CLOSING_REFERENCES = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\b:?\s+(?:([\w.-]+\/[\w.-]+))?#(\d+)\b/gi;
+/**
+ * The issue number of the first closing keyword in `text` that points at an
+ * issue in `repository` (`Resolves #12`, `fixes owner/repo#12` naming this
+ * repository, case-insensitively); undefined when there is none.
+ */
+export function closingIssueNumber(text, repository) {
+    if (!text)
+        return undefined;
+    for (const match of text.matchAll(CLOSING_REFERENCES)) {
+        if (match[1] && match[1].toLowerCase() !== repository.toLowerCase())
+            continue;
+        const number = Number(match[2]);
+        if (Number.isSafeInteger(number) && number > 0)
+            return number;
+    }
+    return undefined;
+}
+/**
+ * Whether `next` (a fix round's final message) can replace the description
+ * whose agent-written text was `previous`: not empty, at least
+ * MIN_PR_BODY_CHARS non-whitespace characters, and keeping a closing keyword
+ * when the previous text had one.
+ */
+export function assessFinalMessage(next, previous) {
+    const text = next?.trim() ?? "";
+    if (!text)
+        return { ok: false, reason: "empty" };
+    if (text.replace(/\s/g, "").length < MIN_PR_BODY_CHARS)
+        return { ok: false, reason: "too_short" };
+    if (previous && hasClosingKeyword(previous) && !hasClosingKeyword(text)) {
+        return { ok: false, reason: "missing_closing_keyword" };
+    }
+    return { ok: true };
+}
+/**
+ * Whether the PR description is still what wardby last wrote. It must start
+ * with the root run's marker, and its normalized hash must match the recorded
+ * one. Without a recorded hash (a description written before hashes were
+ * recorded), it must match `legacySha256`, the hash of the body wardby would
+ * have written for the root run, rebuilt from stored records; without that
+ * either it counts as edited, so a person's text is never overwritten.
+ * `previousAgentText` does not decide edit status; it is carried for callers.
+ */
+export function isUneditedDescription(input) {
+    const body = input.currentBody.replace(/\r\n/g, "\n");
+    if (!body.startsWith(`${RUN_MARKER_PREFIX}${input.rootRunId} -->`))
+        return false;
+    const expected = input.recordedSha256 ?? input.legacySha256;
+    if (!expected)
+        return false;
+    return descriptionSha256(body) === expected;
+}
+/** A backtick fence one longer than the longest backtick run in `text` (at least three). */
+function fenceFor(text) {
+    const longest = Math.max(0, ...Array.from(text.matchAll(/`+/g), (m) => m[0].length));
+    return "`".repeat(Math.max(3, longest + 1));
+}
+/**
+ * wardby's description comment, parsed; undefined for any other comment.
+ * Only the first line (the marker) and second line (the applied marker) are
+ * structural, so text inside a proposal can't change its state.
+ */
+export function parseDescriptionComment(body) {
+    const text = body.replace(/\r\n/g, "\n");
+    const lines = text.split("\n");
+    const marker = DESCRIPTION_COMMENT_MARKER_LINE.exec(lines[0] ?? "");
+    if (!marker)
+        return undefined;
+    if (lines[1] === DESCRIPTION_COMMENT_APPLIED_MARKER)
+        return { applied: true };
+    const proposed = proposalOf(text);
+    const runId = proposed === undefined ? undefined : proposingRunId(text);
+    return {
+        ...(marker[1] ? { headSha: marker[1] } : {}),
+        applied: false,
+        ...(runId ? { runId } : {}),
+        ...(proposed !== undefined ? { proposed } : {}),
+    };
+}
+/** The fenced block under "Proposed description"; undefined when absent. */
+function proposalOf(text) {
+    const at = text.indexOf(PROPOSAL_SUMMARY);
+    if (at === -1)
+        return undefined;
+    const open = /\n(`{3,})markdown\n/.exec(text.slice(at));
+    if (!open)
+        return undefined;
+    const start = at + open.index + open[0].length;
+    const close = text.indexOf(`\n${open[1]}\n`, start - 1);
+    const end = close === -1 ? text.indexOf(`\n${open[1]}`, start - 1) : close;
+    if (end < start - 1)
+        return undefined;
+    const proposal = text.slice(start, Math.max(start, end)).trimEnd();
+    return proposal || undefined;
+}
+/** The run a fallback comment names as its proposer (in its header, before the proposal). */
+function proposingRunId(text) {
+    const header = text.slice(0, Math.max(0, text.indexOf(PROPOSAL_SUMMARY)));
+    const named = /latest run \(`([^`\n]+)`\)/.exec(header)?.[1];
+    return named && SAFE_RUN_ID.test(named) ? named : undefined;
+}
+/**
+ * wardby's description comments on a pull request, read the same way by the
+ * writer and the reviewer: up to MAX_DESCRIPTION_COMMENT_PAGES pages of 100
+ * (oldest first), only comments `isOurs` accepts that start with the
+ * pull-request-level marker. `newest` is the one in use; `older` are
+ * duplicates (oldest first).
+ */
+export async function findDescriptionComments(fetchPage, isOurs) {
+    const found = [];
+    for (let page = 1; page <= MAX_DESCRIPTION_COMMENT_PAGES; page++) {
+        const comments = await fetchPage(page);
+        for (const item of comments) {
+            if (!item || typeof item !== "object")
+                continue;
+            const comment = item;
+            if (typeof comment.body !== "string" || typeof comment.id !== "number")
+                continue;
+            const parsed = parseDescriptionComment(comment.body);
+            if (!parsed || !isOurs(comment))
+                continue;
+            found.push({
+                id: comment.id,
+                body: comment.body,
+                ...(typeof comment.html_url === "string" ? { url: comment.html_url } : {}),
+                parsed,
+            });
+        }
+        if (comments.length < 100)
+            break;
+    }
+    return { newest: found.at(-1) ?? null, older: found.slice(0, -1) };
+}
+/** What a duplicate description comment becomes: a pointer to the one in use. */
+export function supersededDescriptionComment(url) {
+    const link = url && /^https:\/\/[^\s)]+$/.test(url) ? `[the current one](${url})` : "a newer comment";
+    return `${DESCRIPTION_COMMENT_SUPERSEDED_MARKER}\n\nSuperseded by ${link}.`;
+}
+/**
+ * The pull request's description comment, carrying the description wardby's
+ * latest run proposed when it could not apply it (it couldn't confirm the
+ * description is still its own text). There is one per pull request,
+ * edited in place by later runs, its marker stamped with `headSha`, the head
+ * commit the proposal describes. Holds the body in a collapsed fenced block,
+ * and stays under MAX_DESCRIPTION_COMMENT_CHARS (a long body is truncated).
+ * Throws on a run id or head that isn't safe to quote.
+ */
+export function descriptionFallbackComment(runId, proposedBody, headSha) {
+    if (!SAFE_RUN_ID.test(runId))
+        throw new Error("description_comment_run_id_invalid");
+    if (headSha !== undefined && !HEAD_SHA.test(headSha))
+        throw new Error("description_comment_head_invalid");
+    const head = [
+        headSha ? `<!-- wardby-description head=${headSha} -->` : DESCRIPTION_COMMENT_MARKER,
+        "",
+        `This is the current description proposed by wardby's latest run (\`${runId}\`)${headSha ? ` for commit ${headSha.slice(0, 12)}` : ""}. ` +
+            "It was not applied because wardby couldn't confirm the description is unchanged since it wrote it (for example, a person edited it), and wardby never overwrites a person's edits. " +
+            "The pull request author can copy it into the description; wardby then keeps it up to date again. Later runs update this comment.",
+        "",
+        PROPOSAL_SUMMARY,
+        "",
+    ].join("\n");
+    const truncatedNote = "\n\n_The proposed description was truncated to fit in a comment._";
+    let body = proposedBody.replace(/\r\n/g, "\n").trimEnd();
+    let note = "";
+    const render = () => {
+        const fence = fenceFor(body);
+        return `${head}${fence}markdown\n${body}\n${fence}${note}\n\n</details>`;
+    };
+    let comment = render();
+    if (comment.length >= MAX_DESCRIPTION_COMMENT_CHARS) {
+        note = truncatedNote;
+        // Headroom for the fence growing if the cut leaves a longer backtick run (it can't), plus the note.
+        const overhead = comment.length - body.length + note.length + 64;
+        body = body.slice(0, Math.max(0, MAX_DESCRIPTION_COMMENT_CHARS - overhead)).trimEnd();
+        comment = render();
+    }
+    return comment;
+}
+/**
+ * What the description comment becomes once a later run applied its
+ * description directly: no proposal is pending, so nobody (a person or a
+ * reviewer) acts on a stale one.
+ */
+export function descriptionAppliedComment(runId) {
+    if (!SAFE_RUN_ID.test(runId))
+        throw new Error("description_comment_run_id_invalid");
+    return [
+        DESCRIPTION_COMMENT_MARKER,
+        DESCRIPTION_COMMENT_APPLIED_MARKER,
+        "",
+        `wardby's latest run (\`${runId}\`) updated the pull request description directly, so it is current. No proposed description is pending here.`,
+    ].join("\n");
+}

package/dist/providers/vcs/remote.d.ts

@@ -1,4 +1,4 @@
-import type { FinalizeChangesDetails, PreparedWorkspace, VcsProvider } from "./types.js";
+import type { DescriptionWriteOutcome, FinalizeChangesDetails, PreparedWorkspace, VcsProvider } from "./types.js";
 /** What a remote needs to publish a pushed commit (GitHub: open or find the draft PR). */
 export interface PublishInput {
     /** The validated workspace whose headRef was just pushed. */
@@ -6,11 +6,14 @@ export interface PublishInput {
     details?: FinalizeChangesDetails;
     /** Every path the commit changes relative to baseCommit (already validated). */
     changedPaths: readonly string[];
+    /** The commit just pushed (the pull request's new head). */
+    commitSha?: string;
 }
 export type PublishResult = {
     kind: "pull_request";
     number: number;
     url: string;
+    description?: DescriptionWriteOutcome;
 } | {
     kind: "branch";
     branch: string;
@@ -52,7 +55,36 @@ export interface GitRemote {
     assertPushRef?(headRef: string): void;
     /** When set, called inside withAccess right before the push; throws to refuse it (GitHub: unset). */
     beforePush?(repository: string, headRef: string): Promise<void>;
+    /**
+     * Optional: the branch a continuation's pull request currently targets, which
+     * prepareWorkspace merges into the workspace before the agent starts (GitHub:
+     * the open PR's base; local: unset, so no merge). Null when there is nothing to
+     * merge from: not a continuation, the PR is a fork's, or the lookup failed.
+     * Never throws.
+     */
+    pullRequestBase?(input: {
+        runId: string;
+        repository: string;
+        baseRef: string;
+        headRef: string;
+        continuation?: {
+            rootRunId: string;
+        };
+    }): Promise<{
+        ref: string;
+    } | null>;
     notifyContinuationStarted?: VcsProvider["notifyContinuationStarted"];
+    continuationPullRequestDraft?: VcsProvider["continuationPullRequestDraft"];
     notifyContinuationFinished?: VcsProvider["notifyContinuationFinished"];
     readRepositoryFile?: VcsProvider["readRepositoryFile"];
+    /**
+     * Optional: called after the commit and before the push, with the commit
+     * about to become the head. GitHub writes a continuation's description
+     * comment here, so it exists before the push starts a review. Never throws.
+     */
+    proposeDescriptionBeforePush?(input: PublishInput & {
+        commitSha: string;
+    }): Promise<void>;
+    /** Optional: re-derive a continuation's PR description without a push (GitHub only). Never throws. */
+    refreshDescription?: VcsProvider["refreshPullRequestDescription"];
 }

package/dist/providers/vcs/routing.d.ts

@@ -1,5 +1,5 @@
 import type { RepositoryFileInput } from "./github.js";
-import type { ContinuationFinishedDetails, ContinuationOutcome, FinalizeChangesDetails, FinalizeChangesResult, PreparedWorkspace, VcsPrepareInput, VcsProvider } from "./types.js";
+import type { ContinuationFinishedDetails, ContinuationOutcome, ContinuationTarget, DescriptionWriteOutcome, FinalizeChangesDetails, FinalizeChangesResult, PreparedWorkspace, VcsPrepareInput, VcsProvider } from "./types.js";
 /** Keeps the `vcs_github_not_configured` code prefix that error matching and categorization key on. */
 export declare const VCS_GITHUB_NOT_CONFIGURED_ERROR = "vcs_github_not_configured: set GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY to run coding agents on GitHub repositories";
 export interface RoutingVcsOptions {
@@ -28,6 +28,8 @@ export declare class RoutingVcsProvider implements VcsProvider {
     notifyContinuationStarted(workspace: PreparedWorkspace, details?: {
         agentName?: string;
     }): Promise<void>;
-    notifyContinuationFinished(workspace: PreparedWorkspace, outcome: ContinuationOutcome, details?: ContinuationFinishedDetails): Promise<void>;
+    notifyContinuationFinished(workspace: ContinuationTarget, outcome: ContinuationOutcome, details?: ContinuationFinishedDetails): Promise<void>;
+    refreshPullRequestDescription(workspace: ContinuationTarget, details: FinalizeChangesDetails): Promise<DescriptionWriteOutcome | undefined>;
+    continuationPullRequestDraft(workspace: PreparedWorkspace): Promise<boolean | undefined>;
     readRepositoryFile(input: RepositoryFileInput): Promise<string | null>;
 }

package/dist/providers/vcs/routing.js

@@ -46,6 +46,12 @@ export class RoutingVcsProvider {
     async notifyContinuationFinished(workspace, outcome, details) {
         await this.optionalTarget(workspace.repository)?.notifyContinuationFinished?.(workspace, outcome, details);
     }
+    async refreshPullRequestDescription(workspace, details) {
+        return this.optionalTarget(workspace.repository)?.refreshPullRequestDescription?.(workspace, details);
+    }
+    async continuationPullRequestDraft(workspace) {
+        return this.optionalTarget(workspace.repository)?.continuationPullRequestDraft?.(workspace);
+    }
     async readRepositoryFile(input) {
         return (await this.optionalTarget(input.repository)?.readRepositoryFile?.(input)) ?? null;
     }

package/dist/providers/vcs/types.d.ts

@@ -1,4 +1,10 @@
-import type { RelatedPullRequestsInput, RepositoryFileInput } from "./github.js";
+import type { PackageAuditReport } from "../../coding/registry/audit-mode.js";
+import type { DescriptionBaseline, DescriptionUpdateResult, RelatedPullRequestsInput, RepositoryFileInput } from "./github.js";
+/** What happened to a pull request description: wardby just wrote it (a new PR) or updated a fix round's. */
+export type DescriptionWriteOutcome = {
+    kind: "written";
+    sha256: string;
+} | DescriptionUpdateResult;
 export interface VcsPrepareInput {
     runId: string;
     repository: string;
@@ -45,7 +51,30 @@ export interface PreparedWorkspace {
     continuation?: {
         rootRunId: string;
     };
+    /**
+     * Set when prepareWorkspace merged the pull request's current target branch
+     * into a continuation's workspace (it was behind): the target branch, the
+     * commit merged, and the paths the merge left conflicted (markers in the
+     * workspace). Read back from the workspace's git metadata on recovery, never
+     * from worker output.
+     */
+    targetMerge?: TargetMerge;
 }
+export interface TargetMerge {
+    ref: string;
+    targetCommit: string;
+    conflictedPaths: string[];
+}
+/**
+ * The pull request a continuation run works on, without its local workspace:
+ * what the host-side finish signals and the no-push description refresh need.
+ * A run finished by another control-plane process (a deploy moved it) has no
+ * workspace to recover, so the executor builds this from the run record, and
+ * `baseCommit` is then unknown.
+ */
+export type ContinuationTarget = Pick<PreparedWorkspace, "runId" | "repository" | "baseRef" | "headRef" | "continuation"> & {
+    baseCommit?: string;
+};
 /** Already-validated/redacted agent-authored fields (coding/protocol.ts) surfaced in the opened PR, if any. */
 export interface FinalizeChangesDetails {
     summary?: string;
@@ -59,20 +88,33 @@ export interface FinalizeChangesDetails {
         ecosystem: string;
         name: string;
         version: string;
+        /** Blocking advisories the run's accepted set waived to serve it. */
+        acceptedAdvisories?: readonly string[];
     }[];
     packageRefusals?: readonly {
         ecosystem: string;
         name: string;
         reason: string;
     }[];
+    /** Package audit mode (control-plane records): the mode the run(s) had and what the registry served only
+     *  because of it, for the PR body's caution banner. Absent when the mode was off. */
+    packageAudit?: PackageAuditReport;
+    /** Folders whose node_modules the run's dependency cache restored from a snapshot ("." for the root), for the PR body. */
+    restoredDependencies?: readonly string[];
     /** Originating issue (control-plane data): named in the PR title and body. Provider-neutral. */
     issue?: {
         key: string;
         url?: string;
         trackerName?: string;
     };
+    /** The same-repository issue the run came from (a mention on a GitHub issue): the body's `From issue #N` line (a link; it never closes the issue). */
+    issueNumber?: number;
     /** The request's other pull requests (control-plane rows): the PR body's Related pull requests section. */
     related?: RelatedPullRequestsInput;
+    /** Fix rounds: the control plane's record of the description wardby last wrote; enables the description update. */
+    description?: {
+        baseline: DescriptionBaseline;
+    };
 }
 export type FinalizeChangesResult = {
     outcome: "no_changes";
@@ -88,6 +130,7 @@ export type FinalizeChangesResult = {
     commitSha: string;
     pullRequestNumber: number;
     pullRequestUrl: string;
+    description?: DescriptionWriteOutcome;
 } | {
     /** Revision-in-place: pushed a new commit onto an existing open PR's
      * branch instead of opening a new one. */
@@ -99,6 +142,13 @@ export type FinalizeChangesResult = {
     commitSha: string;
     pullRequestNumber: number;
     pullRequestUrl: string;
+    description?: DescriptionWriteOutcome;
+    /** The pushed head is a merge of the PR's target branch (see PreparedWorkspace.targetMerge). */
+    targetMerge?: {
+        ref: string;
+        targetCommit: string;
+        conflicts: number;
+    };
 } | {
     /** Pushed the run's branch to a remote with no pull requests (a local
      * repository): headRef now points at commitSha there. */
@@ -143,12 +193,13 @@ export interface VcsProvider {
      * `FinalizeChangesDetails.summary`) so the "done" status reflects what
      * actually happened instead of a caller having to go find out.
      * `budget_exhausted` is a failure that ran out of budget;
-     * `details.budgetSentence` then says how (see core/budget-wording.ts).
+     * `details.budgetSentence` then says how (see core/budget-wording.ts), and
+     * `details.changesPushed` says its changes so far were pushed anyway.
      * A `failed` run the model provider refused carries `details.providerSentence`.
      * A `failed` run whose changes touched a protected path carries
      * `details.protectedPathSentence` (see coding/protected-path-wording.ts).
      */
-    notifyContinuationFinished?(workspace: PreparedWorkspace, outcome: ContinuationOutcome, details?: ContinuationFinishedDetails): Promise<void>;
+    notifyContinuationFinished?(workspace: ContinuationTarget, outcome: ContinuationOutcome, details?: ContinuationFinishedDetails): Promise<void>;
     /**
      * The raw text of one repository file at a ref, read through the host's API
      * without a clone, or null when it does not exist. Dispatch reads a coding
@@ -157,6 +208,19 @@ export interface VcsProvider {
      * provider (or test double) without it gives runs no services.
      */
     readRepositoryFile?(input: RepositoryFileInput): Promise<string | null>;
+    /**
+     * Re-derive a continuation's pull request description without pushing (a fix
+     * round that made no changes). Undefined when there is nothing to refresh
+     * (no description details, or a remote without pull requests). Never throws.
+     */
+    refreshPullRequestDescription?(workspace: ContinuationTarget, details: FinalizeChangesDetails): Promise<DescriptionWriteOutcome | undefined>;
+    /**
+     * Whether the pull request a continuation pushes to is still a draft, per
+     * the host: true or false, or undefined when unknown (a fresh run, a remote
+     * without pull requests, a pull request no longer open, or a failed
+     * lookup). Optional; never throws.
+     */
+    continuationPullRequestDraft?(workspace: PreparedWorkspace): Promise<boolean | undefined>;
 }
 export type ContinuationOutcome = "succeeded" | "failed" | "budget_exhausted";
 export interface ContinuationFinishedDetails {
@@ -164,10 +228,23 @@ export interface ContinuationFinishedDetails {
     agentName?: string;
     /** Host-safe sentence naming the run's budget; used with `budget_exhausted`. */
     budgetSentence?: string;
+    /** Host-safe sentence for a run that finished over its base budget (core/budget-wording.ts); used with `succeeded`. */
+    overrunSentence?: string;
     /** Host-safe sentence naming a model-provider refusal (see core/provider-wording.ts); used with `failed`. */
     providerSentence?: string;
     /** Host-safe sentence naming a coding-run service that never became ready (coding/services/wording.ts); used with `failed`. */
     serviceSentence?: string;
     /** Host-safe sentence naming a protected path the run's changes touched (coding/protected-path-wording.ts); used with `failed`. */
     protectedPathSentence?: string;
+    /** Host-safe sentence naming what was merged from the target branch (coding/merge-wording.ts); used with `succeeded`. */
+    mergeSentence?: string;
+    /** Host-safe sentence naming a file still holding conflict markers (coding/merge-wording.ts); used with `failed`. */
+    conflictMarkersSentence?: string;
+    /**
+     * Set with `budget_exhausted` when the run's changes so far were pushed anyway
+     * (the pull request it opened or continued, or a branch with no number).
+     */
+    changesPushed?: {
+        pullRequestNumber?: number;
+    };
 }