@lchase/kiln 0.11.0 → 0.13.0

package/README.md

@@ -254,6 +254,33 @@ By default, serve runs `kiln tick` once when it starts and then every 30 seconds
 
 The Jira API token is not rendered. Do not commit checkout paths or job files.
 
+## Triggers
+
+A trigger starts work without `kiln add`. `kiln serve` evaluates triggers on each tick. `kiln tick` does the same pass once. Config is the `triggers` and `routes` arrays in `kiln.config.json`, re-read when the file changes.
+
+Two triggers are built in. `review-requests` is a schedule, cron `0 * * * *` (minute 0 of every hour, local time). `pr-activity` reads Kiln-owned pull requests from the same snapshot the fix loop already fetched. It does not poll a second time. Add a Jira trigger per repo when you want one:
+
+```json
+{
+  "triggers": [
+    { "id": "sample-ready", "kind": "jira", "repo": "web", "every": "5m", "label": "sample", "status": "Ready" }
+  ],
+  "routes": [
+    { "id": "sample-ready", "trigger": "sample-ready", "action": "create", "workflow": "feature", "repo": "web" }
+  ]
+}
+```
+
+`every` defaults to `5m` (`30s`, `5m`, `1h`). `label` and `status` compile to JQL. A `jql` string replaces them. `enabled` defaults to true. The Triggers page and `PUT /api/settings` send `{ "triggers": [{ "id", "enabled" }] }` and leave cron, JQL, and repo on the file.
+
+A cron fires once per slot. While serve was down, startup fires the latest missed slot once and does not replay the ones behind it. A Jira poll that was missed does the same: one search, not one per skipped interval. The router writes `trigger.routed` with a `dedupe` property (`review:<repo>:<number>:<head sha>`, `jira:<trigger>:<issue>`, `pr:<job>:<comment>`). A later tick that sees that value does not create another job. Comments and commits from `kiln`, a `[bot]` login, a `kiln:` subject, or a `Kiln-Job` trailer are ignored.
+
+A failed fire stores `last_error` and `lastErrorAt` under `<kiln-home>/triggers/state.json`, appends `trigger.failed`, and waits for the next slot. It does not retry on the next tick. Pause and the daily dollar cap append `trigger.skipped` with reason `paused` or `capped` and do not queue the fire.
+
+`review-requests` lists open pull requests where your `gh` user is the requested reviewer (`gh pr list --search review-requested:@me` in each registered GitHub repo). A pull request already drafted at that head SHA is skipped. The `review` workflow returns findings (severity, file, line, suggested comment) and stops on a gate in the Inbox. Approving that gate posts the draft as a pull request comment (`COMMENT` only) under your `gh` user: the markdown is the body, and findings with a file and line are inline comments. Kiln does not approve the pull request or merge it. Rejecting or revising the gate does not post. Pause and the daily cap do not post. Posting the same repo, pull request, and head SHA again does not create a second review. A failed post stays in Needs a hand with `review.failed` and does not count as posted. `reviewPrompt` is a path to your own prompt file. Omitted, Kiln uses `prompts/kiln/review.md`.
+
+Jira search sends `JIRA_API_TOKEN` only as a Basic header in a child process. The token is not written into the job, the spec, or the event log. Polling is the only Jira ingress. A webhook can later call the same issue-to-event function.
+
 ## Tick, status, approve
 
 ```bash

package/assets/serve.css

@@ -257,6 +257,26 @@ body.open .drawer { transform: none; }
 .repo-row .num { font-family: var(--mono); font-size: 13px; }
 .repo-row .d-actions { margin-top: 0; flex: none; }
 #settings-error { white-space: pre-wrap; }
+.trigger {
+  border: 1px solid var(--line);
+  background: var(--card);
+  border-radius: 10px;
+  padding: 14px 16px;
+  margin: 0 0 12px;
+}
+.trigger h3 { margin: 0 0 4px; color: var(--ink); font-size: 15px; letter-spacing: 0; text-transform: none; }
+.trigger .err { margin: 6px 0 0; color: var(--human); font-family: var(--mono); font-size: 12px; line-height: 16px; }
+.trigger button {
+  margin-top: 10px;
+  background: var(--card-hover);
+  border: 1px solid var(--line-strong);
+  border-radius: 6px;
+  padding: 4px 10px;
+  cursor: pointer;
+}
+.trigger .recent { list-style: none; margin: 10px 0 0; padding: 0; }
+.trigger .recent li { margin: 4px 0; font-size: 12px; line-height: 16px; color: var(--muted); }
+.trigger .ev { font-family: var(--mono); color: var(--ink); }
 
 @media (max-width: 960px) {
   .shell { grid-template-columns: 1fr; }

package/assets/serve.js

@@ -911,6 +911,54 @@
       .catch(function () { showSettingsError("Could not load settings."); });
   }
 
+  function toggleTrigger(button) {
+    var id = button.getAttribute("data-trigger-toggle");
+    var enabled = button.getAttribute("data-enabled") !== "true";
+    var error = document.getElementById("trigger-error");
+    if (error) error.hidden = true;
+    button.disabled = true;
+    fetch("/api/settings", { cache: "no-store", headers: { Accept: "application/json" } })
+      .then(function (response) { return response.json().then(function (data) { return { ok: response.ok, data: data }; }); })
+      .then(function (result) {
+        if (!result.ok) throw new Error((result.data && result.data.error) || "Could not load settings.");
+        var data = result.data;
+        var toggles = [];
+        var buttons = document.querySelectorAll("[data-trigger-toggle]");
+        for (var i = 0; i < buttons.length; i++) {
+          var buttonId = buttons[i].getAttribute("data-trigger-toggle");
+          var on = buttons[i].getAttribute("data-enabled") === "true";
+          if (buttonId === id) on = enabled;
+          toggles.push({ id: buttonId, enabled: on });
+        }
+        var body = { revision: data.revision, repos: data.repos || {}, triggers: toggles };
+        ["stallTimeoutMs", "maxAttempts", "maxFixRounds", "maxSameFingerprint", "dailyDollarCap"].forEach(function (key) {
+          if (data[key] !== undefined && data[key] !== null) body[key] = data[key];
+        });
+        if (data.sandbox) body.sandbox = data.sandbox;
+        return fetch("/api/settings", {
+          method: "PUT",
+          headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            "X-Kiln-CSRF": document.body.getAttribute("data-csrf") || "",
+          },
+          body: JSON.stringify(body),
+        });
+      })
+      .then(function (response) { return response.json().then(function (data) { return { ok: response.ok, data: data }; }); })
+      .then(function (result) {
+        if (!result.ok) throw new Error((result.data && result.data.error) || "Could not save settings.");
+        location.reload();
+      })
+      .catch(function (err) {
+        button.disabled = false;
+        if (error) {
+          error.hidden = false;
+          error.textContent = err && err.message ? err.message : "Could not update the trigger.";
+        }
+      });
+  }
+
   function saveSettings() {
     if (settingsSaving) return;
     if (!flushEditor()) return;
@@ -1011,6 +1059,11 @@
   document.addEventListener("click", function (event) {
     var target = event.target;
     if (!target || !target.closest) return;
+    var triggerToggle = target.closest("[data-trigger-toggle]");
+    if (triggerToggle) {
+      toggleTrigger(triggerToggle);
+      return;
+    }
     var settingsControl = target.closest("#open-settings");
     if (settingsControl) {
       if (settingsControl.tagName !== "A") openSettings();

package/dist/attention.js

@@ -102,6 +102,8 @@ function toItem(job) {
 export function attentionReason(job, tail = errorTail(job)) {
     switch (job.state) {
         case "needs-human": {
+            if (job.reviewPostError)
+                return job.reviewPostError;
             if (job.stopReason === "attempt-cap")
                 return "Attempt cap reached";
             if (job.stopReason === "fingerprint")

package/dist/board-view.js

@@ -61,6 +61,8 @@ export function parseSeenQuery(values) {
     return seen;
 }
 export function isInbox(job) {
+    if (job.reviewPostError)
+        return false;
     if (job.canApprove || job.canReject || job.canRevise)
         return true;
     return job.state === "needs-human" && job.gates.length > 0 && !job.stopReason && !job.feedbackReason;
@@ -504,11 +506,14 @@ function toBoardJob(job, events) {
         spec: Boolean(job.specPath),
         log: Boolean(job.logPath),
         ...(job.logTail?.trim() ? { logTail: job.logTail.trim() } : {}),
+        ...(job.reviewPostError ? { reviewPostError: job.reviewPostError } : {}),
     };
 }
 function finishedLine(job) {
     if (job.state === "rejected")
         return "Rejected";
+    if (job.workflow === "review")
+        return job.reviewUrl ? "comment posted" : "approved";
     if (job.prNumber)
         return `merged · PR #${job.prNumber}`;
     if (job.prUrl && httpUrl(job.prUrl))
@@ -525,6 +530,8 @@ function httpUrl(url) {
     }
 }
 function handLine(job, failure) {
+    if (job.reviewPostError)
+        return job.reviewPostError;
     let label = "Needs a person";
     if (job.stopReason === "attempt-cap")
         label = "Attempt cap";

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { addRepo, renderRepoList, resolveKilnConfig } from "./config.js";
 import { renderSandboxStatus, runSandboxBuild } from "./sandbox.js";
 import { answerJob, retryJob, reviseJob, runStatus, runTick } from "./driver.js";
+import { productionHost } from "./host.js";
 import { pauseFactory, resumeFactory } from "./rails.js";
 import { parseSince, renderLedgerFile } from "./ledger.js";
 import { startServe } from "./serve.js";
@@ -62,7 +63,9 @@ function usage() {
         "yak/<run-id> and opens a draft pull request. An investigation is done when",
         "its gate is approved. It does not open a pull request. status prints the",
         "derived state, and the findings path once an investigation is approved.",
-        "approve and reject answer the human gate. retry launches a failed or dead",
+        "approve and reject answer the human gate. Approving a review draft posts",
+        "it as a pull request comment and does not approve or merge that pull request.",
+        "retry launches a failed or dead",
         "job again, the same way tick launches, and clears the attempt ledger.",
         "A landed job that only failed to open its pull request is delivered again.",
         "A running job with no yak event or log output for stallTimeoutMs (default",
@@ -88,6 +91,11 @@ function usage() {
         "that requests changes starts a fix on that same branch, up to maxFixRounds",
         "(default 2). Kiln does not merge, approve, or comment. Past that bound the",
         "job is needs-human with reason feedback-exhausted.",
+        "Triggers in the kiln config start work without kiln add. A cron fires",
+        "on the serve tick in local time, once per slot, and once on startup",
+        "when a slot was missed. Jira polls are per repo. Kiln-owned pull",
+        "request activity uses the same read as the fix loop. A failed fire",
+        "waits for the next slot. Pause and the daily cap skip the fire.",
         "",
         "serve listens on 127.0.0.1. The page is a board of workflow stages:",
         "queued, spec, build, review, approve, land, PR review, Done (landed locally),",
@@ -401,7 +409,7 @@ function tickCommand(argv) {
         usage();
     }
     const config = resolveKilnConfig({ configPath: flags.configPath });
-    process.stdout.write(runTick(config));
+    process.stdout.write(runTick(config, productionHost()));
 }
 function statusCommand(argv) {
     const flags = parseFlags(argv);

package/dist/config.js

@@ -54,6 +54,11 @@ export function loadKilnConfig(configPath, options = {}) {
         sandbox: parsed.data.sandbox ?? {},
         workflowSandbox: workflowSandboxFrom(parsed.data.workflows),
         ...(jira ? { jira } : {}),
+        triggers: parsed.data.triggers ?? [],
+        routes: parsed.data.routes ?? [],
+        ...(parsed.data.reviewPrompt
+            ? { reviewPrompt: resolveConfiguredPath(configDir, parsed.data.reviewPrompt, home) }
+            : {}),
     };
 }
 /**

package/dist/driver.js

@@ -18,10 +18,12 @@ import { jobBasename, packageRoot } from "./paths.js";
 import { decide, isLanded, jobState, } from "./reconcile.js";
 import { fileMtimeMs, isPidAlive, readAttemptLedger, recoverRuns, resetAttemptLedger, } from "./reliability.js";
 import { projectRunJournal, promptsHash } from "./project.js";
+import { postApprovedReview, reviewPostForJob } from "./review-post.js";
 import { gateAnswerCommand, renderStatus, renderTick, statusView, yakCliPath, sandboxFailureDetail, } from "./report.js";
 import { AGENT_SANDBOX_IMAGE, injectAgentSandbox, jobIsSandboxed, probeSandboxEnvironment, PROXY_SANDBOX_IMAGE, requiredSandboxImages, resolveSandbox, sandboxIsEnabled, sandboxPreflight, sandboxPreflightFor, } from "./sandbox.js";
 import { JobSchema } from "./schemas.js";
-import { leafStepIds, materializeWorkflow, workflowInputs, workflowNeedsTestCommand, workflowStepPlan } from "./workflow.js";
+import { ensureReviewHead, evaluateTriggers, recordOwnedPullRequest, reviewHeadOf, } from "./triggers.js";
+import { leafStepIds, materializeWorkflow, REVIEW_WORKFLOW, workflowInputs, workflowNeedsTestCommand, workflowStepPlan, } from "./workflow.js";
 const TAG_PREFIX = "kiln:";
 export function jobTag(jobId) {
     return `${TAG_PREFIX}${jobId}`;
@@ -53,8 +55,14 @@ export function runTick(config, host = defaultHost(), options = {}) {
         const midway = observe(config, host, now);
         bindOpenFixRuns(config, midway);
         const published = publishReadyFixes(config, host, midway);
+        evaluateTriggers({
+            config,
+            now,
+            startup: options.triggerStartup ?? startup,
+            ...(host.reviews ? { reviews: host.reviews } : {}),
+        });
         const world = observe(config, host, now);
-        const feedbackNotes = watchPullRequests(config, world, host);
+        const feedbackNotes = watchPullRequests(config, world, host, now);
         const actions = decide(world.observation, now);
         if (world.observation.spendBlocked) {
             recordDailyCap(config.kilnDir, spendSnapshot(readEvents(config.kilnDir, { warn: () => { } }), config.dailyDollarCap, now), now);
@@ -90,6 +98,19 @@ export function answerJob(config, jobId, choice, host = defaultHost()) {
     if (!gate) {
         throw new Error(`Job ${jobId} has no open gate that accepts ${choice}.`);
     }
+    if (choice === "approve" && job.workflow === REVIEW_WORKFLOW) {
+        postApprovedReview({
+            kilnDir: config.kilnDir,
+            jobId,
+            runId: job.run.runId,
+            repo: job.repo,
+            sourceRef: job.source?.kind === "trigger" ? job.source.ref : undefined,
+            checkout: job.run.checkout,
+            host,
+            paused: world.observation.paused === true,
+            spendBlocked: world.observation.spendBlocked === true,
+        });
+    }
     const command = gateAnswerCommand(job.run.checkout, job.run.runId, gate, choice, job.run.title ?? job.title);
     const result = spawnSync("sh", ["-c", command], { encoding: "utf8" });
     const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
@@ -314,6 +335,9 @@ function observe(config, host, now = new Date()) {
         const findingsPath = entry.job?.workflow === INVESTIGATION_WORKFLOW
             ? existingFindingsPath(config.kilnDir, entry.job.id)
             : undefined;
+        const reviewPost = entry.job
+            ? reviewPostForJob(events, { jobId: entry.job.id, repo: entry.job.repo, source: entry.job.source })
+            : {};
         const logTail = readLogTail(logPath);
         const stepPlan = entry.job ? workflowStepPlan(entry.job.workflow) : undefined;
         const diffSummary = run &&
@@ -333,6 +357,8 @@ function observe(config, host, now = new Date()) {
             ...(entry.job?.stack ? { stack: true } : {}),
             ...(delivery ? { delivery } : {}),
             ...(findingsPath ? { findingsPath } : {}),
+            ...(reviewPost.error ? { reviewPostError: reviewPost.error } : {}),
+            ...(reviewPost.url ? { reviewUrl: reviewPost.url } : {}),
             launching,
             launchFailed,
             ...(launchError ? { launchError } : {}),
@@ -749,7 +775,7 @@ function gateEdit(checkout, runId, stepId) {
  * Read each open pull request once per tick and attach a plan.
  * `readStatus` does not call this. A host with no feedback reader does not watch.
  */
-function watchPullRequests(config, world, host) {
+function watchPullRequests(config, world, host, now) {
     const notes = [];
     if (!host.feedback)
         return notes;
@@ -775,11 +801,28 @@ function watchPullRequests(config, world, host) {
             ledger,
             snapshot,
         });
+        recordOwnedPullRequest(config, {
+            jobId: job.jobId,
+            repo: job.repo,
+            prNumber: job.delivery?.prNumber ?? 0,
+            headSha: snapshot.headSha,
+            comments: snapshot.comments.map((comment) => ({
+                id: comment.id,
+                author: comment.author,
+                body: comment.body,
+                resolved: comment.resolved,
+            })),
+            reviews: snapshot.reviews.map((review) => ({
+                id: review.id,
+                author: review.author,
+                body: review.body,
+            })),
+        }, now);
     }
     return notes;
 }
 function shouldWatch(job) {
-    if (job.deliver !== "pr" || job.workflow === INVESTIGATION_WORKFLOW)
+    if (job.deliver !== "pr" || job.workflow === INVESTIGATION_WORKFLOW || job.workflow === REVIEW_WORKFLOW)
         return false;
     if (job.error || job.feedbackLedgerError || job.feedbackExhausted || job.feedbackAmbiguous)
         return false;
@@ -1041,7 +1084,9 @@ function launchJob(config, world, job, host, sandboxFacts) {
     if (workflowNeedsTestCommand(sourceWorkflow) && !testCommand?.trim()) {
         throw new Error(`Repo ${job.repo} has no test command. Set repos.${job.repo}.test. The feature workflow refuses to run an empty KILN_TEST.`);
     }
-    const workflow = materializeWorkflow(config.kilnDir, job.id, job.workflow);
+    const workflow = materializeWorkflow(config.kilnDir, job.id, job.workflow, {
+        ...(config.reviewPrompt ? { reviewPrompt: config.reviewPrompt } : {}),
+    });
     const logPath = join(config.kilnDir, "logs", `${jobBasename(job.id)}.log`);
     mkdirSync(dirname(logPath), { recursive: true });
     ensureCheckoutExcludes(repo.path);
@@ -1053,14 +1098,23 @@ function launchJob(config, world, job, host, sandboxFacts) {
         if (blocked)
             return { jobId: job.id, repo: job.repo, output: blocked };
         assertStackTarget(world, job);
-        baseSha = resolveLaunchBase({
-            checkout: repo.path,
-            deliver: repo.deliver,
-            stack: job.stack === true,
-            ...(repo.base ? { configuredBase: repo.base } : {}),
-            ...(job.stack ? { upstreamBranch: upstreamLocalBranch(world, job) } : {}),
-            git: host.git,
-        });
+        const pinned = reviewHeadOf(job);
+        if (pinned) {
+            const number = Number(job.source?.ref.split(":")[2]);
+            if (Number.isInteger(number) && number > 0)
+                ensureReviewHead(repo.path, number, pinned);
+            baseSha = resolveCommit(host, repo.path, pinned);
+        }
+        else {
+            baseSha = resolveLaunchBase({
+                checkout: repo.path,
+                deliver: repo.deliver,
+                stack: job.stack === true,
+                ...(repo.base ? { configuredBase: repo.base } : {}),
+                ...(job.stack ? { upstreamBranch: upstreamLocalBranch(world, job) } : {}),
+                git: host.git,
+            });
+        }
         specText = specHandedToYak(config, world, job);
     }
     catch (error) {

package/dist/events.js

@@ -9,8 +9,8 @@ import { redactDeep } from "./redact.js";
  * parses it. A write failure is reported and does not escape to the caller.
  *
  * `run_id` and `step` are null when the moment has none. `job_id` is null
- * for `config.reloaded`, `kiln.paused`, `kiln.resumed`, and `budget.blocked`,
- * which are not a job.
+ * for `config.reloaded`, `kiln.paused`, `kiln.resumed`, `budget.blocked`,
+ * and trigger fires that do not belong to a job yet.
  */
 export const EVENT_NAMES = [
     "job.added",
@@ -31,6 +31,12 @@ export const EVENT_NAMES = [
     "kiln.paused",
     "kiln.resumed",
     "budget.blocked",
+    "trigger.fired",
+    "trigger.routed",
+    "trigger.failed",
+    "trigger.skipped",
+    "review.posted",
+    "review.failed",
 ];
 const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
 const once = z.string().min(1).optional();
@@ -131,6 +137,57 @@ const BudgetBlocked = z.object({
     cap: z.number().nonnegative(),
     once,
 });
+const TriggerFired = z.object({
+    trigger_id: z.string().min(1),
+    source: z.enum(["schedule", "jira", "pr", "review"]),
+    /** Stable dedupe id. Not named `key`: the redactor masks any property with that name. */
+    dedupe: z.string().min(1),
+    external_id: z.string().min(1),
+    revision: z.string().min(1),
+    repo: z.string().min(1).optional(),
+    title: z.string().min(1).optional(),
+    once,
+});
+const TriggerRouted = z.object({
+    trigger_id: z.string().min(1),
+    dedupe: z.string().min(1),
+    action: z.enum(["create", "attach"]),
+    workflow: z.string().min(1).optional(),
+    repo: z.string().min(1).optional(),
+    once,
+});
+const TriggerFailed = z.object({
+    trigger_id: z.string().min(1),
+    error: z.string().min(1),
+    once,
+});
+const TriggerSkipped = z.object({
+    trigger_id: z.string().min(1),
+    reason: z.enum(["paused", "capped"]),
+    once,
+});
+const ReviewPosted = z.object({
+    repo: z.string().min(1),
+    number: z.number().int().positive(),
+    sha: z.string().regex(/^[0-9a-f]{7,64}$/i),
+    review_id: z.string().min(1),
+    url: z.string().min(1),
+    findings: z.number().int().nonnegative(),
+    inline: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative(),
+    /** `review:<repo>:<number>:<head sha>`. Same shape as the review-request dedupe. */
+    dedupe: z.string().min(1),
+    once,
+});
+const ReviewFailed = z.object({
+    repo: z.string().min(1),
+    number: z.number().int().positive(),
+    sha: z.string().regex(/^[0-9a-f]{7,64}$/i),
+    class: z.enum(["transient", "deterministic", "budget"]),
+    detail: z.string().min(1),
+    dedupe: z.string().min(1),
+    once,
+});
 const envelope = {
     id: z.string().min(1),
     ts: z.string().regex(ISO_UTC, "ts must be ISO-8601 UTC"),
@@ -176,6 +233,32 @@ export const EventSchema = z.discriminatedUnion("event", [
         job_id: z.string().min(1).nullable(),
         properties: BudgetBlocked,
     }),
+    z.object({
+        ...envelope,
+        event: z.literal("trigger.fired"),
+        job_id: z.string().min(1).nullable(),
+        properties: TriggerFired,
+    }),
+    z.object({
+        ...envelope,
+        event: z.literal("trigger.routed"),
+        job_id: z.string().min(1).nullable(),
+        properties: TriggerRouted,
+    }),
+    z.object({
+        ...envelope,
+        event: z.literal("trigger.failed"),
+        job_id: z.string().min(1).nullable(),
+        properties: TriggerFailed,
+    }),
+    z.object({
+        ...envelope,
+        event: z.literal("trigger.skipped"),
+        job_id: z.string().min(1).nullable(),
+        properties: TriggerSkipped,
+    }),
+    z.object({ ...envelope, event: z.literal("review.posted"), job_id: z.string().min(1), properties: ReviewPosted }),
+    z.object({ ...envelope, event: z.literal("review.failed"), job_id: z.string().min(1), properties: ReviewFailed }),
 ]);
 const LOCK_WAIT_MS = 5_000;
 const pauseBuf = new Int32Array(new SharedArrayBuffer(4));

package/dist/host.js

@@ -18,6 +18,59 @@ export class HostError extends Error {
 export function defaultHost() {
     return { github: realGitHub, git: realGitRemote, feedback: realPullRequestFeedback };
 }
+/** `kiln tick` and `kiln serve`. Review requests use the operator's gh auth. */
+export function productionHost() {
+    return { ...defaultHost(), reviews: { list: listReviewRequests } };
+}
+/**
+ * Open pull requests awaiting the authenticated user's review, per registered repo.
+ * A remote that is not GitHub is skipped, so a local test origin does not call gh.
+ */
+export function listReviewRequests(repos) {
+    const found = [];
+    for (const repo of repos) {
+        if (!githubRemote(repo.path))
+            continue;
+        const result = spawnSync(ghBin(), ["pr", "list", "--search", "review-requested:@me", "--state", "open", "--limit", "50", "--json", "number,title,url,headRefOid"], {
+            cwd: repo.path,
+            encoding: "utf8",
+            timeout: 20_000,
+            env: { ...process.env, GH_PROMPT_DISABLED: "1", GIT_TERMINAL_PROMPT: "0" },
+        });
+        if (result.error || result.status !== 0) {
+            throw new HostError(`Could not list review requests for ${repo.name}.`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout || "[]");
+        }
+        catch {
+            throw new HostError("gh pr list returned data that is not JSON.");
+        }
+        if (!Array.isArray(parsed))
+            throw new HostError("gh pr list returned data that is not a list.");
+        for (const item of parsed) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const record = item;
+            const number = typeof record.number === "number" ? record.number : Number.NaN;
+            const sha = typeof record.headRefOid === "string" ? record.headRefOid.trim().toLowerCase() : "";
+            if (!Number.isInteger(number) || number <= 0 || !/^[0-9a-f]{7,64}$/.test(sha))
+                continue;
+            const title = typeof record.title === "string" && record.title.trim() ? record.title.trim() : `PR ${number}`;
+            const url = typeof record.url === "string" ? record.url : "";
+            found.push({ repo: repo.name, number, title, url, headSha: sha });
+        }
+    }
+    return found;
+}
+function githubRemote(checkout) {
+    const result = gitResult(checkout, ["remote", "get-url", "origin"]);
+    if (result.status !== 0)
+        return false;
+    const url = result.stdout.trim();
+    return /github\.com[:/]/i.test(url);
+}
 const YAK_BRANCH = /^yak\/[A-Za-z0-9._-]+$/;
 function assertYakBranch(branch, baseBranch) {
     if (branch === baseBranch || branch === `refs/heads/${baseBranch}`) {
@@ -121,11 +174,12 @@ export const realGitRemote = {
 function ghBin() {
     return process.env.KILN_GH && process.env.KILN_GH.length > 0 ? process.env.KILN_GH : "gh";
 }
-function runGh(checkout, args) {
+function runGh(checkout, args, input) {
     const bin = ghBin();
     const result = spawnSync(bin, args, {
         cwd: checkout,
         encoding: "utf8",
+        input,
         env: { ...process.env, GH_PROMPT_DISABLED: "1", GIT_TERMINAL_PROMPT: "0" },
     });
     if (result.error) {
@@ -251,4 +305,55 @@ export const realGitHub = {
         }
         return { state: asState(parsed.state), mergedAt: asMergedAt(parsed.mergedAt) };
     },
+    postCommentReview(input) {
+        return submitCommentReview(input);
+    },
 };
+/**
+ * `POST /repos/{owner}/{repo}/pulls/{number}/reviews` with `event: COMMENT`.
+ * One call submits the review. There is no pending-review step, no approve,
+ * and no merge.
+ */
+export function submitCommentReview(input) {
+    const repo = githubOwnerRepo(input.checkout);
+    const event = "COMMENT";
+    const payload = {
+        commit_id: input.commitId,
+        body: input.body,
+        event,
+    };
+    if (input.comments.length > 0) {
+        payload.comments = input.comments.map((comment) => ({
+            path: comment.path,
+            body: comment.body,
+            line: comment.line,
+            side: "RIGHT",
+        }));
+    }
+    const result = runGh(input.checkout, ["api", "--method", "POST", `repos/${repo.owner}/${repo.name}/pulls/${input.number}/reviews`, "--input", "-"], JSON.stringify(payload));
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout).trim() || "gh api failed";
+        throw new HostError(`Could not post the pull request review: ${detail}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        throw new HostError("gh api returned data that is not a pull request review.");
+    }
+    const id = typeof parsed.id === "number" || typeof parsed.id === "string" ? String(parsed.id) : "";
+    const url = typeof parsed.html_url === "string" ? parsed.html_url.trim() : "";
+    if (!id || !url)
+        throw new HostError("gh api did not return a review id and URL.");
+    return { id, url };
+}
+function githubOwnerRepo(checkout) {
+    const result = runGh(checkout, ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"]);
+    const name = result.stdout.trim();
+    const [owner, repo] = name.split("/");
+    if (result.status !== 0 || !owner || !repo || name.split("/").length !== 2) {
+        throw new HostError(`Could not read owner/name for the review: ${(result.stderr || result.stdout).trim() || name || "gh repo view failed"}`);
+    }
+    return { owner, name: repo };
+}