@wardby/cli 0.2.1 → 0.3.0

package/dist/core/repo-access.js

@@ -0,0 +1,136 @@
+import { HOST_PERMISSION_RANK, ReviewHostError, } from "../providers/review-host/types.js";
+import { logger } from "./logger.js";
+const log = logger.child({ module: "repo-access" });
+export const AUTHORIZED_VIA = ["host_permission", "admin", "grandfathered"];
+/**
+ * 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 function requiredLevel(kind) {
+    return kind === "read" ? "read" : "write";
+}
+export function atLeast(level, required) {
+    return HOST_PERMISSION_RANK[level] >= HOST_PERMISSION_RANK[required];
+}
+/** 5xx, rate limits (403/429), and transport failures: worth one retry for a run already under way. */
+export function isTransientHostError(err) {
+    if (!(err instanceof ReviewHostError) || err.code !== "host_api_error")
+        return false;
+    return err.message === "github_api_unavailable" || /^github_api_error:(5\d\d|429|403)(:|$)/.test(err.message);
+}
+export const DEFAULT_REPO_ACCESS_TTL_MS = 5 * 60_000;
+export function createRepoAccessGate(options) {
+    const ttlMs = options.ttlMs ?? DEFAULT_REPO_ACCESS_TTL_MS;
+    const maxEntries = options.maxEntries ?? 1000;
+    const now = options.now ?? (() => Date.now());
+    const retryDelayMs = options.retryDelayMs ?? 1000;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const cache = new Map();
+    /** The user's level, or why it could not be determined (host missing or failing). */
+    async function levelOf(provider, repository, user, fresh, retryTransient) {
+        const key = `${provider}\u0000${repository}\u0000${user.id}`;
+        const hit = cache.get(key);
+        if (!fresh && hit && hit.expiresAt > now())
+            return { ok: true, level: hit.level, login: user.login };
+        const host = options.hosts[provider];
+        if (!host) {
+            log.warn({ provider, repository }, "no review host configured for a repository access check");
+            return { ok: false, transient: false };
+        }
+        let answer;
+        for (let attempt = 0; !answer; attempt++) {
+            if (attempt > 0)
+                await sleep(retryDelayMs);
+            try {
+                answer = await host.repositoryPermission(repository, user);
+            }
+            catch (err) {
+                const transient = isTransientHostError(err);
+                log.warn({ err, provider, repository, hostUserId: user.id, transient, attempt }, "repository access check failed");
+                // Strict: no retry. In flight: one retry of a transient error, then check_unavailable.
+                if (!transient || !retryTransient || attempt > 0)
+                    return { ok: false, transient: transient && retryTransient };
+            }
+        }
+        cache.delete(key);
+        cache.set(key, { level: answer.level, expiresAt: now() + ttlMs });
+        while (cache.size > maxEntries)
+            cache.delete(cache.keys().next().value);
+        return { ok: true, ...answer };
+    }
+    const unavailable = (answer) => ({
+        ok: false,
+        reason: answer.transient ? "check_unavailable" : "check_failed",
+    });
+    function decide(level, required) {
+        return atLeast(level, required) ? { ok: true, level } : { ok: false, reason: "insufficient_permission", level };
+    }
+    async function authorizePrincipal(input) {
+        let identity;
+        try {
+            identity = await options.db.hostIdentity.findUnique({
+                where: { principalId_provider: { principalId: input.principalId, provider: input.provider } },
+            });
+        }
+        catch (err) {
+            log.warn({ err, provider: input.provider }, "could not read a host identity; denying");
+            return { ok: false, reason: "check_failed" };
+        }
+        if (!identity)
+            return { ok: false, reason: "identity_not_linked" };
+        const answer = await levelOf(input.provider, input.repository, { id: identity.hostUserId, login: identity.login }, input.fresh === true, input.retryTransient === true);
+        if (!answer.ok)
+            return unavailable(answer);
+        if (answer.login !== identity.login) {
+            await options.db.hostIdentity
+                .updateMany({
+                where: { principalId: input.principalId, provider: input.provider, hostUserId: identity.hostUserId },
+                data: { login: answer.login },
+            })
+                .catch((err) => log.warn({ err }, "could not record a renamed host login"));
+        }
+        return decide(answer.level, input.required);
+    }
+    return {
+        async authorizeUse(input) {
+            if (!input.ownerId)
+                return { ok: false, reason: "owner_required" };
+            if (input.authorizedVia === "admin" || input.authorizedVia === "grandfathered")
+                return { ok: true };
+            if (input.authorizedVia !== "host_permission")
+                return { ok: false, reason: "not_authorized" };
+            return authorizePrincipal({
+                principalId: input.ownerId,
+                provider: input.provider,
+                repository: input.repository,
+                required: input.required,
+                retryTransient: input.retryTransient,
+            });
+        },
+        authorizePrincipal,
+        async authorizeHostUser(input) {
+            const answer = await levelOf(input.provider, input.repository, input.user, input.fresh === true, false);
+            if (!answer.ok)
+                return unavailable(answer);
+            return decide(answer.level, input.required);
+        },
+    };
+}
+/** Actionable, non-leaking text for a denial, for tool results and run errors. */
+export function describeDenial(decision, repository) {
+    switch (decision.reason) {
+        case "owner_required":
+            return `Agents without an owner cannot use repositories; an admin can assign one with make_owner.`;
+        case "not_authorized":
+            return `This agent's access to ${repository} was never authorized; re-link it (link_repository) or update the coding profile.`;
+        case "identity_not_linked":
+            return `The agent owner has not linked a GitHub account; run link_host_account first.`;
+        case "insufficient_permission":
+            return `The agent owner's GitHub account has ${decision.level ?? "no"} access to ${repository}, which is not enough.`;
+        case "check_failed":
+            return `Could not verify access to ${repository} right now; try again later.`;
+        case "check_unavailable":
+            return `GitHub could not be reached (or rate-limited wardby) while re-checking access to ${repository}, so the use was refused for safety. Try again later.`;
+    }
+}

package/dist/core/review-host-checks.d.ts

@@ -0,0 +1,11 @@
+import type { PrismaClient, Run } from "#prisma";
+import type { ReviewHostRegistry } from "../providers/review-host/types.js";
+/**
+ * A check the control plane started for a run must never stay "in progress":
+ * when the run reaches any terminal state without the review tool having
+ * completed it, complete it as a failure. Not neutral: branch protection
+ * counts a neutral required check as passing, which would let a pull request
+ * merge with no review. Best effort — a failure is logged, not retried; the
+ * check's Re-run button still works. Never throws.
+ */
+export declare function closeOpenHostCheck(db: Pick<PrismaClient, "runHostCheck" | "run">, run: Pick<Run, "id" | "status">, hosts: ReviewHostRegistry | undefined): Promise<void>;

package/dist/core/review-host-checks.js

@@ -0,0 +1,41 @@
+import { loadBudgetSentence } from "./budget-wording.js";
+import { logger } from "./logger.js";
+const log = logger.child({ module: "review-host-checks" });
+/**
+ * A check the control plane started for a run must never stay "in progress":
+ * when the run reaches any terminal state without the review tool having
+ * completed it, complete it as a failure. Not neutral: branch protection
+ * counts a neutral required check as passing, which would let a pull request
+ * merge with no review. Best effort — a failure is logged, not retried; the
+ * check's Re-run button still works. Never throws.
+ */
+export async function closeOpenHostCheck(db, run, hosts) {
+    if (!hosts)
+        return;
+    try {
+        const check = await db.runHostCheck.findUnique({ where: { runId: run.id } });
+        if (!check || check.completedAt)
+            return;
+        const host = hosts[check.provider];
+        if (!host)
+            return;
+        const outOfBudget = run.status === "refused" || run.status === "budget_exhausted";
+        await host.completeCheck(check.repository, {
+            checkId: check.checkId,
+            conclusion: "failure",
+            ...(outOfBudget
+                ? {
+                    title: "Review could not run: out of budget",
+                    summary: `${await loadBudgetSentence(db, run.id, run.status)} Use Re-run after raising the budget or when it resets.`,
+                }
+                : {
+                    title: "Review did not complete",
+                    summary: `wardby run ${run.id} ended with status "${run.status}" before publishing a review. Use Re-run to try again.`,
+                }),
+        });
+        await db.runHostCheck.update({ where: { runId: run.id }, data: { completedAt: new Date() } });
+    }
+    catch (err) {
+        log.warn({ err, runId: run.id }, "could not complete the run's host check");
+    }
+}

package/dist/core/review-host-tools.d.ts

@@ -0,0 +1,47 @@
+import type { LoadedTool } from "../providers/engine/types.js";
+import { type ReviewHostProvider, type ReviewHostRegistry } from "../providers/review-host/types.js";
+import { type RepoAccessDecision } from "./repo-access.js";
+export interface RepositoryLink {
+    provider: ReviewHostProvider;
+    repository: string;
+    access: "read" | "write";
+    checkName: string | null;
+}
+export interface RunHostCheckRef {
+    provider: string;
+    repository: string;
+    checkId: string;
+    /** The head the check was started on; the check is only the review's if the heads match. */
+    headSha: string;
+    /**
+     * The pull request the run was dispatched for. A check (the run's own, or a
+     * new one under the link's checkName) is only ever published for this PR;
+     * null (a row from before it was recorded) binds to no PR.
+     */
+    prNumber: number | null;
+}
+export interface ReviewToolContext {
+    agentId: string;
+    links: readonly RepositoryLink[];
+    hosts: ReviewHostRegistry;
+    /** The run's open check, if the control plane started one. */
+    runCheck: RunHostCheckRef | null;
+    /** Records that the run's check is now completed (RunHostCheck.completedAt). */
+    markRunCheckCompleted: () => Promise<void>;
+    /**
+     * Re-authorizes the link against its current stamp and the agent's current
+     * owner (core/repo-access.ts). Called before every host call; a denial or a
+     * throw refuses the call.
+     */
+    authorize: (link: RepositoryLink) => Promise<RepoAccessDecision>;
+}
+export declare const REVIEW_HOST_TOOL_DEFS: LoadedTool[];
+export declare const REVIEW_HOST_TOOL_NAMES: ReadonlySet<string>;
+export declare function resolveLink(links: readonly RepositoryLink[], repositoryArg: string): RepositoryLink | "ambiguous" | null;
+/**
+ * Dispatches one built-in repo tool call. Never throws — mirrors
+ * runner.ts's `runSandboxTool` contract: a failure becomes a JSON error
+ * result fed back to the model as the tool's result, not an engine-halting
+ * exception.
+ */
+export declare function handleReviewHostTool(name: string, argsJson: string, ctx: ReviewToolContext): Promise<string>;

package/dist/core/review-host-tools.js

@@ -0,0 +1,347 @@
+/**
+ * Built-in code-review tools (`repo_*`) for native agents with at least one
+ * AgentRepository link. Like the memory built-ins they are synthesized by the
+ * runner, recognized by name, and never run in the sandbox. The security
+ * boundary is here: every call names a repository, which must resolve to one
+ * of this agent's links (with write access for write tools); the host then
+ * mints its own least-permission credential. The model never sees a token,
+ * a check id, or a marker. Never throws — failures are JSON tool results.
+ * See docs/private/2026-09-25-code-review-host-design.md §7.
+ */
+import { z } from "zod";
+import { REVIEW_HOST_PROVIDERS, ReviewHostError, } from "../providers/review-host/types.js";
+import { normalizeGitHubRepository } from "../coding/protocol.js";
+import { logger } from "./logger.js";
+import { describeDenial } from "./repo-access.js";
+const log = logger.child({ module: "review-host-tools" });
+const DEFAULT_PATCH_CHARS = 60_000;
+const SHA = z.string().regex(/^[0-9a-f]{40}$/);
+const Repository = z.string().min(1).max(300);
+const PrReadArgs = z
+    .object({
+    repository: Repository,
+    prNumber: z.number().int().positive(),
+    sinceSha: SHA.optional(),
+    maxPatchChars: z.number().int().positive().max(200_000).optional(),
+})
+    .strict();
+const ReadFileArgs = z
+    .object({
+    repository: Repository,
+    path: z.string().min(1).max(500),
+    ref: z.string().min(1).max(200).optional(),
+    startLine: z.number().int().positive().optional(),
+    maxLines: z.number().int().positive().max(2000).optional(),
+})
+    .strict();
+const ListFilesArgs = z
+    .object({
+    repository: Repository,
+    ref: z.string().min(1).max(200).optional(),
+    pathPrefix: z.string().max(500).optional(),
+})
+    .strict();
+const InlineCommentArgs = z
+    .object({
+    path: z.string().min(1).max(500),
+    line: z.number().int().positive(),
+    side: z.enum(["LEFT", "RIGHT"]).optional(),
+    severity: z.string().min(1).max(20),
+    body: z.string().min(1).max(4000),
+})
+    .strict();
+const PublishArgs = z
+    .object({
+    repository: Repository,
+    prNumber: z.number().int().positive(),
+    headSha: SHA,
+    verdict: z.enum(["APPROVE", "CHANGES_REQUESTED", "COMMENT"]),
+    summary: z.string().min(1).max(140),
+    body: z.string().min(1).max(60_000),
+    comments: z.array(InlineCommentArgs).max(50).optional(),
+    resolveThreadIds: z
+        .array(z.string().regex(/^[A-Za-z0-9_=-]{1,100}$/))
+        .max(100)
+        .optional(),
+})
+    .strict();
+const CommentArgs = z
+    .object({
+    repository: Repository,
+    number: z.number().int().positive(),
+    body: z.string().min(1).max(20_000),
+    replyToReviewCommentId: z
+        .string()
+        .regex(/^\d{1,20}$/)
+        .optional(),
+})
+    .strict();
+const REPOSITORY_PROP = {
+    type: "string",
+    description: 'The repository as "owner/name" (or "github.com/owner/name"); must be one this agent is linked to.',
+};
+export const REVIEW_HOST_TOOL_DEFS = [
+    {
+        name: "repo_pr_read",
+        description: "Reads a pull request: title, body, author, state, refs, headSha, isFork, each changed file's unified-diff patch (patches share a character budget; truncated ones are flagged), lastReviewedSha — the head you last reviewed on this PR, if any — and openThreads: your own unresolved inline review threads (id, path, line, outdated, body). Pass sinceSha (usually lastReviewedSha) to get only what changed since then; if baseMergedSince is true, the base branch was merged in meanwhile and each file shows the PR's full diff against the base, limited to files that changed since sinceSha.",
+        jsonSchema: {
+            type: "object",
+            properties: {
+                repository: REPOSITORY_PROP,
+                prNumber: { type: "integer", minimum: 1 },
+                sinceSha: { type: "string", pattern: "^[0-9a-f]{40}$" },
+                maxPatchChars: { type: "integer", minimum: 1, maximum: 200000 },
+            },
+            required: ["repository", "prNumber"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "repo_read_file",
+        description: "Reads a file with line numbers (paged by startLine/maxLines, default 400 lines) or lists a directory, at a ref. Use the PR's headSha as the ref when reviewing.",
+        jsonSchema: {
+            type: "object",
+            properties: {
+                repository: REPOSITORY_PROP,
+                path: { type: "string" },
+                ref: { type: "string" },
+                startLine: { type: "integer", minimum: 1 },
+                maxLines: { type: "integer", minimum: 1, maximum: 2000 },
+            },
+            required: ["repository", "path"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "repo_list_files",
+        description: 'Lists every file (path and size) at a ref (default: the default branch), optionally under a path prefix such as "tests/". Skips node_modules, dist, and lockfiles.',
+        jsonSchema: {
+            type: "object",
+            properties: { repository: REPOSITORY_PROP, ref: { type: "string" }, pathPrefix: { type: "string" } },
+            required: ["repository"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "repo_publish_review",
+        description: "Publishes your review of one pull request head, in one call: inline comments on diff lines (a ```suggestion block in a comment body becomes a one-click fix; comments on lines outside the diff move to the summary automatically), one summary comment that is edited in place on later reviews, and — only on the pull request this run was started for, by an agent linked with a check name — the check conclusion (APPROVE = success, CHANGES_REQUESTED = failure, COMMENT = neutral). Pass resolveThreadIds with the ids of your openThreads that this head fixes; only your own open threads on this PR are resolved, and the result lists resolvedThreadIds and skippedThreadIds. Returns published:false with reason stale_head if the PR moved on; then stop.",
+        jsonSchema: {
+            type: "object",
+            properties: {
+                repository: REPOSITORY_PROP,
+                prNumber: { type: "integer", minimum: 1 },
+                headSha: { type: "string", pattern: "^[0-9a-f]{40}$" },
+                verdict: { type: "string", enum: ["APPROVE", "CHANGES_REQUESTED", "COMMENT"] },
+                summary: { type: "string", maxLength: 140, description: "One line, shown on the check." },
+                body: { type: "string", maxLength: 60000, description: "The full review in markdown." },
+                comments: {
+                    type: "array",
+                    maxItems: 50,
+                    items: {
+                        type: "object",
+                        properties: {
+                            path: { type: "string" },
+                            line: {
+                                type: "integer",
+                                minimum: 1,
+                                description: "Line number in the new file (side RIGHT) or the old file (side LEFT).",
+                            },
+                            side: { type: "string", enum: ["LEFT", "RIGHT"] },
+                            severity: { type: "string", description: "e.g. CRITICAL, MAJOR, MINOR, NIT" },
+                            body: { type: "string", maxLength: 4000 },
+                        },
+                        required: ["path", "line", "severity", "body"],
+                        additionalProperties: false,
+                    },
+                },
+                resolveThreadIds: {
+                    type: "array",
+                    maxItems: 100,
+                    items: { type: "string", pattern: "^[A-Za-z0-9_=-]{1,100}$" },
+                    description: "Ids from repo_pr_read's openThreads whose problem this head fixes. Leave a thread out when unsure.",
+                },
+            },
+            required: ["repository", "prNumber", "headSha", "verdict", "summary", "body"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "repo_comment",
+        description: "Posts a comment on an issue or pull request conversation, or — with replyToReviewCommentId — replies inside an inline review thread.",
+        jsonSchema: {
+            type: "object",
+            properties: {
+                repository: REPOSITORY_PROP,
+                number: { type: "integer", minimum: 1, description: "The issue or pull request number." },
+                body: { type: "string", maxLength: 20000 },
+                replyToReviewCommentId: { type: "string", pattern: "^\\d{1,20}$" },
+            },
+            required: ["repository", "number", "body"],
+            additionalProperties: false,
+        },
+    },
+];
+export const REVIEW_HOST_TOOL_NAMES = new Set(REVIEW_HOST_TOOL_DEFS.map((t) => t.name));
+const WRITE_TOOLS = new Set(["repo_publish_review", "repo_comment"]);
+const HOST_PREFIXES = { github: "github.com/" };
+function normalizeFor(provider, value) {
+    try {
+        if (provider === "github")
+            return normalizeGitHubRepository(value);
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export function resolveLink(links, repositoryArg) {
+    const raw = repositoryArg.trim();
+    for (const provider of REVIEW_HOST_PROVIDERS) {
+        const prefix = HOST_PREFIXES[provider];
+        if (raw.toLowerCase().startsWith(prefix)) {
+            const repository = normalizeFor(provider, raw.slice(prefix.length));
+            return links.find((l) => l.provider === provider && l.repository === repository) ?? null;
+        }
+    }
+    const matches = links.filter((l) => l.repository === normalizeFor(l.provider, raw));
+    if (matches.length > 1)
+        return "ambiguous";
+    return matches[0] ?? null;
+}
+function error(code, message = code) {
+    return JSON.stringify({ error: code, message });
+}
+/** Bookkeeping only: a failure to record the check completed is logged and never changes the tool result. */
+async function markCompleted(ctx) {
+    try {
+        await ctx.markRunCheckCompleted();
+    }
+    catch (err) {
+        log.warn({ err, agentId: ctx.agentId }, "could not record the run's check completed");
+    }
+}
+/**
+ * Dispatches one built-in repo tool call. Never throws — mirrors
+ * runner.ts's `runSandboxTool` contract: a failure becomes a JSON error
+ * result fed back to the model as the tool's result, not an engine-halting
+ * exception.
+ */
+export async function handleReviewHostTool(name, argsJson, ctx) {
+    let parsed;
+    try {
+        parsed = JSON.parse(argsJson || "{}");
+    }
+    catch (err) {
+        return error("invalid_arguments_json", err instanceof Error ? err.message : String(err));
+    }
+    const repositoryArg = parsed?.repository;
+    if (typeof repositoryArg !== "string")
+        return error("invalid_arguments", "repository is required");
+    const link = resolveLink(ctx.links, repositoryArg);
+    if (link === "ambiguous")
+        return error("repository_not_linked", "Ambiguous repository; qualify it as host/owner/name.");
+    if (!link)
+        return error("repository_not_linked", `This agent is not linked to "${repositoryArg}".`);
+    if (WRITE_TOOLS.has(name) && link.access !== "write") {
+        return error("write_access_required", `This agent's link to ${link.repository} is read-only.`);
+    }
+    const host = ctx.hosts[link.provider];
+    if (!host)
+        return error("host_not_configured", `No ${link.provider} host is configured on this deployment.`);
+    let decision;
+    try {
+        decision = await ctx.authorize(link);
+    }
+    catch (err) {
+        log.warn({ err, agentId: ctx.agentId }, "repository authorization failed; denying");
+        decision = { ok: false, reason: "check_failed" };
+    }
+    if (!decision.ok) {
+        log.info({ agentId: ctx.agentId, repository: link.repository, reason: decision.reason }, "repository use denied");
+        return error(decision.reason === "check_unavailable" ? "repository_access_unavailable" : "repository_access_denied", describeDenial(decision, link.repository));
+    }
+    try {
+        switch (name) {
+            case "repo_pr_read": {
+                const a = PrReadArgs.parse(parsed);
+                return JSON.stringify(await host.readPullRequest(link.repository, a.prNumber, {
+                    sinceSha: a.sinceSha,
+                    maxPatchChars: a.maxPatchChars ?? DEFAULT_PATCH_CHARS,
+                    agentMarker: ctx.agentId,
+                }));
+            }
+            case "repo_read_file": {
+                const a = ReadFileArgs.parse(parsed);
+                return JSON.stringify(await host.readFile(link.repository, a.path, a.ref, {
+                    startLine: a.startLine ?? 1,
+                    maxLines: a.maxLines ?? 400,
+                }));
+            }
+            case "repo_list_files": {
+                const a = ListFilesArgs.parse(parsed);
+                return JSON.stringify(await host.listFiles(link.repository, a.ref, a.pathPrefix));
+            }
+            case "repo_publish_review": {
+                const a = PublishArgs.parse(parsed);
+                const runCheck = ctx.runCheck;
+                // E-08/H5-4: a verdict check is only ever published on the PR this
+                // run was dispatched for (never a fork: those are never dispatched).
+                // Any other publish is comments only, with no check at all.
+                const samePullRequest = runCheck !== null &&
+                    runCheck.provider === link.provider &&
+                    runCheck.repository === link.repository &&
+                    runCheck.prNumber !== null &&
+                    runCheck.prNumber === a.prNumber;
+                const ownsCheck = samePullRequest && a.headSha === runCheck.headSha;
+                if (samePullRequest && !ownsCheck) {
+                    // The run's check sits on another head; close it rather than attach this review's verdict to it.
+                    try {
+                        await host.completeCheck(link.repository, {
+                            checkId: runCheck.checkId,
+                            conclusion: "neutral",
+                            title: "Superseded by a newer push",
+                            summary: "This run reviewed a newer commit; see that commit's check.",
+                        });
+                        await markCompleted(ctx);
+                    }
+                    catch (err) {
+                        log.warn({ err, agentId: ctx.agentId }, "could not supersede the run's check");
+                    }
+                }
+                const result = await host.publishReview(link.repository, {
+                    prNumber: a.prNumber,
+                    headSha: a.headSha,
+                    verdict: a.verdict,
+                    summary: a.summary,
+                    body: a.body,
+                    comments: (a.comments ?? []).map((c) => ({ ...c, side: c.side ?? "RIGHT" })),
+                    agentMarker: ctx.agentId,
+                    ...(samePullRequest && link.checkName ? { checkName: link.checkName } : {}),
+                    ...(ownsCheck ? { checkId: runCheck.checkId } : {}),
+                    ...(a.resolveThreadIds?.length ? { resolveThreadIds: a.resolveThreadIds } : {}),
+                });
+                if (ownsCheck)
+                    await markCompleted(ctx);
+                return JSON.stringify(result);
+            }
+            case "repo_comment": {
+                const a = CommentArgs.parse(parsed);
+                return JSON.stringify(await host.comment(link.repository, {
+                    number: a.number,
+                    body: a.body,
+                    replyToReviewCommentId: a.replyToReviewCommentId,
+                }));
+            }
+            default:
+                return error("unknown_tool", `No built-in tool named "${name}".`);
+        }
+    }
+    catch (err) {
+        if (err instanceof z.ZodError) {
+            return error("invalid_arguments", err.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; "));
+        }
+        if (err instanceof ReviewHostError)
+            return error(err.code, err.message);
+        return error("host_api_error", "The host request failed.");
+    }
+}

package/dist/core/run-heartbeat.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Liveness for native runs that no executor watches: an attended
+ * `wardby run` and a native sub-agent child, which runs inline inside its
+ * parent's tool call. Managed runs already beat through their executor
+ * (InProcessExecutor, DbosExecutor). A beat is what keeps a run's budget
+ * hold counted against its budget group (budget-groups.ts isHoldLive): once a
+ * process dies and the beats stop, the hold lapses on its own instead of
+ * pinning the group for the rest of the period.
+ */
+import type { PrismaClient } from "#prisma";
+type RunDb = Pick<PrismaClient, "run">;
+/** Beats `runId` once now and every `intervalMs` until `fn` settles. */
+export declare function withRunHeartbeat<T>(db: RunDb, runId: string, fn: () => Promise<T>, intervalMs?: number): Promise<T>;
+/** The part of `process` an interrupt handler needs (a fake in tests). */
+export interface SignalTarget {
+    once(signal: NodeJS.Signals, listener: () => void): unknown;
+    off(signal: NodeJS.Signals, listener: () => void): unknown;
+    exit(code: number): never | void;
+}
+/**
+ * For an attended run: on SIGINT/SIGTERM, record the run as `cancelled`
+ * (only if it is still pending/running) and exit with the conventional
+ * 128+signal code, instead of leaving a `running` row behind. Returns a
+ * function that removes the handlers once the run has finished.
+ */
+export declare function cancelRunOnSignal(db: RunDb, runId: string, target?: SignalTarget): () => void;
+export {};

package/dist/core/run-heartbeat.js

@@ -0,0 +1,54 @@
+import { HEARTBEAT_INTERVAL_MS } from "./timing.js";
+async function beat(db, runId) {
+    try {
+        await db.run.updateMany({
+            where: { id: runId, status: { in: ["pending", "running"] } },
+            data: { heartbeatAt: new Date() },
+        });
+    }
+    catch {
+        // A missed beat only lets the hold lapse a little sooner; never fatal to the run.
+    }
+}
+/** Beats `runId` once now and every `intervalMs` until `fn` settles. */
+export async function withRunHeartbeat(db, runId, fn, intervalMs = HEARTBEAT_INTERVAL_MS) {
+    await beat(db, runId);
+    const timer = setInterval(() => void beat(db, runId), intervalMs);
+    timer.unref?.();
+    try {
+        return await fn();
+    }
+    finally {
+        clearInterval(timer);
+    }
+}
+const EXIT_CODES = { SIGINT: 130, SIGTERM: 143 };
+/**
+ * For an attended run: on SIGINT/SIGTERM, record the run as `cancelled`
+ * (only if it is still pending/running) and exit with the conventional
+ * 128+signal code, instead of leaving a `running` row behind. Returns a
+ * function that removes the handlers once the run has finished.
+ */
+export function cancelRunOnSignal(db, runId, target = process) {
+    const handlers = new Map();
+    const remove = () => {
+        for (const [signal, handler] of handlers)
+            target.off(signal, handler);
+        handlers.clear();
+    };
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        const handler = () => {
+            remove();
+            void db.run
+                .updateMany({
+                where: { id: runId, status: { in: ["pending", "running"] } },
+                data: { status: "cancelled", error: `Interrupted by ${signal}.`, finishedAt: new Date() },
+            })
+                .catch(() => undefined)
+                .finally(() => target.exit(EXIT_CODES[signal] ?? 1));
+        };
+        handlers.set(signal, handler);
+        target.once(signal, handler);
+    }
+    return remove;
+}