@wardby/cli 0.2.0 → 0.3.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,61 @@
+/**
+ * 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">;
+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;
+}
+/** 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 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;
+}): 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>;
+export {};

package/dist/core/host-status.js

@@ -0,0 +1,211 @@
+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"]);
+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 };
+}
+/** The agent's reply as a quote, cut to MAX_REPLY_CHARS, with @-mentions defused so nobody is pinged. */
+function quoteReply(text) {
+    const cut = text.length > MAX_REPLY_CHARS ? `${text.slice(0, MAX_REPLY_CHARS)}…` : text;
+    return cut
+        .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}`;
+    return `✅ Finished without opening a pull request.${quoted}\n\n${footer}`;
+}
+/**
+ * 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 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) => pullRequestOutcome(c.codingRun?.result))
+            .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;
+        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/http-runtime.js

@@ -57,11 +57,10 @@
  * later in the process, would replace this Agent with an h2-enabled one and
  * silently restore the corruption — the price of fixing this with a dispatcher
  * instead of owning the fetch stack. Nothing in the runtime image does that
- * today: the only other `setGlobalDispatcher` calls in the tree are undici
- * copies bundled inside `@prisma/client/runtime/binary.*` (guarded by the same
- * `=== undefined` check, and the binary engine is not the default) and
+ * today: the only other `setGlobalDispatcher` call in the tree is
  * `node-fetch-native` under the `prisma` CLI, which `deploy/Dockerfile:25`
- * asserts is absent from the runtime image.
+ * asserts is absent from the runtime image. (Prisma 7's client runtime and
+ * `@prisma/adapter-pg` contain none; Prisma 6's `runtime/binary.*` did.)
  *
  * Restoring Node's OWN dispatcher instead is not possible, though not for the
  * reason one might guess: undici defines the legacy symbol `configurable: false`

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/lease.d.ts

@@ -7,7 +7,7 @@
  * expired, or already ours, and `RETURNING` tells the caller which case it
  * was — zero rows means someone else holds an unexpired lease.
  */
-import type { PrismaClient } from "@prisma/client";
+import type { PrismaClient } from "#prisma";
 export type LeaseDb = Pick<PrismaClient, "$queryRaw">;
 /** Attempts to acquire (or renew) the lease for `scope`. Returns whether `holder` now holds it. */
 export declare function tryAcquireLease(db: LeaseDb, scope: string, holder: string, ttlMs: number): Promise<boolean>;

package/dist/core/private-directory.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Creates `path` as a private directory, or verifies an existing one is safe to
+ * trust.
+ *
+ * `mkdir(..., { mode: 0o700 })` does nothing to a directory that already
+ * exists. The coding state roots default to fixed names under the OS temp
+ * directory, so on a shared host another user could create one first -- or
+ * point it somewhere else with a symlink -- and then read or plant the job
+ * records, workspaces and artifacts wardby keeps there. This refuses:
+ *
+ * - a symlink, or anything that is not a directory;
+ * - a directory owned by a different user (root excepted: an operator-mounted
+ *   volume is commonly root-owned);
+ * - a directory any other user can write to.
+ *
+ * Group write is allowed, since a Kubernetes `fsGroup` volume is group-writable
+ * by design and its group is chosen by the operator. Ownership and mode are not
+ * checked on platforms without POSIX uids.
+ */
+export declare function ensurePrivateDirectory(path: string): Promise<void>;

package/dist/core/private-directory.js

@@ -0,0 +1,36 @@
+import { lstat, mkdir } from "node:fs/promises";
+/**
+ * Creates `path` as a private directory, or verifies an existing one is safe to
+ * trust.
+ *
+ * `mkdir(..., { mode: 0o700 })` does nothing to a directory that already
+ * exists. The coding state roots default to fixed names under the OS temp
+ * directory, so on a shared host another user could create one first -- or
+ * point it somewhere else with a symlink -- and then read or plant the job
+ * records, workspaces and artifacts wardby keeps there. This refuses:
+ *
+ * - a symlink, or anything that is not a directory;
+ * - a directory owned by a different user (root excepted: an operator-mounted
+ *   volume is commonly root-owned);
+ * - a directory any other user can write to.
+ *
+ * Group write is allowed, since a Kubernetes `fsGroup` volume is group-writable
+ * by design and its group is chosen by the operator. Ownership and mode are not
+ * checked on platforms without POSIX uids.
+ */
+export async function ensurePrivateDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    const metadata = await lstat(path);
+    if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+        throw new Error(`${path} must be a real directory, not a symlink.`);
+    }
+    const uid = process.getuid?.();
+    if (uid === undefined)
+        return;
+    if (metadata.uid !== uid && metadata.uid !== 0) {
+        throw new Error(`${path} is owned by uid ${metadata.uid}, not this process (uid ${uid}). Remove it or choose another path.`);
+    }
+    if ((metadata.mode & 0o002) !== 0) {
+        throw new Error(`${path} is writable by other users. Run chmod o-w on it or choose another path.`);
+    }
+}

package/dist/core/provider-wording.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What a host (a PR comment, a check summary) is told when the model provider
+ * itself refused a run's requests: the class of problem and who has to act.
+ * Public repositories read these, so they never carry the provider's own
+ * error code or message; the code stays in the operator log.
+ */
+export type ProviderFailureClass = "quota" | "rate_limited" | "unavailable" | "rejected";
+/** Files an upstream error code (or `http_<status>`) under the class of problem it names. */
+export declare function classifyProviderFailure(code: string): ProviderFailureClass;
+export declare function providerSentence(providerClass: ProviderFailureClass): string;
+/** The class a run's `provider_<class>` failure category names, or null for any other category. */
+export declare function providerClassOfCategory(category: string | null | undefined): ProviderFailureClass | null;