@lchase/kiln 0.12.0 → 0.13.0

package/README.md

@@ -277,7 +277,7 @@ A cron fires once per slot. While serve was down, startup fires the latest misse
 
 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 the gate does not post, approve, or merge. There is no gated posting path for a review comment yet, so the draft stops there. `reviewPrompt` is a path to your own prompt file. Omitted, Kiln uses `prompts/kiln/review.md`.
+`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.
 

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

@@ -63,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",

package/dist/driver.js

@@ -18,6 +18,7 @@ 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";
@@ -97,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 ?? ""}`;
@@ -321,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 &&
@@ -340,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 } : {}),

package/dist/events.js

@@ -35,6 +35,8 @@ export const EVENT_NAMES = [
     "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();
@@ -164,6 +166,28 @@ const TriggerSkipped = z.object({
     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"),
@@ -233,6 +257,8 @@ export const EventSchema = z.discriminatedUnion("event", [
         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

@@ -174,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) {
@@ -304,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 };
+}

package/dist/report.js

@@ -132,6 +132,10 @@ export function statusDetails(job) {
         lines.push(`findings ${job.findingsPath}`);
     else if (job.workflow === INVESTIGATION_WORKFLOW && job.state === "done")
         lines.push("findings missing");
+    if (job.reviewUrl)
+        lines.push(`review ${job.reviewUrl}`);
+    if (job.reviewPostError)
+        lines.push(job.reviewPostError);
     if (job.prPending)
         lines.push("pull request not opened yet");
     if (job.state === "failed" && job.deliveryError)
@@ -222,6 +226,8 @@ function toStatusJob(job, observation) {
             ...(job.specPath ? { specPath: job.specPath } : {}),
             ...(job.logPath ? { logPath: job.logPath } : {}),
             ...(job.findingsPath ? { findingsPath: job.findingsPath } : {}),
+            ...(job.reviewPostError ? { reviewPostError: job.reviewPostError } : {}),
+            ...(job.reviewUrl ? { reviewUrl: job.reviewUrl } : {}),
             launchFailed: job.launchFailed,
             attemptCount: job.attemptCount ?? 0,
             maxAttempts: job.attemptCap ?? observation.maxAttempts,
@@ -270,6 +276,8 @@ function toStatusJob(job, observation) {
         ...(job.logPath ? { logPath: job.logPath } : {}),
         ...(job.specPath ? { specPath: job.specPath } : {}),
         ...(job.findingsPath ? { findingsPath: job.findingsPath } : {}),
+        ...(job.reviewPostError ? { reviewPostError: job.reviewPostError } : {}),
+        ...(job.reviewUrl ? { reviewUrl: job.reviewUrl } : {}),
         launchFailed: job.launchFailed,
         attemptCount: job.attemptCount ?? 0,
         maxAttempts: job.attemptCap ?? observation.maxAttempts,

package/dist/review-post.js

@@ -0,0 +1,269 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendEvent, readEvents } from "./events.js";
+import { classifyFailureText } from "./failure.js";
+import { realGitHub } from "./host.js";
+import { redact } from "./redact.js";
+import { parseReviewSource } from "./triggers.js";
+/**
+ * A review draft the human has not posted yet, and the COMMENT review Kiln
+ * writes after they approve the Inbox gate.
+ *
+ * The review event is always COMMENT. Kiln does not approve, request
+ * changes, or merge. A second approve at the same `review:<repo>:<number>:<sha>`
+ * does not post again.
+ */
+export const REVIEW_SEVERITIES = ["note", "nit", "warning", "blocking"];
+const NEEDS_HUMAN_REASON = "review-post";
+/** Target of a review-request job, or undefined when the draft is not tied to a pull request. */
+export function reviewTargetFrom(repo, sourceRef) {
+    if (!sourceRef)
+        return undefined;
+    const parsed = parseReviewSource(sourceRef);
+    if (!parsed || parsed.repo !== repo)
+        return undefined;
+    return {
+        repo: parsed.repo,
+        number: parsed.number,
+        sha: parsed.sha,
+        dedupe: `review:${parsed.repo}:${parsed.number}:${parsed.sha}`,
+    };
+}
+export function reviewAlreadyPosted(events, dedupe) {
+    return events.some((event) => event.event === "review.posted" && event.properties.dedupe === dedupe);
+}
+/**
+ * Latest post for this job. A `review.posted` for the same dedupe, including
+ * one recorded on another job, counts as posted.
+ */
+export function reviewPostForJob(events, job) {
+    const dedupe = job.source?.kind === "trigger" ? reviewTargetFrom(job.repo, job.source.ref)?.dedupe : undefined;
+    let url;
+    let error;
+    for (const event of events) {
+        const posted = event.event === "review.posted" &&
+            (event.job_id === job.jobId || (dedupe !== undefined && event.properties.dedupe === dedupe));
+        if (posted) {
+            url = event.properties.url;
+            error = undefined;
+            continue;
+        }
+        if (event.event === "review.failed" && event.job_id === job.jobId) {
+            url = undefined;
+            error = `Could not post the review (${event.properties.class}). ${event.properties.detail}`;
+        }
+    }
+    return { ...(url ? { url } : {}), ...(error ? { error } : {}) };
+}
+/** The draft step's artifact. Missing or unreadable is undefined. Extra fields are ignored. */
+export function readReviewDraft(checkout, runId) {
+    const path = join(checkout, ".runs", runId, "artifacts", "draft.json");
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return parseReviewDraft(JSON.parse(readFileSync(path, "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parseReviewDraft(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const markdown = value.markdown;
+    if (typeof markdown !== "string" || !markdown.trim())
+        return undefined;
+    const raw = value.findings;
+    const findings = [];
+    if (Array.isArray(raw)) {
+        for (const item of raw) {
+            const finding = parseFinding(item);
+            if (finding)
+                findings.push(finding);
+        }
+    }
+    return { markdown: markdown.trim(), findings };
+}
+/**
+ * Body is the draft markdown. Findings with a real file and line become
+ * inline comments. Anything else is folded into the body when the markdown
+ * does not already contain it. Line numbers are never invented.
+ */
+export function buildCommentReview(draft) {
+    const comments = [];
+    const skipped = [];
+    for (const finding of draft.findings) {
+        const path = commentPath(finding.file);
+        const line = commentLine(finding.line);
+        if (!path || line === undefined) {
+            skipped.push(finding);
+            continue;
+        }
+        comments.push({ path, line, body: commentText(finding) });
+    }
+    return {
+        body: redact(foldSkipped(draft.markdown, skipped)),
+        comments: comments.map((comment) => ({ ...comment, body: redact(comment.body) })),
+        findings: draft.findings.length,
+        inline: comments.length,
+        skipped: skipped.length,
+    };
+}
+/**
+ * Post the approved draft, or do nothing when that head SHA was already
+ * posted. Throws without calling gh when the factory is paused, the daily
+ * cap is blocking, or the post fails. The caller leaves the gate open on throw.
+ */
+export function postApprovedReview(input) {
+    const target = reviewTargetFrom(input.repo, input.sourceRef);
+    if (!target) {
+        recordNeedsHuman(input);
+        throw new Error("This review draft is not tied to a pull request, so Kiln will not post it.");
+    }
+    const events = readEvents(input.kilnDir, { warn: () => { } });
+    if (reviewAlreadyPosted(events, target.dedupe))
+        return;
+    if (input.paused) {
+        throw new Error("Paused. Kiln will not post this review until kiln resume.");
+    }
+    if (input.spendBlocked) {
+        throw new Error("Daily cap reached. Kiln will not post this review until the local day rolls over.");
+    }
+    const draft = readReviewDraft(input.checkout, input.runId);
+    if (!draft) {
+        failPost(input, target, "deterministic", "The draft artifact is missing or unreadable.");
+    }
+    const review = buildCommentReview(draft);
+    const poster = input.host.github.postCommentReview ?? realGitHub.postCommentReview;
+    if (!poster) {
+        failPost(input, target, "deterministic", "gh cannot post a review from this host.");
+    }
+    let posted;
+    try {
+        posted = poster.call(input.host.github, {
+            checkout: input.checkout,
+            number: target.number,
+            commitId: target.sha,
+            body: review.body,
+            comments: review.comments,
+        });
+    }
+    catch (error) {
+        const detail = publicDetail(error);
+        failPost(input, target, classifyFailureText(detail), detail);
+    }
+    appendEvent(input.kilnDir, {
+        job_id: input.jobId,
+        run_id: input.runId,
+        event: "review.posted",
+        step: "approve",
+        properties: {
+            repo: target.repo,
+            number: target.number,
+            sha: target.sha,
+            review_id: posted.id,
+            url: posted.url,
+            findings: review.findings,
+            inline: review.inline,
+            skipped: review.skipped,
+            dedupe: target.dedupe,
+            once: `posted:${target.dedupe}`,
+        },
+    });
+}
+function failPost(input, target, failureClass, detail) {
+    const clipped = detail.trim() || "The review was not posted.";
+    appendEvent(input.kilnDir, {
+        job_id: input.jobId,
+        run_id: input.runId,
+        event: "review.failed",
+        step: "approve",
+        properties: {
+            repo: target.repo,
+            number: target.number,
+            sha: target.sha,
+            class: failureClass,
+            detail: clipped,
+            dedupe: target.dedupe,
+        },
+    });
+    recordNeedsHuman(input);
+    throw new Error(`Could not post the review (${failureClass}). ${clipped}`);
+}
+function recordNeedsHuman(input) {
+    appendEvent(input.kilnDir, {
+        job_id: input.jobId,
+        run_id: input.runId,
+        event: "needs-human",
+        step: "approve",
+        properties: { reason: NEEDS_HUMAN_REASON, once: `needs-human:${NEEDS_HUMAN_REASON}` },
+    });
+}
+function publicDetail(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const cleaned = redact(message).replace(/\s+/g, " ").trim();
+    if (cleaned.length > 500)
+        return `${cleaned.slice(0, 499)}…`;
+    return cleaned || "The review was not posted.";
+}
+function parseFinding(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const record = value;
+    if (typeof record.comment !== "string" || !record.comment.trim())
+        return undefined;
+    const severity = REVIEW_SEVERITIES.find((item) => item === record.severity) ?? "note";
+    const file = typeof record.file === "string" ? record.file : undefined;
+    const line = commentLine(record.line);
+    return {
+        severity,
+        comment: record.comment.trim(),
+        ...(file !== undefined ? { file } : {}),
+        ...(line !== undefined ? { line } : {}),
+    };
+}
+/** A relative path inside the repo. Absolute paths and `..` are not locations. A leading `./` is a normal relative path. */
+export function commentPath(file) {
+    if (!file)
+        return undefined;
+    const raw = file.trim().replace(/\\/g, "/");
+    if (!raw || raw.startsWith("/") || raw.startsWith("~") || /^[A-Za-z]:/.test(raw))
+        return undefined;
+    if (/[\0\r\n]/.test(raw))
+        return undefined;
+    const parts = raw.split("/");
+    if (parts.some((part) => part === "" || part === ".."))
+        return undefined;
+    const cleaned = parts.filter((part) => part !== ".");
+    if (cleaned.length === 0)
+        return undefined;
+    return cleaned.join("/");
+}
+function commentLine(line) {
+    if (typeof line !== "number" || !Number.isInteger(line) || line < 1)
+        return undefined;
+    return line;
+}
+function commentText(finding) {
+    const text = finding.comment.trim();
+    if (finding.severity === "nit")
+        return `**nit** (not blocking)\n\n${text}`;
+    return `**${finding.severity}**\n\n${text}`;
+}
+function foldSkipped(markdown, skipped) {
+    const base = markdown.trim();
+    const extra = skipped.filter((finding) => !base.includes(finding.comment.trim()));
+    if (extra.length === 0)
+        return `${base}\n`;
+    const lines = [
+        base,
+        "",
+        "## Not posted on a line",
+        "",
+        "These findings had no file and line Kiln could check, so they are only in this review.",
+        "",
+    ];
+    for (const finding of extra)
+        lines.push(`- **${finding.severity}** ${finding.comment.trim()}`);
+    return `${lines.join("\n")}\n`;
+}

package/dist/serve-page.js

@@ -137,7 +137,7 @@ function triggersHtml(rows) {
     const body = rows.length === 0
         ? `<p class="empty">No triggers.</p>`
         : rows.map((row) => triggerCard(row)).join("\n");
-    return `<header class="list-head"><h2>Triggers</h2><p class="meta">The clock, Jira, and pull request activity can start work. Kiln does not post, approve, or merge.</p><p class="form-error" id="trigger-error" role="alert" hidden></p></header>${body}`;
+    return `<header class="list-head"><h2>Triggers</h2><p class="meta">The clock, Jira, and pull request activity can start work. A review is posted only after you approve it. Kiln does not approve or merge.</p><p class="form-error" id="trigger-error" role="alert" hidden></p></header>${body}`;
 }
 function triggerCard(row) {
     const on = row.enabled;
@@ -166,7 +166,7 @@ function listHtml(model, csrf) {
         return `<header class="list-head"><h2>Inbox</h2><p class="meta">Approve, reject, or revise. Kiln does not do this on its own.</p></header>${jobList(board.inbox, "inbox", "Nothing is waiting on a gate.", csrf)}`;
     }
     if (model.section === "hand") {
-        return `<header class="list-head"><h2>Needs a hand</h2><p class="meta">A breaker tripped, a cap was hit, or a run failed with no retry left.</p></header>${jobList(board.hand, "hand", "Nothing needs a person.", csrf)}`;
+        return `<header class="list-head"><h2>Needs a hand</h2><p class="meta">A breaker tripped, a cap was hit, a review could not be posted, or a run failed with no retry left.</p></header>${jobList(board.hand, "hand", "Nothing needs a person.", csrf)}`;
     }
     if (model.section === "history") {
         return `<header class="list-head"><h2>History</h2></header>${jobList(board.history, "history", "No finished jobs.", csrf)}`;
@@ -266,7 +266,7 @@ function dependsHtml(job) {
     return `<p class="deps">depends on ${links}</p>${detail ? `<p class="meta">${escapeHtml(detail)}</p>` : ""}`;
 }
 function actionsHtml(job, section, csrf) {
-    const showGate = section === "inbox" || section === "job";
+    const showGate = section === "inbox" || section === "job" || (section === "hand" && Boolean(job.reviewPostError));
     const showRetry = section === "hand" || section === "repos" || section === "job";
     if (!showGate && !showRetry)
         return "";

package/dist/triggers.js

@@ -34,6 +34,16 @@ const BUILTIN_ROUTES = [
     { id: PR_ACTIVITY_TRIGGER, trigger: PR_ACTIVITY_TRIGGER, action: "attach" },
 ];
 const REVIEW_REF = /^review:([^:]+):(\d+):([0-9a-f]{7,64})$/i;
+/** `review:<repo>:<number>:<head sha>` from a review-request job. SHA is lowercase. */
+export function parseReviewSource(ref) {
+    const match = REVIEW_REF.exec(ref);
+    const repo = match?.[1];
+    const number = Number(match?.[2]);
+    const sha = match?.[3]?.toLowerCase();
+    if (!repo || !sha || !Number.isInteger(number) || number <= 0)
+        return undefined;
+    return { repo, number, sha };
+}
 export function effectiveTriggers(file) {
     const byId = new Map();
     for (const trigger of BUILTIN_TRIGGERS)
@@ -234,7 +244,7 @@ export function jiraIssueEvent(triggerId, repo, issue) {
 export function reviewHeadOf(job) {
     if (job.workflow !== REVIEW_WORKFLOW || job.source?.kind !== "trigger")
         return undefined;
-    return REVIEW_REF.exec(job.source.ref)?.[3];
+    return parseReviewSource(job.source.ref)?.sha;
 }
 /** Download the pull request head when the checkout does not have that commit yet. */
 export function ensureReviewHead(checkout, prNumber, sha) {
@@ -490,7 +500,7 @@ function reviewSpec(input) {
     if (input.url)
         lines.push(`Pull request: ${input.url}`);
     lines.push(`Number: ${input.number}`, `Head: ${input.sha}`, `Base: ${input.base}`, "");
-    lines.push("Read the change and return a draft review.", "Do not post, approve, merge, or push.", "Approving the gate keeps the draft. Kiln does not post it to GitHub.", "");
+    lines.push("Read the change and return a draft review.", "Do not post, approve, merge, or push.", "Approving the gate posts this draft as a pull request comment. Kiln does not approve the pull request or merge it.", "");
     return lines.join("\n");
 }
 function appendFire(config, event, now) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lchase/kiln",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Run a workflow on any registered repo. A markdown spec is the input.",
   "license": "MIT",
   "type": "module",

package/prompts/kiln/review.md

@@ -1,6 +1,6 @@
 Kiln runs this review inside yak. The working directory is an isolated worktree at `{{input.baseRef}}`. That commit is the pull request head. Do not guess a branch name.
 
-Read the change. Return a draft review and nothing else. Do not post the review, approve the pull request, merge it, push, or comment. Do not change product code. Do not create, modify, or delete files. Read-only git and file inspection are allowed.
+Read the change. Return a draft review and nothing else. Do not post the review, approve the pull request, merge it, push, or comment. Kiln posts the draft only after a person approves the gate, and only as a comment. Do not change product code. Do not create, modify, or delete files. Read-only git and file inspection are allowed.
 
 Return JSON with `markdown` and `findings`. `findings` is a list. Each item has `severity` (`note`, `nit`, `warning`, or `blocking`), `file`, `line`, and `comment`. `comment` is the text a person might post later. `markdown` is the whole draft a person will read, and it must include every finding with its severity, file, line, and suggested comment. If you find nothing, return an empty `findings` list and say so in `markdown`.
 

package/workflows/review.yaml

@@ -1,9 +1,9 @@
 # Draft review of one pull request, run by yak (@lchase/yak).
 #
 # The agent returns findings (severity, file, line, suggested comment).
-# A person approves or rejects the draft in the Inbox. Approving does not
-# post, approve, or merge on GitHub: Kiln has no gated posting path for a
-# review comment, so the draft stops here.
+# A person approves or rejects the draft in the Inbox. Approving posts the
+# draft as a pull request comment. Kiln does not approve the pull request
+# or merge it. Rejecting or revising does not post.
 #
 # `reviewPrompt` in the kiln config replaces prompts/kiln/review.md.
 # The packaged file is the generic default.
@@ -60,5 +60,5 @@ steps:
             decision: { type: string, enum: [approve, reject] }
           required: [decision]
       render:
-        inline: "Draft review for \"{{input.title}}\"?\n\nApproving keeps this draft. Kiln does not post it to GitHub.\n\n{{draft.markdown}}"
+        inline: "Draft review for \"{{input.title}}\"?\n\nApproving posts this draft as a pull request comment. Kiln does not approve the pull request or merge it.\n\n{{draft.markdown}}"
     produces: approval