@wardby/cli 0.5.3 → 0.7.0

package/dist/core/host-events.js

@@ -1,12 +1,25 @@
-import { linkedPullRequestAttribution, openingRunAttribution, RESPONSE_PATH_SNAPSHOT_BUDGET } from "./attribution.js";
+/**
+ * Host-neutral routing of code-review host events (GitHub App webhooks today)
+ * to the native agents linked to that repository. Adapters normalise their
+ * payloads into HostEvent (providers/review-host/github-events.ts); this
+ * module decides which agents run. See
+ * docs/private/2026-09-25-code-review-host-design.md §6.3.
+ */
+import { Prisma } from "#prisma";
+import { linkedPullRequestAttribution, openingRunAttribution, resolveWorkItem, RESPONSE_PATH_SNAPSHOT_BUDGET, } from "./attribution.js";
+import { headStoppedAtBudget, pushingRunInFlight } from "./budget-stopped-head.js";
 import { checkContinuation, dispatchRun } from "./dispatch.js";
 import { mentionStatusRow, postMentionStatus } from "./host-status.js";
-import { handlePullRequestClosed } from "./issue-bridge.js";
+import { githubIssueKey, handlePullRequestClosed } from "./issue-bridge.js";
 import { logger } from "./logger.js";
-import { MAX_SIBLING_HINTS, openSiblings, SIBLING_GUIDANCE } from "./related-pull-requests.js";
+import { withoutMarkdownCode } from "./markdown-code.js";
+import { maybeMarkReady } from "./mark-ready.js";
+import { syncMergeOrderChecksForPullRequest } from "./merge-order-check.js";
+import { MAX_SIBLING_HINTS, openPullRequestHints, openSiblings, openSiblingsForIssue, runTreeRoot, SIBLING_GUIDANCE, } from "./related-pull-requests.js";
 import { requiredLevel } from "./repo-access.js";
 import { composeTaskOverride } from "./untrusted-content.js";
 import { DEFAULT_KNOWLEDGE_BUNDLE_PATH, parseConcept, RESERVED_BUNDLE_FILES, } from "../knowledge/concept.js";
+import { KNOWLEDGE_CONFIG_MAX_BYTES, KNOWLEDGE_CONFIG_PATH, resolveKnowledgeLocation } from "../knowledge/location.js";
 import { driftScope } from "../knowledge/relevance.js";
 import { spanHash } from "../knowledge/span-hash.js";
 const log = logger.child({ module: "host-events" });
@@ -22,11 +35,14 @@ export const DEFERRED_REVIEW_BATCH = 50;
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/** A `@app review` outside code: quoting the command in code documents it. */
 export function isReviewCommand(body, mentionHandle) {
-    return new RegExp(`(^|[^\\w-])@${escapeRegExp(mentionHandle)}\\s+review(?![\\w-])`, "i").test(body);
+    return new RegExp(`(^|[^\\w-])@${escapeRegExp(mentionHandle)}\\s+review(?![\\w-])`, "i").test(withoutMarkdownCode(body));
 }
 const MAX_BUNDLE_FILES = 200;
 const BUNDLE_FILE_LINES = 2000;
+/** `.wardby/knowledge.yaml` is one short key; a longer read is refused as too large. */
+const KNOWLEDGE_CONFIG_MAX_LINES = 200;
 const MAX_LISTED_CHANGES = 200;
 /** The whole bundle load (listing plus reads) must finish inside GitHub's ~10 s webhook window. */
 const BUNDLE_LOAD_DEADLINE_MS = 4000;
@@ -40,7 +56,7 @@ const BUNDLE_INCOMPLETE_TEXT = "The knowledge bundle could not be fully read; tr
  * commits, so they and the affected concept paths travel as untrusted context.
  * Commit messages and author names are never included.
  */
-export function mergeTaskText(event, scope, bundleComplete = true, citations = new Map()) {
+export function mergeTaskText(event, scope, bundleComplete = true, citations = new Map(), bundlePath = DEFAULT_KNOWLEDGE_BUNDLE_PATH) {
     const statusOf = (concept) => citations.get(concept) ?? { state: "unverified" };
     const changed = event.changedPathsComplete
         ? `Changed files:\n${[
@@ -52,7 +68,7 @@ export function mergeTaskText(event, scope, bundleComplete = true, citations = n
         : "The changed-file list is incomplete (GitHub includes at most 2048 commits per push and the list is capped at 1000 paths); treat every knowledge concept as possibly affected.";
     const listed = scope
         ? `Knowledge concepts whose citations, affects globs, or files changed (${scope.reason}):\n` +
-            scope.concepts.map((p) => `- ${DEFAULT_KNOWLEDGE_BUNDLE_PATH}/${p} — ${describeStatus(statusOf(p))}`).join("\n")
+            scope.concepts.map((p) => `- ${bundlePath}/${p} — ${describeStatus(statusOf(p))}`).join("\n")
         : null;
     let context;
     if (!bundleComplete)
@@ -67,7 +83,7 @@ export function mergeTaskText(event, scope, bundleComplete = true, citations = n
     if (scope && scope.concepts.length > 0) {
         const states = scope.concepts.map((p) => statusOf(p).state);
         const count = (state) => states.filter((x) => x === state).length;
-        const onlyKnowledge = event.changedPathsComplete && event.changedPaths.every((p) => p.startsWith(`${DEFAULT_KNOWLEDGE_BUNDLE_PATH}/`));
+        const onlyKnowledge = event.changedPathsComplete && event.changedPaths.every((p) => p.startsWith(`${bundlePath}/`));
         summary =
             `Citation check at ${event.after.slice(0, 12)}: ${count("verified")} of ${states.length} affected concepts verified, ` +
                 `${count("stale")} stale, ${count("unverified")} not verified. Only knowledge files changed: ${onlyKnowledge ? "yes" : "no"}.`;
@@ -97,13 +113,36 @@ function startBudget(ms) {
     });
     return { promise, expired: () => expired, clear: () => clearTimeout(timer) };
 }
+/**
+ * `.wardby/knowledge.yaml` at the pushed commit, or null when it does not
+ * exist. Reads within the shared budget; a deadline or a host error throws,
+ * which resolveKnowledgeLocation turns into the default bundle with a warning.
+ */
+async function readKnowledgeConfig(host, event, budget) {
+    const read = await Promise.race([
+        host.readFile(event.repository, KNOWLEDGE_CONFIG_PATH, event.after, {
+            startLine: 1,
+            maxLines: KNOWLEDGE_CONFIG_MAX_LINES,
+        }),
+        budget.promise,
+    ]);
+    if (read === "deadline")
+        throw new Error("the read hit its deadline");
+    if (read.kind === "not_found")
+        return null;
+    if (read.kind !== "file")
+        throw new Error("it is not a file");
+    if (read.truncated || Buffer.byteLength(read.text, "utf8") > KNOWLEDGE_CONFIG_MAX_BYTES)
+        throw new Error(`it is larger than ${KNOWLEDGE_CONFIG_MAX_BYTES} bytes`);
+    return read.text;
+}
 /**
  * The knowledge bundle at the pushed commit, read with bounded concurrency
  * under one overall deadline. A failure never fails the route; it yields an
  * incomplete result so the watcher treats every concept as possibly affected.
  */
-async function loadBundle(host, event, budget) {
-    const prefix = `${DEFAULT_KNOWLEDGE_BUNDLE_PATH}/`;
+async function loadBundle(host, event, budget, bundlePath) {
+    const prefix = `${bundlePath}/`;
     const concepts = [];
     const where = { repository: event.repository, after: event.after };
     let filesRead = 0;
@@ -297,6 +336,12 @@ export function mentionTaskText(event, siblings = []) {
         if (hints)
             sections.push(hints);
     }
+    else if (!event.isPullRequest) {
+        // An issue mention: the issue's open wardby pull requests, worded as a Jira issue's are.
+        const hints = openPullRequestHints(siblings);
+        if (hints)
+            sections.push(hints);
+    }
     const title = event.subject?.title.replace(/\s+/g, " ").trim().slice(0, MAX_TITLE);
     const description = event.subject?.body.trim() ? event.subject.body.slice(0, MAX_TASK_BODY) : "";
     sections.push([
@@ -333,11 +378,54 @@ async function priorRunContinues(deps, event) {
     const check = await checkContinuation(deps.db, event.priorRunId, event.repository);
     return check.ok && check.root.pullRequestNumber === event.number;
 }
+/** The reply to a mention whose author can see the repository but cannot push to it. */
+export const NO_WRITE_ACCESS_BODY = "😕 I can't act on this: a mention starts work only for people with write access to this repository. " +
+    "Ask someone with write access to mention me instead.";
+/** Associations that mean the account holds a role on the repository, not just a view of a public one. */
+const ROLE_ASSOCIATIONS = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
+/**
+ * Whether a refused author should be told why. Triage is granted explicitly, so
+ * it always counts. GitHub reports `read` for every account on a public
+ * repository, so there `read` counts only with a role association; on a private
+ * repository `read` means the account was given access (a private organization
+ * member is labelled CONTRIBUTOR or NONE). Unknown facts stay silent.
+ */
+function explainsRefusal(level, event) {
+    if (level === "triage")
+        return true;
+    if (level !== "read")
+        return false;
+    return event.repositoryPrivate === true || ROLE_ASSOCIATIONS.has(event.authorAssociation ?? "");
+}
 export function unknownPriorRunBody(priorRunId) {
     return (`❌ I can't continue this pull request. Its description names wardby run \`${priorRunId}\`, but this wardby ` +
         "deployment has no record of that run opening this pull request (another wardby deployment may have opened it). " +
         "Ask the deployment that opened it, or make the change on this branch by hand.");
 }
+/**
+ * Never names the App's handle: this comment is posted by the App, and a
+ * body that mentioned it could be matched as a mention of itself.
+ */
+export function mentionDeclinedBody(reason) {
+    switch (reason) {
+        case "no_responder":
+            return (`ℹ️ I didn't start a run: no agent on this repository is set up to answer mentions. ` +
+                'An agent owner can link one with the `mention` trigger (`link_repository`, `triggers: ["mention"]`).');
+        case "no_reviewer":
+            return (`ℹ️ I didn't start a review: no reviewer agent is linked to this repository. ` +
+                "An agent owner can link one with the `pull_request` trigger and a `checkName` (`link_repository`).");
+        case "agent_not_authorized":
+            return ("ℹ️ I didn't start a run: the agent linked here can no longer use this repository. " +
+                "Its owner's GitHub account needs access to it again; they can re-authorize it or re-link the agent.");
+        case "pull_request_not_reviewable":
+            return "ℹ️ I didn't start a review: this pull request is closed or comes from a fork, and wardby reviews only open pull requests from branches of this repository.";
+    }
+}
+/** A review run's task: the head to review, plus any extra context its trigger adds. */
+export function reviewTaskText(repository, prNumber, headSha, context) {
+    const task = `Review pull request #${prNumber} in ${repository} (head ${headSha}).`;
+    return context ? composeTaskOverride(`${task}\n\n${context.task}`, context.untrustedContext) : task;
+}
 /** Run states that already cover a commit: a review of it is under way or done. */
 const COVERING_REVIEW_STATUSES = ["pending", "running", "succeeded"];
 /**
@@ -360,9 +448,16 @@ async function alreadyReviewed(deps, repository, prNumber, headSha, agentId) {
     });
     return prior !== null;
 }
-async function startReviews(deps, host, repository, prNumber, headSha, targets, 
+/** Starts one review run per target on a pull request head; returns the started run ids. */
+export async function startReviews(deps, host, repository, prNumber, headSha, targets, 
 /** True for automatic triggers; an explicit re-run or `@wardby review` always runs. */
-skipReviewedCommits = false) {
+skipReviewedCommits = false, 
+/**
+ * Extra context for this review: `task` (written by wardby, trusted) is appended to the
+ * review task; `untrustedContext` (anything a model or a person wrote) travels separately,
+ * delivered as data.
+ */
+context) {
     const runIds = [];
     // One lookup per PR, not per reviewer, and none at all when every reviewer
     // skips this commit: taken at the first actual dispatch.
@@ -404,7 +499,7 @@ skipReviewedCommits = false) {
                 selfDefects: { db: deps.db, issueTrackers: deps.issueTrackers },
                 agentId: target.agentId,
                 trigger: "host_event",
-                taskOverride: `Review pull request #${prNumber} in ${repository} (head ${headSha}).`,
+                taskOverride: reviewTaskText(repository, prNumber, headSha, context),
                 attribution: await linkedAttribution(),
                 afterPersist: checkId
                     ? async (tx, run) => {
@@ -436,6 +531,59 @@ skipReviewedCommits = false) {
     }
     return runIds;
 }
+async function budgetDraftDecision(deps, host, repository, prNumber, headSha, 
+/** The pull request's origin, when the caller already reads it once per event. */
+readOrigin) {
+    const review = { kind: "review" };
+    const read = readOrigin ?? (host.pullRequestOrigin ? () => host.pullRequestOrigin(repository, prNumber) : undefined);
+    if (!read)
+        return review;
+    try {
+        const origin = await read();
+        if (origin.draft !== true || !origin.markerRunId)
+            return review;
+        const runId = await pushingRunInFlight(deps.db, { markerRunId: origin.markerRunId, repository });
+        if (runId)
+            return { kind: "wait", runId: await pushingRunHold(deps.db, runId) };
+        const stopped = await headStoppedAtBudget(deps.db, {
+            markerRunId: origin.markerRunId,
+            repository,
+            prNumber,
+            headSha,
+        });
+        return stopped ? { kind: "skip" } : review;
+    }
+    catch (err) {
+        log.warn({ err, repository, prNumber }, "could not read the pull request's coding run; reviewing as usual");
+        return review;
+    }
+}
+/**
+ * Instead of reviewing a budget-stopped draft (budgetDraftDecision `skip`): completes a neutral
+ * check per reviewer. No review run, so no RunHostCheck and no fix round. A reviewer that already
+ * reviewed this commit (an explicit request) keeps that review's check: a neutral one over it
+ * would stand, unreviewed again, once the draft is marked ready (that automatic review skips a
+ * reviewed commit).
+ */
+async function postSkippedReviewChecks(deps, host, repository, prNumber, headSha, targets) {
+    log.info({ repository, prNumber, headSha, agentIds: targets.map((t) => t.agentId) }, "review skipped: the draft's last push stopped at its budget");
+    for (const target of targets) {
+        try {
+            if (await alreadyReviewed(deps, repository, prNumber, headSha, target.agentId))
+                continue;
+            const { checkId } = await host.startCheck(repository, { headSha, name: target.checkName });
+            await host.completeCheck(repository, {
+                checkId,
+                conclusion: "neutral",
+                title: "Skipped: stopped at its budget",
+                summary: "The last push came from a run that stopped at its budget before finishing. This draft is reviewed when the work continues or when it is marked ready for review.",
+            });
+        }
+        catch (err) {
+            log.warn({ err, repository, prNumber, agentId: target.agentId }, "could not post the skipped review check");
+        }
+    }
+}
 /**
  * CI finished on a pull request's head: re-runs, once per head, each review
  * that published only a COMMENT while CI there was still running or had not
@@ -471,6 +619,16 @@ async function rereviewAfterCi(deps, host, event, prNumber, reviewerLinks) {
         // Only reviewers still authorized are claimed, so a denied one keeps its chance for later.
         const allowed = await authorizedLinks(deps, event, reviewerLinks.filter((l) => waiting.some((r) => r.run.agentId === l.agentId)));
         const allowedIds = new Set(allowed.map((l) => l.agentId));
+        // Decided before the claim, so a re-review not started here is not used up.
+        const decision = await budgetDraftDecision(deps, host, event.repository, prNumber, event.headSha);
+        if (decision.kind === "wait") {
+            log.info({ repository: event.repository, prNumber, headSha: event.headSha, runId: decision.runId }, "CI finished: re-review held while the pull request's coding run is still running");
+            return [];
+        }
+        if (decision.kind === "skip") {
+            await postSkippedReviewChecks(deps, host, event.repository, prNumber, event.headSha, reviewTargets(allowed));
+            return [];
+        }
         // Claimed per row, so concurrent completions re-run each review only once.
         const agentIds = new Set();
         for (const row of waiting.filter((r) => allowedIds.has(r.run.agentId))) {
@@ -590,6 +748,7 @@ async function deferUntilCi(deps, host, key, links) {
                     prNumber: key.prNumber,
                     headSha: key.headSha,
                     agentId: { in: links.map((l) => l.agentId) },
+                    reason: "ci",
                 },
                 select: { id: true, agentId: true, checkName: true },
             });
@@ -602,12 +761,28 @@ async function deferUntilCi(deps, host, key, links) {
     }
     return { startNow: [], runIds };
 }
+/**
+ * Deferred rows whose pull request's coding run is still in flight (budgetDraftDecision `wait`):
+ * they now wait for that run, as for a delegating run (reason "request", leadRunId = the run),
+ * and are released when it finishes (startDeferredForRequest from its terminal hook, or the
+ * sweep). The run may have finished meanwhile, its release finding no row: released here then.
+ */
+async function waitForPushingRun(deps, key, rows, runId) {
+    const where = { repository: key.repository, prNumber: key.prNumber, headSha: key.headSha };
+    await deps.db.deferredReview.updateMany({
+        where: { id: { in: rows.map((r) => r.id) } },
+        data: { reason: "request", leadRunId: runId },
+    });
+    log.info({ ...where, runId }, "deferred review held while the pull request's coding run is still running");
+    const run = await deps.db.run.findUnique({ where: { id: runId }, select: { status: true } });
+    return !run || !RUN_NOT_FINISHED.has(run.status) ? releaseRequestRows(deps, runId, "request") : [];
+}
 /**
  * Starts deferred reviews for one PR head. The head must still be that sha,
  * open, and not a fork; otherwise every row is dropped (a newer push records
  * its own). Each row is claimed by deleting it, so a concurrent ci_completed
- * delivery or sweep starts each review only once. On `ci`, only reviewers
- * still authorized are claimed (the rest wait for the sweep); on `sweep` (the
+ * delivery or sweep starts each review only once. On `ci` and `request`, only
+ * reviewers still authorized are claimed (the rest wait for the sweep); on `sweep` (the
  * last attempt) every row is claimed and unauthorized or unlinked reviewers
  * are dropped.
  */
@@ -619,11 +794,14 @@ async function startDeferred(deps, host, key, rows, reviewerLinks, mode, reason)
         log.info({ ...where, state: head.state }, "deferred review dropped: the pull request moved on or closed");
         return [];
     }
+    const decision = await budgetDraftDecision(deps, host, key.repository, key.prNumber, key.headSha);
+    if (decision.kind === "wait")
+        return waitForPushingRun(deps, key, rows, decision.runId);
     const allowed = await authorizedLinks(deps, key, reviewerLinks.filter((l) => rows.some((r) => r.agentId === l.agentId)));
     const allowedIds = new Set(allowed.map((l) => l.agentId));
     const targets = [];
     for (const row of rows) {
-        if (mode === "ci" && !allowedIds.has(row.agentId))
+        if (mode !== "sweep" && !allowedIds.has(row.agentId))
             continue;
         const claimed = await deps.db.deferredReview.deleteMany({ where: { id: row.id } });
         if (claimed.count !== 1)
@@ -637,6 +815,10 @@ async function startDeferred(deps, host, key, rows, reviewerLinks, mode, reason)
         return [];
     log.info({ ...where, agentIds: targets.map((t) => t.agentId), reason }, "starting the deferred review");
     try {
+        if (decision.kind === "skip") {
+            await postSkippedReviewChecks(deps, host, key.repository, key.prNumber, key.headSha, targets);
+            return [];
+        }
         return await startReviews(deps, host, key.repository, key.prNumber, key.headSha, targets, true);
     }
     catch (err) {
@@ -647,14 +829,16 @@ async function startDeferred(deps, host, key, rows, reviewerLinks, mode, reason)
 }
 /**
  * ci_completed: starts the reviews deferred on this head (see deferUntilCi),
- * unless CI there is still pending (a later completion decides). Never
+ * unless CI there is still pending (a later completion decides). Rows still
+ * waiting for their delegating run (reason "request") are not CI's to start:
+ * startDeferredForRequest hands them over once that run is terminal. Never
  * throws; a failure is logged and the rows stay for the reconciler sweep.
  */
 async function startDeferredAfterCi(deps, host, event, prNumber, reviewerLinks) {
     try {
         const key = { provider: event.provider, repository: event.repository, prNumber, headSha: event.headSha };
         const rows = await deps.db.deferredReview.findMany({
-            where: key,
+            where: { ...key, reason: "ci" },
             select: { id: true, agentId: true, checkName: true },
         });
         if (rows.length === 0)
@@ -676,9 +860,21 @@ async function startDeferredAfterCi(deps, host, event, prNumber, reviewerLinks)
  * DEFERRED_REVIEW_MAX_AGE_MS, and starts (regardless of CI) those waiting
  * longer than DEFERRED_REVIEW_MAX_WAIT_MS, at most DEFERRED_REVIEW_BATCH per
  * pass, oldest first. Covers CI that never reported, ran very long, or whose
- * completion webhook was missed. Never throws; returns the runs started.
+ * completion webhook was missed. Rows waiting for a delegating run (reason
+ * "request") are released the same way once they are that old, but only when
+ * that run is terminal (or gone): a lead the reconciler marked lost never
+ * reaches its finalizer. Never throws; returns the runs started.
  */
 export async function startDeferredReviews(deps, now = new Date()) {
+    const providers = Object.keys(deps.hosts);
+    const runIds = await sweepCiRows(deps, providers, now);
+    // Outside the CI half's try: a failure there never keeps request rows from being released.
+    if (providers.length > 0)
+        runIds.push(...(await sweepRequestRows(deps, providers, now)));
+    return runIds;
+}
+/** The sweep's half for expiry and CI rows: drops rows past the max age, then starts CI rows past the max wait. */
+async function sweepCiRows(deps, providers, now) {
     const runIds = [];
     try {
         const expired = await deps.db.deferredReview.deleteMany({
@@ -686,12 +882,12 @@ export async function startDeferredReviews(deps, now = new Date()) {
         });
         if (expired.count > 0)
             log.info({ count: expired.count }, "dropped deferred reviews older than 24 h");
-        const providers = Object.keys(deps.hosts);
         if (providers.length === 0)
             return runIds;
         const due = await deps.db.deferredReview.findMany({
             where: {
                 provider: { in: providers },
+                reason: "ci",
                 createdAt: { lte: new Date(now.getTime() - DEFERRED_REVIEW_MAX_WAIT_MS) },
             },
             select: {
@@ -732,6 +928,246 @@ export async function startDeferredReviews(deps, now = new Date()) {
     }
     return runIds;
 }
+/** The sweep's half for request rows: releases those older than the max wait whose delegating run is terminal or gone. */
+async function sweepRequestRows(deps, providers, now) {
+    const runIds = [];
+    try {
+        // Joined in the query, so leads still running never fill the batch ahead of finished ones.
+        const leads = await deps.db.$queryRaw `
+      SELECT DISTINCT d."leadRunId"
+      FROM "DeferredReview" d
+      LEFT JOIN "Run" r ON r."id" = d."leadRunId"
+      WHERE d."reason" = 'request'
+        AND d."leadRunId" IS NOT NULL
+        AND d."provider" IN (${Prisma.join(providers)})
+        AND d."createdAt" <= ${new Date(now.getTime() - DEFERRED_REVIEW_MAX_WAIT_MS)}
+        AND (r."id" IS NULL OR r."status"::text NOT IN ('pending', 'running'))
+      LIMIT ${DEFERRED_REVIEW_BATCH}`;
+        for (const { leadRunId } of leads)
+            runIds.push(...(await releaseRequestRows(deps, leadRunId, "sweep")));
+    }
+    catch (err) {
+        log.warn({ err }, "deferred review sweep failed for reviews waiting on a delegating run");
+    }
+    return runIds;
+}
+/**
+ * The run whose finish a review of this pull request waits for: the root of
+ * the run tree when the PR's opening coding run was delegated (it has a
+ * parent run) and that root is not terminal yet; otherwise null (a
+ * non-delegated coding PR, a finished request, or an unknown marker). A lead's
+ * delegate_to_* calls block until each child is terminal, so a terminal root
+ * means every sibling coding run of the request has finished and opened its
+ * pull request. A continuation's marker resolves to its root coding run, then
+ * up that run's parents. `repository`, when given, must be the coding run's.
+ */
+export async function requestLeadRunId(db, prMarkerRunId, repository) {
+    const root = await runTreeRoot(db, prMarkerRunId, repository);
+    if (!root || root.isOpener || !RUN_NOT_FINISHED.has(root.status))
+        return null;
+    return root.id;
+}
+/** Run statuses that mean the delegating run has not finished. */
+const RUN_NOT_FINISHED = new Set(["pending", "running"]);
+/**
+ * The run a draft's review waits for while its coding run `pushingRunId` may still be pushing:
+ * that run's top-level lead while the lead is pending or running, else the coding run itself.
+ * A follow-up's lead is not the one requestLeadRunId finds (that walks up from the pull
+ * request's opening run), yet the review should still wait for the whole request (#259); and
+ * the lead's finalizer releases it outside every workflow step, where the coding run's own
+ * terminal hook, inside the lead's delegation step, could not start a review run.
+ */
+async function pushingRunHold(db, pushingRunId) {
+    // UNION, not UNION ALL: a parentRunId cycle (never written, but not a constraint) can't recurse forever.
+    const rows = await db.$queryRaw `
+    WITH RECURSIVE up AS (
+      SELECT r."id", r."parentRunId", r."status"::text AS "status" FROM "Run" r WHERE r."id" = ${pushingRunId}
+      UNION
+      SELECT p."id", p."parentRunId", p."status"::text FROM "Run" p JOIN up u ON p."id" = u."parentRunId"
+    )
+    SELECT u."id", u."status" FROM up u WHERE u."parentRunId" IS NULL LIMIT 1`;
+    const root = rows[0];
+    return root && root.id !== pushingRunId && RUN_NOT_FINISHED.has(root.status) ? root.id : pushingRunId;
+}
+/**
+ * pr_updated for a pull request a delegated coding run opened, while the
+ * request's lead run is still running: records one DeferredReview row per
+ * reviewer (reason "request", with or without waitForCi) and starts nothing;
+ * the lead's finalizer (startDeferredForRequest) or the sweep starts them.
+ * Returns null, to review as without it, for any other pull request, or when
+ * the lead cannot be resolved or the deferral cannot be recorded. A draft whose
+ * own coding run (root or continuation) is still in flight waits for that run
+ * the same way: it may have pushed this head before recording whether it
+ * stopped at its budget (budgetDraftDecision); its terminal hook releases them.
+ */
+async function deferUntilRequest(deps, host, key, links, 
+/** The pull request's origin, read at most once per event (shared with the merge order check). */
+readOrigin) {
+    if (links.length === 0 || !readOrigin)
+        return null;
+    let leadRunId;
+    try {
+        const origin = await readOrigin();
+        if (!origin.markerRunId)
+            return null;
+        leadRunId = await requestLeadRunId(deps.db, origin.markerRunId, key.repository);
+        // A draft's own coding run still in flight may have pushed this head before recording its
+        // result (a stop at its budget among them): wait for it the same way (budgetDraftDecision).
+        if (!leadRunId && origin.draft === true) {
+            const pushing = await pushingRunInFlight(deps.db, {
+                markerRunId: origin.markerRunId,
+                repository: key.repository,
+            });
+            leadRunId = pushing && (await pushingRunHold(deps.db, pushing));
+        }
+    }
+    catch (err) {
+        log.warn({ err, repository: key.repository, prNumber: key.prNumber }, "could not read the pull request's delegating run; reviewing as usual");
+        return null;
+    }
+    if (!leadRunId)
+        return null;
+    const head = { provider: key.provider, repository: key.repository, prNumber: key.prNumber, headSha: key.headSha };
+    try {
+        // Idempotent per head and reviewer, like deferUntilCi.
+        await deps.db.deferredReview.createMany({
+            data: links.map((l) => ({ ...head, agentId: l.agentId, checkName: l.checkName, reason: "request", leadRunId })),
+            skipDuplicates: true,
+        });
+        // A row this head already had for CI waits for the request too: released only when both are done.
+        await deps.db.deferredReview.updateMany({
+            where: { ...head, agentId: { in: links.map((l) => l.agentId) }, reason: "ci" },
+            data: { reason: "request", leadRunId },
+        });
+    }
+    catch (err) {
+        log.warn({ err, repository: key.repository, prNumber: key.prNumber }, "could not record the deferred review; reviewing as usual");
+        return null;
+    }
+    log.info({ ...head, leadRunId, agentIds: links.map((l) => l.agentId) }, "review deferred until the delegating run finishes");
+    // The lead may have finished between the lookup and the insert, its
+    // finalizer finding no row yet: check once more (rows are claimed by
+    // delete, so a racing finalizer starts each review once). A failure leaves
+    // the rows for the sweep.
+    const runIds = [];
+    try {
+        const lead = await deps.db.run.findUnique({ where: { id: leadRunId }, select: { status: true } });
+        if (!lead || !RUN_NOT_FINISHED.has(lead.status)) {
+            runIds.push(...(await releaseRequestRows(deps, leadRunId, "request")));
+        }
+    }
+    catch (err) {
+        log.warn({ err, repository: key.repository, prNumber: key.prNumber, leadRunId }, "could not re-check the delegating run after deferring; the sweep starts the review");
+    }
+    return { runIds };
+}
+/**
+ * The delegating run `leadRunId` is terminal (it succeeded, failed, or was
+ * cancelled): releases every review that waited for it. A reviewer linked
+ * with waitForCi whose head's CI is still pending is handed to CI (the row
+ * becomes reason "ci", its max wait counted from now); every other row is
+ * started (claimed by delete, so concurrent releases start each review once).
+ * Called from the lead's finalizer, after the related pull requests sections
+ * were rewritten. Never throws.
+ */
+export async function startDeferredForRequest(deps, leadRunId) {
+    try {
+        await releaseRequestRows(deps, leadRunId, "request");
+    }
+    catch (err) {
+        log.warn({ err, leadRunId }, "could not start the reviews waiting for the delegating run");
+    }
+}
+async function releaseRequestRows(deps, leadRunId, mode) {
+    const rows = await deps.db.deferredReview.findMany({
+        where: { leadRunId, reason: "request" },
+        select: {
+            id: true,
+            provider: true,
+            repository: true,
+            prNumber: true,
+            headSha: true,
+            agentId: true,
+            checkName: true,
+        },
+        orderBy: { createdAt: "asc" },
+    });
+    const groups = new Map();
+    for (const row of rows) {
+        const id = JSON.stringify([row.provider, row.repository, row.prNumber, row.headSha]);
+        groups.set(id, [...(groups.get(id) ?? []), row]);
+    }
+    const runIds = [];
+    for (const group of groups.values()) {
+        const first = group[0];
+        const provider = first.provider;
+        const key = { provider, repository: first.repository, prNumber: first.prNumber, headSha: first.headSha };
+        const host = deps.hosts[provider];
+        if (!host)
+            continue;
+        try {
+            const reviewerLinks = (await loadLinks(deps, provider, key.repository)).filter(isReviewerLink);
+            runIds.push(...(await releaseRequestHead(deps, host, key, group, reviewerLinks, mode)));
+        }
+        catch (err) {
+            log.warn({ err, repository: key.repository, prNumber: key.prNumber, leadRunId }, "could not start a review waiting for the delegating run");
+        }
+    }
+    return runIds;
+}
+/** One head's request rows: hands waitForCi rows with CI still pending to CI, starts the rest. */
+async function releaseRequestHead(deps, host, key, rows, reviewerLinks, mode) {
+    const waitsForCi = new Set(reviewerLinks.filter((l) => l.waitForCi).map((l) => l.agentId));
+    let ciRows = rows.filter((r) => waitsForCi.has(r.agentId));
+    if (ciRows.length > 0 && host.readCi) {
+        let state;
+        try {
+            state = (await host.readCi(key.repository, key.headSha)).state;
+        }
+        catch (err) {
+            log.warn({ err, repository: key.repository, prNumber: key.prNumber }, "could not read CI; reviewing now");
+        }
+        if (state === undefined || !CI_NOT_FINISHED_ON_PUSH.has(state))
+            ciRows = [];
+    }
+    else
+        ciRows = [];
+    const startNow = rows.filter((r) => !ciRows.includes(r));
+    const runIds = startNow.length > 0
+        ? await startDeferred(deps, host, key, startNow, reviewerLinks, mode, "the delegating run finished")
+        : [];
+    if (ciRows.length === 0 || !host.readCi)
+        return runIds;
+    const ids = ciRows.map((r) => r.id);
+    // Only a row still waiting for the request flips: a concurrent release that claimed it already started it.
+    await deps.db.deferredReview.updateMany({
+        where: { id: { in: ids }, reason: "request" },
+        data: { reason: "ci", createdAt: new Date() },
+    });
+    log.info({
+        repository: key.repository,
+        prNumber: key.prNumber,
+        headSha: key.headSha,
+        agentIds: ciRows.map((r) => r.agentId),
+    }, "the delegating run finished; review deferred until CI finishes");
+    // As in deferUntilCi: CI may have finished before the flip, its ci_completed skipping the request row.
+    try {
+        const again = (await host.readCi(key.repository, key.headSha)).state;
+        if (!CI_NOT_FINISHED_ON_PUSH.has(again)) {
+            const handed = await deps.db.deferredReview.findMany({
+                where: { id: { in: ids }, reason: "ci" },
+                select: { id: true, agentId: true, checkName: true },
+            });
+            if (handed.length > 0) {
+                runIds.push(...(await startDeferred(deps, host, key, handed, reviewerLinks, "ci", "CI finished")));
+            }
+        }
+    }
+    catch (err) {
+        log.warn({ err, repository: key.repository, prNumber: key.prNumber }, "could not re-read CI after the delegating run finished; the sweep starts the review");
+    }
+    return runIds;
+}
 export async function routeHostEvent(event, deps) {
     const none = { runIds: [], followUps: [] };
     if (event.kind === "pr_closed") {
@@ -742,7 +1178,18 @@ export async function routeHostEvent(event, deps) {
             number: event.prNumber,
             merged: event.merged,
         });
-        return none;
+        // The merge order checks of the sets this PR is a step of, after the response. Never throws.
+        if (!deps.hosts[event.provider]?.upsertNamedCheck)
+            return none;
+        const pr = { repository: event.repository, number: event.prNumber };
+        return {
+            runIds: [],
+            followUps: [
+                () => syncMergeOrderChecksForPullRequest(deps, pr, {
+                    closed: { ...pr, merged: event.merged },
+                }),
+            ],
+        };
     }
     const host = deps.hosts[event.provider];
     if (!host)
@@ -767,11 +1214,14 @@ export async function routeHostEvent(event, deps) {
             const budget = startBudget(BUNDLE_LOAD_DEADLINE_MS);
             let taskOverride;
             try {
-                const { concepts, complete } = await loadBundle(host, event, budget);
+                const { bundlePath, warning } = await resolveKnowledgeLocation(() => readKnowledgeConfig(host, event, budget));
+                if (warning)
+                    log.warn({ repository: event.repository, after: event.after }, warning);
+                const { concepts, complete } = await loadBundle(host, event, budget, bundlePath);
                 const scope = driftScope({
                     changedPaths: event.changedPaths,
                     changedPathsComplete: event.changedPathsComplete,
-                    bundlePath: DEFAULT_KNOWLEDGE_BUNDLE_PATH,
+                    bundlePath,
                     concepts,
                 });
                 // Only the concepts the merge affects are checked, and only against a bundle that was fully read.
@@ -779,7 +1229,7 @@ export async function routeHostEvent(event, deps) {
                 const citations = complete
                     ? await verifyCitations(host, event, concepts.filter((c) => affected.has(c.path)), budget)
                     : new Map();
-                taskOverride = mergeTaskText(event, scope, complete, citations);
+                taskOverride = mergeTaskText(event, scope, complete, citations, bundlePath);
             }
             finally {
                 budget.clear();
@@ -816,30 +1266,62 @@ export async function routeHostEvent(event, deps) {
             return { runIds, followUps: [] };
         }
         case "pr_updated": {
-            if (event.isFork || reviewerLinks.length === 0)
+            if (event.isFork)
                 return none;
+            // Read at most once per event, by the request deferral and the merge order check alike.
+            let origin;
+            const readOrigin = host.pullRequestOrigin
+                ? () => (origin ??= host.pullRequestOrigin(event.repository, event.prNumber))
+                : undefined;
+            // A new head needs the merge order check re-posted (check runs are per commit), on every
+            // path below, a review held for the delegating run included. After the response; never throws.
+            const followUps = host.upsertNamedCheck && readOrigin
+                ? [
+                    () => syncMergeOrderChecksForPullRequest(deps, { repository: event.repository, number: event.prNumber }, { origin: { repository: event.repository, number: event.prNumber, read: readOrigin } }),
+                ]
+                : [];
+            if (reviewerLinks.length === 0)
+                return { runIds: [], followUps };
             const allowed = await authorizedLinks(deps, event, reviewerLinks);
             if (allowed.length === 0)
-                return none;
+                return { runIds: [], followUps };
+            // A PR a delegated coding run opened is reviewed once the whole request
+            // finished, so its sibling PRs exist and the related section is current (#259).
+            const request = await deferUntilRequest(deps, host, event, allowed, readOrigin);
+            if (request)
+                return { runIds: request.runIds, followUps };
             // Reviewers linked with waitForCi review this head only once its CI finished.
             const deferral = await deferUntilCi(deps, host, event, allowed.filter((l) => l.waitForCi));
             const startNow = new Set(deferral.startNow);
             const reviewers = reviewTargets(allowed.filter((l) => !l.waitForCi || startNow.has(l)));
             const runIds = [...deferral.runIds];
             if (reviewers.length > 0) {
-                runIds.push(...(await startReviews(deps, host, event.repository, event.prNumber, event.headSha, reviewers, true)));
+                // A coding run still in flight was already waited for (deferUntilRequest); should
+                // recording that have failed, the head is reviewed as usual.
+                const decision = await budgetDraftDecision(deps, host, event.repository, event.prNumber, event.headSha, readOrigin);
+                if (decision.kind === "skip") {
+                    await postSkippedReviewChecks(deps, host, event.repository, event.prNumber, event.headSha, reviewers);
+                }
+                else {
+                    runIds.push(...(await startReviews(deps, host, event.repository, event.prNumber, event.headSha, reviewers, true)));
+                }
             }
-            return { runIds, followUps: [] };
+            return { runIds, followUps };
         }
         case "ci_completed": {
             if (reviewerLinks.length === 0)
                 return none;
             const runIds = [];
+            // CI going green may be the last thing a pull request waited for (#287); evaluated
+            // after the response (a host read per PR could otherwise exceed the webhook timeout).
+            const followUps = event.prNumbers.map((prNumber) => async () => {
+                await maybeMarkReady({ db: deps.db, hosts: deps.hosts, log }, event.repository, prNumber, event.provider);
+            });
             for (const prNumber of event.prNumbers) {
                 runIds.push(...(await rereviewAfterCi(deps, host, event, prNumber, reviewerLinks)));
                 runIds.push(...(await startDeferredAfterCi(deps, host, event, prNumber, reviewerLinks)));
             }
-            return { runIds, followUps: [] };
+            return { runIds, followUps };
         }
         case "check_rerun": {
             const owners = reviewerLinks.filter((l) => l.checkName === event.checkName);
@@ -862,12 +1344,15 @@ export async function routeHostEvent(event, deps) {
             const reviewCommand = event.isPullRequest && isReviewCommand(event.body, deps.mentionHandle);
             const responderLink = links.find((l) => l.access === "write" && l.triggers.includes("mention"));
             const candidates = reviewCommand ? reviewerLinks : responderLink ? [responderLink] : [];
-            if (candidates.length === 0)
+            // Explanations off and nothing to start: say nothing, and skip the author lookup.
+            if (candidates.length === 0 && deps.mentionExplanations === false)
                 return none;
             // H5-3: a mention drives a write-capable agent holding its owner's
             // tools and secrets, so its author needs real push access to the
             // repository (author_association, checked upstream, is only a
-            // pre-filter). Checked by the author's immutable id.
+            // pre-filter). Checked by the author's immutable id. Checked before
+            // anything is said back: someone without write access gets no reply at
+            // all, so a mention can never be used to probe what is linked here.
             const author = await deps.repoAccess.authorizeHostUser({
                 provider: event.provider,
                 repository: event.repository,
@@ -876,15 +1361,54 @@ export async function routeHostEvent(event, deps) {
             });
             if (!author.ok) {
                 log.info({ repository: event.repository, number: event.number, reason: author.reason, level: author.level }, "mention ignored: its author lacks write access");
-                return none;
+                // Someone who can read the repository gets told why; a stranger on a public repository (GitHub reports `read` for everyone) learns nothing.
+                if (author.reason !== "insufficient_permission" || !explainsRefusal(author.level, event)) {
+                    return none;
+                }
+                const refuse = async () => {
+                    await host.acknowledge(event.repository, event.comment, "refused").catch((err) => {
+                        log.warn({ err, repository: event.repository, number: event.number }, "could not add the reaction");
+                    });
+                    await host
+                        .comment(event.repository, {
+                        number: event.number,
+                        body: NO_WRITE_ACCESS_BODY,
+                        ...(event.replyToReviewCommentId ? { replyToReviewCommentId: event.replyToReviewCommentId } : {}),
+                    })
+                        .catch((err) => {
+                        log.warn({ err, repository: event.repository, number: event.number }, "could not post the refusal");
+                    });
+                };
+                return { runIds: [], followUps: [refuse] };
             }
+            // The author may use wardby here, so tell them why nothing started
+            // instead of leaving the mention unanswered.
+            const decline = (reason) => {
+                log.info({ repository: event.repository, number: event.number, reason }, "mention declined");
+                if (deps.mentionExplanations === false)
+                    return none;
+                const reply = async () => {
+                    await host
+                        .comment(event.repository, {
+                        number: event.number,
+                        body: mentionDeclinedBody(reason),
+                        ...(event.replyToReviewCommentId ? { replyToReviewCommentId: event.replyToReviewCommentId } : {}),
+                    })
+                        .catch((err) => {
+                        log.warn({ err, repository: event.repository, number: event.number }, "could not post the explanation");
+                    });
+                };
+                return { runIds: [], followUps: [reply] };
+            };
+            if (candidates.length === 0)
+                return decline(reviewCommand ? "no_reviewer" : "no_responder");
             const allowed = await authorizedLinks(deps, event, candidates);
             if (allowed.length === 0)
-                return none;
+                return decline("agent_not_authorized");
             if (reviewCommand) {
                 const head = await host.pullRequestHead(event.repository, event.number);
                 if (head.isFork || head.state !== "open")
-                    return none;
+                    return decline("pull_request_not_reviewable");
                 return {
                     runIds: await startReviews(deps, host, event.repository, event.number, head.headSha, reviewTargets(allowed)),
                     followUps: [react],
@@ -909,9 +1433,15 @@ export async function routeHostEvent(event, deps) {
                 return { runIds: [], followUps: [react, reply] };
             }
             // Seeded from the PR's validated marker run: the request it belongs to. Stored state only.
-            const siblings = event.isPullRequest && event.priorRunId
-                ? await openSiblings(deps.db, event.priorRunId, { repository: event.repository, number: event.number })
-                : [];
+            // An issue mention is seeded from the issue's recorded pull requests instead.
+            const siblings = event.isPullRequest
+                ? event.priorRunId
+                    ? await openSiblings(deps.db, event.priorRunId, { repository: event.repository, number: event.number })
+                    : []
+                : await openSiblingsForIssue(deps.db, {
+                    provider: "github",
+                    key: githubIssueKey(event.repository, event.number),
+                });
             const dispatched = await dispatchRun({
                 db: deps.db,
                 executor: deps.executor,
@@ -921,7 +1451,11 @@ export async function routeHostEvent(event, deps) {
                 taskOverride: mentionTaskText(event, siblings),
                 attribution: event.isPullRequest
                     ? await linkedPullRequestAttribution(deps.db, deps.issueTrackers, { codeProvider: host.provider, repository: event.repository, number: event.number }, RESPONSE_PATH_SNAPSHOT_BUDGET)
-                    : undefined,
+                    : // A mention on an issue is that issue's own run tree, like a Jira issue event's.
+                        {
+                            source: "issue_event",
+                            item: await resolveWorkItem(deps.db, deps.issueTrackers, "github", githubIssueKey(event.repository, event.number), RESPONSE_PATH_SNAPSHOT_BUDGET),
+                        },
                 // Where to report, written with the run: even if this instance dies
                 // before the follow-up below, the run's outcome still gets a comment.
                 afterPersist: async (tx, run) => {