@wardby/cli 0.6.0 → 0.8.0

package/dist/providers/vcs/git.js

@@ -1,19 +1,41 @@
 import { spawn } from "node:child_process";
-import { lstat, mkdir, opendir, readFile, readlink, realpath, rm } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { lstat, mkdir, open, opendir, readFile, readlink, realpath, rm, writeFile, } from "node:fs/promises";
 import { isAbsolute, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gitExcludePathspecs, normalizeCollectExclusions } from "../../coding/collect-exclude.js";
 import { WARDBY_PROTECTED_PATHS, isProtectedPathException, isWellFormedProtectedPath, protectedPathBody, protectsSomePath, } from "../../coding/protected-paths.js";
 import { ensurePrivateDirectory } from "../../core/private-directory.js";
+import { simulatorGitEnvironment } from "../../config/test-simulators.js";
 import { globRegex } from "../../core/glob.js";
+import { redactExactSecretValues } from "../../core/secret-spans.js";
 import { MAX_REDACTED_SPAN, redactTokenShapedValues, normalizeGitRef } from "../../coding/protocol.js";
-import { isSafeGitHubInstallationToken } from "./github.js";
+import { isSafeGitAuthToken } from "./remote.js";
 export const DEFAULT_MAX_CHANGED_FILES = 1_000;
 export const DEFAULT_MAX_DIFF_BYTES = 1024 * 1024;
 const MAX_GIT_OUTPUT_BYTES = 2 * 1024 * 1024;
 const MAX_WORKSPACE_ENTRIES = 100_000;
 const SAFE_COMMIT_SHA = /^[0-9a-f]{40}$/;
+const SAFE_GIT_USERNAME = /^[A-Za-z0-9._-]{1,64}$/;
 const SAFE_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+/** Where a continuation's target branch is fetched to (never under refs/remotes, so baseCommit's ref is untouched). */
+const MERGE_TARGET_REF = "refs/wardby/merge-target";
+/** Where the head branch is re-fetched while deepening history (see fetchMergeTarget). */
+const MERGE_HEAD_REF = "refs/wardby/merge-head";
+/**
+ * The trusted automatic merge of the target branch, recorded at prepare time:
+ * a commit whose tree is the merge result (markers in conflicted files), whose
+ * parents are baseCommit and the target commit, and whose message carries the
+ * target ref and the conflicted paths as JSON. Recovery and finalize read it
+ * back; the agent's changes are measured against its tree.
+ */
+const MERGE_STATE_REF = "refs/wardby/merge-state";
+const MERGE_STATE_SUBJECT = "wardby merge state";
+/** How far `fetch --deepen` goes, step by step, looking for a merge base in a depth-1 clone. */
+const MERGE_BASE_DEEPEN_STEPS = [64, 256, 1024, 4096];
+/** A conflict marker pair at the start of a line: git writes 7 characters (any longer run counts too), then a space or the line end. */
+const CONFLICT_MARKER_START = /^<{7,}(?: |\r?$)/m;
+const CONFLICT_MARKER_END = /^>{7,}(?: |\r?$)/m;
 const HARDENED_GIT_CONFIG = [
     "-c",
     "core.hooksPath=/dev/null",
@@ -41,11 +63,10 @@ export function redactGitOutput(value, secrets = []) {
     // MAX_REDACTED_SPAN of margin rather than on all 2 MiB git may have produced
     // (see redactAndTruncate: the margin is what keeps truncation safe). The rest
     // is discarded here and never reaches a log or the database.
-    let output = value.slice(0, GIT_OUTPUT_DISPLAY_BYTES + MAX_REDACTED_SPAN);
-    for (const secret of secrets) {
-        if (secret)
-            output = output.split(secret).join("[REDACTED]");
-    }
+    // The shared span-union redactor; any non-empty value counts here, as it always has.
+    const output = redactExactSecretValues(value.slice(0, GIT_OUTPUT_DISPLAY_BYTES + MAX_REDACTED_SPAN), secrets, {
+        minLength: 1,
+    });
     return redactTokenShapedValues(output).slice(0, GIT_OUTPUT_DISPLAY_BYTES);
 }
 /** Runs Git without a shell or inherited application secrets. */
@@ -62,9 +83,12 @@ export class NodeGitCommandRunner {
             options.askPassPath ?? fileURLToPath(new URL("../../../scripts/git-askpass.sh", import.meta.url));
     }
     async run(args, options = {}) {
-        if (options.authToken !== undefined && !isSafeGitHubInstallationToken(options.authToken)) {
+        if (options.authToken !== undefined && !isSafeGitAuthToken(options.authToken)) {
             throw new Error("git_auth_token_invalid");
         }
+        if (options.authUsername !== undefined && !SAFE_GIT_USERNAME.test(options.authUsername)) {
+            throw new Error("git_auth_username_invalid");
+        }
         const env = {
             PATH: this.path,
             HOME: this.options.homeDir,
@@ -77,8 +101,11 @@ export class NodeGitCommandRunner {
             GIT_TERMINAL_PROMPT: "0",
             GCM_INTERACTIVE: "never",
             GIT_ASKPASS: options.authToken ? this.askPassPath : "/bin/false",
+            ...(options.authToken && options.authUsername ? { WARDBY_GIT_USERNAME: options.authUsername } : {}),
             SSH_ASKPASS: "/bin/false",
             GIT_LFS_SKIP_SMUDGE: "1",
+            // WARDBY_TEST_SIMULATORS (test only): the simulator's throwaway CA; empty otherwise.
+            ...simulatorGitEnvironment(),
         };
         const maxBytes = options.maxOutputBytes ?? MAX_GIT_OUTPUT_BYTES;
         const secrets = options.authToken ? [options.authToken] : [];
@@ -133,7 +160,7 @@ export class NodeGitCommandRunner {
                     stdout: Buffer.concat(stdout).toString("utf8"),
                     stderr: redactGitOutput(Buffer.concat(stderr).toString("utf8"), secrets),
                 };
-                if (code !== 0) {
+                if (code !== 0 && (code === null || !options.acceptExitCodes?.includes(code))) {
                     rejectPromise(new GitCommandError(code, result.stderr.trim()));
                     return;
                 }
@@ -192,6 +219,26 @@ function nullSeparated(value) {
         values.pop();
     return values.map(validateChangedPath);
 }
+function safeGitRef(value) {
+    try {
+        return normalizeGitRef(value);
+    }
+    catch {
+        return null;
+    }
+}
+/** The merge state's message: a fixed subject, then the target ref and conflicted paths as JSON. */
+function mergeStateMessage(targetMerge) {
+    return `${MERGE_STATE_SUBJECT}\n\n${JSON.stringify({ ref: targetMerge.ref, conflicted: targetMerge.conflictedPaths })}\n`;
+}
+function sameTargetMerge(left, right) {
+    if (!left || !right)
+        return left === right;
+    return (left.ref === right.ref &&
+        left.targetCommit === right.targetCommit &&
+        left.conflictedPaths.length === right.conflictedPaths.length &&
+        left.conflictedPaths.every((path, index) => path === right.conflictedPaths[index]));
+}
 function directChild(root, child) {
     return child.startsWith(`${root}${sep}`) && !child.slice(root.length + 1).includes(sep);
 }
@@ -244,9 +291,14 @@ export class GitVcsProvider {
         // baseCommit already means exactly what it needs to: "where this
         // round started."
         const cloneBranch = normalized.continuation ? normalized.headRef : normalized.baseRef;
+        // A continuation is first brought up to date with the branch its pull
+        // request targets now (a person may have retargeted it since the root run).
+        const target = normalized.continuation ? await this.remote.pullRequestBase?.(normalized) : null;
+        const mergeRef = target ? safeGitRef(target.ref) : null;
+        let mergeFetched = false;
         try {
             await this.remote.withAccess(normalized.repository, async (token) => {
-                const auth = token !== undefined ? { authToken: token } : {};
+                const auth = this.gitAuth(token);
                 if (this.remote.refNotFoundError) {
                     const listed = await this.git.run([
                         ...HARDENED_GIT_CONFIG,
@@ -280,6 +332,9 @@ export class GitVcsProvider {
                     cloneUrl,
                     workspacePath,
                 ], { cwd: runRoot, ...auth });
+                if (mergeRef && mergeRef !== normalized.headRef) {
+                    mergeFetched = await this.fetchMergeTarget(gitMetadataPath, workspacePath, cloneBranch, mergeRef, auth);
+                }
             });
             await rm(resolve(workspacePath, ".git"), { force: true });
             const baseCommit = await this.revParseRaw(gitMetadataPath, workspacePath, `refs/remotes/origin/${cloneBranch}^{commit}`);
@@ -307,7 +362,15 @@ export class GitVcsProvider {
                 "HEAD",
                 `refs/heads/${normalized.headRef}`,
             ]);
-            await this.gitForPaths(gitMetadataPath, workspacePath, ["read-tree", "--reset", "-u", baseCommit]);
+            const merged = mergeFetched && mergeRef
+                ? await this.mergeTargetBranch(gitMetadataPath, workspacePath, baseCommit, mergeRef)
+                : null;
+            await this.gitForPaths(gitMetadataPath, workspacePath, [
+                "read-tree",
+                "--reset",
+                "-u",
+                merged?.tree ?? baseCommit,
+            ]);
             await this.inspectWorkspace(workspacePath);
             return {
                 id: `vcs-${normalized.runId}`,
@@ -315,6 +378,7 @@ export class GitVcsProvider {
                 baseCommit,
                 workspacePath,
                 gitMetadataPath,
+                ...(merged ? { targetMerge: merged.targetMerge } : {}),
             };
         }
         catch (error) {
@@ -351,19 +415,30 @@ export class GitVcsProvider {
         const symbolicHead = (await this.gitFor(prepared, ["symbolic-ref", "--short", "HEAD"])).stdout.trim();
         if (symbolicHead !== prepared.headRef)
             throw new Error("vcs_head_ref_mismatch");
+        const merge = await this.readMergeState(prepared);
         const currentHead = await this.revParse(prepared, "HEAD");
         if (currentHead !== prepared.baseCommit) {
             const parent = await this.revParse(prepared, "HEAD^");
             if (parent !== prepared.baseCommit)
                 throw new Error("vcs_commit_history_invalid");
+            if (merge && (await this.revParse(prepared, "HEAD^2")) !== merge.targetCommit) {
+                throw new Error("vcs_commit_history_invalid");
+            }
         }
-        return prepared;
+        if (!merge)
+            return prepared;
+        const { stateCommit: _stateCommit, ...targetMerge } = merge;
+        return { ...prepared, targetMerge };
     }
     async finalizeChanges(workspace, details) {
         const prepared = await this.validatePrepared(workspace);
         await this.inspectWorkspace(prepared.workspacePath);
         await this.assertRemote(prepared);
         await this.assertSafeLocalConfig(prepared.gitMetadataPath);
+        // The merge state on disk is the trusted record; the handle must agree with it.
+        const merge = await this.readMergeState(prepared);
+        if (!sameTargetMerge(merge, prepared.targetMerge))
+            throw new Error("vcs_workspace_handle_invalid");
         // Excluded paths (src/coding/collect-exclude.ts) are never collected from the worker, so
         // they are also neither added nor deleted here: tracked files under them stay untouched.
         await this.gitFor(prepared, [
@@ -373,15 +448,12 @@ export class GitVcsProvider {
             ":/",
             ...gitExcludePathspecs(normalizeCollectExclusions(prepared.collectExclude)),
         ]);
-        const changed = nullSeparated((await this.gitFor(prepared, [
-            "diff",
-            "--cached",
-            "--name-only",
-            "-z",
-            "--no-renames",
-            prepared.baseCommit,
-            "--",
-        ])).stdout);
+        // Every check below applies to the agent's own changes: against baseCommit, or, after a
+        // merge, against the trusted automatic merge result (so the target branch's own changes,
+        // protected paths included, pass, while any agent edit -- a conflict it resolved, a
+        // target change it reverted -- is checked).
+        const comparedTo = merge?.stateCommit ?? prepared.baseCommit;
+        const changed = nullSeparated((await this.gitFor(prepared, ["diff", "--cached", "--name-only", "-z", "--no-renames", comparedTo, "--"])).stdout);
         if (changed.length > this.maxChangedFiles)
             throw new Error("vcs_changed_file_limit");
         const protectedChange = changed.find(protectedPathMatcher(prepared.protectedPaths));
@@ -389,7 +461,7 @@ export class GitVcsProvider {
             throw new Error(`vcs_protected_path:${protectedChange}`);
         let diff;
         try {
-            diff = (await this.gitFor(prepared, ["diff", "--cached", "--binary", "--no-ext-diff", "--no-textconv", prepared.baseCommit, "--"], { maxOutputBytes: this.maxDiffBytes })).stdout;
+            diff = (await this.gitFor(prepared, ["diff", "--cached", "--binary", "--no-ext-diff", "--no-textconv", comparedTo, "--"], { maxOutputBytes: this.maxDiffBytes })).stdout;
         }
         catch (error) {
             if (error instanceof GitCommandError && error.message.includes("git_output_limit")) {
@@ -399,8 +471,12 @@ export class GitVcsProvider {
         }
         if (Buffer.byteLength(diff, "utf8") > this.maxDiffBytes)
             throw new Error("vcs_diff_size_limit");
+        // After the size limits, so a conflicted file is never read past what the diff limit allows.
+        if (merge)
+            await this.assertConflictsResolved(prepared.workspacePath, merge.conflictedPaths);
         const currentHead = await this.revParse(prepared, "HEAD");
-        if (changed.length === 0 && currentHead === prepared.baseCommit) {
+        // A merge with no agent edits still has the merge itself to push.
+        if (!merge && changed.length === 0 && currentHead === prepared.baseCommit) {
             return {
                 outcome: "no_changes",
                 repository: prepared.repository,
@@ -412,7 +488,10 @@ export class GitVcsProvider {
         if (symbolicHead !== prepared.headRef)
             throw new Error("vcs_head_ref_mismatch");
         let commitSha;
-        if (currentHead === prepared.baseCommit) {
+        if (currentHead === prepared.baseCommit && merge) {
+            commitSha = await this.commitMerge(prepared, merge);
+        }
+        else if (currentHead === prepared.baseCommit) {
             await this.gitFor(prepared, ["commit", "--no-verify", "--no-gpg-sign", "-m", `Wardby run ${prepared.runId}`]);
             commitSha = await this.revParse(prepared, "HEAD");
         }
@@ -420,14 +499,21 @@ export class GitVcsProvider {
             const parent = await this.revParse(prepared, "HEAD^");
             if (parent !== prepared.baseCommit)
                 throw new Error("vcs_commit_history_invalid");
+            if (merge && (await this.revParse(prepared, "HEAD^2")) !== merge.targetCommit) {
+                throw new Error("vcs_commit_history_invalid");
+            }
             const afterCommitChanges = nullSeparated((await this.gitFor(prepared, ["diff", "--cached", "--name-only", "-z", "HEAD", "--"])).stdout);
             if (afterCommitChanges.length > 0)
                 throw new Error("vcs_finalized_workspace_changed");
             commitSha = currentHead;
         }
         await this.remote.assertContinuationOpen(prepared);
+        // Before the push: a description comment must already exist when the push starts a review.
+        await this.remote
+            .proposeDescriptionBeforePush?.({ workspace: prepared, details, changedPaths: changed, commitSha })
+            .catch(() => undefined);
         await this.pushOnce(prepared, commitSha);
-        const published = await this.remote.publish({ workspace: prepared, details, changedPaths: changed });
+        const published = await this.remote.publish({ workspace: prepared, details, changedPaths: changed, commitSha });
         if (published.kind === "branch") {
             if (published.branch !== prepared.headRef)
                 throw new Error("vcs_head_ref_mismatch");
@@ -449,8 +535,47 @@ export class GitVcsProvider {
             commitSha,
             pullRequestNumber: published.number,
             pullRequestUrl: published.url,
+            ...(published.description ? { description: published.description } : {}),
+            ...(merge && prepared.continuation
+                ? {
+                    targetMerge: {
+                        ref: merge.ref,
+                        targetCommit: merge.targetCommit,
+                        conflicts: merge.conflictedPaths.length,
+                    },
+                }
+                : {}),
         };
     }
+    /** The two-parent merge commit (baseCommit, the target) of the staged tree, as the Wardby identity. */
+    async commitMerge(prepared, merge) {
+        const tree = (await this.gitFor(prepared, ["write-tree"])).stdout.trim();
+        if (!SAFE_COMMIT_SHA.test(tree))
+            throw new Error("vcs_commit_sha_invalid");
+        const commitSha = (await this.gitFor(prepared, [
+            "commit-tree",
+            tree,
+            "-p",
+            prepared.baseCommit,
+            "-p",
+            merge.targetCommit,
+            "-m",
+            `Merge ${merge.ref} into ${prepared.headRef} (Wardby run ${prepared.runId})`,
+        ])).stdout.trim();
+        if (!SAFE_COMMIT_SHA.test(commitSha))
+            throw new Error("vcs_commit_sha_invalid");
+        await this.gitFor(prepared, ["update-ref", `refs/heads/${prepared.headRef}`, commitSha, prepared.baseCommit]);
+        return commitSha;
+    }
+    /** Re-derive a continuation's PR description without a push, delegated to the remote; never throws. */
+    async refreshPullRequestDescription(workspace, details) {
+        try {
+            return await this.remote.refreshDescription?.(workspace, details);
+        }
+        catch {
+            return { kind: "skipped", reason: "error" };
+        }
+    }
     async cleanup(workspace) {
         const expected = this.expectedPaths(workspace.runId);
         if (workspace.id !== `vcs-${workspace.runId}` ||
@@ -465,6 +590,15 @@ export class GitVcsProvider {
      * delegated to the remote; a remote without one is a no-op. Wrapped so
      * this can NEVER throw or otherwise affect the real coding run.
      */
+    /** Delegated to the remote; never throws (undefined on any failure). */
+    async continuationPullRequestDraft(workspace) {
+        try {
+            return await this.remote.continuationPullRequestDraft?.(workspace);
+        }
+        catch {
+            return undefined;
+        }
+    }
     async notifyContinuationStarted(workspace, details) {
         try {
             await this.remote.notifyContinuationStarted?.(workspace, details);
@@ -561,6 +695,179 @@ export class GitVcsProvider {
         }
         return { ...workspace, ...normalized };
     }
+    /**
+     * Fetches a continuation's target branch from the same `origin` the clone
+     * came from (never another URL, so never a fork) and deepens the depth-1
+     * clone step by step until the head and the target share a merge base.
+     * Returns true once they do; throws vcs_target_merge_failed when the fetch
+     * fails or no merge base turns up within MERGE_BASE_DEEPEN_STEPS.
+     */
+    async fetchMergeTarget(gitMetadataPath, workspacePath, cloneBranch, ref, auth) {
+        const fetch = (depth, refspec) => this.gitForPaths(gitMetadataPath, workspacePath, [...this.remote.gitConfig, "fetch", "--no-tags", "--no-write-fetch-head", ...depth, "origin", refspec], auth);
+        const target = `+refs/heads/${ref}:${MERGE_TARGET_REF}`;
+        // The head is deepened through its own ref under refs/wardby, so the clone's
+        // refs/remotes/origin/<head> (baseCommit) never moves.
+        const head = `+refs/heads/${cloneBranch}:${MERGE_HEAD_REF}`;
+        try {
+            await fetch(["--depth", "1"], target);
+            for (const step of [0, ...MERGE_BASE_DEEPEN_STEPS]) {
+                if (step > 0) {
+                    // One fetch per side: newer git deepens only the refs a fetch names
+                    // (older git deepened every shallow boundary), and a fetch naming
+                    // both deepens only one of them.
+                    await fetch([`--deepen=${step}`], head);
+                    await fetch([`--deepen=${step}`], target);
+                }
+                const base = await this.gitForPaths(gitMetadataPath, workspacePath, ["merge-base", `refs/remotes/origin/${cloneBranch}`, MERGE_TARGET_REF], { acceptExitCodes: [1] });
+                if (base.stdout.trim())
+                    return true;
+            }
+        }
+        catch (error) {
+            throw new Error("vcs_target_merge_failed", { cause: error });
+        }
+        throw new Error("vcs_target_merge_failed");
+    }
+    /**
+     * Merges the fetched target into baseCommit without touching the index or
+     * the working tree (`merge-tree --write-tree`: no MERGE_HEAD, no hooks, no
+     * merge drivers -- none are configured), and records the result as the merge
+     * state. Null when the target is already part of the branch (nothing to merge).
+     */
+    async mergeTargetBranch(gitMetadataPath, workspacePath, baseCommit, ref) {
+        const targetCommit = await this.revParseRaw(gitMetadataPath, workspacePath, `${MERGE_TARGET_REF}^{commit}`);
+        const mergeBase = (await this.gitForPaths(gitMetadataPath, workspacePath, ["merge-base", baseCommit, targetCommit])).stdout.trim();
+        if (mergeBase === targetCommit)
+            return null;
+        // The clone is --no-checkout and nothing is read into the index or the
+        // working tree until after this merge, so no repository .gitattributes
+        // (a marker size, `-merge`, `merge=union`) can steer it.
+        let output;
+        try {
+            output = (await this.gitForPaths(gitMetadataPath, workspacePath, ["merge-tree", "--write-tree", "-z", "--name-only", "--no-messages", baseCommit, targetCommit], { acceptExitCodes: [1] })).stdout;
+        }
+        catch (error) {
+            throw new Error("vcs_target_merge_failed", { cause: error });
+        }
+        const [tree, ...paths] = output.split("\0");
+        if (!SAFE_COMMIT_SHA.test(tree))
+            throw new Error("vcs_target_merge_failed");
+        const conflictedPaths = [...new Set(paths.filter(Boolean))].map(validateChangedPath);
+        if (conflictedPaths.length > this.maxChangedFiles)
+            throw new Error("vcs_target_merge_failed");
+        const targetMerge = { ref, targetCommit, conflictedPaths };
+        // The message goes through a file: a long conflicted-path list could pass an argument's size limit.
+        const messagePath = resolve(gitMetadataPath, "WARDBY_MERGE_STATE_MSG");
+        await writeFile(messagePath, mergeStateMessage(targetMerge), { mode: 0o600 });
+        try {
+            const stateCommit = (await this.gitForPaths(gitMetadataPath, workspacePath, [
+                "commit-tree",
+                tree,
+                "-p",
+                baseCommit,
+                "-p",
+                targetCommit,
+                "-F",
+                messagePath,
+            ])).stdout.trim();
+            if (!SAFE_COMMIT_SHA.test(stateCommit))
+                throw new Error("vcs_commit_sha_invalid");
+            await this.gitForPaths(gitMetadataPath, workspacePath, ["update-ref", MERGE_STATE_REF, stateCommit]);
+        }
+        finally {
+            await rm(messagePath, { force: true });
+        }
+        return { tree, targetMerge };
+    }
+    /** The recorded merge state (see MERGE_STATE_REF), validated, or undefined when the workspace merged nothing. */
+    async readMergeState(workspace) {
+        const { gitMetadataPath, workspacePath } = workspace;
+        const stateCommit = (await this.gitForPaths(gitMetadataPath, workspacePath, [
+            "for-each-ref",
+            "--format=%(objectname)",
+            MERGE_STATE_REF,
+        ])).stdout.trim();
+        if (!stateCommit)
+            return undefined;
+        if (!SAFE_COMMIT_SHA.test(stateCommit))
+            throw new Error("vcs_merge_state_invalid");
+        const raw = (await this.gitForPaths(gitMetadataPath, workspacePath, ["cat-file", "commit", stateCommit])).stdout;
+        const split = raw.indexOf("\n\n");
+        if (split < 0)
+            throw new Error("vcs_merge_state_invalid");
+        const parents = raw
+            .slice(0, split)
+            .split("\n")
+            .filter((line) => line.startsWith("parent "))
+            .map((line) => line.slice("parent ".length));
+        const message = raw.slice(split + 2);
+        if (parents.length !== 2 ||
+            parents[0] !== workspace.baseCommit ||
+            !SAFE_COMMIT_SHA.test(parents[1]) ||
+            !message.startsWith(`${MERGE_STATE_SUBJECT}\n\n`)) {
+            throw new Error("vcs_merge_state_invalid");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(message.slice(MERGE_STATE_SUBJECT.length + 2));
+        }
+        catch (error) {
+            throw new Error("vcs_merge_state_invalid", { cause: error });
+        }
+        const state = parsed;
+        if (typeof state.ref !== "string" ||
+            !Array.isArray(state.conflicted) ||
+            state.conflicted.length > this.maxChangedFiles ||
+            state.conflicted.some((path) => typeof path !== "string")) {
+            throw new Error("vcs_merge_state_invalid");
+        }
+        const ref = safeGitRef(state.ref);
+        if (!ref)
+            throw new Error("vcs_merge_state_invalid");
+        return {
+            ref,
+            targetCommit: parents[1],
+            conflictedPaths: state.conflicted.map(validateChangedPath),
+            stateCommit,
+        };
+    }
+    /**
+     * Refuses to finalize while a file the merge left conflicted still holds a
+     * conflict marker pair. Only those files are read: elsewhere a line of
+     * `<<<<<<<` may be legitimate content (a fixture, a doc about merging).
+     */
+    async assertConflictsResolved(workspacePath, conflictedPaths) {
+        for (const path of conflictedPaths) {
+            const fullPath = resolve(workspacePath, path);
+            if (!fullPath.startsWith(`${workspacePath}${sep}`))
+                throw new Error("vcs_changed_path_invalid");
+            // One no-follow open, then stat and read through that handle: nothing can swap the file in between.
+            let handle;
+            try {
+                handle = await open(fullPath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+            }
+            catch (error) {
+                const code = error.code;
+                // Deleted while resolving, or a symlink (ELOOP): nothing left to hold a marker.
+                if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP")
+                    continue;
+                throw error;
+            }
+            let content;
+            try {
+                // Not a regular file (a directory now stands there): nothing to scan.
+                if (!(await handle.stat()).isFile())
+                    continue;
+                content = await handle.readFile("utf8");
+            }
+            finally {
+                await handle.close();
+            }
+            if (CONFLICT_MARKER_START.test(content) && CONFLICT_MARKER_END.test(content)) {
+                throw new Error(`vcs_conflict_markers_remain:${path}`);
+            }
+        }
+    }
     async inspectWorkspace(workspacePath) {
         const rootStat = await lstat(workspacePath);
         if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
@@ -635,10 +942,16 @@ export class GitVcsProvider {
             throw new Error("vcs_git_config_unsafe");
         }
     }
+    /** The git credentials for a remote's access token; none when the remote needs no token. */
+    gitAuth(token) {
+        if (token === undefined)
+            return {};
+        return { authToken: token, ...(this.remote.gitUsername ? { authUsername: this.remote.gitUsername } : {}) };
+    }
     async pushOnce(workspace, commitSha) {
         this.remote.assertPushRef?.(workspace.headRef);
         await this.remote.withAccess(workspace.repository, async (token) => {
-            const auth = token !== undefined ? { authToken: token } : {};
+            const auth = this.gitAuth(token);
             const remote = await this.remoteHead(workspace, auth);
             if (remote === commitSha)
                 return;

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

@@ -1,6 +1,6 @@
 import { type GitHubRepositoryAccess, type RepositoryFileInput } from "./github.js";
 import type { GitRemote, PublishInput, PublishResult } from "./remote.js";
-import type { ContinuationFinishedDetails, ContinuationOutcome, PreparedWorkspace } from "./types.js";
+import type { ContinuationFinishedDetails, ContinuationOutcome, ContinuationTarget, DescriptionWriteOutcome, FinalizeChangesDetails, PreparedWorkspace } from "./types.js";
 export interface GitHubRemoteOptions {
     github: GitHubRepositoryAccess;
     /** Test-only transport override; production composition always uses github.com. */
@@ -42,7 +42,30 @@ export declare class GitHubRemote implements GitRemote {
             rootRunId: string;
         };
     }): Promise<void>;
-    publish({ workspace: prepared, details, changedPaths }: PublishInput): Promise<PublishResult>;
+    /** See GitRemote.pullRequestBase: the root run's open PR's current base branch. Never throws. */
+    pullRequestBase(input: {
+        runId: string;
+        repository: string;
+        baseRef: string;
+        headRef: string;
+        continuation?: {
+            rootRunId: string;
+        };
+    }): Promise<{
+        ref: string;
+    } | null>;
+    /** See VcsProvider.continuationPullRequestDraft: GitHub's draft flag on the root run's open PR. Never throws. */
+    continuationPullRequestDraft(workspace: PreparedWorkspace): Promise<boolean | undefined>;
+    /** A continuation's description comment, written before the push (see GitRemote.proposeDescriptionBeforePush). Never throws. */
+    proposeDescriptionBeforePush({ workspace: prepared, details, changedPaths, commitSha, }: PublishInput & {
+        commitSha: string;
+    }): Promise<void>;
+    publish({ workspace: prepared, details, changedPaths, commitSha }: PublishInput): Promise<PublishResult>;
+    /** The no-push path: a fix round that changed nothing still re-derives its PR description. */
+    refreshDescription(workspace: ContinuationTarget, details: FinalizeChangesDetails): Promise<DescriptionWriteOutcome | undefined>;
+    /** Never throws: a description problem must not fail an already-pushed run. */
+    private updateDescription;
+    private descriptionInput;
     /**
      * Best-effort "wardby is working on this PR" signal (see VcsProvider) --
      * whole body wrapped so this can NEVER throw or otherwise affect the
@@ -62,6 +85,6 @@ export declare class GitHubRemote implements GitRemote {
      * github.ts). Safe to call more than once for the same run. Same
      * never-throw contract as notifyContinuationStarted.
      */
-    notifyContinuationFinished(workspace: PreparedWorkspace, outcome: ContinuationOutcome, details?: ContinuationFinishedDetails): Promise<void>;
+    notifyContinuationFinished(workspace: ContinuationTarget, outcome: ContinuationOutcome, details?: ContinuationFinishedDetails): Promise<void>;
     readRepositoryFile(input: RepositoryFileInput): Promise<string | null>;
 }