looply-cli 0.5.10 → 0.5.11

package/dist/branch-delivery.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NO_CHECKS_GRACE_MS = exports.CHECKS_PATIENCE_MS = exports.BRANCH_DELIVERIES_FILE = void 0;
+exports.FOLLOW_DEPLOYS_MS = exports.NO_CHECKS_GRACE_MS = exports.CHECKS_PATIENCE_MS = exports.BRANCH_DELIVERIES_FILE = void 0;
 exports.nodeDeliveryGit = nodeDeliveryGit;
 exports.makeDeployPush = makeDeployPush;
 exports.fileDeliveryStore = fileDeliveryStore;
@@ -10,6 +10,9 @@ exports.stackedOn = stackedOn;
 exports.pullTitle = pullTitle;
 exports.pullBody = pullBody;
 exports.deliverBranch = deliverBranch;
+exports.describeForeign = describeForeign;
+exports.unmergedForeign = unmergedForeign;
+exports.mergeGuard = mergeGuard;
 exports.decideChecks = decideChecks;
 exports.advanceDeliveries = advanceDeliveries;
 exports.makeReleaseRunner = makeReleaseRunner;
@@ -19,8 +22,12 @@ const node_path_1 = require("node:path");
 const delivery_rules_1 = require("./delivery-rules");
 const git_driver_1 = require("./git-driver");
 const integrator_1 = require("./integrator");
+const branch_replay_1 = require("./branch-replay");
+const commit_ownership_1 = require("./commit-ownership");
 const run_base_1 = require("./run-base");
-function nodeDeliveryGit(cwd, configuredBase, rawExec = (0, git_driver_1.nodeGitExec)(cwd)) {
+function nodeDeliveryGit(cwd, configuredBase, rawExec = (0, git_driver_1.nodeGitExec)(cwd), 
+/** Where a rebuild's temporary worktree goes (os tmpdir by default), and how git is run in it. */
+rebuild = {}) {
     /**
      * NO SIGN-IN WINDOW, EVER. The network verbs here (push, ls-remote) reach the
      * person's credential helper — Git Credential Manager on Windows — which opens
@@ -77,6 +84,47 @@ function nodeDeliveryGit(cwd, configuredBase, rawExec = (0, git_driver_1.nodeGit
                 return { ok: true };
             return { ok: false, because: (0, delivery_rules_1.redactUrl)(`${r.stderr}\n${r.stdout}`.trim()).slice(0, 400) || `git push exited ${r.code}` };
         },
+        async freshBase(base) {
+            const name = (0, delivery_rules_1.shortBranch)(base);
+            if (/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(name) && !name.includes('..')) {
+                // Read-only for the person: it moves origin's remote-tracking copy and nothing else.
+                await out(['fetch', '--quiet', '--no-tags', delivery_rules_1.DELIVERY_REMOTE, `refs/heads/${name}:refs/remotes/${delivery_rules_1.DELIVERY_REMOTE}/${name}`]).catch(() => undefined);
+            }
+            const tracking = `refs/remotes/${delivery_rules_1.DELIVERY_REMOTE}/${name}`;
+            return (await driver.refExists(tracking).catch(() => false)) ? tracking : base;
+        },
+        async commitsBetween(base, tip) {
+            const r = await out(['rev-list', '--reverse', '--topo-order', '--parents', `${base}..${tip}`, '--']).catch(() => null);
+            if (r === null || r.code !== 0)
+                return null;
+            return r.stdout
+                .split(/\r?\n/)
+                .map((l) => l.trim().split(/\s+/))
+                .filter((ids) => /^[0-9a-f]{40}$/.test(ids[0] ?? ''))
+                .map(([sha, ...parents]) => ({ sha: sha, parents }));
+        },
+        async replay(base, commits) {
+            try {
+                return await (0, branch_replay_1.replayOnto)(exec, (dir) => {
+                    const inner = (rebuild.execAt ?? git_driver_1.nodeGitExec)(dir);
+                    return (args) => inner(['-c', 'credential.interactive=never', ...args]);
+                }, base, commits, rebuild.scratchRoot);
+            }
+            catch (e) {
+                return { ok: false, because: e.message.slice(0, 300) };
+            }
+        },
+        async treeOf(ref) {
+            const r = await out(['rev-parse', '--verify', '--quiet', `${ref}^{tree}`]).catch(() => null);
+            return r !== null && r.code === 0 && r.stdout.trim() !== '' ? r.stdout.trim() : null;
+        },
+        async createBranch(name, sha) {
+            // `branch` without `-f` refuses an existing name, so this can only ever ADD a branch.
+            if (!name.startsWith(integrator_1.RUN_BRANCH_PREFIX) || !/^[0-9a-f]{40}$/.test(sha))
+                return false;
+            const r = await out(['branch', '--no-track', name, sha]).catch(() => null);
+            return r !== null && r.code === 0;
+        },
     };
 }
 /**
@@ -174,12 +222,7 @@ async function findGoalBranch(git, input, branches) {
     return null;
 }
 /** Which goal a run branch belongs to, from the lane claims; undefined when nothing says. */
-function goalOfBranch(claims, branch) {
-    for (let i = claims.length - 1; i >= 0; i--)
-        if (claims[i].branch === branch)
-            return claims[i].goalId;
-    return undefined;
-}
+const goalOfBranch = commit_ownership_1.ownerOfBranch;
 /**
  * THE OTHER, UNMERGED GOAL'S BRANCH THIS ONE IS BUILT ON — or null.
  *
@@ -235,6 +278,7 @@ function reportOf(e) {
         dependsOn: e.dependsOn,
         mergeSha: e.mergeSha ?? null,
         deploy: e.deploy ?? null,
+        ...(e.environments === undefined ? {} : { environments: e.environments }),
     };
 }
 async function save(deps, e) {
@@ -280,6 +324,14 @@ function pullBody(input) {
             lines.push(`⚠️ This builds on \`${input.stacked.branch}\`${input.stacked.goalId ? ` (goal ${input.stacked.goalId})` : ''}, which is not merged and not on GitHub, so this pull request also contains that branch's commits. Review or merge that work first.`);
         }
     }
+    if (input.rebuilt) {
+        lines.push('');
+        lines.push(`This branch was rebuilt from \`${input.rebuilt.from}\` onto the base with only this goal's own commits: ${input.rebuilt.without}.`);
+    }
+    if (input.foreign) {
+        lines.push('');
+        lines.push(`⚠️ ${input.foreign.charAt(0).toUpperCase()}${input.foreign.slice(1)}. Looply will not merge this while that is so.`);
+    }
     return lines.join('\n');
 }
 /**
@@ -332,10 +384,14 @@ async function deliverOnce(deps, input) {
             ? `there is no local branch ${input.branch} (only ${integrator_1.RUN_BRANCH_PREFIX}* branches are delivered)`
             : `no ${integrator_1.RUN_BRANCH_PREFIX}* branch on this machine holds commit ${input.sha.slice(0, 12)}`);
     }
-    const branch = found.name;
-    const tip = found.sha;
-    // Already done at this tip: say it again (the server may have missed it), do nothing else.
-    if (prior !== null && prior.branch === branch && prior.sha === tip && prior.pullRequestUrl !== null) {
+    const original = { name: found.name, sha: found.sha };
+    let branch = found.name;
+    let tip = found.sha;
+    // Already done at this tip — as it is, or as its rebuild: say it again (the server may have missed it), do nothing else.
+    if (input.replace !== true &&
+        prior !== null &&
+        prior.pullRequestUrl !== null &&
+        ((prior.branch === branch && prior.sha === tip) || (prior.rebuiltFrom?.branch === branch && prior.rebuiltFrom.sha === tip))) {
         return save(deps, { ...prior, updatedAt: at });
     }
     const remoteUrl = await deps.git.remoteUrl();
@@ -350,6 +406,30 @@ async function deliverOnce(deps, input) {
     const refused = (0, delivery_rules_1.pushRefusal)({ remote: delivery_rules_1.DELIVERY_REMOTE, remoteUrl, branch, base, protectedBranches });
     if (refused !== null)
         return notPushed(branch, refused);
+    /**
+     * OTHER GOALS' UNMERGED COMMITS UNDER THIS ONE: REBUILD WITHOUT THEM, WHEN IT CAN.
+     * A pull request that carries another ticket's unreviewed work is one a green check — or an
+     * "Approve and ship" — would merge into the base with it. So unless that other goal is one
+     * this goal DECLARES it depends on (then the stacking is the point, and the merge guard holds
+     * it until the dependency merges), the goal's own commits are replayed onto the base as
+     * `<branch>-solo`, and that is what is delivered. When the replay refuses, the branch goes as
+     * it is, and says so.
+     */
+    const onOrigin = await deps.git.remoteRunBranches().catch(() => new Set());
+    const plan = await planRebuild(deps, input, { branch, tip, base, branches, onOrigin, prior, at });
+    const rebuilt = plan.kind === 'rebuilt' ? plan : null;
+    const foreignLeft = plan.kind === 'stacked' ? plan.foreign : [];
+    const knownBranches = rebuilt === null ? branches : [...branches, { name: rebuilt.branch, sha: rebuilt.sha }];
+    if (rebuilt !== null) {
+        branch = rebuilt.branch;
+        tip = rebuilt.sha;
+        deps.log(`deliver : rebuilt ${original.name} as ${branch} (${tip.slice(0, 12)}) without ${rebuilt.withoutText}`);
+        if (api !== null && (await api.branchProtected(branch)) === true)
+            protectedBranches.push(branch);
+        const refusedSolo = (0, delivery_rules_1.pushRefusal)({ remote: delivery_rules_1.DELIVERY_REMOTE, remoteUrl, branch, base, protectedBranches });
+        if (refusedSolo !== null)
+            return notPushed(branch, refusedSolo);
+    }
     // Never forced: origin's copy must be absent, this tip, or something this tip contains.
     const theirs = await deps.git.remoteSha(branch);
     if (theirs !== null && theirs !== tip && !(await deps.git.isAncestor(theirs, tip))) {
@@ -361,9 +441,8 @@ async function deliverOnce(deps, input) {
             return notPushed(branch, `git push to origin failed: ${pushed.because}`);
         deps.log(`deliver : pushed ${branch} (${tip.slice(0, 12)}) to origin`);
     }
-    const onOrigin = await deps.git.remoteRunBranches().catch(() => new Set());
     onOrigin.add(branch);
-    const stack = await stackedOn(deps.git, { branch, tip, goalId: input.goalId, base, claims: input.claims, branches, onOrigin });
+    const stack = await stackedOn(deps.git, { branch, tip, goalId: input.goalId, base, claims: input.claims, branches: knownBranches, onOrigin });
     const projectBase = base === null ? null : (0, delivery_rules_1.shortBranch)(base);
     const entry = {
         ...blank(branch),
@@ -373,6 +452,7 @@ async function deliverOnce(deps, input) {
         projectBase,
         dependsOn: stack?.branch ?? null,
         state: 'pushed',
+        ...(rebuilt === null ? {} : { rebuiltFrom: { branch: original.name, sha: original.sha, without: rebuilt.without } }),
     };
     if (gh === null) {
         return save(deps, { ...entry, note: `pushed to origin (${remoteUrl === null ? 'no URL' : (0, delivery_rules_1.redactUrl)(remoteUrl)}); origin is not on github.com, so no pull request was opened` });
@@ -394,7 +474,12 @@ async function deliverOnce(deps, input) {
     if (prBase === null) {
         return save(deps, { ...entry, note: `pushed ${branch} to origin, but no pull request was opened: the project's base branch could not be found (set run.base_branch)` });
     }
+    const absorbs = replacing !== null ? [replacing.goalId] : [];
+    const foreignStill = foreignLeft.filter((f) => f.goalId === undefined || !absorbs.includes(f.goalId));
+    const foreignText = foreignStill.length > 0 ? describeForeign(deps.store, foreignStill, projectBase ?? prBase) : null;
+    const couldNot = plan.kind === 'stacked' && plan.because !== null ? `Looply could not rebuild it without that work (${plan.because})` : null;
     let pull = await api.findPull(branch);
+    let replacedOwn = null;
     if (pull === null || (pull.state === 'closed' && !pull.merged)) {
         const stackedPull = stack !== null && stack.onOrigin ? await api.findPull(stack.branch).catch(() => null) : null;
         try {
@@ -402,26 +487,63 @@ async function deliverOnce(deps, input) {
                 title: pullTitle(input.goalText),
                 head: branch,
                 base: prBase,
-                body: pullBody({ goalId: input.goalId, goalText: input.goalText, branch, sha: tip, ...(input.checks ? { checks: input.checks } : {}), mode: input.mode, stacked: stack, stackedPull }),
+                body: pullBody({
+                    goalId: input.goalId,
+                    goalText: input.goalText,
+                    branch,
+                    sha: tip,
+                    ...(input.checks ? { checks: input.checks } : {}),
+                    mode: input.mode,
+                    stacked: stack,
+                    stackedPull,
+                    rebuilt: rebuilt === null ? null : { from: original.name, without: rebuilt.withoutText },
+                    foreign: foreignText,
+                }),
             });
             deps.log(`deliver : opened ${pull.url} (${branch} → ${prBase})`);
             if (replacing !== null) {
                 await api.closePull(replacing.pullNumber, `Replaced by ${pull.url}, which contains this work and its fix.`).catch(() => undefined);
                 await save(deps, { ...replacing, done: true, note: `replaced by ${pull.url}`, updatedAt: at });
             }
+            // `--rebuild`: the old pull request of this goal's stacked branch is closed, pointing here.
+            if (input.replace === true && rebuilt !== null && prior !== null && prior.pullNumber !== null && prior.branch === original.name && prior.pullRequestUrl !== pull.url) {
+                const old = await api.getPull(prior.pullNumber).catch(() => null);
+                if (old !== null && old.state === 'open' && !old.merged) {
+                    await api.closePull(prior.pullNumber, `Replaced by ${pull.url}, which holds only this ticket's work.`);
+                    deps.log(`deliver : closed ${prior.pullRequestUrl} (replaced by ${pull.url})`);
+                    replacedOwn = prior;
+                }
+            }
         }
         catch (e) {
             return save(deps, { ...entry, note: `pushed ${branch} to origin, but GitHub refused the pull request: ${e.message}` });
         }
     }
-    const state = pull.merged ? 'merged' : input.mode === 'pr' ? 'pr-open' : 'waiting-checks';
-    const note = stack === null
-        ? null
-        : replacing !== null
-            ? `replaces ${replacing.pullRequestUrl} (its checks failed); contains that work and the fix`
-            : stack.onOrigin
-                ? `builds on ${stack.branch}, which is not merged yet; the pull request targets it`
-                : `builds on ${stack.branch}${stack.goalId ? ` (goal ${stack.goalId})` : ''}, which is not merged or pushed; the pull request also contains its commits`;
+    /**
+     * 🔴 UNDER `merge`/`deploy`, A PULL REQUEST INTO THE BASE THAT STILL CARRIES ANOTHER GOAL'S
+     * UNMERGED WORK IS `blocked` FROM THE START — the merge guard in `advanceOne` would say so on
+     * its first pass anyway, and the ticket should not read "waiting for checks" in between. One
+     * that targets its dependency's branch waits for that branch as before, and meets the guard
+     * once it is retargeted.
+     */
+    const blocked = !pull.merged && input.mode !== 'pr' && foreignStill.length > 0 && (pull.base || prBase) === projectBase;
+    const state = pull.merged ? 'merged' : input.mode === 'pr' ? 'pr-open' : blocked ? 'blocked' : 'waiting-checks';
+    const tail = (s) => (couldNot === null ? s : `${s}; ${couldNot}`);
+    const note = replacing !== null
+        ? `replaces ${replacing.pullRequestUrl} (its checks failed); contains that work and the fix`
+        : blocked
+            ? couldNot === null
+                ? guardNote(foreignText, original.name)
+                : `not merged: ${foreignText}; merge or close that first (${couldNot})`
+            : rebuilt !== null
+                ? `rebuilt onto ${projectBase ?? prBase} without ${rebuilt.withoutText}${replacedOwn !== null ? `; replaces ${replacedOwn.pullRequestUrl}` : ''}`
+                : stack !== null
+                    ? tail(stack.onOrigin
+                        ? `builds on ${stack.branch}, which is not merged yet; the pull request targets it`
+                        : `builds on ${stack.branch}${stack.goalId ? ` (goal ${stack.goalId})` : ''}, which is not merged or pushed; the pull request also contains its commits`)
+                    : foreignText !== null
+                        ? tail(foreignText)
+                        : null;
     return save(deps, {
         ...entry,
         pullNumber: pull.number,
@@ -429,8 +551,167 @@ async function deliverOnce(deps, input) {
         base: pull.base || prBase,
         state,
         note,
+        ...(absorbs.length > 0 ? { absorbs } : {}),
     });
 }
+/**
+ * Decide — and, when it is the answer, do — the rebuild of a branch that carries other goals'
+ * unmerged commits. Never throws for git's sake: anything git will not do is `stacked` with the
+ * reason, and the branch is delivered as it is.
+ */
+async function planRebuild(deps, input, at) {
+    if (at.base === null)
+        return { kind: 'unknown' };
+    // The same goal at the same tip was rebuilt before and that branch is still here: use it.
+    const before = at.prior?.rebuiltFrom;
+    if (before && before.branch === at.branch && before.sha === at.tip) {
+        const kept = at.branches.find((b) => b.name === at.prior.branch);
+        if (kept !== undefined) {
+            return { kind: 'rebuilt', branch: kept.name, sha: kept.sha, without: before.without, withoutText: withoutSentence(before.without) };
+        }
+    }
+    const ref = await deps.git.freshBase(at.base);
+    const owned = await (0, commit_ownership_1.commitOwnership)(deps.git, { tip: at.tip, base: ref, goalId: input.goalId, claims: input.claims, branches: at.branches, onOrigin: at.onOrigin });
+    if (owned === null)
+        return { kind: 'unknown' };
+    const foreign = await unmergedForeign(deps.git, deps.store, owned.foreign, []);
+    if (foreign.length === 0)
+        return { kind: 'clean' };
+    if (foreign.some((f) => f.goalId !== undefined && (input.dependsOn ?? []).includes(f.goalId))) {
+        return { kind: 'stacked', foreign, because: null };
+    }
+    if (owned.merges.some((m) => owned.own.includes(m))) {
+        return { kind: 'stacked', foreign, because: "this goal's own commits include a merge, which Looply never replays" };
+    }
+    const replayed = await deps.git.replay(ref, owned.own);
+    if (!replayed.ok)
+        return { kind: 'stacked', foreign, because: replayed.because };
+    // `<branch>-solo`, or the next free `-solo-N`; one already here with exactly this content is reused.
+    const stem = at.branch.replace(/-solo(-\d+)?$/, '');
+    let name = null;
+    let sha = replayed.sha;
+    for (let i = 1; i <= 20 && name === null; i++) {
+        const candidate = i === 1 ? `${stem}${commit_ownership_1.SOLO_SUFFIX}` : `${stem}${commit_ownership_1.SOLO_SUFFIX}-${i}`;
+        const existing = at.branches.find((b) => b.name === candidate);
+        if (existing === undefined && !at.onOrigin.has(candidate)) {
+            if (!(await deps.git.createBranch(candidate, replayed.sha))) {
+                return { kind: 'stacked', foreign, because: `the branch ${candidate} could not be created` };
+            }
+            name = candidate;
+        }
+        else if (existing !== undefined && (await deps.git.treeOf(existing.sha)) === replayed.tree && (await deps.git.isAncestor(ref, existing.sha))) {
+            name = candidate;
+            sha = existing.sha;
+        }
+    }
+    if (name === null)
+        return { kind: 'stacked', foreign, because: `every ${stem}${commit_ownership_1.SOLO_SUFFIX} name up to -20 is taken` };
+    // Name the rebuilt branch as this goal's in the lane claims, from the original branch's own record.
+    const source = [...input.claims].reverse().find((r) => r.branch === at.branch && r.goalId === input.goalId);
+    if (source !== undefined && deps.recordClaim !== undefined) {
+        try {
+            deps.recordClaim({
+                schema: source.schema,
+                kind: 'claims',
+                at: at.at,
+                branch: name,
+                runId: source.runId,
+                goalId: input.goalId,
+                goalVersion: source.goalVersion,
+                planRevision: source.planRevision,
+                servings: [],
+                ...(source.kind === 'claims' && source.workspace !== undefined ? { workspace: source.workspace } : {}),
+            });
+        }
+        catch {
+            /* bookkeeping; `ownerOfBranch` still reads a -solo branch through its original */
+        }
+    }
+    const without = foreign.map((f) => ({ goalId: f.goalId ?? null, branch: f.branch, commits: f.commits.length }));
+    return { kind: 'rebuilt', branch: name, sha, without, withoutText: withoutSentence(without) };
+}
+function plural(n, word) {
+    return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
+function withoutSentence(without) {
+    const n = without.reduce((s, w) => s + w.commits, 0);
+    const byGoal = new Map();
+    for (const w of without) {
+        const key = w.goalId ?? `branch:${w.branch}`;
+        const g = byGoal.get(key) ?? { goalId: w.goalId, branches: [], commits: 0 };
+        g.branches.push(w.branch);
+        g.commits += w.commits;
+        byGoal.set(key, g);
+    }
+    const parts = [...byGoal.values()].map((g) => `${g.commits} of ${g.goalId ? `goal ${g.goalId}` : 'another goal'} (${g.branches.join(', ')})`);
+    return `${plural(n, 'commit')} from other goals: ${parts.join('; ')}`;
+}
+/** The plain sentence a ticket shows for other goals' work still in a pull request. */
+function describeForeign(store, foreign, base) {
+    const groups = (0, commit_ownership_1.foreignByGoal)(foreign);
+    const prOf = (goalId, branches) => {
+        const e = goalId !== undefined ? store?.get(goalId) : store?.all().find((x) => branches.includes(x.branch));
+        if (!e || e.pullNumber === null || e.done === true)
+            return '';
+        return branches.includes(e.branch) || (e.rebuiltFrom && branches.includes(e.rebuiltFrom.branch)) ? `, PR #${e.pullNumber}` : '';
+    };
+    const parts = groups.map((g) => `${plural(g.commits, 'commit')} of ${g.goalId ? `goal ${g.goalId}` : 'another goal'} (${g.branches.join(', ')}${prOf(g.goalId, g.branches)})`);
+    if (parts.length === 1)
+        return `it also contains ${parts[0]}, which is not merged into ${base}`;
+    const n = groups.reduce((s, g) => s + g.commits, 0);
+    return `it also contains ${n} commits of other goals that are not merged into ${base}: ${parts.join('; ')}`;
+}
+function guardNote(foreignText, branch) {
+    return `not merged: ${foreignText}; merge or close that first, or rebuild this branch without it (looply deliver --rebuild ${branch})`;
+}
+/**
+ * Drop the foreign work that is merged after all, or carried on purpose:
+ *   - a goal this pull request ABSORBS (a fix-up that replaced that goal's red pull request);
+ *   - a goal whose own delivery is merged, from this branch or a rebuild of it — a person may
+ *     have squashed it, so its commits are not in the base by sha, but its work is.
+ */
+async function unmergedForeign(git, store, foreign, absorbs = []) {
+    const out = [];
+    for (const f of foreign) {
+        if (f.goalId !== undefined && absorbs.includes(f.goalId))
+            continue;
+        const e = f.goalId !== undefined ? store.get(f.goalId) : store.all().find((x) => x.branch === f.branch);
+        if (e && (e.state === 'merged' || e.state === 'deployed' || e.state === 'deploy-failed')) {
+            const top = f.commits[f.commits.length - 1];
+            const same = e.branch === f.branch || e.rebuiltFrom?.branch === f.branch || (top !== undefined && (await git.isAncestor(top, e.sha).catch(() => false)));
+            if (same)
+                continue;
+        }
+        out.push(f);
+    }
+    return out;
+}
+/**
+ * 🔴 THE MERGE GUARD: may this pull request's head be merged into the base without bringing
+ * another goal's unmerged work with it? Asked right before every merge — automatic or approved —
+ * and on every pass while the answer is no. Origin's base is fetched first; a head this machine
+ * cannot read is a NO (it is checked again next pass), never a guess.
+ */
+async function mergeGuard(deps, e, head) {
+    const base = e.projectBase ?? e.base;
+    if (base === null)
+        return { ok: false, note: 'not merged: the base branch it would merge into is not known', foreign: [] };
+    const ref = await deps.git.freshBase(base);
+    const branches = await deps.git.runBranches().catch(() => []);
+    const onOrigin = await deps.git.remoteRunBranches().catch(() => new Set());
+    const owned = await (0, commit_ownership_1.commitOwnership)(deps.git, { tip: head, base: ref, goalId: e.goalId, claims: deps.claims?.() ?? [], branches, onOrigin });
+    if (owned === null) {
+        return {
+            ok: false,
+            note: `not merged: Looply could not read this pull request's commits (${head.slice(0, 12)}) on this machine to check whose work they are; it checks again on the next pass`,
+            foreign: [],
+        };
+    }
+    const left = await unmergedForeign(deps.git, deps.store, owned.foreign, e.absorbs ?? []);
+    if (left.length === 0)
+        return { ok: true };
+    return { ok: false, note: guardNote(describeForeign(deps.store, left, base), e.rebuiltFrom?.branch ?? e.branch), foreign: left };
+}
 /* ─────────────────────────────────────────────── merge, then deploy ── */
 /** How long `merge` waits for checks before handing the pull request to a person. */
 exports.CHECKS_PATIENCE_MS = 24 * 60 * 60_000;
@@ -461,9 +742,13 @@ function decideChecks(required, checks) {
     const waiting = checks.filter((c) => c.state === 'pending').map((c) => c.name);
     return waiting.length > 0 ? { kind: 'pending', waiting } : { kind: 'green' };
 }
-/** States a pass may move on. `pr-open` and `checks-failed` move only on a person's approval. */
-const ADVANCING = ['waiting-checks', 'merged', 'pr-open', 'checks-failed'];
-const APPROVABLE = ['pr-open', 'waiting-checks', 'checks-failed'];
+/**
+ * States a pass may move on. `pr-open` and `checks-failed` move only on a person's approval.
+ * `blocked` is re-examined on every pass: it unblocks by itself once the other goals' work it
+ * carries is merged into the base, and an approval given meanwhile is remembered, not acted on.
+ */
+const ADVANCING = ['waiting-checks', 'merged', 'pr-open', 'checks-failed', 'blocked', 'deployed', 'deploy-failed'];
+const APPROVABLE = ['pr-open', 'waiting-checks', 'checks-failed', 'blocked'];
 /**
  * One pass over every delivered pull request still waiting on Looply:
  *
@@ -495,31 +780,80 @@ async function advanceOne(deps, e) {
     if (!e.approvedAt && APPROVABLE.includes(e.state) && e.pullNumber !== null) {
         const approved = deps.shipRequested(e.goalId);
         if (approved !== null) {
-            e = { ...e, approvedAt: approved, state: 'waiting-checks', note: 'approved to ship by a person; merging once the checks allow', updatedAt: at };
+            // 🔴 A BLOCKED ONE STAYS BLOCKED: the approval is kept, and acted on once it unblocks.
+            e =
+                e.state === 'blocked'
+                    ? { ...e, approvedAt: approved, updatedAt: at }
+                    : { ...e, approvedAt: approved, state: 'waiting-checks', note: 'approved to ship by a person; merging once the checks allow', updatedAt: at };
             await save(deps, e);
         }
     }
     const approved = !!e.approvedAt;
     const wantsMerge = approved || mode === 'merge' || mode === 'deploy';
     const wantsDeploy = approved || mode === 'deploy';
-    if (e.state === 'pr-open' || e.state === 'checks-failed')
-        return;
     if (e.state === 'waiting-checks' && !wantsMerge) {
         await save(deps, { ...e, mode, state: 'pr-open', note: `delivery is now "${mode}", so Looply will not merge it; a person merges`, updatedAt: at });
         return;
     }
-    if (e.state === 'merged' && (!wantsDeploy || e.deploy))
-        return;
-    if (e.owner === null || e.repo === null || e.pullNumber === null)
+    const client = e.owner !== null && e.repo !== null ? await deps.github(e.owner, e.repo) : null;
+    const gh = client?.api ?? null;
+    // Merged: where did it get to? (Looply's own deploy steps once, then GitHub's word for 14 days.)
+    if (e.state === 'merged' || e.state === 'deployed' || e.state === 'deploy-failed') {
+        await followDeploys(deps, gh, e, wantsDeploy, mode);
         return;
-    const client = await deps.github(e.owner, e.repo);
-    if (client.api === null)
+    }
+    if (gh === null || e.pullNumber === null)
         return; // no credentials right now: try again next pass
-    const api = client.api;
+    const api = gh;
+    const pullNumber = e.pullNumber;
+    /**
+     * A PERSON'S OWN MERGE IS SEEN TOO. A pull request Looply is not merging (`pr-open`,
+     * `checks-failed`) is still read every pass: merged on GitHub by a person, it becomes `merged`
+     * with its merge commit, and its deploys are followed like any other.
+     */
+    if (e.state === 'pr-open' || e.state === 'checks-failed') {
+        const pull = await api.getPull(pullNumber);
+        if (pull.merged) {
+            e = { ...e, state: 'merged', mergeSha: pull.mergeSha ?? e.mergeSha ?? null, note: 'merged by a person', updatedAt: at };
+            await save(deps, e);
+            await followDeploys(deps, api, e, wantsDeploy, mode);
+        }
+        else if (pull.state === 'closed') {
+            await save(deps, { ...e, done: true, note: 'the pull request was closed without merging; Looply leaves it', updatedAt: at });
+        }
+        return;
+    }
+    if (e.state === 'blocked') {
+        const pull = await api.getPull(pullNumber);
+        if (pull.merged) {
+            // A person merged it themselves: theirs to decide, and it is what happened.
+            e = { ...e, state: 'merged', mergeSha: pull.mergeSha ?? e.mergeSha ?? null, note: 'merged by a person', updatedAt: at };
+            await save(deps, e);
+        }
+        else if (pull.state === 'closed') {
+            await save(deps, { ...e, state: 'pr-open', done: true, note: 'the pull request was closed without merging; Looply leaves it', updatedAt: at });
+            return;
+        }
+        else {
+            const guard = await mergeGuard(deps, e, pull.headSha || e.sha);
+            if (!guard.ok) {
+                if (guard.note !== e.note)
+                    await save(deps, { ...e, note: guard.note, updatedAt: at });
+                return;
+            }
+            const base = e.projectBase ?? pull.base;
+            if (!wantsMerge) {
+                await save(deps, { ...e, mode, state: 'pr-open', note: `the other goals' work it carried is merged into ${base} now; a person merges this one`, updatedAt: at });
+                return;
+            }
+            e = { ...e, state: 'waiting-checks', note: `the other goals' work it carried is merged into ${base} now; merging once the checks allow`, updatedAt: at };
+            await save(deps, e);
+        }
+    }
     if (e.state === 'waiting-checks') {
-        const pull = await api.getPull(e.pullNumber);
+        const pull = await api.getPull(pullNumber);
         if (pull.merged) {
-            e = { ...e, state: 'merged', note: 'merged by a person', updatedAt: at };
+            e = { ...e, state: 'merged', mergeSha: pull.mergeSha ?? e.mergeSha ?? null, note: 'merged by a person', updatedAt: at };
             await save(deps, e);
         }
         else if (pull.state === 'closed') {
@@ -540,6 +874,17 @@ async function advanceOne(deps, e) {
                 }
                 return;
             }
+            /**
+             * 🔴 NEVER ANOTHER GOAL'S UNMERGED WORK. Checked here — after any retarget, before the
+             * checks are even read — so neither green CI nor "Approve and ship" can carry another
+             * ticket's unreviewed commits into the base. `merge` below is pinned to the same head.
+             */
+            const guard = await mergeGuard(deps, e, pull.headSha || e.sha);
+            if (!guard.ok) {
+                deps.log(`deliver : ${e.goalId}: ${guard.note}`);
+                await save(deps, { ...e, state: 'blocked', note: guard.note, updatedAt: at });
+                return;
+            }
             const verdict = decideChecks(await api.requiredChecks(pull.base), await api.checksFor(pull.headSha));
             const age = now - Date.parse(e.approvedAt ?? e.openedAt);
             if (verdict.kind === 'red') {
@@ -569,51 +914,166 @@ async function advanceOne(deps, e) {
             await save(deps, e);
         }
     }
-    if (e.state !== 'merged' || !wantsDeploy || e.deploy)
-        return;
-    await save(deps, await deployMerged(deps, e, mode));
+    if (e.state === 'merged')
+        await followDeploys(deps, api, e, wantsDeploy, mode);
 }
-/** Run the configured deploy step for a merged pull request, and say what happened. */
-async function deployMerged(deps, e, mode) {
-    const at = new Date(deps.now()).toISOString();
-    const base = e.projectBase ?? '';
+/* ────────────────────────────────────────── where the merge got to ── */
+/** How long a merged commit's deploys are followed for, so one done outside Looply is still seen. */
+exports.FOLLOW_DEPLOYS_MS = 14 * 24 * 60 * 60_000;
+/** The environments to deploy, in order; the single `deploy` (or, under `deploy`, a declared release step) when none are named. */
+function plansFor(deps, mode) {
+    const named = deps.environments?.() ?? [];
+    if (named.length > 0)
+        return [...named];
     // Absent: under `deploy` with a declared release step, run it (the setting before deploy kinds existed).
-    const cfg = deps.deploy() ?? (mode === 'deploy' && deps.release() !== null ? { kind: 'run' } : { kind: 'none' });
-    const done = (ok, detail, state) => ({
-        ...e,
-        state,
-        done: true,
-        deploy: { kind: cfg.kind, ok, detail: detail.slice(0, 600) },
-        note: ok ? null : detail.slice(0, 600),
-        updatedAt: at,
-    });
-    if (cfg.kind === 'none')
-        return done(true, 'merged; nothing is configured to deploy', 'merged');
-    if (cfg.kind === 'merge-deploys')
-        return done(true, `merged into ${base}, which deploys it${e.mergeSha ? ` (${e.mergeSha.slice(0, 12)})` : ''}`, 'deployed');
-    if (cfg.kind === 'push') {
-        if (!e.mergeSha)
-            return done(false, 'merged, but GitHub did not say which commit the merge made, so nothing was pushed to deploy', 'deploy-failed');
-        deps.log(`deliver : deploying ${e.mergeSha.slice(0, 12)} to ${cfg.remote} ${cfg.branch}`);
-        const r = await deps.deployPush(cfg.remote, cfg.branch, e.mergeSha, base);
-        return r.ok
-            ? done(true, `pushed ${e.mergeSha.slice(0, 12)} to ${cfg.branch} on ${cfg.remote}`, 'deployed')
-            : done(false, `pushing to ${cfg.remote} ${cfg.branch} failed: ${r.because}`, 'deploy-failed');
-    }
-    const command = deps.release();
-    if (command === null)
-        return done(false, 'merged; not deployed — no release step is declared (deliver.release in .looply/config.yaml)', 'deploy-failed');
-    deps.log(`deliver : running the declared release step for ${e.goalId}`);
-    const r = await deps.runRelease(command, {
-        LOOPLY_GOAL_ID: e.goalId,
-        LOOPLY_BRANCH: e.branch,
-        LOOPLY_BASE_BRANCH: base,
-        LOOPLY_MERGED_SHA: e.mergeSha ?? '',
-        LOOPLY_PULL_REQUEST_URL: e.pullRequestUrl ?? '',
-    });
-    return r.code === 0
-        ? done(true, 'the declared release step finished', 'deployed')
-        : done(false, `the release step exited ${r.code}: ${r.tail.slice(-300)}`, 'deploy-failed');
+    const d = deps.deploy() ?? (mode === 'deploy' && deps.release() !== null ? { kind: 'run' } : null);
+    if (d === null || d.kind === 'none')
+        return [];
+    return [{ name: d.kind === 'push' ? d.remote : 'default', deploy: d, unnamed: true }];
+}
+/**
+ * 🔴 WHERE A MERGED COMMIT IS, TOLD TRUTHFULLY, PER ENVIRONMENT.
+ *
+ * The first time it is seen merged, every environment gets a row and Looply runs its OWN deploy
+ * steps, in order (only under `deploy` or "Approve and ship"; a failure stops the ones after it):
+ *   - `push`  → deployed when the git push exited 0 (a push to Heroku returns only after the release);
+ *   - `run`   → deployed when the project's declared release step exited 0;
+ *   - `merge-deploys` → UNCONFIRMED: the merge should deploy it, but a merge is not a deploy;
+ *   - `none`  → waiting: nothing here deploys it.
+ * Then, every pass, GitHub's Deployments for the merge commit are read, and an environment of the
+ * same name (any, for the one unnamed environment) that GitHub says is `success` is `deployed`,
+ * `failure`/`error` is `failed`, still running is `deploying` — which is how a Heroku or Netlify
+ * deploy, or one a person ran by hand, is seen. Nothing else ever makes a row `deployed`.
+ *
+ * The delivery is `done` once every environment is deployed or failed, or 14 days after the merge;
+ * a pass that changes nothing records nothing. No environment configured: done at the merge, and
+ * the report says nothing is configured to deploy.
+ */
+async function followDeploys(deps, api, e, wantsDeploy, mode) {
+    const nowMs = deps.now();
+    const at = new Date(nowMs).toISOString();
+    let x = { ...e, mergedAt: e.mergedAt ?? at };
+    const plans = plansFor(deps, mode);
+    if (x.environments === undefined) {
+        if (plans.length === 0) {
+            await save(deps, { ...x, done: true, deploy: { kind: 'none', ok: true, detail: 'merged; nothing is configured to deploy' }, updatedAt: at });
+            return;
+        }
+        x = await deployAll(deps, x, plans, wantsDeploy, at);
+    }
+    const sha = x.mergeSha ?? null;
+    if (api?.deploymentsFor && sha !== null) {
+        const found = await api.deploymentsFor(sha).catch(() => null);
+        if (found !== null)
+            x = { ...x, environments: (x.environments ?? []).map((row) => fromGitHub(row, plans, found)) };
+    }
+    const rows = x.environments ?? [];
+    const settled = rows.every((r) => r.state === 'deployed' || r.state === 'failed');
+    const expired = nowMs - Date.parse(x.mergedAt) > exports.FOLLOW_DEPLOYS_MS;
+    const failed = rows.find((r) => r.state === 'failed');
+    const state = failed ? 'deploy-failed' : rows.length > 0 && settled ? 'deployed' : 'merged';
+    const open = rows.filter((r) => r.state !== 'deployed');
+    const note = open.length === 0
+        ? null
+        : `${expired && !settled ? 'after 14 days, ' : ''}${open.map((r) => `${r.name}: ${r.detail ?? r.state}`).join('; ')}`.slice(0, 600);
+    x = { ...x, state, note, ...(settled || expired ? { done: true } : {}) };
+    const same = JSON.stringify({ ...x, updatedAt: '' }) === JSON.stringify({ ...e, updatedAt: '' });
+    if (!same)
+        await save(deps, { ...x, updatedAt: at });
+}
+/** Run Looply's own deploy step for each environment, in order, and make every row. */
+async function deployAll(deps, e, plans, wantsDeploy, at) {
+    const base = e.projectBase ?? '';
+    const sha = e.mergeSha ?? null;
+    const rows = [];
+    let stoppedBy = null;
+    for (const p of plans) {
+        const row = (state, detail) => ({
+            name: p.name,
+            test: p.test === true,
+            state,
+            sha,
+            at: state === 'waiting' ? null : at,
+            url: p.url ?? null,
+            detail: detail.slice(0, 600),
+        });
+        const d = p.deploy;
+        if (stoppedBy !== null) {
+            rows.push(row('waiting', `not deployed: the deploy to ${stoppedBy} failed first`));
+            continue;
+        }
+        if (d.kind === 'none') {
+            rows.push(row('waiting', `no deploy step is configured for ${p.name}`));
+            continue;
+        }
+        if (d.kind === 'merge-deploys') {
+            rows.push(row('unconfirmed', `merged into ${base}, which should deploy it; not confirmed yet`));
+            continue;
+        }
+        if (!wantsDeploy) {
+            rows.push(row('waiting', `Looply deploys only under "deploy" or after "Approve and ship"`));
+            continue;
+        }
+        if (d.kind === 'push') {
+            if (sha === null) {
+                rows.push(row('failed', 'merged, but GitHub did not say which commit the merge made, so nothing was pushed to deploy'));
+            }
+            else {
+                deps.log(`deliver : deploying ${sha.slice(0, 12)} to ${d.remote} ${d.branch} (${p.name})`);
+                const r = await deps.deployPush(d.remote, d.branch, sha, base);
+                rows.push(r.ok ? row('deployed', `pushed ${sha.slice(0, 12)} to ${d.branch} on ${d.remote}`) : row('failed', `pushing to ${d.remote} ${d.branch} failed: ${r.because}`));
+            }
+        }
+        else {
+            const command = deps.release();
+            if (command === null) {
+                rows.push(row('failed', 'merged; not deployed — no release step is declared (deliver.release in .looply/config.yaml)'));
+            }
+            else {
+                deps.log(`deliver : running the declared release step for ${e.goalId} (${p.name})`);
+                const r = await deps.runRelease(command, {
+                    LOOPLY_GOAL_ID: e.goalId,
+                    LOOPLY_BRANCH: e.branch,
+                    LOOPLY_BASE_BRANCH: base,
+                    LOOPLY_MERGED_SHA: sha ?? '',
+                    LOOPLY_PULL_REQUEST_URL: e.pullRequestUrl ?? '',
+                    LOOPLY_ENVIRONMENT: p.name,
+                });
+                rows.push(r.code === 0 ? row('deployed', 'the declared release step finished') : row('failed', `the release step exited ${r.code}: ${r.tail.slice(-300)}`));
+            }
+        }
+        if (rows[rows.length - 1].state === 'failed')
+            stoppedBy = p.name;
+    }
+    // The one-line summary older readers know: the failed step, else the first environment's.
+    const lead = rows.find((r) => r.state === 'failed') ?? rows[0];
+    const leadPlan = plans[rows.indexOf(lead)];
+    return { ...e, environments: rows, deploy: { kind: leadPlan.deploy.kind, ok: lead.state !== 'failed', detail: lead.detail ?? '' } };
+}
+/** GitHub's word on one environment, when it has one and the row is not already settled. */
+function fromGitHub(row, plans, found) {
+    if (row.state === 'deployed' || row.state === 'failed')
+        return row;
+    const plan = plans.find((p) => p.name === row.name);
+    const match = found.find((d) => plan?.unnamed === true || d.environment.toLowerCase() === row.name.toLowerCase());
+    if (match === undefined)
+        return row;
+    const state = match.state === 'success' || match.state === 'inactive'
+        ? 'deployed'
+        : match.state === 'failure' || match.state === 'error'
+            ? 'failed'
+            : ['in_progress', 'queued', 'pending'].includes(match.state)
+                ? 'deploying'
+                : null;
+    if (state === null || (state === row.state && (match.url ?? row.url) === row.url))
+        return row;
+    const said = match.description ? `: ${match.description}` : '';
+    const detail = state === 'deployed'
+        ? `GitHub reports it deployed to ${match.environment}${match.state === 'inactive' ? ' (since replaced by a newer deploy)' : ''}${said}`
+        : state === 'failed'
+            ? `GitHub reports the deploy to ${match.environment} failed${said}`
+            : `GitHub reports a deploy to ${match.environment} in progress${said}`;
+    return { ...row, state, at: Number.isNaN(Date.parse(match.at)) ? row.at : new Date(match.at).toISOString(), url: match.url ?? row.url, detail: detail.slice(0, 600) };
 }
 /**
  * Run the project's declared release step in the project folder, hidden, bounded