@wardby/cli 0.6.0 → 0.7.0

package/dist/core/grants.js

@@ -4,13 +4,13 @@ export const LEVELS = {
     budget_group: ["read", "use", "write"],
 };
 /**
- * Highest level an "everyone" grant may carry: never write. Everyone-write
- * on an agent would bring back the old public-mutable model (anyone
- * rewriting the prompt of an agent that holds its owner's tools and
- * secrets). Also applied when a stored everyone row is read, so a row
- * written around grant_access can't exceed it either.
+ * Highest level an "everyone" grant may carry. Agents may be public-write
+ * (anyone signed in can edit them) but only while they hold none of their
+ * owner's bindings: see agentOwnerBindings and the guard in grant_access and
+ * the binding tools. Otherwise anyone could rewrite the prompt of an agent
+ * that holds its owner's secrets.
  */
-export const EVERYONE_MAX = { agent: "execute", tool: "use", budget_group: "use" };
+export const EVERYONE_MAX = { agent: "write", tool: "use", budget_group: "use" };
 /** Types grant_access/revoke_access accept today (Phase 1: agents only). */
 export const SHAREABLE_TYPES = ["agent"];
 export const EVERYONE_KEY = "everyone";
@@ -124,3 +124,52 @@ export async function deleteGrantsFor(db, type, resourceId) {
     const { count } = await db.resourceGrant.deleteMany({ where: { resourceType: type, resourceId } });
     return count;
 }
+/**
+ * The owner-only bindings an agent holds, by kind (empty = none). An agent
+ * may be public-write only while this is empty; binding a secret, datastore,
+ * repository, sub-agent or owner-granted tool capability to a public-write
+ * agent is refused for the same reason. A coding profile counts: its
+ * repository is the owner's GitHub access, and the prompt is part of every
+ * coding task.
+ */
+export async function agentOwnerBindings(db, agentId) {
+    const [secrets, datastores, repositories, subagents, capabilityTools, codingProfiles] = await Promise.all([
+        db.agentSecret.count({ where: { agentId } }),
+        db.agentDatastore.count({ where: { agentId } }),
+        db.agentRepository.count({ where: { agentId } }),
+        db.agentSubAgent.count({ where: { parentAgentId: agentId } }),
+        // The owner's attach_tool stamps its consent even when it grants nothing:
+        // only an attachment that carries a capability counts.
+        db.agentTool.count({
+            where: {
+                agentId,
+                capabilitiesGrantedById: { not: null },
+                NOT: {
+                    allowedSecrets: { equals: [] },
+                    allowedDatastorePrefixes: { equals: [] },
+                    allowedHosts: { equals: [] },
+                    allowedSharedDatastorePrefixes: { equals: {} },
+                },
+            },
+        }),
+        db.codingAgentProfile.count({ where: { agentId } }),
+    ]);
+    return Object.entries({
+        secrets,
+        datastores,
+        repositories,
+        "sub-agents": subagents,
+        "tool capabilities": capabilityTools,
+        "a coding repository": codingProfiles,
+    })
+        .filter(([, count]) => count > 0)
+        .map(([kind]) => kind);
+}
+/** True when everyone holds write on the agent. */
+export async function isPublicWritable(db, agentId) {
+    const row = await db.resourceGrant.findFirst({
+        where: { resourceType: "agent", resourceId: agentId, granteeKey: EVERYONE_KEY },
+        select: { level: true },
+    });
+    return row !== null && atLeast("agent", row.level, "write");
+}

package/dist/core/host-events.d.ts

@@ -13,7 +13,7 @@ import { type OpenSibling } from "./related-pull-requests.js";
 import { type RepoAccessGate } from "./repo-access.js";
 import { type DriftScope } from "../knowledge/relevance.js";
 export type { HostEvent };
-export type HostEventDb = Pick<PrismaClient, "agentRepository" | "deferredReview" | "agent" | "run" | "runHostCheck" | "runHostStatus" | "codingRun" | "task" | "webhook" | "budgetGroup" | "issuePullRequest" | "workItem" | "runAttribution" | "agentIssueProject" | "$transaction" | "$queryRaw">;
+export type HostEventDb = Pick<PrismaClient, "runBudgetEvent" | "agentRepository" | "deferredReview" | "agent" | "run" | "runHostCheck" | "runHostStatus" | "codingRun" | "registryFetch" | "registryAuditRecord" | "task" | "webhook" | "budgetGroup" | "issuePullRequest" | "workItem" | "runAttribution" | "agentIssueProject" | "$transaction" | "$queryRaw">;
 export interface RouteHostEventDeps {
     db: HostEventDb;
     executor: Executor;
@@ -24,6 +24,12 @@ export interface RouteHostEventDeps {
     repoAccess: RepoAccessGate;
     /** Issue trackers for moving/commenting on the issue a closed PR was opened for; absent → pr_closed is ignored. */
     issueTrackers?: IssueTrackerRegistry;
+    /**
+     * False (WARDBY_MENTION_EXPLANATIONS=false): a mention that starts nothing gets no
+     * reply saying why. The reply is a comment anyone who can see the repository reads,
+     * so a deployment may keep what is linked there to itself. Absent = true.
+     */
+    mentionExplanations?: boolean;
 }
 /** What starting a review needs: everything routing needs except the mention handle. */
 export type ReviewStartDeps = Omit<RouteHostEventDeps, "mentionHandle">;
@@ -38,6 +44,7 @@ export interface RouteResult {
     /** Cosmetic work to do after the webhook response is sent (reactions, status comments). */
     followUps: Array<() => Promise<void>>;
 }
+/** A `@app review` outside code: quoting the command in code documents it. */
 export declare function isReviewCommand(body: string, mentionHandle: string): boolean;
 type PushEvent = Extract<HostEvent, {
     kind: "push";
@@ -56,7 +63,7 @@ type ConceptCitationStatus = {
  * commits, so they and the affected concept paths travel as untrusted context.
  * Commit messages and author names are never included.
  */
-export declare function mergeTaskText(event: PushEvent, scope: DriftScope | null, bundleComplete?: boolean, citations?: ReadonlyMap<string, ConceptCitationStatus>): string;
+export declare function mergeTaskText(event: PushEvent, scope: DriftScope | null, bundleComplete?: boolean, citations?: ReadonlyMap<string, ConceptCitationStatus>, bundlePath?: string): string;
 type MentionEvent = Extract<HostEvent, {
     kind: "mention";
 }>;
@@ -83,7 +90,16 @@ export declare function siblingContinuationHints(siblings: readonly OpenSibling[
  * taskOverride column.
  */
 export declare function mentionTaskText(event: MentionEvent, siblings?: readonly OpenSibling[]): string;
+/** The reply to a mention whose author can see the repository but cannot push to it. */
+export declare const NO_WRITE_ACCESS_BODY: string;
 export declare function unknownPriorRunBody(priorRunId: string): string;
+/** Why a mention from someone allowed to use wardby started nothing; posted so they are not left guessing. */
+export type MentionDeclineReason = "no_responder" | "no_reviewer" | "agent_not_authorized" | "pull_request_not_reviewable";
+/**
+ * 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 declare function mentionDeclinedBody(reason: MentionDeclineReason): string;
 export interface ReviewTarget {
     agentId: string;
     checkName: string;

package/dist/core/host-events.js

@@ -6,16 +6,20 @@
  * docs/private/2026-09-25-code-review-host-design.md §6.3.
  */
 import { Prisma } from "#prisma";
-import { linkedPullRequestAttribution, openingRunAttribution, RESPONSE_PATH_SNAPSHOT_BUDGET } from "./attribution.js";
+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 { withoutMarkdownCode } from "./markdown-code.js";
+import { maybeMarkReady } from "./mark-ready.js";
 import { syncMergeOrderChecksForPullRequest } from "./merge-order-check.js";
-import { MAX_SIBLING_HINTS, openSiblings, runTreeRoot, SIBLING_GUIDANCE, } from "./related-pull-requests.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" });
@@ -31,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;
@@ -49,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${[
@@ -61,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)
@@ -76,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"}.`;
@@ -106,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;
@@ -306,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([
@@ -342,11 +378,49 @@ 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}).`;
@@ -457,6 +531,59 @@ context) {
     }
     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
@@ -492,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))) {
@@ -624,6 +761,22 @@ 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
@@ -641,6 +794,9 @@ 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 = [];
@@ -659,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) {
@@ -809,13 +969,36 @@ export async function requestLeadRunId(db, prMarkerRunId, repository) {
 }
 /** 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.
+ * 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). */
@@ -828,6 +1011,15 @@ 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");
@@ -1022,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.
@@ -1034,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();
@@ -1101,7 +1296,15 @@ export async function routeHostEvent(event, deps) {
             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 };
         }
@@ -1109,11 +1312,16 @@ export async function routeHostEvent(event, deps) {
             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);
@@ -1136,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,
@@ -1150,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],
@@ -1183,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,
@@ -1195,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) => {