@wardby/cli 0.2.1 → 0.3.0

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/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/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;

package/dist/core/provider-wording.js

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+const CLASSES = ["quota", "rate_limited", "unavailable", "rejected"];
+const QUOTA_MARKERS = ["quota", "spend_limit", "billing", "insufficient_funds", "credit"];
+const UNAVAILABLE_CODES = new Set([
+    "server_error",
+    "overloaded",
+    "overloaded_error",
+    "service_unavailable",
+    // Anthropic's name for an internal server error.
+    "api_error",
+]);
+/** Files an upstream error code (or `http_<status>`) under the class of problem it names. */
+export function classifyProviderFailure(code) {
+    const lower = code.toLowerCase();
+    // Checked first: an exhausted account is the one case only an operator can fix.
+    if (QUOTA_MARKERS.some((marker) => lower.includes(marker)))
+        return "quota";
+    if (lower.includes("rate_limit"))
+        return "rate_limited";
+    if (UNAVAILABLE_CODES.has(lower) || /^http_5\d\d$/.test(lower))
+        return "unavailable";
+    return "rejected";
+}
+const SENTENCES = {
+    quota: "The model provider refused the request: its account has reached a spending or quota limit. An operator needs to raise the limit with the provider, then retry.",
+    rate_limited: "The model provider is rate-limiting requests. Try again later.",
+    unavailable: "The model provider reported an outage or overload. Try again later.",
+    rejected: "The model provider rejected the request.",
+};
+export function providerSentence(providerClass) {
+    return SENTENCES[providerClass];
+}
+/** The class a run's `provider_<class>` failure category names, or null for any other category. */
+export function providerClassOfCategory(category) {
+    if (!category?.startsWith("provider_"))
+        return null;
+    const value = category.slice("provider_".length);
+    return CLASSES.includes(value) ? value : null;
+}

package/dist/core/reconciler.d.ts

@@ -27,17 +27,53 @@
  * UPDATE commits first flips the row out of the matched status, so the
  * second one's WHERE simply matches zero rows — double-reconcile is a
  * no-op, not a race.
+ *
+ * Each pass also completes review-host checks left "in progress" by a run
+ * that ended without reaching `executeRun`'s own finalizer (reaped here as
+ * `lost`, failed to start, failed while loading, ...). One sweep covers all
+ * of those paths instead of patching each. Mention status comments get the
+ * same sweep: it also catches a run that ended before its comment was posted.
  */
 import type { PrismaClient } from "#prisma";
 import type { Executor } from "../providers/executor/types.js";
-export type ReconcilerDb = Pick<PrismaClient, "run">;
+import type { ReviewHostRegistry } from "../providers/review-host/types.js";
+export type ReconcilerDb = Pick<PrismaClient, "run" | "runHostCheck" | "runHostStatus">;
+/**
+ * How long after a run finishes before its still-open check counts as
+ * orphaned: long enough that the sweep never races `executeRun`'s own
+ * `closeOpenHostCheck` for a run that just ended.
+ */
+export declare const ORPHANED_CHECK_GRACE_MS = 60000;
+/** Upper bound on checks completed per pass, so a backlog drains over several passes. */
+export declare const ORPHANED_CHECK_BATCH = 50;
+/** How long after a run finishes the sweep keeps trying to complete its check. */
+export declare const ORPHANED_CHECK_MAX_AGE_MS: number;
+/**
+ * Completes (as a failure) open host checks whose run reached a terminal status
+ * at least ORPHANED_CHECK_GRACE_MS and at most ORPHANED_CHECK_MAX_AGE_MS
+ * ago. Newest-finished first, so old checks the host keeps refusing cannot
+ * starve newer ones. A check the host still refuses after the max age (the
+ * check was deleted, the App was uninstalled, ...) is left as it is rather
+ * than retried forever; its Re-run button still works. Never queries when
+ * no host is configured. `closeOpenHostCheck` is best-effort and never throws.
+ */
+export declare function closeOrphanedHostChecks(db: Pick<PrismaClient, "runHostCheck" | "run">, hosts: ReviewHostRegistry | undefined, now?: Date): Promise<void>;
+/**
+ * Completes open mention status comments on the same terms as
+ * closeOrphanedHostChecks: the run ended between ORPHANED_CHECK_GRACE_MS and
+ * ORPHANED_CHECK_MAX_AGE_MS ago, newest first, at most ORPHANED_CHECK_BATCH per
+ * pass. `completeHostStatus` is best-effort and never throws.
+ */
+export declare function closeOrphanedHostStatuses(db: Pick<PrismaClient, "runHostStatus" | "run">, hosts: ReviewHostRegistry | undefined, now?: Date): Promise<void>;
 /** Runs one reconciliation pass. Returns the number of runs marked `lost`. */
-export declare function reconcileOnce(db: ReconcilerDb, now?: Date, heartbeatTimeoutMs?: number, executor?: Executor): Promise<number>;
+export declare function reconcileOnce(db: ReconcilerDb, now?: Date, heartbeatTimeoutMs?: number, executor?: Executor, reviewHosts?: ReviewHostRegistry): Promise<number>;
 export interface ReconcilerOptions {
     db?: ReconcilerDb;
     intervalMs?: number;
     heartbeatTimeoutMs?: number;
     executor?: Executor;
+    /** Hosts used to complete checks orphaned by runs that ended abnormally; none configured = no sweep. */
+    reviewHosts?: ReviewHostRegistry;
 }
 export interface ReconcilerHandle {
     stop(): void;

package/dist/core/reconciler.js

@@ -27,13 +27,95 @@
  * UPDATE commits first flips the row out of the matched status, so the
  * second one's WHERE simply matches zero rows — double-reconcile is a
  * no-op, not a race.
+ *
+ * Each pass also completes review-host checks left "in progress" by a run
+ * that ended without reaching `executeRun`'s own finalizer (reaped here as
+ * `lost`, failed to start, failed while loading, ...). One sweep covers all
+ * of those paths instead of patching each. Mention status comments get the
+ * same sweep: it also catches a run that ended before its comment was posted.
  */
 import { HEARTBEAT_TIMEOUT_MS, RECONCILE_INTERVAL_MS } from "./timing.js";
 import { prisma as defaultDb } from "./db.js";
 import { logger } from "./logger.js";
+import { closeOpenHostCheck } from "./review-host-checks.js";
+import { completeHostStatus } from "./host-status.js";
 const reconcilerLog = logger.child({ module: "reconciler" });
+/**
+ * How long after a run finishes before its still-open check counts as
+ * orphaned: long enough that the sweep never races `executeRun`'s own
+ * `closeOpenHostCheck` for a run that just ended.
+ */
+export const ORPHANED_CHECK_GRACE_MS = 60_000;
+/** Upper bound on checks completed per pass, so a backlog drains over several passes. */
+export const ORPHANED_CHECK_BATCH = 50;
+/** How long after a run finishes the sweep keeps trying to complete its check. */
+export const ORPHANED_CHECK_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Completes (as a failure) open host checks whose run reached a terminal status
+ * at least ORPHANED_CHECK_GRACE_MS and at most ORPHANED_CHECK_MAX_AGE_MS
+ * ago. Newest-finished first, so old checks the host keeps refusing cannot
+ * starve newer ones. A check the host still refuses after the max age (the
+ * check was deleted, the App was uninstalled, ...) is left as it is rather
+ * than retried forever; its Re-run button still works. Never queries when
+ * no host is configured. `closeOpenHostCheck` is best-effort and never throws.
+ */
+export async function closeOrphanedHostChecks(db, hosts, now = new Date()) {
+    const providers = Object.keys(hosts ?? {});
+    if (!hosts || providers.length === 0)
+        return;
+    const orphans = await db.runHostCheck.findMany({
+        where: {
+            completedAt: null,
+            // A check for a provider that isn't configured could never be completed; keep it out of the batch.
+            provider: { in: providers },
+            run: {
+                status: { notIn: ["pending", "running"] },
+                finishedAt: {
+                    lte: new Date(now.getTime() - ORPHANED_CHECK_GRACE_MS),
+                    gte: new Date(now.getTime() - ORPHANED_CHECK_MAX_AGE_MS),
+                },
+            },
+        },
+        select: { run: { select: { id: true, status: true } } },
+        orderBy: { run: { finishedAt: "desc" } },
+        take: ORPHANED_CHECK_BATCH,
+    });
+    for (const { run } of orphans)
+        await closeOpenHostCheck(db, run, hosts);
+}
+/**
+ * Completes open mention status comments on the same terms as
+ * closeOrphanedHostChecks: the run ended between ORPHANED_CHECK_GRACE_MS and
+ * ORPHANED_CHECK_MAX_AGE_MS ago, newest first, at most ORPHANED_CHECK_BATCH per
+ * pass. `completeHostStatus` is best-effort and never throws.
+ */
+export async function closeOrphanedHostStatuses(db, hosts, now = new Date()) {
+    const providers = Object.keys(hosts ?? {});
+    if (!hosts || providers.length === 0)
+        return;
+    const orphans = await db.runHostStatus.findMany({
+        where: {
+            completedAt: null,
+            provider: { in: providers },
+            run: {
+                status: { notIn: ["pending", "running"] },
+                finishedAt: {
+                    lte: new Date(now.getTime() - ORPHANED_CHECK_GRACE_MS),
+                    gte: new Date(now.getTime() - ORPHANED_CHECK_MAX_AGE_MS),
+                },
+            },
+        },
+        select: { run: { select: { id: true, status: true, finalText: true } } },
+        orderBy: { run: { finishedAt: "desc" } },
+        take: ORPHANED_CHECK_BATCH,
+    });
+    // postIfMissing: by now the dispatching instance's follow-up has had its
+    // chance; a run that ended with no comment (it died first) gets one here.
+    for (const { run } of orphans)
+        await completeHostStatus(db, run, hosts, { postIfMissing: true });
+}
 /** Runs one reconciliation pass. Returns the number of runs marked `lost`. */
-export async function reconcileOnce(db, now = new Date(), heartbeatTimeoutMs = HEARTBEAT_TIMEOUT_MS, executor) {
+export async function reconcileOnce(db, now = new Date(), heartbeatTimeoutMs = HEARTBEAT_TIMEOUT_MS, executor, reviewHosts) {
     const cutoff = new Date(now.getTime() - heartbeatTimeoutMs);
     const stale = {
         executionManaged: true,
@@ -133,6 +215,8 @@ export async function reconcileOnce(db, now = new Date(), heartbeatTimeoutMs = H
         });
         lost += result.count;
     }
+    await closeOrphanedHostChecks(db, reviewHosts, now);
+    await closeOrphanedHostStatuses(db, reviewHosts, now);
     return lost;
 }
 export function startReconciler(options = {}) {
@@ -140,7 +224,7 @@ export function startReconciler(options = {}) {
     const intervalMs = options.intervalMs ?? RECONCILE_INTERVAL_MS;
     const heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? HEARTBEAT_TIMEOUT_MS;
     const timer = setInterval(() => {
-        reconcileOnce(db, new Date(), heartbeatTimeoutMs, options.executor).catch((err) => {
+        reconcileOnce(db, new Date(), heartbeatTimeoutMs, options.executor, options.reviewHosts).catch((err) => {
             reconcilerLog.error({ err }, "reconcile pass failed");
         });
     }, intervalMs);

package/dist/core/repo-access.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Repository access authorization, host-neutral (security findings
+ * H5-1/A3/C3-2 and H5-3). An agent may use a repository only when its current
+ * owner's verified host identity has enough permission on it, or when the
+ * authorization was an explicit, recorded admin approval (or predates
+ * enforcement: "grandfathered"). Owner-less (public) agents never hold
+ * repository authority: anyone can edit them.
+ *
+ * One gate serves every point of use (a coding run before its workspace is
+ * prepared, each repo_* tool call, each host-event dispatch and mention
+ * author) and every set-time check (link_repository, create/update_agent).
+ * Host answers are cached per (provider, repository, host user id) for a
+ * short TTL, positive and negative alike; set-time checks bypass the cache
+ * and refresh it. A host error always denies: fail closed.
+ * See docs/private/2026-09-26-repo-access-authorization-spec-and-plan.md.
+ */
+import type { PrismaClient } from "#prisma";
+import { type HostPermission, type HostUser, type ReviewHostRegistry } from "../providers/review-host/types.js";
+export type { HostPermission };
+/** How an authorization was granted; stored on the row that grants the authority. */
+export type AuthorizedVia = "host_permission" | "admin" | "grandfathered";
+export declare const AUTHORIZED_VIA: readonly AuthorizedVia[];
+export type RepoAccessDenial = "owner_required" | "not_authorized" | "identity_not_linked" | "insufficient_permission" | "check_failed"
+/** In-flight use only: the host was unreachable or rate-limited, even after one retry. */
+ | "check_unavailable";
+export type RepoAccessDecision = {
+    ok: true;
+    level?: HostPermission;
+} | {
+    ok: false;
+    reason: RepoAccessDenial;
+    level?: HostPermission;
+};
+/** What a use of the repository needs. */
+export type RepoAccessKind = "coding" | "write" | "read" | "mention";
+/**
+ * Coding runs and write links push, comment, and publish checks; a mention
+ * drives a write-capable agent holding its owner's tools and secrets, so
+ * triage is not enough for it either.
+ */
+export declare function requiredLevel(kind: RepoAccessKind): HostPermission;
+export declare function atLeast(level: HostPermission, required: HostPermission): boolean;
+export interface AuthorizeUseInput {
+    /** The agent's CURRENT owner — never whoever authorized the link. */
+    ownerId: string | null;
+    provider: string;
+    repository: string;
+    required: HostPermission;
+    /** The stamp on the row granting the authority (null = never authorized). */
+    authorizedVia: string | null;
+    /**
+     * A use by a run already under way (a launched coding run, its final push,
+     * a repo_* call): a transient host error (5xx, timeout, rate limit) is
+     * retried once, then denied as `check_unavailable`. Starting something new
+     * and set-time checks stay strict: any error is `check_failed`, no retry.
+     */
+    retryTransient?: boolean;
+}
+export interface RepoAccessGate {
+    /** Point of use: may this agent (by its owner and stamp) use the repository now? */
+    authorizeUse(input: AuthorizeUseInput): Promise<RepoAccessDecision>;
+    /** Does this principal's linked identity have `required` on the repository? */
+    authorizePrincipal(input: {
+        principalId: string;
+        provider: string;
+        repository: string;
+        required: HostPermission;
+        /** Bypass (and refresh) the cache: set-time checks. */
+        fresh?: boolean;
+    }): Promise<RepoAccessDecision>;
+    /** Does this host user (e.g. a mention's author) have `required` on the repository? */
+    authorizeHostUser(input: {
+        provider: string;
+        repository: string;
+        user: HostUser;
+        required: HostPermission;
+        fresh?: boolean;
+    }): Promise<RepoAccessDecision>;
+}
+export interface RepoAccessGateOptions {
+    db: Pick<PrismaClient, "hostIdentity">;
+    hosts: ReviewHostRegistry;
+    /** Default 5 minutes. */
+    ttlMs?: number;
+    /** Default 1000; the oldest entry is evicted first. */
+    maxEntries?: number;
+    now?: () => number;
+    /** Delay before the one retry of a transient error (default 1s). */
+    retryDelayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** 5xx, rate limits (403/429), and transport failures: worth one retry for a run already under way. */
+export declare function isTransientHostError(err: unknown): boolean;
+export declare const DEFAULT_REPO_ACCESS_TTL_MS: number;
+export declare function createRepoAccessGate(options: RepoAccessGateOptions): RepoAccessGate;
+/** Actionable, non-leaking text for a denial, for tool results and run errors. */
+export declare function describeDenial(decision: Extract<RepoAccessDecision, {
+    ok: false;
+}>, repository: string): string;