@wardby/cli 0.4.1 → 0.5.0

package/dist/core/issue-events.js

@@ -2,6 +2,7 @@ import { RESPONSE_PATH_SNAPSHOT_BUDGET, resolveWorkItem } from "./attribution.js
 import { dispatchRun } from "./dispatch.js";
 import { issueStatusRow, postIssueWorkingStatus } from "./issue-status.js";
 import { logger } from "./logger.js";
+import { openSiblingsForIssue, SIBLING_GUIDANCE } from "./related-pull-requests.js";
 import { composeTaskOverride } from "./untrusted-content.js";
 const log = logger.child({ module: "issue-events" });
 const MAX_TASK_BODY = 8000;
@@ -42,11 +43,15 @@ export function issueTaskText(event, matched, issueUrl, link, openPrs = []) {
         "Use jira_get_issue to read the issue. Your final answer is posted on this issue for you when you finish, so " +
             "do not also post it with jira_comment; use jira_comment only for other issues or progress notes on long work.",
     ];
-    // Control-plane data from stored rows (validated at write time), never issue text.
-    for (const pr of openPrs.filter((p) => RUN_ID_RE.test(p.openedByRunId))) {
-        sections.push(`This issue already has an open pull request wardby opened: ${pr.repository}#${pr.number} (${pr.url}). ` +
+    // Control-plane data from stored rows (validated here), never issue text.
+    const hinted = openPrs.filter((p) => RUN_ID_RE.test(p.openedByRunId));
+    for (const pr of hinted) {
+        sections.push(`This issue already has an open pull request wardby opened: ${pr.repository}#${pr.number} ` +
+            `(https://github.com/${pr.repository}/pull/${pr.number}). ` +
             `To revise it, delegate with continuePriorRun set to exactly "${pr.openedByRunId}".`);
     }
+    if (hinted.length > 0)
+        sections.push(SIBLING_GUIDANCE);
     if (matched.includes("mention") && event.comment) {
         sections.push(`Request comment:\n${event.comment.body.slice(0, MAX_TASK_BODY)}`);
     }
@@ -80,20 +85,6 @@ function matchedKinds(event, link, bot) {
         }
     });
 }
-async function openPullRequests(db, issueKey, agentId) {
-    try {
-        return await db.issuePullRequest.findMany({
-            where: { issueProvider: "jira", issueKey, agentId, state: "open" },
-            orderBy: { createdAt: "desc" },
-            take: 3,
-            select: { repository: true, number: true, url: true, openedByRunId: true },
-        });
-    }
-    catch (err) {
-        log.warn({ err, issueKey, agentId }, "open pull requests could not be looked up; continuing without a hint");
-        return [];
-    }
-}
 const JQL_FILTER_BUDGET = { timeoutMs: 5000, retryOn429: false };
 export async function routeIssueEvent(event, deps) {
     const result = { runIds: [], followUps: [] };
@@ -108,6 +99,10 @@ export async function routeIssueEvent(event, deps) {
     // One snapshot per event, taken lazily on the first dispatch so an event no link matches costs nothing.
     let item;
     const workItem = () => (item ??= resolveWorkItem(deps.db, deps.trackers, event.provider, event.issueKey, RESPONSE_PATH_SNAPSHOT_BUDGET));
+    // Likewise the card's open siblings: one lookup per event (every matched
+    // link gets the same whole-card hints), not one per link.
+    let siblings;
+    const openPrs = () => (siblings ??= openSiblingsForIssue(deps.db, { provider: event.provider, key: event.issueKey }));
     for (const link of links) {
         if (link.access !== "write" || !link.agent.ownerId || link.agent.kind !== "native")
             continue;
@@ -126,7 +121,6 @@ export async function routeIssueEvent(event, deps) {
             if (!ok)
                 continue;
         }
-        const openPrs = await openPullRequests(deps.db, event.issueKey, link.agentId);
         try {
             const dispatched = await dispatchRun({
                 db: deps.db,
@@ -135,7 +129,7 @@ export async function routeIssueEvent(event, deps) {
                 agentId: link.agentId,
                 trigger: "host_event",
                 attribution: { source: "issue_event", item: await workItem() },
-                taskOverride: issueTaskText(event, matched, tracker.issueUrl(event.issueKey), link, openPrs),
+                taskOverride: issueTaskText(event, matched, tracker.issueUrl(event.issueKey), link, await openPrs()),
                 afterPersist: async (tx, run) => {
                     await tx.runIssueStatus.create({ data: issueStatusRow(event, run.id, link.commentVisibilityRole) });
                 },

package/dist/core/pull-request-state-sync.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Keeps IssuePullRequest.state current when a pr_closed webhook was missed
+ * (an outage, a redelivery that never came). Each reconciler pass reads a
+ * small batch of rows still marked open — least recently checked first —
+ * from the code host and settles merged or closed ones through
+ * handlePullRequestClosed, the webhook's own path. Sibling continuation hints
+ * and the Related pull requests section read this state. Best effort: never throws.
+ */
+import type { PrismaClient } from "#prisma";
+import type { IssueTrackerRegistry } from "../providers/issue-tracker/types.js";
+import type { ReviewHostRegistry } from "../providers/review-host/types.js";
+/** Rows checked per pass (each is one token mint + one GET + one revoke). */
+export declare const PR_STATE_SYNC_BATCH = 10;
+/** A row is re-checked at most this often. */
+export declare const PR_STATE_SYNC_MIN_AGE_MS: number;
+export type PullRequestStateSyncDb = Pick<PrismaClient, "issuePullRequest" | "agentIssueProject">;
+export declare function syncOpenPullRequestStates(db: PullRequestStateSyncDb, hosts: ReviewHostRegistry | undefined, trackers: IssueTrackerRegistry | undefined, now?: Date): Promise<number>;

package/dist/core/pull-request-state-sync.js

@@ -0,0 +1,53 @@
+import { handlePullRequestClosed } from "./issue-bridge.js";
+import { logger } from "./logger.js";
+const log = logger.child({ module: "pull-request-state-sync" });
+/** Rows checked per pass (each is one token mint + one GET + one revoke). */
+export const PR_STATE_SYNC_BATCH = 10;
+/** A row is re-checked at most this often. */
+export const PR_STATE_SYNC_MIN_AGE_MS = 10 * 60_000;
+export async function syncOpenPullRequestStates(db, hosts, trackers, now = new Date()) {
+    // handlePullRequestClosed needs trackers; without them no IssuePullRequest rows are written anyway.
+    if (!hosts || !trackers)
+        return 0;
+    let settled = 0;
+    try {
+        const rows = await db.issuePullRequest.findMany({
+            where: { state: "open", updatedAt: { lt: new Date(now.getTime() - PR_STATE_SYNC_MIN_AGE_MS) } },
+            orderBy: { updatedAt: "asc" },
+            take: PR_STATE_SYNC_BATCH,
+            select: { id: true, codeProvider: true, repository: true, number: true },
+        });
+        const touch = (id) => db.issuePullRequest
+            .updateMany({ where: { id, state: "open" }, data: { updatedAt: now } })
+            .catch((err) => log.warn({ err, id }, "could not mark a pull request as checked"));
+        for (const row of rows) {
+            const host = hosts[row.codeProvider];
+            if (!host?.pullRequestOrigin)
+                continue;
+            try {
+                const origin = await host.pullRequestOrigin(row.repository, row.number);
+                if (origin.state === "open" && origin.merged !== true) {
+                    await touch(row.id);
+                    continue;
+                }
+                const merged = origin.merged === true;
+                await handlePullRequestClosed(db, trackers, {
+                    codeProvider: row.codeProvider,
+                    repository: row.repository,
+                    number: row.number,
+                    merged,
+                });
+                settled += 1;
+                log.info({ repository: row.repository, number: row.number, merged }, "settled a pull request whose close was missed");
+            }
+            catch (err) {
+                log.warn({ err, repository: row.repository, number: row.number }, "could not sync a pull request's state");
+                await touch(row.id);
+            }
+        }
+    }
+    catch (err) {
+        log.warn({ err }, "pull request state sync failed");
+    }
+    return settled;
+}

package/dist/core/reconciler.d.ts

@@ -34,11 +34,16 @@
  * of those paths instead of patching each. Mention status comments, and the
  * status comments of runs started by Jira issue events, get the same sweep:
  * it also catches a run that ended before its comment was posted.
+ *
+ * Given host-event deps, each pass also starts reviews deferred until CI
+ * finished (waitForCi links) whose CI has not finished in time, and drops
+ * deferred reviews that are too old (host-events.ts startDeferredReviews).
  */
 import type { PrismaClient } from "#prisma";
 import type { Executor } from "../providers/executor/types.js";
 import type { ReviewHostRegistry } from "../providers/review-host/types.js";
 import type { IssueTrackerRegistry } from "../providers/issue-tracker/types.js";
+import { type ReviewStartDeps } from "./host-events.js";
 export type ReconcilerDb = Pick<PrismaClient, "run" | "runHostCheck" | "runHostStatus" | "runIssueStatus" | "agentIssueProject" | "issuePullRequest" | "codingRun" | "agent" | "$transaction" | "$queryRaw">;
 /**
  * How long after a run finishes before its still-open check counts as
@@ -68,7 +73,9 @@ export declare function closeOrphanedHostChecks(db: Pick<PrismaClient, "runHostC
  */
 export declare function closeOrphanedHostStatuses(db: Pick<PrismaClient, "runHostStatus" | "run">, hosts: ReviewHostRegistry | undefined, now?: Date): Promise<void>;
 /** Runs one reconciliation pass. Returns the number of runs marked `lost`. */
-export declare function reconcileOnce(db: ReconcilerDb, now?: Date, heartbeatTimeoutMs?: number, executor?: Executor, reviewHosts?: ReviewHostRegistry, issueTrackers?: IssueTrackerRegistry): Promise<number>;
+export declare function reconcileOnce(db: ReconcilerDb, now?: Date, heartbeatTimeoutMs?: number, executor?: Executor, reviewHosts?: ReviewHostRegistry, issueTrackers?: IssueTrackerRegistry, 
+/** What starting a deferred review needs; absent = no deferred-review sweep. */
+deferredReviews?: ReviewStartDeps): Promise<number>;
 export interface ReconcilerOptions {
     db?: ReconcilerDb;
     intervalMs?: number;
@@ -78,6 +85,8 @@ export interface ReconcilerOptions {
     reviewHosts?: ReviewHostRegistry;
     /** Trackers used to complete issue status comments orphaned the same way; none configured = no sweep. */
     issueTrackers?: IssueTrackerRegistry;
+    /** Host-event deps for starting deferred reviews (waitForCi) whose CI never finished; absent = no sweep. */
+    deferredReviews?: ReviewStartDeps;
 }
 export interface ReconcilerHandle {
     stop(): void;

package/dist/core/reconciler.js

@@ -34,6 +34,10 @@
  * of those paths instead of patching each. Mention status comments, and the
  * status comments of runs started by Jira issue events, get the same sweep:
  * it also catches a run that ended before its comment was posted.
+ *
+ * Given host-event deps, each pass also starts reviews deferred until CI
+ * finished (waitForCi links) whose CI has not finished in time, and drops
+ * deferred reviews that are too old (host-events.ts startDeferredReviews).
  */
 import { HEARTBEAT_TIMEOUT_MS, RECONCILE_INTERVAL_MS } from "./timing.js";
 import { prisma as defaultDb } from "./db.js";
@@ -42,6 +46,8 @@ import { closeOpenHostCheck } from "./review-host-checks.js";
 import { completeHostStatus } from "./host-status.js";
 import { closeOrphanedIssueStatuses } from "./issue-status.js";
 import { fileSelfDefect } from "./self-defects.js";
+import { syncOpenPullRequestStates } from "./pull-request-state-sync.js";
+import { startDeferredReviews } from "./host-events.js";
 const reconcilerLog = logger.child({ module: "reconciler" });
 /** A pass waits this long per self-defect, then moves on; the filing finishes (or logs) in the background. */
 const SELF_DEFECT_WAIT = { waitMs: 2_000 };
@@ -120,7 +126,9 @@ export async function closeOrphanedHostStatuses(db, hosts, now = new Date()) {
         await completeHostStatus(db, run, hosts, { postIfMissing: true });
 }
 /** Runs one reconciliation pass. Returns the number of runs marked `lost`. */
-export async function reconcileOnce(db, now = new Date(), heartbeatTimeoutMs = HEARTBEAT_TIMEOUT_MS, executor, reviewHosts, issueTrackers) {
+export async function reconcileOnce(db, now = new Date(), heartbeatTimeoutMs = HEARTBEAT_TIMEOUT_MS, executor, reviewHosts, issueTrackers, 
+/** What starting a deferred review needs; absent = no deferred-review sweep. */
+deferredReviews) {
     const cutoff = new Date(now.getTime() - heartbeatTimeoutMs);
     const stale = {
         executionManaged: true,
@@ -228,6 +236,11 @@ export async function reconcileOnce(db, now = new Date(), heartbeatTimeoutMs = H
     await closeOrphanedHostChecks(db, reviewHosts, now);
     await closeOrphanedHostStatuses(db, reviewHosts, now);
     await closeOrphanedIssueStatuses(db, issueTrackers, now);
+    // Settle stored pull requests whose merge/close webhook was missed; bounded per pass, never throws.
+    await syncOpenPullRequestStates(db, reviewHosts, issueTrackers, now);
+    // Start reviews whose head's CI never finished (waitForCi links); bounded per pass, never throws.
+    if (deferredReviews)
+        await startDeferredReviews(deferredReviews, now);
     return lost;
 }
 export function startReconciler(options = {}) {
@@ -235,7 +248,7 @@ export function startReconciler(options = {}) {
     const intervalMs = options.intervalMs ?? RECONCILE_INTERVAL_MS;
     const heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? HEARTBEAT_TIMEOUT_MS;
     const timer = setInterval(() => {
-        reconcileOnce(db, new Date(), heartbeatTimeoutMs, options.executor, options.reviewHosts, options.issueTrackers).catch((err) => {
+        reconcileOnce(db, new Date(), heartbeatTimeoutMs, options.executor, options.reviewHosts, options.issueTrackers, options.deferredReviews).catch((err) => {
             reconcilerLog.error({ err }, "reconcile pass failed");
         });
     }, intervalMs);

package/dist/core/related-pull-requests.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The pull requests that came from the same request as a run: every pull
+ * request opened by a coding run in the same top-level run tree (a lead that
+ * fanned out to several repositories), plus any recorded for the same tracker
+ * issue (IssuePullRequest). Control-plane rows only.
+ * Ordered by when each pull request's coding run was dispatched: the lead's
+ * delegation order (for a lead with parallelDelegations, the order its
+ * concurrent delegations were admitted, ties broken by repository#number).
+ * A PR opened while siblings were still running lists only the PRs opened
+ * before it; updateRelatedPullRequests rewrites every open PR of the set
+ * with the full list when the lead run ends. Continuations join
+ * the set in both directions: a follow-up that continued one of the set's
+ * pull requests brings the original request's tree, and the original request
+ * brings every later follow-up tree that continued one of its pull requests.
+ */
+import { type PrismaClient, type Run } from "#prisma";
+import { type IssueTrackerRegistry } from "../providers/issue-tracker/types.js";
+import type { ReviewHostRegistry } from "../providers/review-host/types.js";
+/** Most pull requests a group holds; the description shows fewer (MAX_RELATED_PULL_REQUESTS). */
+export declare const MAX_RELATED_GROUP = 50;
+export type RelatedPullRequestsDb = Pick<PrismaClient, "run" | "codingRun" | "issuePullRequest" | "$queryRaw">;
+export type StoredPullRequestState = "open" | "merged" | "closed";
+export interface RelatedPullRequest {
+    repository: string;
+    number: number;
+    openedAt: Date;
+    /** The coding run that opened it: the continuePriorRun target for a follow-up. */
+    openedByRunId: string;
+    /** Only when stored (IssuePullRequest.state, kept current by pr_closed); otherwise unknown. */
+    state?: StoredPullRequestState;
+}
+export interface RelatedPullRequestGroup {
+    pullRequests: RelatedPullRequest[];
+    /** The first well-formed issue seen on the group's coding runs. */
+    issue?: {
+        provider: string;
+        key: string;
+    };
+}
+export declare function collectRelatedPullRequests(db: RelatedPullRequestsDb, runId: string, 
+/**
+ * Scopes the issue join (and any tree row explicitly tagged for a
+ * different issue) to exactly this issue, instead of every issue key the
+ * tree's coding runs happen to carry. Used by openSiblingsForIssue so a
+ * tree that touches two cards never leaks the other card's pull requests
+ * into this one's continuation hints; omitted by every other caller, which
+ * keeps today's "every issue the tree touched" behavior (Decision 2).
+ */
+onlyIssueKey?: {
+    provider: string;
+    key: string;
+}): Promise<RelatedPullRequestGroup>;
+/**
+ * After a native run ends, rewrites the Related pull requests section on
+ * every open pull request of its request (control-plane rows only). Best
+ * effort: never throws, and never removes a section (a set of one writes
+ * nothing). Only PRs the App authored, whose marker names a coding run this
+ * deployment recorded in that repository, are edited.
+ */
+export declare function updateRelatedPullRequests(db: RelatedPullRequestsDb, run: Pick<Run, "id">, hosts: ReviewHostRegistry | undefined, trackers: IssueTrackerRegistry | undefined): Promise<void>;
+/** Most open siblings hinted in one task. */
+export declare const MAX_SIBLING_HINTS = 10;
+/** Closes every sibling-hint block (mention and Jira alike). */
+export declare const SIBLING_GUIDANCE: string;
+export interface OpenSibling {
+    repository: string;
+    number: number;
+    openedByRunId: string;
+}
+/**
+ * The group's pull requests a follow-up may continue: stored state "open", or
+ * no stored state yet (a same-tree sibling not recorded for an issue), minus
+ * `exclude` and malformed run ids. Stored state only: no host call. A hint for
+ * a PR that has closed since is refused by the continuation itself (git.ts).
+ */
+export declare function openSiblingsOf(group: RelatedPullRequestGroup, exclude?: {
+    repository: string;
+    number: number;
+}): OpenSibling[];
+/** Open siblings of the request `seedRunId` belongs to. Never throws. */
+export declare function openSiblings(db: RelatedPullRequestsDb, seedRunId: string, exclude: {
+    repository: string;
+    number: number;
+}): Promise<OpenSibling[]>;
+/**
+ * Open pull requests of a whole card: seeded from the newest pull request
+ * recorded for the issue (any agent), then the collector is scoped to this
+ * issue alone (never "every issue the tree touched") so a tree that happens
+ * to also carry another card's coding runs can't leak that card's pull
+ * requests into this one's hints. Never throws.
+ */
+export declare function openSiblingsForIssue(db: RelatedPullRequestsDb, issue: {
+    provider: string;
+    key: string;
+}): Promise<OpenSibling[]>;

package/dist/core/related-pull-requests.js

@@ -0,0 +1,338 @@
+/**
+ * The pull requests that came from the same request as a run: every pull
+ * request opened by a coding run in the same top-level run tree (a lead that
+ * fanned out to several repositories), plus any recorded for the same tracker
+ * issue (IssuePullRequest). Control-plane rows only.
+ * Ordered by when each pull request's coding run was dispatched: the lead's
+ * delegation order (for a lead with parallelDelegations, the order its
+ * concurrent delegations were admitted, ties broken by repository#number).
+ * A PR opened while siblings were still running lists only the PRs opened
+ * before it; updateRelatedPullRequests rewrites every open PR of the set
+ * with the full list when the lead run ends. Continuations join
+ * the set in both directions: a follow-up that continued one of the set's
+ * pull requests brings the original request's tree, and the original request
+ * brings every later follow-up tree that continued one of its pull requests.
+ */
+import { Prisma } from "#prisma";
+import { CODING_CODE_PROVIDER, normalizeGitHubRepository } from "../coding/protocol.js";
+import { ISSUE_KEY, ISSUE_TRACKER_NAMES, } from "../providers/issue-tracker/types.js";
+import { renderRelatedSection } from "../providers/vcs/github.js";
+import { pullRequestOutcome } from "./host-status.js";
+import { logger } from "./logger.js";
+const log = logger.child({ module: "related-pull-requests" });
+/** Most pull requests a group holds; the description shows fewer (MAX_RELATED_PULL_REQUESTS). */
+export const MAX_RELATED_GROUP = 50;
+/** Most coding runs read per tree walk (and per continuation lookup). */
+const MAX_TREE_CODING_RUNS = 200;
+/** Most forward/reverse expansion passes after the seed's own tree walk. */
+const MAX_EXPANSION_PASSES = 4;
+const STORED_STATES = new Set(["open", "merged", "closed"]);
+/** Every coding run in the top-level trees containing `seeds` (walks up parentRunId, then down). */
+async function treeCodingRuns(db, seeds) {
+    return db.$queryRaw `
+    WITH RECURSIVE up AS (
+      SELECT r."id", r."parentRunId" FROM "Run" r WHERE r."id" IN (${Prisma.join(seeds)})
+      -- UNION, not UNION ALL: a parentRunId cycle (never written, but not a constraint) can't recurse forever.
+      UNION
+      SELECT p."id", p."parentRunId" FROM "Run" p JOIN up u ON p."id" = u."parentRunId"
+    ), down AS (
+      SELECT u."id" FROM up u WHERE u."parentRunId" IS NULL
+      UNION
+      SELECT c."id" FROM "Run" c JOIN down d ON c."parentRunId" = d."id"
+    )
+    SELECT cr."runId", cr."result", cr."rootCodingRunId", cr."issueProvider", cr."issueKey", r."startedAt"
+    FROM "CodingRun" cr
+    JOIN down d ON cr."runId" = d."id"
+    JOIN "Run" r ON r."id" = cr."runId"
+    ORDER BY r."startedAt" ASC, cr."runId" ASC
+    LIMIT ${MAX_TREE_CODING_RUNS}`;
+}
+function safeRepository(value) {
+    try {
+        return normalizeGitHubRepository(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function collectRelatedPullRequests(db, runId, 
+/**
+ * Scopes the issue join (and any tree row explicitly tagged for a
+ * different issue) to exactly this issue, instead of every issue key the
+ * tree's coding runs happen to carry. Used by openSiblingsForIssue so a
+ * tree that touches two cards never leaks the other card's pull requests
+ * into this one's continuation hints; omitted by every other caller, which
+ * keeps today's "every issue the tree touched" behavior (Decision 2).
+ */
+onlyIssueKey) {
+    const rows = await treeCodingRuns(db, [runId]);
+    const seen = new Set(rows.map((r) => r.runId));
+    // A continuation's pull request belongs to the request that opened it, so
+    // the set is closed in both directions: forward (a continuation row walks
+    // to its root's tree) and reverse (an opener's later continuations, found
+    // through the indexed rootCodingRunId, walk their own trees, which may
+    // have opened new pull requests). Repeated until nothing new turns up, at
+    // most MAX_EXPANSION_PASSES times, and never past a full group.
+    const expandedOpeners = new Set();
+    for (let pass = 0; pass < MAX_EXPANSION_PASSES; pass++) {
+        const roots = [];
+        const openers = [];
+        let opened = 0;
+        for (const r of rows) {
+            const outcome = pullRequestOutcome(r.result)?.outcome;
+            if (outcome === "pull_request_updated" && r.rootCodingRunId && !seen.has(r.rootCodingRunId)) {
+                roots.push(r.rootCodingRunId);
+            }
+            else if (outcome === "pull_request_opened") {
+                opened++;
+                if (!expandedOpeners.has(r.runId))
+                    openers.push(r.runId);
+            }
+        }
+        if (opened >= MAX_RELATED_GROUP)
+            break;
+        for (const opener of openers)
+            expandedOpeners.add(opener);
+        const continuations = openers.length > 0
+            ? await db.codingRun.findMany({
+                where: { rootCodingRunId: { in: openers } },
+                select: { runId: true },
+                orderBy: { runId: "asc" },
+                take: MAX_TREE_CODING_RUNS,
+            })
+            : [];
+        const seeds = [...new Set([...roots, ...continuations.map((c) => c.runId)])].filter((id) => !seen.has(id));
+        if (seeds.length === 0)
+            break;
+        let added = 0;
+        for (const extra of await treeCodingRuns(db, seeds)) {
+            if (!seen.has(extra.runId)) {
+                seen.add(extra.runId);
+                rows.push(extra);
+                added++;
+            }
+        }
+        if (added === 0)
+            break;
+    }
+    const byKey = new Map();
+    const keyOf = (repository, number) => `${repository}#${number}`;
+    let issue;
+    const issues = new Map();
+    for (const r of rows) {
+        if (r.issueProvider && r.issueKey && ISSUE_KEY.test(r.issueKey)) {
+            const found = { provider: r.issueProvider, key: r.issueKey };
+            issue ??= found;
+            issues.set(`${found.provider}\0${found.key}`, found);
+        }
+        const pr = pullRequestOutcome(r.result);
+        if (pr?.outcome !== "pull_request_opened")
+            continue;
+        // A tree row explicitly tagged for a different card never joins this one's set.
+        if (onlyIssueKey && r.issueKey && (r.issueProvider !== onlyIssueKey.provider || r.issueKey !== onlyIssueKey.key)) {
+            continue;
+        }
+        const repository = safeRepository(pr.repository);
+        if (repository && !byKey.has(keyOf(repository, pr.pullRequestNumber))) {
+            byKey.set(keyOf(repository, pr.pullRequestNumber), {
+                repository,
+                number: pr.pullRequestNumber,
+                openedAt: new Date(r.startedAt),
+                openedByRunId: r.runId,
+            });
+        }
+    }
+    const issueFilter = onlyIssueKey
+        ? new Map([[`${onlyIssueKey.provider}\0${onlyIssueKey.key}`, onlyIssueKey]])
+        : issues;
+    if (issueFilter.size > 0) {
+        const recorded = await db.issuePullRequest.findMany({
+            where: {
+                codeProvider: CODING_CODE_PROVIDER,
+                OR: [...issueFilter.values()].map((i) => ({ issueProvider: i.provider, issueKey: i.key })),
+            },
+            select: { repository: true, number: true, createdAt: true, openedByRunId: true, state: true },
+            orderBy: { createdAt: "asc" },
+            take: MAX_RELATED_GROUP,
+        });
+        // Every pull request recorded for the issue, merged and closed included (Decision 2).
+        for (const r of recorded) {
+            const repository = safeRepository(r.repository);
+            if (!repository || !Number.isSafeInteger(r.number) || r.number <= 0)
+                continue;
+            const state = STORED_STATES.has(r.state) ? r.state : undefined;
+            const existing = byKey.get(keyOf(repository, r.number));
+            if (existing) {
+                // The tree's own opener and dispatch time stay; the stored state is added.
+                if (state)
+                    existing.state = state;
+                continue;
+            }
+            byKey.set(keyOf(repository, r.number), {
+                repository,
+                number: r.number,
+                openedAt: r.createdAt,
+                openedByRunId: r.openedByRunId,
+                ...(state ? { state } : {}),
+            });
+        }
+    }
+    const pullRequests = [...byKey.values()]
+        .sort((a, b) => a.openedAt.getTime() - b.openedAt.getTime() ||
+        `${a.repository}#${a.number}`.localeCompare(`${b.repository}#${b.number}`))
+        .slice(0, MAX_RELATED_GROUP);
+    return { pullRequests, ...(issue ? { issue } : {}) };
+}
+function issueFor(group, trackers) {
+    if (!group.issue)
+        return undefined;
+    const provider = group.issue.provider;
+    let url;
+    try {
+        url = trackers?.[provider]?.issueUrl(group.issue.key);
+    }
+    catch {
+        url = undefined;
+    }
+    const trackerName = Object.hasOwn(ISSUE_TRACKER_NAMES, provider) ? ISSUE_TRACKER_NAMES[provider] : undefined;
+    return { key: group.issue.key, ...(url ? { url } : {}), ...(trackerName ? { trackerName } : {}) };
+}
+/**
+ * After a native run ends, rewrites the Related pull requests section on
+ * every open pull request of its request (control-plane rows only). Best
+ * effort: never throws, and never removes a section (a set of one writes
+ * nothing). Only PRs the App authored, whose marker names a coding run this
+ * deployment recorded in that repository, are edited.
+ */
+export async function updateRelatedPullRequests(db, run, hosts, trackers) {
+    const host = hosts?.[CODING_CODE_PROVIDER];
+    if (!host?.replaceRelatedSection || !host.pullRequestOrigin)
+        return;
+    try {
+        // A run that delegated nothing has no request set of its own.
+        if (!(await db.run.findFirst({ where: { parentRunId: run.id }, select: { id: true } })))
+            return;
+        const group = await collectRelatedPullRequests(db, run.id);
+        if (group.pullRequests.length < 2)
+            return;
+        const live = [];
+        for (const pr of group.pullRequests) {
+            // A stored merged/closed state is final and such a PR is never edited: no host read.
+            if (pr.state === "merged" || pr.state === "closed") {
+                live.push({ repository: pr.repository, number: pr.number, state: pr.state });
+                continue;
+            }
+            try {
+                const origin = await host.pullRequestOrigin(pr.repository, pr.number);
+                const state = origin.merged
+                    ? "merged"
+                    : origin.state !== "open"
+                        ? "closed"
+                        : origin.draft
+                            ? "draft"
+                            : "open";
+                let markerRunId;
+                if (origin.markerRunId) {
+                    const opener = await db.codingRun.findUnique({
+                        where: { runId: origin.markerRunId },
+                        select: { repository: true },
+                    });
+                    if (opener && opener.repository.toLowerCase() === pr.repository)
+                        markerRunId = origin.markerRunId;
+                }
+                live.push({ repository: pr.repository, number: pr.number, state, ...(markerRunId ? { markerRunId } : {}) });
+            }
+            catch (err) {
+                log.warn({ err, runId: run.id, repository: pr.repository, number: pr.number }, "could not read a related pull request");
+                // The stored state (issue-recorded PRs) is better than none; never edited without a live read.
+                live.push({ repository: pr.repository, number: pr.number, ...(pr.state ? { state: pr.state } : {}) });
+            }
+        }
+        const issue = issueFor(group, trackers);
+        for (const target of live) {
+            if (!target.markerRunId || (target.state !== "open" && target.state !== "draft"))
+                continue;
+            const block = renderRelatedSection({
+                entries: live.map((pr) => ({
+                    repository: pr.repository,
+                    number: pr.number,
+                    ...(pr.state ? { state: pr.state } : {}),
+                    ...(pr === target ? { self: true } : {}),
+                })),
+                ...(issue ? { issue } : {}),
+            });
+            if (!block)
+                continue;
+            try {
+                const outcome = await host.replaceRelatedSection(target.repository, target.number, {
+                    expectedMarkerRunId: target.markerRunId,
+                    block,
+                });
+                log.info({ runId: run.id, repository: target.repository, number: target.number, outcome }, "related pull requests section");
+            }
+            catch (err) {
+                log.warn({ err, runId: run.id, repository: target.repository, number: target.number }, "could not update a related pull requests section");
+            }
+        }
+    }
+    catch (err) {
+        log.warn({ err, runId: run.id }, "could not update related pull requests");
+    }
+}
+/** Most open siblings hinted in one task. */
+export const MAX_SIBLING_HINTS = 10;
+const SAFE_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+/** Closes every sibling-hint block (mention and Jira alike). */
+export const SIBLING_GUIDANCE = "Continue the pull request you were asked about, and a listed open one only when the change requires it. " +
+    "Never open a new pull request in a repository that already has an open pull request listed here. Merged or " +
+    "closed pull requests are not listed: a change there needs a new pull request.";
+/**
+ * The group's pull requests a follow-up may continue: stored state "open", or
+ * no stored state yet (a same-tree sibling not recorded for an issue), minus
+ * `exclude` and malformed run ids. Stored state only: no host call. A hint for
+ * a PR that has closed since is refused by the continuation itself (git.ts).
+ */
+export function openSiblingsOf(group, exclude) {
+    const excluded = exclude ? `${safeRepository(exclude.repository) ?? ""}#${exclude.number}` : "";
+    return group.pullRequests
+        .filter((pr) => (pr.state === undefined || pr.state === "open") &&
+        `${pr.repository}#${pr.number}` !== excluded &&
+        SAFE_RUN_ID.test(pr.openedByRunId))
+        .slice(0, MAX_SIBLING_HINTS)
+        .map((pr) => ({ repository: pr.repository, number: pr.number, openedByRunId: pr.openedByRunId }));
+}
+/** Open siblings of the request `seedRunId` belongs to. Never throws. */
+export async function openSiblings(db, seedRunId, exclude) {
+    try {
+        return openSiblingsOf(await collectRelatedPullRequests(db, seedRunId), exclude);
+    }
+    catch (err) {
+        log.warn({ err, seedRunId }, "could not list open sibling pull requests; continuing without hints");
+        return [];
+    }
+}
+/**
+ * Open pull requests of a whole card: seeded from the newest pull request
+ * recorded for the issue (any agent), then the collector is scoped to this
+ * issue alone (never "every issue the tree touched") so a tree that happens
+ * to also carry another card's coding runs can't leak that card's pull
+ * requests into this one's hints. Never throws.
+ */
+export async function openSiblingsForIssue(db, issue) {
+    try {
+        const newest = await db.issuePullRequest.findMany({
+            where: { issueProvider: issue.provider, issueKey: issue.key, codeProvider: CODING_CODE_PROVIDER },
+            orderBy: { createdAt: "desc" },
+            take: 1,
+            select: { openedByRunId: true },
+        });
+        const seed = newest[0]?.openedByRunId;
+        if (!seed || !SAFE_RUN_ID.test(seed))
+            return [];
+        return openSiblingsOf(await collectRelatedPullRequests(db, seed, issue));
+    }
+    catch (err) {
+        log.warn({ err, issueKey: issue.key }, "could not list the issue's open pull requests; continuing without hints");
+        return [];
+    }
+}