@goodtek/vibeops 2.5.2 → 3.1.0

package/dist/lib/merge-config.js

@@ -0,0 +1,125 @@
+import { join } from "node:path";
+import { readTextOrNull } from "./filesystem.js";
+import { VIBEOPS_CONFIG_FILE } from "./paths.js";
+export const MERGE_GATE_DEFAULTS = {
+    requiredChecks: [],
+    releaseRequiredChecks: [],
+    waitTimeoutSeconds: 900,
+    pollIntervalSeconds: 5,
+    emptyRollupGraceSeconds: 30,
+    allowNoChecks: false,
+};
+/** Inclusive bounds for the numeric settings (seconds). */
+export const MERGE_GATE_LIMITS = {
+    waitTimeoutSeconds: { min: 1, max: 7_200 },
+    pollIntervalSeconds: { min: 1, max: 300 },
+    emptyRollupGraceSeconds: { min: 0, max: 600 },
+};
+const KNOWN_KEYS = new Set([
+    "requiredChecks",
+    "releaseRequiredChecks",
+    "waitTimeoutSeconds",
+    "pollIntervalSeconds",
+    "emptyRollupGraceSeconds",
+    "allowNoChecks",
+]);
+/** Invalid `merge` block in `.vibeops.json`. Merge commands refuse to run. */
+export class MergeConfigError extends Error {
+    constructor(message) {
+        super(`${VIBEOPS_CONFIG_FILE} merge: ${message}`);
+        this.name = "MergeConfigError";
+    }
+}
+function checkList(key, raw) {
+    if (!Array.isArray(raw)) {
+        throw new MergeConfigError(`\`${key}\` must be an array of check names.`);
+    }
+    return raw.map((item, i) => {
+        if (typeof item !== "string" || item.trim().length === 0) {
+            throw new MergeConfigError(`\`${key}[${i}]\` must be a non-empty string.`);
+        }
+        return item.trim();
+    });
+}
+function seconds(key, raw) {
+    const { min, max } = MERGE_GATE_LIMITS[key];
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw < min || raw > max) {
+        throw new MergeConfigError(`\`${key}\` must be an integer between ${min} and ${max}.`);
+    }
+    return raw;
+}
+/**
+ * Validate the raw `merge` block (fail closed): must be an object, only known
+ * keys, lists of non-empty strings, bounded integer seconds, boolean flags.
+ * `undefined` → defaults.
+ */
+export function parseMergeConfig(raw) {
+    if (raw === undefined)
+        return MERGE_GATE_DEFAULTS;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new MergeConfigError("must be an object.");
+    }
+    const o = raw;
+    const unknown = Object.keys(o).filter((k) => !KNOWN_KEYS.has(k));
+    if (unknown.length > 0) {
+        throw new MergeConfigError(`unknown key${unknown.length > 1 ? "s" : ""} ${unknown
+            .map((k) => `\`${k}\``)
+            .join(", ")} (allowed: ${[...KNOWN_KEYS].join(", ")}).`);
+    }
+    const cfg = {
+        requiredChecks: o.requiredChecks === undefined
+            ? MERGE_GATE_DEFAULTS.requiredChecks
+            : checkList("requiredChecks", o.requiredChecks),
+        releaseRequiredChecks: o.releaseRequiredChecks === undefined
+            ? MERGE_GATE_DEFAULTS.releaseRequiredChecks
+            : checkList("releaseRequiredChecks", o.releaseRequiredChecks),
+        waitTimeoutSeconds: o.waitTimeoutSeconds === undefined
+            ? MERGE_GATE_DEFAULTS.waitTimeoutSeconds
+            : seconds("waitTimeoutSeconds", o.waitTimeoutSeconds),
+        pollIntervalSeconds: o.pollIntervalSeconds === undefined
+            ? MERGE_GATE_DEFAULTS.pollIntervalSeconds
+            : seconds("pollIntervalSeconds", o.pollIntervalSeconds),
+        emptyRollupGraceSeconds: o.emptyRollupGraceSeconds === undefined
+            ? MERGE_GATE_DEFAULTS.emptyRollupGraceSeconds
+            : seconds("emptyRollupGraceSeconds", o.emptyRollupGraceSeconds),
+        allowNoChecks: MERGE_GATE_DEFAULTS.allowNoChecks,
+    };
+    if (o.allowNoChecks !== undefined) {
+        if (typeof o.allowNoChecks !== "boolean") {
+            throw new MergeConfigError("`allowNoChecks` must be true or false.");
+        }
+        cfg.allowNoChecks = o.allowNoChecks;
+    }
+    if (cfg.pollIntervalSeconds > cfg.waitTimeoutSeconds) {
+        throw new MergeConfigError("`pollIntervalSeconds` must not exceed `waitTimeoutSeconds`.");
+    }
+    return cfg;
+}
+/**
+ * Read and validate `.vibeops.json` `merge`. Throws `MergeConfigError` on an
+ * invalid block; a missing file or block yields the defaults.
+ */
+export async function readMergeConfig(root) {
+    const text = await readTextOrNull(join(root, VIBEOPS_CONFIG_FILE));
+    if (text === null)
+        return MERGE_GATE_DEFAULTS;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new MergeConfigError("file is not valid JSON.");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return MERGE_GATE_DEFAULTS;
+    }
+    return parseMergeConfig(parsed.merge);
+}
+/** Gate options (milliseconds) derived from resolved config. */
+export function mergeGateTiming(cfg) {
+    return {
+        timeoutMs: cfg.waitTimeoutSeconds * 1000,
+        intervalMs: cfg.pollIntervalSeconds * 1000,
+        emptyRollupGraceMs: cfg.emptyRollupGraceSeconds * 1000,
+    };
+}

package/dist/lib/merge-request-readiness.js

@@ -4,8 +4,13 @@ const ACTIVE_PIPELINE_STATUSES = new Set([
     "created",
     "waiting_for_resource",
     "preparing",
+    "scheduled",
+    "waiting_for_callback",
+    "canceling",
 ]);
 const TERMINAL_PIPELINE_FAILURES = new Set(["failed", "canceled"]);
+/** Pipeline statuses that count as green for the merge gate (`none` = no pipeline). */
+const GREEN_PIPELINE_STATUSES = new Set(["success", "skipped", "none"]);
 function normalizePipelineStatus(raw) {
     if (raw === null || raw === undefined || raw.trim().length === 0)
         return "none";
@@ -18,6 +23,8 @@ function normalizePipelineStatus(raw) {
         return "failed";
     if (status === "canceled" || status === "cancelled")
         return "canceled";
+    if (status === "manual")
+        return "manual";
     if (ACTIVE_PIPELINE_STATUSES.has(status))
         return "running";
     return "unknown";
@@ -25,6 +32,18 @@ function normalizePipelineStatus(raw) {
 export function pipelineStatusFromHost(raw) {
     return normalizePipelineStatus(raw);
 }
+/**
+ * Merge-gate verdict for a single pipeline status (GitLab head pipeline, or the
+ * aggregated GitHub rollup). Unknown / manual / failed / canceled are red —
+ * never merge on a status we cannot prove is green.
+ */
+export function pipelineGateState(status) {
+    if (GREEN_PIPELINE_STATUSES.has(status))
+        return "green";
+    if (isPipelineActive(status))
+        return "pending";
+    return "red";
+}
 export function isPipelineActive(status) {
     return status === "running" || status === "pending";
 }
@@ -50,7 +69,7 @@ export function isMergeRequestReadyToMerge(readiness) {
     }
     if (TERMINAL_PIPELINE_FAILURES.has(readiness.pipelineStatus))
         return false;
-    if (isPipelineActive(readiness.pipelineStatus))
+    if (pipelineGateState(readiness.pipelineStatus) !== "green")
         return false;
     const mergeStatus = readiness.mergeStatus?.trim().toLowerCase() ?? "";
     return mergeStatus === "can_be_merged" || detailed === "mergeable";

package/dist/lib/pr-create.js

@@ -1,8 +1,10 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { mergeRequestLabel } from "./git-host.js";
-import { isMergeRequestReadyToMerge, isPipelineActive, pipelineStatusFromHost, } from "./merge-request-readiness.js";
+import { classifyRollup, evaluateCheckGate, formatCheckGateProblems, } from "./check-rollup.js";
+import { isMergeRequestReadyToMerge, isPipelineActive, pipelineGateState, pipelineStatusFromHost, } from "./merge-request-readiness.js";
 import { dim, log } from "./logger.js";
+import { MERGE_GATE_DEFAULTS, mergeGateTiming } from "./merge-config.js";
 const execFileAsync = promisify(execFile);
 async function ghPrCreate(opts) {
     const { stdout } = await execFileAsync("gh", [
@@ -192,52 +194,125 @@ export async function getMergeRequestState(cwd, host, url) {
     const details = await getMergeRequestDetails(cwd, host, url);
     return details?.state ?? "unknown";
 }
-export async function getMergeRequestDetails(cwd, host, url) {
-    const ref = prRefFromUrl(url);
-    try {
-        if (host === "gitlab") {
-            const { stdout } = await execFileAsync("glab", ["mr", "view", ref, "-F", "json"], { cwd, maxBuffer: 1024 * 1024 });
-            const parsed = JSON.parse(stdout.trim());
-            const state = normalizeGlabMergeRequestState(parsed.state ?? "");
-            return {
-                state,
-                mergedAt: parsed.merged_at ?? null,
-                mergeCommitSha: parsed.merge_commit_sha ?? null,
-                squashCommitSha: parsed.squash_commit_sha ?? null,
-                mergeStatus: parsed.merge_status ?? null,
-                detailedMergeStatus: parsed.detailed_merge_status ?? null,
-                pipelineStatus: pipelineStatusFromHost(parsed.head_pipeline?.status),
-                hasConflicts: parsed.has_conflicts ?? null,
-            };
+/** Host CLI returned JSON without a field the merge gate needs — fail closed. */
+export class MergeRequestShapeError extends Error {
+    constructor(tool, problems) {
+        super(`${tool} output cannot be trusted for the merge gate: ${problems.join("; ")}.`);
+        this.name = "MergeRequestShapeError";
+    }
+}
+/** Describe every field that violates its rule (`undefined`, `null`, `""`, wrong type). */
+function shapeProblems(obj, rules) {
+    const out = [];
+    for (const [field, rule] of Object.entries(rules)) {
+        const v = obj[field];
+        if (rule === "present") {
+            if (!(field in obj) || v === undefined)
+                out.push(`\`${field}\` is missing`);
         }
-        const { stdout } = await execFileAsync("gh", ["pr", "view", ref, "--json", "state,mergedAt,mergeCommit,mergeable,statusCheckRollup"], { cwd, maxBuffer: 1024 * 1024 });
-        const parsed = JSON.parse(stdout.trim());
-        const checks = parsed.statusCheckRollup ?? [];
-        let pipelineStatus = "none";
-        if (checks.some((c) => (c.state ?? "").toUpperCase() === "PENDING")) {
-            pipelineStatus = "running";
+        else if (rule === "array") {
+            if (!Array.isArray(v))
+                out.push(`\`${field}\` is missing or not a list`);
         }
-        else if (checks.some((c) => (c.state ?? "").toUpperCase() === "FAILURE")) {
-            pipelineStatus = "failed";
+        else if (typeof v !== "string" || v.trim().length === 0) {
+            out.push(`\`${field}\` is missing or empty`);
         }
-        else if (checks.length > 0) {
-            pipelineStatus = "success";
+    }
+    return out;
+}
+export async function getMergeRequestDetails(cwd, host, url) {
+    try {
+        return await readMergeRequestDetails(cwd, host, url, { strict: false });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read MR/PR details from the host CLI. Throws on CLI / JSON errors. With
+ * `strict`, also throws `MergeRequestShapeError` when a field the merge gate
+ * relies on is absent (never treat missing data as green).
+ */
+export async function readMergeRequestDetails(cwd, host, url, options) {
+    const ref = prRefFromUrl(url);
+    if (host === "gitlab") {
+        const { stdout } = await execFileAsync("glab", ["mr", "view", ref, "-F", "json"], { cwd, maxBuffer: 1024 * 1024 });
+        const parsed = JSON.parse(stdout.trim());
+        if (options.strict) {
+            const problems = shapeProblems(parsed, {
+                state: "nonEmptyString",
+                merge_status: "present",
+                detailed_merge_status: "present",
+                // `null` = no pipeline; the key itself must be there.
+                head_pipeline: "present",
+                sha: "nonEmptyString",
+            });
+            const pipeline = parsed.head_pipeline;
+            if (pipeline !== null &&
+                pipeline !== undefined &&
+                (typeof pipeline.status !== "string" || pipeline.status.trim().length === 0)) {
+                problems.push("`head_pipeline.status` is missing or empty");
+            }
+            if (problems.length > 0)
+                throw new MergeRequestShapeError("glab", problems);
         }
-        const mergeable = parsed.mergeable?.trim().toUpperCase() ?? "";
+        const state = normalizeGlabMergeRequestState(parsed.state ?? "");
         return {
-            state: normalizeGhMergeRequestState(parsed.state ?? ""),
-            mergedAt: parsed.mergedAt ?? null,
-            mergeCommitSha: parsed.mergeCommit?.oid ?? null,
-            squashCommitSha: null,
-            mergeStatus: mergeable === "MERGEABLE" ? "can_be_merged" : mergeable.toLowerCase(),
-            detailedMergeStatus: mergeable.toLowerCase(),
-            pipelineStatus,
-            hasConflicts: mergeable === "CONFLICTING" ? true : mergeable === "MERGEABLE" ? false : null,
+            state,
+            mergedAt: parsed.merged_at ?? null,
+            mergeCommitSha: parsed.merge_commit_sha ?? null,
+            squashCommitSha: parsed.squash_commit_sha ?? null,
+            mergeStatus: parsed.merge_status ?? null,
+            detailedMergeStatus: parsed.detailed_merge_status ?? null,
+            pipelineStatus: pipelineStatusFromHost(parsed.head_pipeline?.status),
+            hasConflicts: parsed.has_conflicts ?? null,
+            checks: null,
+            headSha: parsed.sha ?? null,
         };
     }
-    catch {
-        return null;
+    const { stdout } = await execFileAsync("gh", [
+        "pr",
+        "view",
+        ref,
+        "--json",
+        "state,mergedAt,mergeCommit,mergeable,headRefOid,statusCheckRollup",
+    ], { cwd, maxBuffer: 4 * 1024 * 1024 });
+    const parsed = JSON.parse(stdout.trim());
+    if (options.strict) {
+        const problems = shapeProblems(parsed, {
+            state: "nonEmptyString",
+            mergeable: "nonEmptyString",
+            headRefOid: "nonEmptyString",
+            statusCheckRollup: "array",
+        });
+        if (problems.length > 0)
+            throw new MergeRequestShapeError("gh", problems);
+    }
+    const checks = classifyRollup(parsed.statusCheckRollup);
+    const gate = evaluateCheckGate(checks);
+    let pipelineStatus = "none";
+    if (gate.state === "red") {
+        pipelineStatus = "failed";
+    }
+    else if (gate.state === "pending") {
+        pipelineStatus = "running";
     }
+    else if (checks.length > 0) {
+        pipelineStatus = "success";
+    }
+    const mergeable = parsed.mergeable?.trim().toUpperCase() ?? "";
+    return {
+        state: normalizeGhMergeRequestState(parsed.state ?? ""),
+        mergedAt: parsed.mergedAt ?? null,
+        mergeCommitSha: parsed.mergeCommit?.oid ?? null,
+        squashCommitSha: null,
+        mergeStatus: mergeable === "MERGEABLE" ? "can_be_merged" : mergeable.toLowerCase(),
+        detailedMergeStatus: mergeable.toLowerCase(),
+        pipelineStatus,
+        hasConflicts: mergeable === "CONFLICTING" ? true : mergeable === "MERGEABLE" ? false : null,
+        checks,
+        headSha: parsed.headRefOid ?? null,
+    };
 }
 /** Poll host until MR/PR state is merged (or timeout). */
 export async function waitForMergeRequestMerged(cwd, host, url, options = {}) {
@@ -264,26 +339,135 @@ function mergeRequestReadinessFromDetails(details) {
         hasConflicts: details.hasConflicts,
     };
 }
-/** Poll until MR/PR CI finished and host reports mergeable (or already merged). */
-export async function waitForMergeRequestReadyToMerge(cwd, host, url, options = {}) {
-    const timeoutMs = options.timeoutMs ?? 900_000;
-    const intervalMs = options.intervalMs ?? 5_000;
-    const deadline = Date.now() + timeoutMs;
+/** Thrown by `mergeMergeRequest` when the merge gate refuses (red / pending / missing checks). */
+export class MergeGateError extends Error {
+    problems;
+    constructor(label, problems) {
+        super(`Refusing to merge ${label}:\n${problems.map((p) => `  - ${p}`).join("\n")}`);
+        this.name = "MergeGateError";
+        this.problems = problems;
+    }
+}
+function evaluateDetailsGate(details, requiredChecks) {
+    if (details.checks !== null) {
+        const gate = evaluateCheckGate(details.checks, requiredChecks);
+        return {
+            state: gate.state,
+            problems: formatCheckGateProblems(gate),
+            noChecks: details.checks.length === 0,
+        };
+    }
+    const state = pipelineGateState(details.pipelineStatus);
+    return {
+        state,
+        problems: state === "green" ? [] : [`head pipeline is ${details.pipelineStatus}`],
+        noChecks: details.pipelineStatus === "none",
+    };
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+/**
+ * Merge gate: poll the MR/PR until every check is green and the host reports it
+ * mergeable. Refuses immediately on any failed check, on host output it cannot
+ * trust, and on "no checks at all" (unless allowed); refuses after the timeout
+ * when checks stay pending or a required check never appears.
+ */
+export async function waitForMergeGate(cwd, host, url, options = {}) {
+    const defaults = mergeGateTiming(MERGE_GATE_DEFAULTS);
+    const timeoutMs = options.timeoutMs ?? defaults.timeoutMs;
+    const intervalMs = options.intervalMs ?? defaults.intervalMs;
+    const graceMs = options.emptyRollupGraceMs ?? defaults.emptyRollupGraceMs;
+    const allowNoChecks = options.allowNoChecks ?? MERGE_GATE_DEFAULTS.allowNoChecks;
+    const waitForPending = options.waitForPending !== false;
+    const required = options.requiredChecks ?? [];
     const label = mergeRequestLabel(host);
+    const start = Date.now();
+    const deadline = start + timeoutMs;
     let loggedWait = false;
-    while (Date.now() < deadline) {
-        const details = await getMergeRequestDetails(cwd, host, url);
-        const readiness = mergeRequestReadinessFromDetails(details);
-        if (readiness !== null && isMergeRequestReadyToMerge(readiness)) {
-            return true;
+    let warnedGitLabRequired = false;
+    for (;;) {
+        let problems = [];
+        let details = null;
+        try {
+            details = await readMergeRequestDetails(cwd, host, url, { strict: true });
+        }
+        catch (error) {
+            if (error instanceof MergeRequestShapeError) {
+                return { ok: false, problems: [error.message] };
+            }
+            const msg = error instanceof Error ? error.message.split("\n")[0] : String(error);
+            problems = [`could not read ${label} details from the host: ${msg}`];
+        }
+        if (details === null) {
+            // problems set in catch; keep polling (transient CLI / network error).
+        }
+        else if (details.state === "merged") {
+            return { ok: true, alreadyMerged: true, details };
+        }
+        else if (details.state !== "open") {
+            return { ok: false, problems: [`${label} is ${details.state}, not open`] };
+        }
+        else {
+            const gitlab = details.checks === null;
+            if (gitlab && required.length > 0 && !warnedGitLabRequired) {
+                log.warn("merge.requiredChecks is GitHub-only; GitLab uses the head pipeline status.");
+                warnedGitLabRequired = true;
+            }
+            const ev = evaluateDetailsGate(details, required);
+            if (ev.state === "red") {
+                return { ok: false, problems: ev.problems };
+            }
+            if (details.hasConflicts === true) {
+                return { ok: false, problems: [`${label} has merge conflicts`] };
+            }
+            // "No checks at all" is judged here only when no required check could
+            // report it instead (GitHub with requiredChecks → "never ran" path).
+            const noChecksRule = ev.noChecks && (gitlab || required.length === 0);
+            const inGrace = waitForPending && noChecksRule && Date.now() - start < graceMs;
+            if (ev.state === "pending") {
+                problems = ev.problems;
+            }
+            else if (inGrace) {
+                problems = ["no status checks reported yet"];
+            }
+            else if (noChecksRule && !allowNoChecks) {
+                return {
+                    ok: false,
+                    problems: [
+                        `the host reports no checks for this ${label} — refusing (fail closed). ` +
+                            "Configure CI and `merge.requiredChecks`, or set `merge.allowNoChecks: true` in .vibeops.json for a repo without CI",
+                    ],
+                };
+            }
+            else {
+                const readiness = mergeRequestReadinessFromDetails(details);
+                if (readiness !== null && isMergeRequestReadyToMerge(readiness)) {
+                    if (noChecksRule) {
+                        // Once, after the gate has decided to merge — not on every poll.
+                        log.warn(`WARNING: merging ${label} with NO checks (merge.allowNoChecks is true). Nothing verified this change.`);
+                    }
+                    return { ok: true, alreadyMerged: false, details };
+                }
+                problems = [
+                    `host does not report the ${label} as mergeable yet (${details.detailedMergeStatus || details.mergeStatus || "unknown"})`,
+                ];
+            }
+        }
+        const now = Date.now();
+        if (!waitForPending || now >= deadline) {
+            const suffix = waitForPending
+                ? ` (gave up after ${Math.round(timeoutMs / 1000)}s)`
+                : "";
+            return {
+                ok: false,
+                problems: problems.map((p, i) => (i === problems.length - 1 ? `${p}${suffix}` : p)),
+            };
         }
         if (!loggedWait) {
-            log.info(dim(`Waiting for ${label} pipeline / merge checks…`));
+            log.info(dim(`Waiting for ${label} checks: ${problems.join("; ")}…`));
             loggedWait = true;
         }
-        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        await sleep(Math.min(intervalMs, deadline - now));
     }
-    return false;
 }
 function isMergeHttp405(error) {
     const msg = error instanceof Error ? error.message : String(error);
@@ -312,68 +496,74 @@ export async function mergeMergeRequest(opts) {
     const ref = prRefFromUrl(opts.url);
     const method = opts.method ?? "squash";
     const label = mergeRequestLabel(opts.host);
-    if (opts.waitForCi === true && opts.dryRun !== true) {
-        const ready = await waitForMergeRequestReadyToMerge(opts.cwd, opts.host, opts.url);
-        if (!ready) {
-            throw new Error(`${label} is not ready to merge yet (pipeline running, checks pending, or timeout).`);
-        }
-    }
-    const details = await getMergeRequestDetails(opts.cwd, opts.host, opts.url);
-    const readiness = mergeRequestReadinessFromDetails(details);
-    const pipelineActive = readiness !== null ? isPipelineActive(readiness.pipelineStatus) : false;
     if (opts.dryRun === true) {
+        const required = opts.requiredChecks && opts.requiredChecks.length > 0
+            ? ` + required: ${opts.requiredChecks.join(", ")}`
+            : "";
+        log.info(`would check ${label} status checks (all green${required}) before merging`);
         if (opts.host === "gitlab") {
-            const immediate = opts.immediate !== false && !pipelineActive;
-            const flags = immediate ? " --auto-merge=false" : " (auto-merge when pipeline succeeds)";
-            const methodFlag = method === "squash" ? " --squash" : method === "rebase" ? " --rebase" : "";
-            log.info(`would ${label} merge ${ref} (glab mr merge${flags}${methodFlag})`);
+            log.info(`would ${label} merge ${ref} (glab ${gitLabMergeArgs(ref, method, "<head sha>").join(" ")})`);
         }
         else {
-            log.info(`would gh pr merge ${ref} --${method}`);
+            log.info(`would gh ${gitHubMergeArgs(ref, method, "<head sha>").join(" ")}`);
         }
         return;
     }
-    if (opts.host === "gitlab") {
-        await mergeGitLabMergeRequest({
-            cwd: opts.cwd,
-            ref,
-            method,
-            immediate: opts.immediate !== false && !pipelineActive,
+    const runGate = async () => {
+        const gate = await waitForMergeGate(opts.cwd, opts.host, opts.url, {
+            ...opts.gate,
+            waitForPending: opts.waitForCi === true,
+            requiredChecks: opts.requiredChecks ?? [],
         });
-        return;
-    }
-    const args = ["pr", "merge", ref, `--${method}`];
-    await execFileAsync("gh", args, { cwd: opts.cwd, maxBuffer: 4 * 1024 * 1024 });
-}
-async function mergeGitLabMergeRequest(input) {
-    const attempt = async (immediate) => {
-        const args = ["mr", "merge", input.ref];
-        if (immediate) {
-            args.push("--auto-merge=false");
-        }
-        if (input.method === "squash") {
-            args.push("--squash");
-        }
-        else if (input.method === "rebase") {
-            args.push("--rebase");
+        if (!gate.ok)
+            throw new MergeGateError(label, gate.problems);
+        if (gate.alreadyMerged)
+            return null;
+        if (gate.details.headSha === null || gate.details.headSha.trim().length === 0) {
+            // Strict read already guarantees this; never merge unpinned.
+            throw new MergeGateError(label, ["host did not report the head commit SHA"]);
         }
-        await execFileAsync("glab", args, {
-            cwd: input.cwd,
-            maxBuffer: 4 * 1024 * 1024,
-        });
+        return gate.details;
     };
-    try {
-        await attempt(input.immediate);
-    }
-    catch (error) {
-        if (!input.immediate && isMergeHttp405(error)) {
-            await attempt(false);
-            return;
+    const details = await runGate();
+    if (details === null)
+        return;
+    if (opts.host === "gitlab") {
+        try {
+            await execGlabMerge(opts.cwd, gitLabMergeArgs(ref, method, details.headSha));
         }
-        if (input.immediate && isMergeHttp405(error)) {
-            await attempt(false);
-            return;
+        catch (error) {
+            if (!isMergeHttp405(error))
+                throw error;
+            // 405: GitLab not ready to accept the merge yet (e.g. mergeability still
+            // being computed). Re-run the gate, then retry once with the same flags
+            // (still `--auto-merge=false`, pinned to the re-checked SHA).
+            const again = await runGate();
+            if (again === null)
+                return;
+            await execGlabMerge(opts.cwd, gitLabMergeArgs(ref, method, again.headSha));
         }
-        throw error;
+        return;
     }
+    // Pinned to the commit the gate checked: a push after the gate makes GitHub refuse.
+    await execFileAsync("gh", gitHubMergeArgs(ref, method, details.headSha), {
+        cwd: opts.cwd,
+        maxBuffer: 4 * 1024 * 1024,
+    });
+}
+/** `gh pr merge` argv. `--match-head-commit` needs gh ≥ 2.13.0. */
+export function gitHubMergeArgs(ref, method, headSha) {
+    return ["pr", "merge", ref, `--${method}`, "--match-head-commit", headSha];
+}
+/** `glab mr merge` argv: immediate (never schedule auto-merge) and pinned with `--sha`. */
+export function gitLabMergeArgs(ref, method, headSha) {
+    const args = ["mr", "merge", ref, "--auto-merge=false", "--sha", headSha];
+    if (method === "squash")
+        args.push("--squash");
+    else if (method === "rebase")
+        args.push("--rebase");
+    return args;
+}
+async function execGlabMerge(cwd, args) {
+    await execFileAsync("glab", [...args], { cwd, maxBuffer: 4 * 1024 * 1024 });
 }

package/dist/lib/task-del.js

@@ -2,7 +2,8 @@ import { resolve } from "node:path";
 import { deleteFile } from "./filesystem.js";
 import { GitConfigError, requireGitConfig } from "./git-config.js";
 import { mergeRequestLabel } from "./git-host.js";
-import { gitBranchExists, gitDeleteBranch, gitDeleteRemoteBranch, gitGovernanceOnlyDirty, gitRemoteBranchExists, gitSwitchToBranch, readGitInfo, } from "./git.js";
+import { gitBranchExists, gitDeleteBranch, gitDeleteRemoteBranch, gitGovernanceOnlyDirty, gitRemoteBranchExists, readGitInfo, } from "./git.js";
+import { leaveTaskBranch } from "./git-worktree.js";
 import { dim, log } from "./logger.js";
 import { closeMergeRequest, findMergeRequestByBranches, probeMergeRequestCli, } from "./pr-create.js";
 import { normalizeTaskRef } from "./resolve-task.js";
@@ -83,12 +84,13 @@ export async function deleteTaskBranches(opts) {
     }
     const git = await readGitInfo(cwd);
     if (git.branch === opts.taskBranch) {
-        const switched = await gitSwitchToBranch(cwd, opts.integrationBranch, opts.remote);
-        if (!switched) {
-            log.error(`Integration branch "${opts.integrationBranch}" not found.`);
+        // Worktree-safe (D-006): detach when another worktree owns the integration branch.
+        const left = await leaveTaskBranch(cwd, opts.remote, opts.integrationBranch);
+        if (!left.ok) {
+            log.error(left.message);
             return false;
         }
-        log.ok(`On ${opts.integrationBranch}`);
+        log.ok(left.on === "integration" ? `On ${opts.integrationBranch}` : `Detached at ${left.ref}`);
     }
     if (await gitBranchExists(cwd, opts.taskBranch)) {
         try {