@gethmy/harness 1.0.0

package/src/git-pr.ts

@@ -0,0 +1,839 @@
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+import type { Card } from "@harmony/shared";
+import { SAFE_GIT_REF_PATTERN } from "@harmony/shared";
+import type { MergeStrategy, WorktreeConfig } from "./exec-types.js";
+import { log } from "./log.js";
+
+// Lazy + memoised: promisify(execFile) has no reason to run at module load.
+// git-pr.ts sits in the motor's public barrel (@gethmy/harness `export *`), so
+// hoisting this to module scope would force EVERY consumer of ANY harness
+// export to pay for constructing a promisified execFile, whether or not they
+// ever call a git-pr function. Deferred to first call instead.
+function createExecFileAsync() {
+  return promisify(execFile);
+}
+
+let cachedExecFileAsync: ReturnType<typeof createExecFileAsync> | undefined;
+
+function execFileAsync() {
+  return (cachedExecFileAsync ??= createExecFileAsync());
+}
+
+const TAG = "git-pr";
+
+// ============ GIT PROVIDER DETECTION ============
+
+export type GitProvider =
+  | "github"
+  | "azure"
+  | "gitlab"
+  | "bitbucket"
+  | "unknown";
+
+export function detectGitProvider(cwd?: string): GitProvider {
+  try {
+    const url = execFileSync("git", ["remote", "get-url", "origin"], {
+      cwd,
+      encoding: "utf-8",
+    }).trim();
+
+    if (url.includes("github.com")) return "github";
+    if (url.includes("dev.azure.com") || url.includes("visualstudio.com"))
+      return "azure";
+    if (url.includes("gitlab.com") || /\bgitlab\b/.test(url)) return "gitlab";
+    if (url.includes("bitbucket.org")) return "bitbucket";
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Validate that the CLI for the detected git provider is installed and authenticated.
+ * Returns the provider name or throws with instructions.
+ */
+export function validateGitProviderCli(
+  provider: GitProvider,
+  cwd?: string,
+): void {
+  switch (provider) {
+    case "github": {
+      try {
+        execFileSync("gh", ["auth", "status"], { cwd, stdio: "pipe" });
+      } catch {
+        throw new Error(
+          "GitHub CLI (gh) is not authenticated. Run: gh auth login",
+        );
+      }
+      break;
+    }
+    case "azure": {
+      try {
+        execFileSync("az", ["--version"], { cwd, stdio: "pipe" });
+      } catch {
+        throw new Error(
+          "Azure CLI (az) not found. Install it: https://learn.microsoft.com/en-us/cli/azure/install-azure-cli",
+        );
+      }
+      try {
+        execFileSync("az", ["account", "show"], { cwd, stdio: "pipe" });
+      } catch {
+        throw new Error("Azure CLI is not authenticated. Run: az login");
+      }
+      break;
+    }
+    case "gitlab": {
+      try {
+        execFileSync("glab", ["auth", "status"], { cwd, stdio: "pipe" });
+      } catch {
+        throw new Error(
+          "GitLab CLI (glab) is not installed or not authenticated. Install: https://gitlab.com/gitlab-org/cli — then run: glab auth login",
+        );
+      }
+      break;
+    }
+    case "bitbucket":
+    case "unknown":
+      log.warn(
+        TAG,
+        `Git provider "${provider}" — PR creation will be skipped (no CLI support)`,
+      );
+      break;
+  }
+}
+
+// ============ PR MERGE STATUS ============
+
+export type PrState = "merged" | "open" | "closed" | "unknown";
+
+const VALID_PR_URL_RE =
+  /^https:\/\/(github\.com|gitlab\.com|dev\.azure\.com|bitbucket\.org)\//;
+const PR_URL_RE = /PR:\s*(https?:\/\/[^\s)]+)/;
+
+/** Validate that a PR URL looks like a real provider URL. */
+function isValidPrUrl(url: string): boolean {
+  return VALID_PR_URL_RE.test(url);
+}
+
+// ============ CI STATUS & MERGE (Task 2) ============
+
+export type PrCiStatus = "success" | "pending" | "failure" | "unknown";
+
+const REVIEWED_SHA_RE = /^Reviewed-SHA:\s*([0-9a-f]{7,40})\s*$/im;
+
+export function extractReviewedSha(description: string | null): string | null {
+  if (!description) return null;
+  const m = description.match(REVIEWED_SHA_RE);
+  return m ? m[1] : null;
+}
+
+export function upsertReviewedSha(description: string, sha: string): string {
+  const line = `Reviewed-SHA: ${sha}`;
+  if (REVIEWED_SHA_RE.test(description)) {
+    return description.replace(REVIEWED_SHA_RE, line);
+  }
+  const sep = description ? "\n" : "";
+  return `${description}${sep}${line}`;
+}
+
+/** Derive a single CI verdict from a `gh pr view --json statusCheckRollup` array.
+ * Handles both CheckRun ({status, conclusion}) and legacy StatusContext ({state}).
+ * Empty/non-array (no checks configured) → unknown (conservative: never auto-merge). */
+export function deriveCiStatus(rollup: unknown): PrCiStatus {
+  if (!Array.isArray(rollup) || rollup.length === 0) return "unknown";
+  let anyPending = false;
+  for (const check of rollup) {
+    if (typeof check !== "object" || check === null) continue;
+    const c = check as Record<string, unknown>;
+    if (typeof c.status === "string") {
+      // CheckRun
+      if (c.status.toUpperCase() !== "COMPLETED") {
+        anyPending = true;
+        continue;
+      }
+      const conclusion =
+        typeof c.conclusion === "string" ? c.conclusion.toUpperCase() : "";
+      if (["SUCCESS", "NEUTRAL", "SKIPPED"].includes(conclusion)) continue;
+      return "failure";
+    }
+    if (typeof c.state === "string") {
+      // StatusContext
+      const state = c.state.toUpperCase();
+      if (state === "SUCCESS") continue;
+      if (state === "PENDING") {
+        anyPending = true;
+        continue;
+      }
+      return "failure";
+    }
+  }
+  return anyPending ? "pending" : "success";
+}
+
+export async function getPrStatus(
+  prUrl: string,
+  cwd: string,
+  provider: GitProvider,
+): Promise<{ ciStatus: PrCiStatus; headSha: string | null }> {
+  if (provider !== "github" || !isValidPrUrl(prUrl)) {
+    return { ciStatus: "unknown", headSha: null };
+  }
+  try {
+    const { stdout } = await execFileAsync()(
+      "gh",
+      ["pr", "view", prUrl, "--json", "statusCheckRollup,headRefOid"],
+      { cwd, encoding: "utf-8", timeout: 10_000 },
+    );
+    const parsed = JSON.parse(stdout.trim()) as {
+      statusCheckRollup?: unknown;
+      headRefOid?: unknown;
+    };
+    const headSha =
+      typeof parsed.headRefOid === "string" ? parsed.headRefOid : null;
+    return { ciStatus: deriveCiStatus(parsed.statusCheckRollup), headSha };
+  } catch {
+    return { ciStatus: "unknown", headSha: null };
+  }
+}
+
+export async function mergePullRequest(
+  prUrl: string,
+  cwd: string,
+  provider: GitProvider,
+  strategy: MergeStrategy,
+  deleteBranch: boolean,
+): Promise<void> {
+  if (provider !== "github") {
+    throw new Error(`auto-merge unsupported for provider "${provider}"`);
+  }
+  const args = ["pr", "merge", prUrl, `--${strategy}`];
+  if (deleteBranch) args.push("--delete-branch");
+  await execFileAsync()("gh", args, {
+    cwd,
+    encoding: "utf-8",
+    timeout: 30_000,
+  });
+}
+
+export function getHeadSha(cwd: string): string | null {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd,
+      encoding: "utf-8",
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check whether a PR has been merged using the git provider CLI (async).
+ */
+export async function checkPrMergeStatus(
+  prUrl: string,
+  cwd: string,
+  provider: GitProvider,
+): Promise<PrState> {
+  if (!isValidPrUrl(prUrl)) return "unknown";
+
+  try {
+    switch (provider) {
+      case "github": {
+        const { stdout } = await execFileAsync()(
+          "gh",
+          ["pr", "view", prUrl, "--json", "state", "--jq", ".state"],
+          { cwd, encoding: "utf-8", timeout: 10_000 },
+        );
+        switch (stdout.trim()) {
+          case "MERGED":
+            return "merged";
+          case "OPEN":
+            return "open";
+          case "CLOSED":
+            return "closed";
+          default:
+            return "unknown";
+        }
+      }
+      case "gitlab": {
+        // Extract MR ID from URL (e.g. .../merge_requests/42)
+        const mrMatch = prUrl.match(/merge_requests\/(\d+)/);
+        if (!mrMatch) return "unknown";
+        const { stdout } = await execFileAsync()(
+          "glab",
+          ["mr", "view", mrMatch[1], "--output", "json"],
+          { cwd, encoding: "utf-8", timeout: 10_000 },
+        );
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(stdout.trim());
+        } catch {
+          log.warn(
+            TAG,
+            `Failed to parse glab JSON output for MR ${mrMatch[1]}`,
+          );
+          return "unknown";
+        }
+        if (typeof parsed !== "object" || parsed === null) return "unknown";
+        const state = (parsed as Record<string, unknown>).state;
+        if (state === "merged") return "merged";
+        if (state === "opened") return "open";
+        if (state === "closed") return "closed";
+        return "unknown";
+      }
+      default:
+        return "unknown";
+    }
+  } catch {
+    return "unknown";
+  }
+}
+
+// ============ PR HEAD BRANCH RESOLUTION (for review checkout) ============
+
+export type PrBranchResolution =
+  | { kind: "branch"; branch: string }
+  | { kind: "skip"; reason: string };
+
+/** Strip a `refs/heads/` prefix from a fully-qualified git ref. Azure returns
+ * `sourceRefName` as `refs/heads/<branch>`; a short name passes through. */
+function stripHeadsPrefix(ref: string): string {
+  return ref.replace(/^refs\/heads\//, "");
+}
+
+/** Wrap a resolved head-branch name in a PrBranchResolution, gating on the
+ * shared safe-ref pattern. Shared by every provider's pure parser. */
+function branchOrSkip(branch: string | null): PrBranchResolution {
+  if (!branch) return { kind: "skip", reason: "PR has no head branch name" };
+  if (!SAFE_GIT_REF_PATTERN.test(branch)) {
+    return { kind: "skip", reason: `unsafe git ref: ${branch}` };
+  }
+  return { kind: "branch", branch };
+}
+
+/**
+ * Pure decision from a GitHub `gh pr view --json headRefName,isCrossRepository`
+ * payload (or null when the CLI call failed).
+ */
+function decideGithubPrBranch(rawJson: string | null): PrBranchResolution {
+  if (rawJson === null) {
+    return { kind: "skip", reason: "gh pr view failed" };
+  }
+  let parsed: { headRefName?: unknown; isCrossRepository?: unknown };
+  try {
+    parsed = JSON.parse(rawJson.trim());
+  } catch {
+    return { kind: "skip", reason: "unparseable gh pr view output" };
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return { kind: "skip", reason: "unparseable gh pr view output" };
+  }
+  if (parsed.isCrossRepository === true) {
+    return {
+      kind: "skip",
+      reason: "fork PR (cross-repo head branch not on origin)",
+    };
+  }
+  return branchOrSkip(
+    typeof parsed.headRefName === "string" ? parsed.headRefName : null,
+  );
+}
+
+/**
+ * Pure decision from an Azure DevOps `az repos pr show --output json` payload
+ * (or null when the CLI call failed). Azure names the head branch as a
+ * fully-qualified `sourceRefName` (`refs/heads/<branch>`, stripped here) and
+ * marks a fork PR with a non-null `forkSource`.
+ */
+function decideAzurePrBranch(rawJson: string | null): PrBranchResolution {
+  if (rawJson === null) {
+    return { kind: "skip", reason: "az repos pr show failed" };
+  }
+  let parsed: { sourceRefName?: unknown; forkSource?: unknown };
+  try {
+    parsed = JSON.parse(rawJson.trim());
+  } catch {
+    return { kind: "skip", reason: "unparseable az repos pr show output" };
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return { kind: "skip", reason: "unparseable az repos pr show output" };
+  }
+  if (parsed.forkSource != null) {
+    return {
+      kind: "skip",
+      reason: "fork PR (cross-repo head branch not on origin)",
+    };
+  }
+  const ref =
+    typeof parsed.sourceRefName === "string" ? parsed.sourceRefName : null;
+  return branchOrSkip(ref ? stripHeadsPrefix(ref) : null);
+}
+
+/**
+ * Pure decision: given the provider and the raw provider-CLI stdout (or null
+ * when the call failed), decide the reviewable head branch. Provider-dispatched
+ * so a new provider is one `case` + one pure parser — callers do not change.
+ */
+export function decidePrBranch(
+  provider: GitProvider,
+  rawJson: string | null,
+): PrBranchResolution {
+  switch (provider) {
+    case "github":
+      return decideGithubPrBranch(rawJson);
+    case "azure":
+      return decideAzurePrBranch(rawJson);
+    default:
+      return {
+        kind: "skip",
+        reason: `PR-link review not yet supported for provider "${provider}"`,
+      };
+  }
+}
+
+/**
+ * Extract the numeric PR id from an Azure DevOps PR URL, e.g.
+ * `https://dev.azure.com/{org}/{project}/_git/{repo}/pullrequest/123` (also the
+ * legacy `{org}.visualstudio.com/...` host). Returns null when no id is present.
+ */
+export function extractAzurePrId(prUrl: string): string | null {
+  const m = prUrl.match(/pullrequest\/(\d+)/i);
+  return m ? m[1] : null;
+}
+
+/**
+ * Resolve a PR's reviewable head branch. Thin IO wrapper over decidePrBranch:
+ * GitHub via `gh pr view`, Azure DevOps via `az repos pr show`; any other
+ * provider short-circuits to a structured skip.
+ */
+export async function resolvePrHeadBranch(
+  prUrl: string,
+  cwd: string,
+  provider: GitProvider,
+): Promise<PrBranchResolution> {
+  if (provider === "github") {
+    try {
+      const { stdout } = await execFileAsync()(
+        "gh",
+        ["pr", "view", prUrl, "--json", "headRefName,isCrossRepository"],
+        { cwd, encoding: "utf-8", timeout: 10_000 },
+      );
+      return decidePrBranch("github", stdout);
+    } catch (err) {
+      log.warn(
+        TAG,
+        `gh pr view failed for ${prUrl}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return decidePrBranch("github", null);
+    }
+  }
+  if (provider === "azure") {
+    const prId = extractAzurePrId(prUrl);
+    if (!prId) {
+      return {
+        kind: "skip",
+        reason: `could not parse Azure PR id from ${prUrl}`,
+      };
+    }
+    try {
+      const { stdout } = await execFileAsync()(
+        "az",
+        ["repos", "pr", "show", "--id", prId, "--output", "json"],
+        { cwd, encoding: "utf-8", timeout: 10_000 },
+      );
+      return decidePrBranch("azure", stdout);
+    } catch (err) {
+      log.warn(
+        TAG,
+        `az repos pr show failed for ${prUrl}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return decidePrBranch("azure", null);
+    }
+  }
+  return decidePrBranch(provider, null);
+}
+
+/**
+ * Extract a PR URL from card description. Matches the format written by completion.ts:
+ * `PR: https://...`
+ */
+export function extractPrUrl(description: string | null): string | null {
+  if (!description) return null;
+  const match = description.match(PR_URL_RE);
+  if (!match) return null;
+  try {
+    return new URL(match[1]).href;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a card's PR URL: prefer the `PR:` line stamped in the description,
+ * else look the PR up by its branch via the provider CLI. The by-branch
+ * fallback is what lets merge detection + strand recovery work even when the
+ * approval path never wrote the URL into the description — the #530/#512/#562
+ * merge-strand, where a merged PR existed but the card carried no `PR:` line.
+ */
+export function resolvePrUrl(
+  description: string | null,
+  branchName: string | null,
+  cwd: string,
+  provider: GitProvider,
+): string | null {
+  const fromDesc = extractPrUrl(description);
+  if (fromDesc) return fromDesc;
+  if (!branchName) return null;
+  return findExistingPr(branchName, cwd, provider) || null;
+}
+
+// ============ PUSH (REWORK-AWARE) ============
+
+export function remoteBranchExists(branchName: string, cwd: string): boolean {
+  try {
+    execFileSync(
+      "git",
+      ["ls-remote", "--exit-code", "origin", `refs/heads/${branchName}`],
+      { cwd, stdio: "pipe" },
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function pushBranch(branchName: string, cwd: string): void {
+  if (remoteBranchExists(branchName, cwd)) {
+    log.info(TAG, `Remote branch ${branchName} exists (rework), force-pushing`);
+    // Resolve the remote tip explicitly so the lease anchors to a known SHA.
+    // Bare `--force-with-lease` only checks against the local tracking ref,
+    // which can be stale if it was never fetched in this worktree — that
+    // lets a concurrent update slip through. Fetch + pin the expected SHA.
+    let expectedSha: string | null = null;
+    try {
+      execFileSync("git", ["fetch", "origin", branchName], {
+        cwd,
+        stdio: "pipe",
+      });
+      expectedSha = execFileSync(
+        "git",
+        ["rev-parse", `refs/remotes/origin/${branchName}`],
+        { cwd, encoding: "utf-8" },
+      ).trim();
+    } catch (err) {
+      log.warn(
+        TAG,
+        `could not resolve remote tip for ${branchName}, falling back to weak lease: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+    const lease = expectedSha
+      ? `--force-with-lease=refs/heads/${branchName}:${expectedSha}`
+      : "--force-with-lease";
+    execFileSync("git", ["push", lease, "-u", "origin", branchName], {
+      cwd,
+      stdio: "pipe",
+    });
+  } else {
+    execFileSync("git", ["push", "-u", "origin", branchName], {
+      cwd,
+      stdio: "pipe",
+    });
+  }
+}
+
+/**
+ * Push the current branch's tip to `newRef` on origin and delete `oldRef`.
+ * Used when an approved attempt graduates from `agent-attempts/*` to
+ * `agent/*` — keeps the commits durable across the rename and avoids any
+ * window where the work is unreachable on origin.
+ */
+export function renameRemoteBranch(
+  oldRef: string,
+  newRef: string,
+  cwd: string,
+): void {
+  if (oldRef === newRef) return;
+  let sha: string;
+  try {
+    sha = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd,
+      encoding: "utf-8",
+    }).trim();
+  } catch (err) {
+    throw new Error(
+      `renameRemoteBranch: could not resolve HEAD: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+  log.info(TAG, `Renaming remote ${oldRef} → ${newRef}`);
+  execFileSync(
+    "git",
+    ["push", "origin", `${sha}:refs/heads/${newRef}`, "--force-with-lease"],
+    { cwd, stdio: "pipe" },
+  );
+  try {
+    execFileSync("git", ["push", "origin", `:refs/heads/${oldRef}`], {
+      cwd,
+      stdio: "pipe",
+    });
+  } catch (err) {
+    log.warn(
+      TAG,
+      `renameRemoteBranch: could not delete old ref ${oldRef}: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+  try {
+    execFileSync("git", ["branch", "-m", oldRef, newRef], {
+      cwd,
+      stdio: "pipe",
+    });
+  } catch {
+    // Worktree may not have the old branch checked out — non-fatal.
+  }
+}
+
+/**
+ * Best-effort public branch URL for the recovery button on a failed session.
+ * Returns null when we can't infer a tree URL — the daemon falls back to a
+ * plain `git fetch && git checkout <ref>` instruction in that case.
+ */
+export function getBranchWebUrl(
+  branchName: string,
+  cwd: string,
+): string | null {
+  try {
+    const remoteUrl = execFileSync("git", ["remote", "get-url", "origin"], {
+      cwd,
+      encoding: "utf-8",
+    }).trim();
+    const encoded = branchName.split("/").map(encodeURIComponent).join("/");
+    if (/github\.com[:/]([^/]+)\/([^/.]+)/.test(remoteUrl)) {
+      const m = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/);
+      if (m) return `https://github.com/${m[1]}/${m[2]}/tree/${encoded}`;
+    }
+    if (/gitlab\.com[:/]([^/]+)\/([^/.]+)/.test(remoteUrl)) {
+      const m = remoteUrl.match(/gitlab\.com[:/](.+?)(?:\.git)?$/);
+      if (m) return `https://gitlab.com/${m[1]}/-/tree/${encoded}`;
+    }
+    if (/bitbucket\.org[:/]([^/]+)\/([^/.]+)/.test(remoteUrl)) {
+      const m = remoteUrl.match(/bitbucket\.org[:/](.+?)(?:\.git)?$/);
+      if (m) return `https://bitbucket.org/${m[1]}/branch/${encoded}`;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// ============ PR CREATION (PROVIDER-AWARE) ============
+
+export function buildPrBody(card: Card, commitLog: string): string {
+  return [
+    "## Summary",
+    "",
+    `Automated PR for card **#${card.short_id} — ${card.title}**.`,
+    "",
+    "## Commits",
+    "",
+    "```",
+    commitLog,
+    "```",
+    "",
+    "## Card",
+    "",
+    card.description?.slice(0, 500) || "No description.",
+    "",
+    "---",
+    "*Created by Harmony Agent Daemon*",
+  ].join("\n");
+}
+
+export function createPullRequest(
+  card: Card,
+  branchName: string,
+  worktreePath: string,
+  config: WorktreeConfig,
+  provider: GitProvider,
+  existingPrUrl?: string | null,
+): string | null {
+  // Reuse a PR the card already carries (the #660 PR-link review path: the card
+  // was auto-reviewed *because* it had a resolvable PR link). Re-creating would
+  // open a duplicate — and providers without a findExistingPr branch lookup
+  // (Azure) would ALWAYS duplicate. Provider-agnostic + deterministic: trust the
+  // URL the branch was resolved from, no CLI round-trip or wrong-PR risk.
+  if (existingPrUrl) {
+    log.info(
+      TAG,
+      `Reusing existing PR from card description: ${existingPrUrl}`,
+    );
+    return existingPrUrl;
+  }
+
+  let commitLog = "";
+  try {
+    commitLog = execFileSync(
+      "git",
+      ["log", "--oneline", `origin/${config.worktree.baseBranch}..HEAD`],
+      { cwd: worktreePath, encoding: "utf-8" },
+    ).trim();
+  } catch {
+    commitLog = "(unable to retrieve commit log)";
+  }
+
+  const title = `#${card.short_id} ${card.title}`;
+  const body = buildPrBody(card, commitLog);
+  const base = config.worktree.baseBranch;
+
+  // Check for existing PR first (rework case)
+  const existingUrl = findExistingPr(branchName, worktreePath, provider);
+  if (existingUrl) {
+    log.info(TAG, `PR already exists for ${branchName}, updating body...`);
+    updateExistingPr(branchName, body, worktreePath, provider);
+    return existingUrl;
+  }
+
+  // No existing PR — create a new one
+  try {
+    let result: string;
+
+    switch (provider) {
+      case "github":
+        result = execFileSync(
+          "gh",
+          ["pr", "create", "--title", title, "--body", body, "--base", base],
+          { cwd: worktreePath, encoding: "utf-8" },
+        ).trim();
+        break;
+
+      case "azure": {
+        const azOutput = execFileSync(
+          "az",
+          [
+            "repos",
+            "pr",
+            "create",
+            "--title",
+            title,
+            "--description",
+            body,
+            "--source-branch",
+            branchName,
+            "--target-branch",
+            base,
+            "--auto-complete",
+            "false",
+          ],
+          { cwd: worktreePath, encoding: "utf-8" },
+        ).trim();
+        // az repos pr create returns JSON — extract the URL
+        try {
+          const parsed = JSON.parse(azOutput);
+          result = parsed.remoteUrl ?? parsed.url ?? azOutput;
+        } catch {
+          result = azOutput;
+        }
+        break;
+      }
+
+      case "gitlab":
+        result = execFileSync(
+          "glab",
+          [
+            "mr",
+            "create",
+            "--title",
+            title,
+            "--description",
+            body,
+            "--source-branch",
+            branchName,
+            "--target-branch",
+            base,
+            "--no-editor",
+          ],
+          { cwd: worktreePath, encoding: "utf-8" },
+        ).trim();
+        break;
+
+      default:
+        log.warn(
+          TAG,
+          `No PR CLI for provider "${provider}" — branch pushed but no PR created`,
+        );
+        return null;
+    }
+
+    log.info(TAG, `PR created: ${result}`);
+    return result;
+  } catch (err) {
+    log.error(
+      TAG,
+      `Failed to create PR: ${err instanceof Error ? err.message : err}`,
+    );
+    return null;
+  }
+}
+
+export function findExistingPr(
+  branchName: string,
+  worktreePath: string,
+  provider: GitProvider,
+): string | null {
+  try {
+    switch (provider) {
+      case "github":
+        return execFileSync(
+          "gh",
+          ["pr", "view", branchName, "--json", "url", "--jq", ".url"],
+          { cwd: worktreePath, encoding: "utf-8" },
+        ).trim();
+
+      case "gitlab": {
+        const json = execFileSync(
+          "glab",
+          ["mr", "view", branchName, "--output", "json"],
+          { cwd: worktreePath, encoding: "utf-8" },
+        ).trim();
+        const parsed = JSON.parse(json);
+        return parsed.web_url || null;
+      }
+
+      default:
+        return null;
+    }
+  } catch {
+    return null;
+  }
+}
+
+export function updateExistingPr(
+  branchName: string,
+  body: string,
+  worktreePath: string,
+  provider: GitProvider,
+): void {
+  try {
+    switch (provider) {
+      case "github":
+        execFileSync("gh", ["pr", "edit", branchName, "--body", body], {
+          cwd: worktreePath,
+          stdio: "pipe",
+        });
+        break;
+
+      case "gitlab":
+        execFileSync(
+          "glab",
+          ["mr", "update", branchName, "--description", body],
+          { cwd: worktreePath, stdio: "pipe" },
+        );
+        break;
+    }
+    log.info(TAG, `Updated existing PR body for ${branchName}`);
+  } catch (err) {
+    log.warn(
+      TAG,
+      `Failed to update PR body: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+}