@lchase/kiln 0.3.0 → 0.5.0

package/dist/report.js

@@ -1,6 +1,8 @@
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
+import { readBoardFiles, readReviewRounds } from "./board.js";
+import { feedbackRoundText } from "./feedback.js";
 import { INVESTIGATION_WORKFLOW } from "./findings.js";
 import { inFlightCount, isDone, isLanded, jobState, } from "./reconcile.js";
 export function shellQuote(value) {
@@ -29,6 +31,52 @@ export function gateAnswerCommand(checkout, runId, gate, choice, title) {
     const titlePrefix = title ? `KILN_TASK_TITLE=${shellQuote(title)} ` : "";
     return `cd ${shellQuote(checkout)} && mkdir -p ${pendingDir} && printf '%s\\n' ${shellQuote(answer)} > ${answerFile} && ${titlePrefix}${yakInvocation("resume", runId)}`;
 }
+/**
+ * Mark a workflow's leaf steps from yak journal events.
+ * A later `step.started` reopens a step that already completed (the next loop round).
+ * Events whose id is not in the plan are ignored when the plan is non-empty,
+ * so a loop container does not sit beside its body. An empty plan uses
+ * first-seen event order.
+ */
+export function stepProgress(plan, events) {
+    const order = [...plan];
+    const phase = new Map();
+    for (const id of order)
+        phase.set(id, "pending");
+    for (const event of events) {
+        if (!event.stepId)
+            continue;
+        if (!phase.has(event.stepId)) {
+            if (plan.length > 0)
+                continue;
+            order.push(event.stepId);
+            phase.set(event.stepId, "pending");
+        }
+        if (event.t === "step.started")
+            phase.set(event.stepId, "current");
+        else if (event.t === "step.completed")
+            phase.set(event.stepId, "done");
+        else if (event.t === "step.failed")
+            phase.set(event.stepId, "failed");
+    }
+    return order.map((id) => ({ id, phase: phase.get(id) ?? "pending" }));
+}
+/** Detail of the latest step that failed and has not started or completed since. */
+export function latestStepFailure(events) {
+    const settled = new Set();
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (!event)
+            continue;
+        if (event.t === "step.started" || event.t === "step.completed") {
+            settled.add(event.stepId);
+            continue;
+        }
+        if (event.t === "step.failed" && !settled.has(event.stepId) && event.detail)
+            return event.detail;
+    }
+    return undefined;
+}
 /**
  * Derived state for every job, or for one id.
  * Throws `No job <id>` when that id is not on disk, same as `kiln status`.
@@ -76,6 +124,22 @@ export function statusDetails(job) {
         lines.push(`log ${job.logPath}`);
     if (job.state === "failed" && job.launchError)
         lines.push(job.launchError);
+    if (job.ledgerError)
+        lines.push(job.ledgerError);
+    if (job.feedbackLedgerError)
+        lines.push(job.feedbackLedgerError);
+    if ((job.feedbackRounds?.length ?? 0) > 0)
+        lines.push(`feedback ${job.feedbackRounds?.length}`);
+    if (job.state === "needs-human" && job.feedbackReason)
+        lines.push(`reason ${job.feedbackReason}`);
+    if (job.attemptCount > 0)
+        lines.push(`attempts ${job.attemptCount}`);
+    if (job.lastFailureReason)
+        lines.push(`reason ${job.lastFailureReason}`);
+    if (job.nextRetryAt)
+        lines.push(`next retry ${job.nextRetryAt}`);
+    if (job.state === "dead" && job.attemptCount > 0)
+        lines.push(`retry: kiln retry ${job.jobId}`);
     if (job.noReadableApproval)
         lines.push("no readable approval decision");
     if (job.cancelCommand)
@@ -122,6 +186,10 @@ function toStatusJob(job, observation) {
             ...(job.logPath ? { logPath: job.logPath } : {}),
             ...(job.findingsPath ? { findingsPath: job.findingsPath } : {}),
             launchFailed: job.launchFailed,
+            attemptCount: job.attemptCount ?? 0,
+            maxAttempts: observation.maxAttempts,
+            ...(job.lastFailureReason ? { lastFailureReason: job.lastFailureReason } : {}),
+            ...(job.nextRetryAt ? { nextRetryAt: job.nextRetryAt } : {}),
             invalidReason: job.error,
             prPending: false,
             prClosedUnmerged: false,
@@ -129,13 +197,23 @@ function toStatusJob(job, observation) {
             gates: [],
             canApprove: false,
             canReject: false,
+            steps: progressFor(job),
+            ...(job.createdAt ? { createdAt: job.createdAt } : {}),
+            ...(job.logTail ? { logTail: job.logTail } : {}),
+            ...boardFields(job),
         };
     }
     const state = jobState(job, observation);
-    const gates = state === "needs-human" && job.run ? job.run.gates.map(toGateView) : [];
+    const feedbackReason = job.feedbackExhausted
+        ? "feedback-exhausted"
+        : job.feedbackAmbiguous
+            ? "feedback-ambiguous"
+            : undefined;
+    const gates = state === "needs-human" && job.run && !feedbackReason ? job.run.gates.map(toGateView) : [];
     const prNumber = job.delivery?.prNumber;
     const runId = job.run?.runId;
-    const showBranch = (state === "done" || state === "in-review") && runId !== undefined;
+    const showBranch = runId !== undefined && (state === "done" || state === "in-review" || feedbackReason !== undefined);
+    const failureDetail = job.run?.stepEvents ? latestStepFailure(job.run.stepEvents) : undefined;
     return {
         jobId: job.jobId,
         title: job.title,
@@ -153,20 +231,73 @@ function toStatusJob(job, observation) {
         ...(job.specPath ? { specPath: job.specPath } : {}),
         ...(job.findingsPath ? { findingsPath: job.findingsPath } : {}),
         launchFailed: job.launchFailed,
+        attemptCount: job.attemptCount ?? 0,
+        maxAttempts: observation.maxAttempts,
+        ...(job.lastFailureReason ? { lastFailureReason: job.lastFailureReason } : {}),
+        ...(job.nextRetryAt && !job.retriesExhausted ? { nextRetryAt: job.nextRetryAt } : {}),
+        ...(job.ledgerError ? { ledgerError: job.ledgerError } : {}),
+        ...(job.feedbackLedgerError ? { feedbackLedgerError: job.feedbackLedgerError } : {}),
+        ...(feedbackReason ? { feedbackReason } : {}),
         ...(job.launchError ? { launchError: job.launchError } : {}),
         ...(job.delivery?.error ? { deliveryError: job.delivery.error } : {}),
         ...(job.delivery?.viewError ? { viewError: job.delivery.viewError } : {}),
         prPending: state === "in-review" && !prNumber,
         prClosedUnmerged: job.delivery?.prState === "CLOSED",
         noReadableApproval: state === "failed" && job.run?.status === "ok" && !job.run.gateDecision,
-        ...(state === "dead" && job.run
+        ...(job.run && (job.run.status === "dead" || state === "dead")
             ? { cancelCommand: `fix: cd ${shellQuote(job.run.checkout)} && ${yakInvocation("cancel", job.run.runId)}` }
             : {}),
         gates,
         canApprove: gates.some((gate) => gate.choices.includes("approve")),
         canReject: gates.some((gate) => gate.choices.includes("reject")),
+        steps: progressFor(job),
+        ...(job.createdAt ? { createdAt: job.createdAt } : {}),
+        ...(job.run?.startedAt ? { startedAt: job.run.startedAt } : {}),
+        ...(job.run?.finishedAt ? { finishedAt: job.run.finishedAt } : {}),
+        ...(job.logTail ? { logTail: job.logTail } : {}),
+        ...(job.diffSummary ? { diffSummary: job.diffSummary } : {}),
+        ...(failureDetail ? { failureDetail } : {}),
+        ...boardFields(job),
     };
 }
+function boardFields(job) {
+    const runDir = job.run ? join(job.run.checkout, ".runs", job.run.runId) : undefined;
+    const rounds = readReviewRounds(runDir);
+    const files = readBoardFiles({
+        ...(runDir ? { runDir } : {}),
+        ...(job.specPath ? { specPath: job.specPath } : {}),
+        ...(job.findingsPath ? { findingsPath: job.findingsPath } : {}),
+        ...(job.workflow !== INVESTIGATION_WORKFLOW && job.diffSummary ? { diffSummary: job.diffSummary } : {}),
+        ...(job.logTail ? { logTail: job.logTail } : {}),
+        ...(job.workflow ? { workflow: job.workflow } : {}),
+        gates: job.run?.gates ?? [],
+    });
+    for (const round of job.feedbackRounds ?? []) {
+        const label = round.trigger === "ci" ? "CI" : "review";
+        files.push({
+            id: `feedback-r${round.round}`,
+            group: "Feedback",
+            label: `R${round.round} ${label}.md`,
+            text: feedbackRoundText(round),
+            tone: round.outcome ? "good" : "warn",
+        });
+    }
+    return {
+        ...(rounds.length > 0 ? { rounds } : {}),
+        ...(job.feedbackRounds?.length ? { feedbackRounds: job.feedbackRounds } : {}),
+        ...(files.length > 0 ? { files } : {}),
+    };
+}
+function progressFor(job) {
+    if (job.fixInProgress && !job.run) {
+        return [
+            { id: "build", phase: "current" },
+            { id: "land", phase: "pending" },
+        ];
+    }
+    const plan = job.run?.stepPlan?.length ? job.run.stepPlan : (job.stepPlan ?? []);
+    return stepProgress(plan, job.run?.stepEvents ?? []);
+}
 function toGateView(gate) {
     const choices = gate.choices?.length ? gate.choices : ["approve", "reject"];
     return {
@@ -217,7 +348,7 @@ function blockReasons(job, observation) {
     }
     return reasons;
 }
-export function renderTick(observation, actions, launches, delivers = [], findings = []) {
+export function renderTick(observation, actions, launches, delivers = [], findings = [], notes = [], feedbackNotes = []) {
     const lines = [`tick  inFlight=${inFlightCount(observation)}  maxConcurrent=${observation.maxConcurrent}`];
     for (const job of observation.jobs) {
         if (job.error)
@@ -237,18 +368,30 @@ export function renderTick(observation, actions, launches, delivers = [], findin
             ? `findings ${recorded.jobId}  ${recorded.path}`
             : `findings ${recorded.jobId}  missing`);
     }
+    for (const note of notes) {
+        const next = note.nextRetryAt ? `  next ${note.nextRetryAt}` : "  dead";
+        lines.push(`${note.kind} ${note.jobId}  ${note.reason}  attempt ${note.attempt}${next}`);
+    }
+    for (const note of feedbackNotes) {
+        if (note.trim())
+            lines.push(note);
+    }
     for (const launch of launches) {
-        lines.push(`launch ${launch.jobId}  ${launch.repo}`);
+        const verb = launch.kind === "fix" ? "fix" : launch.retry ? "retry" : "launch";
+        lines.push(`${verb} ${launch.jobId}  ${launch.repo}`);
         for (const line of launch.output.split("\n")) {
             if (line.trim())
                 lines.push(`  ${line}`);
         }
     }
-    if (!actions.some((action) => action.type === "launch") &&
-        launches.length === 0 &&
-        delivers.length === 0 &&
-        findings.length === 0) {
+    const acted = actions.some((action) => action.type === "launch" ||
+        action.type === "retry" ||
+        action.type === "start-fix" ||
+        action.type === "mark-feedback") ||
+        launches.length > 0 ||
+        delivers.length > 0 ||
+        findings.length > 0;
+    if (!acted)
         lines.push("nothing to launch");
-    }
     return `${lines.join("\n")}\n`;
 }

package/dist/schemas.js

@@ -26,9 +26,27 @@ export const JiraConfigSchema = z.object({
     email: z.string().optional(),
     apiToken: z.string().optional(),
 });
+/** No yak event and no log output for this long stalls a running job. `<= 0` disables it. */
+export const DEFAULT_STALL_TIMEOUT_MS = 15 * 60 * 1000;
+/** Transient failures retry until this many attempts, then the job is dead. */
+export const DEFAULT_MAX_ATTEMPTS = 3;
+/** Pull request fix rounds before the job is needs-human (`feedback-exhausted`). */
+export const DEFAULT_MAX_FIX_ROUNDS = 2;
 export const KilnConfigFileSchema = z.object({
     note: z.string().min(1).optional(),
     maxConcurrent: z.number().int().min(1).optional(),
+    /**
+     * Milliseconds without a yak event or log output before a running job is
+     * killed and retried. Default 15 minutes. `0` or negative disables stall detection.
+     */
+    stallTimeoutMs: z.number().int().optional(),
+    /** Transient failures before the job is dead. Default 3. */
+    maxAttempts: z.number().int().min(1).optional(),
+    /**
+     * Fix rounds for an open pull request before the job is needs-human with
+     * reason `feedback-exhausted`. Default 2. Kiln does not merge.
+     */
+    maxFixRounds: z.number().int().min(1).optional(),
     adapter: z.enum(["mock", "claude-code"]).optional(),
     repos: z.record(z.string(), RepoEntrySchema),
     jira: JiraConfigSchema.optional(),
@@ -79,7 +97,9 @@ export const JobSchema = z.object({
  * `deliver=pr`. It does not enter `in-review`. A reject, a failure, a dead
  * process, and an ok run with no readable approval do not unblock an
  * after-merged dependent. A stacked job unblocks when its one upstream has
- * landed, which includes `in-review`.
+ * landed, which includes `in-review`. `dead` is also a job whose transient
+ * failures have used `maxAttempts`. Those attempts live under the kiln
+ * directory, not in this file.
  */
 export const JOB_STATES = [
     "queued",