@wardby/cli 0.2.1 → 0.4.0

package/dist/core/host-identity-links.js

@@ -0,0 +1,189 @@
+/**
+ * Linking a wardby principal to its verified host identity (GitHub today).
+ *
+ *  1. startHostIdentityLink: a single-use OAuth state and a PKCE verifier are
+ *     stored (the state only as a hash) for 10 minutes; the caller gets the
+ *     host's authorize URL.
+ *  2. completeHostIdentityCallback: the host redirects the browser back with
+ *     the state; it is consumed atomically, the code is exchanged (the user
+ *     token is revoked at once by the authorizer), and a one-time
+ *     confirmation code is shown to the person in the browser.
+ *  3. confirmHostIdentityLink: the SAME principal that started the link
+ *     submits the code (at most 5 tries). Only then is the identity stored.
+ *
+ * Step 3 is what stops an attacker from sending a victim their own authorize
+ * URL: the host skips its consent screen for users who already authorized the
+ * App, so one click would otherwise bind the victim's identity to the
+ * attacker's principal. The code is shown only in the victim's browser.
+ * A host user belongs to at most one principal.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { Prisma } from "#prisma";
+import { logger } from "./logger.js";
+const log = logger.child({ module: "host-identity-links" });
+export const HOST_LINK_TTL_MS = 10 * 60_000;
+export const HOST_LINK_MAX_ATTEMPTS = 5;
+export const HOST_LINK_MAX_PENDING = 5;
+const BASE32 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+const CODE_LENGTH = 8;
+export class HostLinkError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "HostLinkError";
+    }
+}
+/** The browser callback a provider's link flow returns to (registered as the App's Callback URL). */
+export function userCallbackPath(provider) {
+    return `/hosts/${provider}/user-callback`;
+}
+function sha256(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function confirmationCode() {
+    // 5 bits per character from a uniformly random byte's low bits (256 % 32 === 0: no bias).
+    return [...randomBytes(CODE_LENGTH)].map((b) => BASE32[b & 31]).join("");
+}
+export async function startHostIdentityLink(input) {
+    const now = input.now ?? new Date();
+    const provider = input.authorizer.provider;
+    await input.db.hostIdentityLinkRequest.deleteMany({ where: { expiresAt: { lte: now } } });
+    const pending = await input.db.hostIdentityLinkRequest.count({
+        where: { principalId: input.principalId, provider },
+    });
+    if (pending >= HOST_LINK_MAX_PENDING) {
+        throw new HostLinkError(429, "Too many account links in progress; finish one or wait 10 minutes.");
+    }
+    const state = randomBytes(32).toString("base64url");
+    const codeVerifier = randomBytes(32).toString("base64url");
+    const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
+    const expiresAt = new Date(now.getTime() + HOST_LINK_TTL_MS);
+    await input.db.hostIdentityLinkRequest.create({
+        data: { principalId: input.principalId, provider, stateHash: sha256(state), codeVerifier, expiresAt },
+    });
+    return {
+        authorizeUrl: input.authorizer.authorizeUrl({ state, codeChallenge, redirectUri: input.redirectUri }),
+        expiresAt,
+    };
+}
+export async function completeHostIdentityCallback(input) {
+    const now = input.now ?? new Date();
+    if (!input.state || !input.code || input.state.length > 256 || input.code.length > 256)
+        return { kind: "invalid" };
+    const stateHash = sha256(input.state);
+    // Single use: only the first callback for a live state wins.
+    const { count } = await input.db.hostIdentityLinkRequest.updateMany({
+        where: { stateHash, provider: input.authorizer.provider, callbackAt: null, expiresAt: { gt: now } },
+        data: { callbackAt: now },
+    });
+    if (count !== 1)
+        return { kind: "invalid" };
+    const request = await input.db.hostIdentityLinkRequest.findUnique({
+        where: { stateHash },
+        include: { principal: { select: { subject: true } } },
+    });
+    if (!request)
+        return { kind: "invalid" };
+    let user;
+    try {
+        user = await input.authorizer.complete({
+            code: input.code,
+            codeVerifier: request.codeVerifier,
+            redirectUri: input.redirectUri,
+        });
+    }
+    catch (err) {
+        log.warn({ err, provider: request.provider }, "host account link: the host refused the authorization");
+        await input.db.hostIdentityLinkRequest.delete({ where: { id: request.id } }).catch(() => undefined);
+        return { kind: "failed" };
+    }
+    const code = confirmationCode();
+    await input.db.hostIdentityLinkRequest.update({
+        where: { id: request.id },
+        // The verifier has done its job; keep nothing reusable.
+        data: { hostUserId: user.hostUserId, login: user.login, confirmHash: sha256(code), codeVerifier: "" },
+    });
+    return {
+        kind: "confirm",
+        code: `${code.slice(0, 4)}-${code.slice(4)}`,
+        login: user.login,
+        subject: request.principal.subject,
+    };
+}
+export async function confirmHostIdentityLink(input) {
+    const now = input.now ?? new Date();
+    const code = input.confirmationCode.toUpperCase().replace(/[\s-]/g, "");
+    if (!new RegExp(`^[${BASE32}]{${CODE_LENGTH}}$`).test(code)) {
+        throw new HostLinkError(400, "The confirmation code is 8 letters and digits, as shown on the page (XXXX-XXXX).");
+    }
+    const request = await input.db.hostIdentityLinkRequest.findFirst({
+        where: {
+            principalId: input.principalId,
+            provider: input.provider,
+            confirmHash: { not: null },
+            hostUserId: { not: null },
+            login: { not: null },
+            attempts: { lt: HOST_LINK_MAX_ATTEMPTS },
+            expiresAt: { gt: now },
+        },
+        orderBy: { callbackAt: "desc" },
+    });
+    if (!request?.confirmHash || !request.hostUserId || !request.login)
+        throw noPendingLink();
+    // Spend an attempt BEFORE comparing, atomically: concurrent guesses can't
+    // each get a comparison before the counter saturates.
+    const claimed = await input.db.hostIdentityLinkRequest.updateMany({
+        where: { id: request.id, attempts: { lt: HOST_LINK_MAX_ATTEMPTS }, expiresAt: { gt: now } },
+        data: { attempts: { increment: 1 } },
+    });
+    if (claimed.count !== 1)
+        throw noPendingLink();
+    const presented = Buffer.from(sha256(code), "hex");
+    const expected = Buffer.from(request.confirmHash, "hex");
+    if (presented.length !== expected.length || !timingSafeEqual(presented, expected)) {
+        const after = await input.db.hostIdentityLinkRequest.findUnique({ where: { id: request.id } });
+        const left = Math.max(0, HOST_LINK_MAX_ATTEMPTS - (after?.attempts ?? HOST_LINK_MAX_ATTEMPTS));
+        throw new HostLinkError(400, left > 0
+            ? `That confirmation code is not right; ${left} attempt${left === 1 ? "" : "s"} left.`
+            : "That confirmation code is not right, and this link attempt is used up. Start again with link_host_account.");
+    }
+    const hostUserId = request.hostUserId;
+    const login = request.login;
+    try {
+        await input.db.$transaction(async (tx) => {
+            // Consume the request first: a concurrent confirmation of the same code loses here.
+            // (Its attempt was already spent above, so attempts may now equal the limit.)
+            const consumed = await tx.hostIdentityLinkRequest.deleteMany({
+                where: { id: request.id, expiresAt: { gt: now } },
+            });
+            if (consumed.count !== 1)
+                throw new HostLinkError(404, "This link attempt is no longer valid; start again.");
+            const holder = await tx.hostIdentity.findUnique({
+                where: { provider_hostUserId: { provider: input.provider, hostUserId } },
+            });
+            if (holder && holder.principalId !== input.principalId)
+                throw alreadyLinked();
+            await tx.hostIdentity.upsert({
+                where: { principalId_provider: { principalId: input.principalId, provider: input.provider } },
+                create: { principalId: input.principalId, provider: input.provider, hostUserId, login },
+                update: { hostUserId, login, linkedAt: now },
+            });
+        }, { isolationLevel: Prisma.TransactionIsolationLevel.Serializable });
+    }
+    catch (err) {
+        if (err instanceof HostLinkError)
+            throw err;
+        if (err instanceof Prisma.PrismaClientKnownRequestError && err.code === "P2002")
+            throw alreadyLinked();
+        throw err;
+    }
+    return { hostUserId, login };
+}
+function noPendingLink() {
+    return new HostLinkError(404, "No account link is waiting for a confirmation code from you. Start again with link_host_account (no code).");
+}
+function alreadyLinked() {
+    return new HostLinkError(409, "That GitHub account is already linked to another wardby account. An operator can unlink it " +
+        "(`wardby auth host-account unlink --subject <subject>`) if it should move to you.");
+}

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

@@ -0,0 +1,78 @@
+/**
+ * The status comment for a run started by an @-mention. Where to comment is
+ * recorded with the run itself (mentionStatusRow, written in the dispatch
+ * transaction); the "working on it" comment is posted right after the webhook
+ * is answered, and edited once with the outcome — the pull requests its coding
+ * sub-runs opened or updated, the agent's reply when none came out, or why it
+ * did not succeed. A run that ends before its comment was posted (the instance
+ * died first, say) still gets one: the reconciler posts the outcome as a new
+ * comment. Best effort throughout: nothing here throws.
+ */
+import type { Prisma, PrismaClient, Run } from "#prisma";
+import type { CodeReviewHost, ReviewHostProvider, ReviewHostRegistry } from "../providers/review-host/types.js";
+export type HostStatusDb = Pick<PrismaClient, "runHostStatus" | "run">;
+export type FinishedRun = Pick<Run, "id" | "status" | "finalText">;
+/** The parts of a CodingRun result this comment uses. */
+export interface PullRequestOutcome {
+    outcome: "pull_request_opened" | "pull_request_updated";
+    repository: string;
+    pullRequestNumber: number;
+    /** The result's own pull request URL; absent from a malformed result. */
+    pullRequestUrl?: string;
+    /** The code host the repository is on. */
+    codeProvider: string;
+    /** The coding sub-run that produced it; set by collectRunOutcome. */
+    runId?: string;
+}
+/** A sub-run that ended without succeeding. */
+export interface FailedChild {
+    id: string;
+    status: string;
+    /** The coding sub-run's failure category; `provider_<class>` names a model-provider refusal. */
+    failureCategory?: string | null;
+    /** The sub-run's Run.error; read only for a service refusal's host sentence (coding/services/wording.ts). */
+    error?: string | null;
+    /** The service names on the coding sub-run (CodingRun.services), for one that never became ready. */
+    services?: string[];
+}
+export declare const runLine: (runId: string) => string;
+export declare function workingBody(runId: string): string;
+/** The status row for a mention run, created in the same transaction as the run. */
+export declare function mentionStatusRow(provider: ReviewHostProvider, event: {
+    repository: string;
+    number: number;
+    replyToReviewCommentId?: string;
+}, runId: string): Prisma.RunHostStatusUncheckedCreateInput;
+export declare function outcomeBody(run: FinishedRun, repository: string, pullRequests: PullRequestOutcome[], failedChildren?: FailedChild[], opts?: {
+    budgetSentence?: string;
+    noPullRequestText?: string;
+    /** The agent's reply IS the answer (no separate reply comment): shown as written, not quoted. */
+    replyAsAnswer?: boolean;
+}): string;
+/** What collectRunOutcome reads: a run's children and, when out of budget, its budget facts. */
+export type RunOutcomeDb = Pick<PrismaClient, "run">;
+/** The parts of a finished run's outcome a status comment reports; shared by GitHub and Jira status comments. */
+export declare function collectRunOutcome(db: RunOutcomeDb, run: FinishedRun): Promise<{
+    pullRequests: PullRequestOutcome[];
+    failedChildren: FailedChild[];
+    budgetSentence?: string;
+}>;
+/**
+ * Writes a finished run's outcome to its status comment and marks it
+ * complete: edits the comment when it exists; when it does not yet, posts the
+ * outcome as a new comment only if `postIfMissing` (the reconciler, well after
+ * the run ended), and otherwise leaves the row for postMentionStatus, which
+ * is about to post it. A failed host call leaves the row open for the
+ * reconciler to retry.
+ */
+export declare function completeHostStatus(db: HostStatusDb, run: FinishedRun, hosts: ReviewHostRegistry | undefined, opts?: {
+    postIfMissing?: boolean;
+}): Promise<void>;
+/**
+ * Posts the "working on it" comment for a mention run whose status row was
+ * written at dispatch, and records the comment on the row. When the run
+ * already ended (a fast failure can beat this follow-up), completes it at
+ * once. Does nothing when the row is gone, already has a comment, or is
+ * already complete. Never throws.
+ */
+export declare function postMentionStatus(db: HostStatusDb, host: CodeReviewHost, runId: string, hosts: ReviewHostRegistry | undefined): Promise<void>;

package/dist/core/host-status.js

@@ -0,0 +1,228 @@
+import { CODING_CODE_PROVIDER } from "../coding/protocol.js";
+import { storedServiceNames } from "../coding/services/catalog.js";
+import { SERVICE_UNREADY_CATEGORY, serviceRefusalSentence, serviceUnreadySentence, } from "../coding/services/wording.js";
+import { PROTECTED_PATH_CATEGORY, PROTECTED_PATH_HOST_LINE } from "../coding/protected-path-wording.js";
+import { loadBudgetSentence } from "./budget-wording.js";
+import { logger } from "./logger.js";
+import { providerClassOfCategory, providerSentence } from "./provider-wording.js";
+const log = logger.child({ module: "host-status" });
+/** Keeps the edited comment readable; the full reply stays on the run. */
+const MAX_REPLY_CHARS = 2000;
+const TERMINAL = new Set(["succeeded", "failed", "refused", "lost", "budget_exhausted", "cancelled"]);
+export const runLine = (runId) => `<sub>wardby run \`${runId}\`</sub>`;
+export function workingBody(runId) {
+    return `👀 Working on it.\n\n${runLine(runId)}`;
+}
+/** The status row for a mention run, created in the same transaction as the run. */
+export function mentionStatusRow(provider, event, runId) {
+    return {
+        runId,
+        provider,
+        repository: event.repository,
+        number: event.number,
+        commentKind: event.replyToReviewCommentId ? "inline" : "conversation",
+        replyToReviewCommentId: event.replyToReviewCommentId ?? null,
+    };
+}
+function pullRequestOutcome(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const r = result;
+    if (r.outcome !== "pull_request_opened" && r.outcome !== "pull_request_updated")
+        return null;
+    if (typeof r.repository !== "string" || typeof r.pullRequestNumber !== "number")
+        return null;
+    if (!Number.isInteger(r.pullRequestNumber) || r.pullRequestNumber <= 0)
+        return null;
+    return {
+        outcome: r.outcome,
+        repository: r.repository,
+        pullRequestNumber: r.pullRequestNumber,
+        codeProvider: CODING_CODE_PROVIDER,
+        ...(typeof r.pullRequestUrl === "string" ? { pullRequestUrl: r.pullRequestUrl } : {}),
+    };
+}
+/** The agent's reply as a quote, cut to MAX_REPLY_CHARS, with @-mentions defused so nobody is pinged. */
+const cutReply = (text) => text.length > MAX_REPLY_CHARS ? `${text.slice(0, MAX_REPLY_CHARS)}…` : text;
+function quoteReply(text) {
+    return cutReply(text)
+        .replace(/@(?=[\w-])/g, "@​")
+        .split("\n")
+        .map((line) => `> ${line}`)
+        .join("\n");
+}
+export function outcomeBody(run, repository, pullRequests, failedChildren = [], opts = {}) {
+    const links = pullRequests.map((pr) => {
+        const ref = pr.repository.toLowerCase() === repository.toLowerCase()
+            ? `#${pr.pullRequestNumber}`
+            : `${pr.repository}#${pr.pullRequestNumber}`;
+        return pr.outcome === "pull_request_opened" ? `Opened ${ref}` : `Pushed changes to ${ref}`;
+    });
+    const partial = links.length > 0 ? `\n\n${links.join(", ")}.` : "";
+    const footer = runLine(run.id);
+    if (run.status === "lost") {
+        return `❌ Interrupted before it finished (for example, wardby restarted). Repeat your request to retry.${partial}\n\n${footer}`;
+    }
+    if (run.status === "budget_exhausted" || run.status === "refused") {
+        // A refused run could not start for lack of budget; see budgetSentence.
+        return `❌ ${opts.budgetSentence ?? "Out of budget."}${partial}\n\n${footer}`;
+    }
+    if (run.status !== "succeeded") {
+        // Only the status: a run's error text can carry internal detail that does not belong on the host.
+        return `❌ Stopped: the run ended with status \`${run.status}\`.${partial}\n\n${footer}`;
+    }
+    const reply = run.finalText?.trim();
+    const quoted = reply ? `\n\n${quoteReply(reply)}` : "";
+    if (failedChildren.length > 0) {
+        // The agent itself finished, but the work it handed off did not.
+        const outOfBudget = failedChildren.filter((c) => c.status === "budget_exhausted");
+        const providerClassOf = (c) => c.status === "failed" ? providerClassOfCategory(c.failureCategory) : null;
+        // A coding sub-run its services stopped: refused at dispatch, or a sidecar never became ready.
+        const serviceSentenceOf = (c) => c.status === "refused"
+            ? serviceRefusalSentence(c.error)
+            : c.status === "failed" && c.failureCategory === SERVICE_UNREADY_CATEGORY
+                ? serviceUnreadySentence(c.services ?? [])
+                : null;
+        // No path reaches this comment (see coding/protected-path-wording.ts), only the category.
+        const protectedPathOf = (c) => c.status === "failed" && c.failureCategory === PROTECTED_PATH_CATEGORY;
+        const providerClasses = new Set(failedChildren.map(providerClassOf).filter((c) => c !== null));
+        const serviceSentences = new Set(failedChildren.map(serviceSentenceOf).filter((s) => s !== null));
+        const protectedPathFailed = failedChildren.some(protectedPathOf);
+        const other = failedChildren.filter((c) => c.status !== "budget_exhausted" &&
+            providerClassOf(c) === null &&
+            serviceSentenceOf(c) === null &&
+            !protectedPathOf(c));
+        const lines = [];
+        if (outOfBudget.length > 0) {
+            lines.push(`A sub-run ran out of budget: ${outOfBudget.map((c) => `\`${c.id}\``).join(", ")}.`);
+        }
+        // The class only, never the provider's code: the sentence says who has to act.
+        for (const providerClass of providerClasses) {
+            lines.push(`A sub-run could not reach the model: ${providerSentence(providerClass)}`);
+        }
+        // The fixed sentence only, never the Run.error code in front of it.
+        for (const sentence of serviceSentences) {
+            lines.push(`A sub-run could not start: ${sentence}`);
+        }
+        if (protectedPathFailed)
+            lines.push(PROTECTED_PATH_HOST_LINE);
+        if (other.length > 0) {
+            lines.push(`A sub-run did not succeed: ${other.map((c) => `\`${c.id}\` (\`${c.status}\`)`).join(", ")}.`);
+        }
+        return `❌ ${lines.join(" ")}${partial}${quoted}\n\n${footer}`;
+    }
+    if (links.length > 0)
+        return `✅ ${links.join(", ")}.\n\n${footer}`;
+    if (opts.replyAsAnswer && reply)
+        return `✅ ${cutReply(reply)}\n\n${footer}`;
+    return `✅ ${opts.noPullRequestText ?? "Finished without opening a pull request."}${quoted}\n\n${footer}`;
+}
+/** The parts of a finished run's outcome a status comment reports; shared by GitHub and Jira status comments. */
+export async function collectRunOutcome(db, run) {
+    const children = await db.run.findMany({
+        where: { parentRunId: run.id },
+        select: {
+            id: true,
+            status: true,
+            error: true,
+            codingRun: { select: { result: true, failureCategory: true, services: true } },
+        },
+        orderBy: { startedAt: "asc" },
+    });
+    const pullRequests = children
+        .map((c) => {
+        const pr = pullRequestOutcome(c.codingRun?.result);
+        return pr ? { ...pr, runId: c.id } : null;
+    })
+        .filter((pr) => pr !== null);
+    const failedChildren = children
+        .filter((c) => TERMINAL.has(c.status) && c.status !== "succeeded")
+        .map((c) => ({
+        id: c.id,
+        status: c.status,
+        failureCategory: c.codingRun?.failureCategory ?? null,
+        error: c.error ?? null,
+        services: storedServiceNames(c.codingRun?.services),
+    }));
+    const budgetSentence = run.status === "budget_exhausted" || run.status === "refused"
+        ? await loadBudgetSentence(db, run.id, run.status)
+        : undefined;
+    return { pullRequests, failedChildren, ...(budgetSentence ? { budgetSentence } : {}) };
+}
+/**
+ * Writes a finished run's outcome to its status comment and marks it
+ * complete: edits the comment when it exists; when it does not yet, posts the
+ * outcome as a new comment only if `postIfMissing` (the reconciler, well after
+ * the run ended), and otherwise leaves the row for postMentionStatus, which
+ * is about to post it. A failed host call leaves the row open for the
+ * reconciler to retry.
+ */
+export async function completeHostStatus(db, run, hosts, opts = {}) {
+    if (!hosts)
+        return;
+    try {
+        const status = await db.runHostStatus.findUnique({ where: { runId: run.id } });
+        if (!status || status.completedAt)
+            return;
+        if (!status.commentId && !opts.postIfMissing)
+            return;
+        const host = hosts[status.provider];
+        if (!host)
+            return;
+        const { pullRequests, failedChildren, budgetSentence } = await collectRunOutcome(db, run);
+        const body = outcomeBody(run, status.repository, pullRequests, failedChildren, { budgetSentence });
+        let commentId = status.commentId;
+        if (commentId) {
+            await host.editComment(status.repository, {
+                kind: status.commentKind === "inline" ? "inline" : "conversation",
+                id: commentId,
+                body,
+            });
+        }
+        else {
+            commentId = (await host.comment(status.repository, {
+                number: status.number,
+                body,
+                ...(status.replyToReviewCommentId ? { replyToReviewCommentId: status.replyToReviewCommentId } : {}),
+            })).id;
+        }
+        await db.runHostStatus.update({ where: { runId: run.id }, data: { commentId, completedAt: new Date() } });
+    }
+    catch (err) {
+        log.warn({ err, runId: run.id }, "could not complete the run's status comment");
+    }
+}
+/**
+ * Posts the "working on it" comment for a mention run whose status row was
+ * written at dispatch, and records the comment on the row. When the run
+ * already ended (a fast failure can beat this follow-up), completes it at
+ * once. Does nothing when the row is gone, already has a comment, or is
+ * already complete. Never throws.
+ */
+export async function postMentionStatus(db, host, runId, hosts) {
+    try {
+        const status = await db.runHostStatus.findUnique({ where: { runId } });
+        if (!status || status.commentId || status.completedAt)
+            return;
+        const posted = await host.comment(status.repository, {
+            number: status.number,
+            body: workingBody(runId),
+            ...(status.replyToReviewCommentId ? { replyToReviewCommentId: status.replyToReviewCommentId } : {}),
+        });
+        const claimed = await db.runHostStatus.updateMany({
+            where: { runId, commentId: null, completedAt: null },
+            data: { commentId: posted.id },
+        });
+        if (claimed.count === 0) {
+            // The reconciler posted the outcome meanwhile; this comment is surplus.
+            log.warn({ runId }, "status comment posted after the outcome; leaving both");
+            return;
+        }
+        const run = await db.run.findUnique({ where: { id: runId }, select: { id: true, status: true, finalText: true } });
+        if (run && TERMINAL.has(run.status))
+            await completeHostStatus(db, run, hosts);
+    }
+    catch (err) {
+        log.warn({ err, runId }, "could not post the status comment");
+    }
+}

package/dist/core/in-flight-runs.d.ts

@@ -0,0 +1,8 @@
+/** Registers a run for the duration of `work`. */
+export declare function trackRun<T>(runId: string, work: () => Promise<T>): Promise<T>;
+export declare function inFlightRunIds(): string[];
+/**
+ * Resolves once no run is executing, or after `timeoutMs`, whichever is
+ * first. Returns the ids still executing at that point (empty when drained).
+ */
+export declare function waitForInFlightRuns(timeoutMs: number): Promise<string[]>;

package/dist/core/in-flight-runs.js

@@ -0,0 +1,56 @@
+/**
+ * Counts the native runs executing in this process, so a shutdown can wait
+ * for them instead of abandoning them. Every native run, however it was
+ * started (a direct start, a DBOS workflow, a workflow adopted from a dead
+ * instance), goes through executeRun, which registers here. Coding jobs are
+ * not counted: they run in their own pods and a new instance collects them.
+ */
+import { logger } from "./logger.js";
+const log = logger.child({ module: "in-flight-runs" });
+const active = new Set();
+let waiters = [];
+/** Registers a run for the duration of `work`. */
+export async function trackRun(runId, work) {
+    active.add(runId);
+    try {
+        return await work();
+    }
+    finally {
+        active.delete(runId);
+        if (active.size === 0) {
+            const done = waiters;
+            waiters = [];
+            for (const wake of done)
+                wake();
+        }
+    }
+}
+export function inFlightRunIds() {
+    return [...active];
+}
+/**
+ * Resolves once no run is executing, or after `timeoutMs`, whichever is
+ * first. Returns the ids still executing at that point (empty when drained).
+ */
+export async function waitForInFlightRuns(timeoutMs) {
+    if (active.size === 0 || timeoutMs <= 0)
+        return inFlightRunIds();
+    log.info({ runIds: inFlightRunIds(), timeoutMs }, "waiting for in-flight runs before shutdown");
+    await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            waiters = waiters.filter((w) => w !== wake);
+            resolve();
+        }, timeoutMs);
+        const wake = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        waiters.push(wake);
+    });
+    const remaining = inFlightRunIds();
+    if (remaining.length > 0)
+        log.warn({ runIds: remaining }, "shutdown drain timed out; these runs are abandoned");
+    else
+        log.info("in-flight runs finished; shutting down");
+    return remaining;
+}

package/dist/core/issue-bridge.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Links a run's pull requests to the issue that started it: records each
+ * issue/PR pair, puts a web link on the issue, and applies the link's
+ * configured status move. Provider-neutral: a code host is only ever
+ * { provider, repository, number }. The issue key comes from the run tree
+ * (RunIssueStatus), never from model output. The status move is a control-plane
+ * action (not gated by allowedTransitions). Nothing here throws, except
+ * handlePullRequestClosed's lookup before it has claimed anything (so the
+ * webhook delivery is rolled back and redelivered).
+ */
+import { type PrismaClient } from "#prisma";
+import { type IssueTracker, type IssueTrackerRegistry } from "../providers/issue-tracker/types.js";
+export type IssueBridgeDb = Pick<PrismaClient, "issuePullRequest">;
+export type PullRequestClosedDb = Pick<PrismaClient, "issuePullRequest" | "agentIssueProject">;
+export interface BridgedPullRequest {
+    codeProvider: string;
+    repository: string;
+    number: number;
+    url: string;
+    openedByRunId: string;
+    outcome: "pull_request_opened" | "pull_request_updated";
+}
+export interface RecordPullRequestsInput {
+    issueKey: string;
+    issueProvider: string;
+    agentId: string;
+    /** The status the link moves the issue to when a pull request is opened, if configured. */
+    onPullRequestOpened?: string | null;
+    pullRequests: BridgedPullRequest[];
+}
+export declare const pullRequestGlobalId: (pr: Pick<BridgedPullRequest, "codeProvider" | "repository" | "number">) => string;
+/**
+ * Returns sentences for the outcome comment (a refused status move); empty
+ * when there is nothing to say. Safe to repeat (a retried completion): each
+ * pair's side effects happen once — the status move only when this call newly
+ * recorded an opened pull request, and a merged/closed pair is never re-linked
+ * (re-posting its web link would un-resolve it). An unreadable store skips
+ * both rather than risk repeating them.
+ */
+export declare function recordPullRequests(db: IssueBridgeDb, tracker: IssueTracker, input: RecordPullRequestsInput): Promise<{
+    notes: string[];
+}>;
+export interface ClosedPullRequest {
+    codeProvider: string;
+    repository: string;
+    number: number;
+    merged: boolean;
+}
+/**
+ * A pull request wardby recorded against an issue was merged or closed: marks
+ * each still-open pair, and, where the agent's link to the issue's project is
+ * still write, comments on the issue (and on merge resolves the web link and
+ * applies the link's onPullRequestMerged move). Only rows wardby wrote are
+ * touched, matched by the host's own identity for the PR — nothing from the
+ * PR's text. The row is claimed first (open → merged/closed), so a duplicate
+ * or concurrent delivery finds nothing to do. Throws only when the lookup of
+ * linked rows fails — before anything is claimed — so the caller's webhook
+ * delivery is rolled back and redelivered; never throws after that.
+ */
+export declare function handlePullRequestClosed(db: PullRequestClosedDb, trackers: IssueTrackerRegistry | undefined, pr: ClosedPullRequest): Promise<void>;