@lchase/kiln 0.6.0 → 0.7.0

package/dist/attention.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { INVESTIGATION_WORKFLOW } from "./findings.js";
+import { AUTH_FAILED_LINE } from "./auth.js";
 import { SANDBOX_PREFLIGHT_PREFIX } from "./sandbox.js";
 /**
  * Attention order for `kiln serve`. Built from the same derived jobs as
@@ -104,8 +105,12 @@ export function attentionReason(job, tail = errorTail(job)) {
             return question ? `Gate: ${oneLine(question)}` : "Waiting on a person";
         }
         case "dead":
+            if (job.lastFailureReason === "auth-failed")
+                return AUTH_FAILED_LINE;
             return job.sandboxError ? `Sandbox: ${oneLine(job.sandboxError)}` : "Run died before it finished";
         case "failed": {
+            if (job.lastFailureReason === "auth-failed")
+                return AUTH_FAILED_LINE;
             if (job.sandboxError)
                 return `Sandbox: ${oneLine(job.sandboxError)}`;
             const why = failureLine(job.launchError) || firstLine(job.deliveryError) || firstLine(job.failureDetail) || firstLine(tail) || "Run failed";

package/dist/auth.js

@@ -0,0 +1,48 @@
+/**
+ * Claude credential shape, checked before tick or serve launches yak.
+ * A missing token is allowed: Claude Code can use a macOS keychain login.
+ * A set-but-unusable value is not, because Claude prefers it and then 401s.
+ * The text names the variable and never includes the value.
+ */
+export const AUTH_PREFLIGHT_PREFIX = "Claude credentials are not usable:";
+/** Printed on an authentication failure. The attempt is not retried. */
+export const AUTH_FAILED_LINE = "Claude login rejected (401) — check CLAUDE_CODE_OAUTH_TOKEN / claude login, then Retry";
+const OAUTH_PREFIX = "sk-ant-oat";
+export function claudeCredentialPreflight(env, adapter) {
+    if (adapter !== "claude-code")
+        return undefined;
+    const lines = [];
+    if (Object.prototype.hasOwnProperty.call(env, "CLAUDE_CODE_OAUTH_TOKEN")) {
+        const value = (env.CLAUDE_CODE_OAUTH_TOKEN ?? "").trim();
+        if (!value) {
+            lines.push("CLAUDE_CODE_OAUTH_TOKEN is set but empty. Unset it, or export a token from `claude setup-token` (it starts with sk-ant-oat). Kiln will not launch.");
+        }
+        else if (!value.startsWith(OAUTH_PREFIX)) {
+            lines.push("CLAUDE_CODE_OAUTH_TOKEN is set but does not look like a Claude OAuth token (expected a value starting with sk-ant-oat). Kiln will not launch.");
+        }
+    }
+    if (Object.prototype.hasOwnProperty.call(env, "ANTHROPIC_API_KEY")) {
+        const value = (env.ANTHROPIC_API_KEY ?? "").trim();
+        if (!value) {
+            lines.push("ANTHROPIC_API_KEY is set but empty. Unset it, or export a key. Kiln will not launch.");
+        }
+    }
+    if (lines.length === 0)
+        return undefined;
+    return `${AUTH_PREFLIGHT_PREFIX}\n${lines.join("\n")}`;
+}
+/**
+ * True when yak's failure detail or the run log shows a rejected Claude login.
+ * `401`, `Invalid bearer token`, and `Failed to authenticate` are the strings
+ * the Claude CLI and the API put on stderr. Yak copies that stderr tail into
+ * the `step.failed` detail and prints the same line on its own stderr, which
+ * Kiln stores under `<kiln-dir>/logs`.
+ */
+export function authenticationFailureLine(texts) {
+    const haystack = texts.join("\n");
+    if (!haystack)
+        return undefined;
+    if (/Invalid bearer token|Failed to authenticate|\b401\b/.test(haystack))
+        return AUTH_FAILED_LINE;
+    return undefined;
+}

package/dist/board.js

@@ -11,7 +11,8 @@ const CATALOG = [
     { id: "explore", label: "Explore", who: "investigator · opus" },
     { id: "land", label: "Land", who: "git commit" },
     { id: "pr-review", label: "PR review", who: "pr-sync" },
-    { id: "merged", label: "Merged", who: "main", tone: "merged" },
+    { id: "done", label: "Done", who: "local", tone: "merged" },
+    { id: "merged", label: "Merged", who: "pr", tone: "merged" },
     { id: "needs-human", label: "Needs human", who: "approve · retry", tone: "human" },
 ];
 const STEP_STAGE = {
@@ -41,7 +42,7 @@ export function stageOf(job) {
     if (job.state === "in-review")
         return "pr-review";
     if (job.state === "done")
-        return "merged";
+        return job.prUrl || job.prNumber ? "merged" : "done";
     const current = job.steps.find((step) => step.phase === "current" || step.phase === "failed");
     if (job.state === "queued" || job.state === "blocked")
         return "queued";
@@ -86,10 +87,14 @@ export function stagesFor(jobs) {
     if (workflows.has("investigation"))
         wanted.add("explore");
     wanted.add("queued");
-    wanted.add("merged");
     wanted.add("needs-human");
-    for (const job of jobs)
-        wanted.add(stageOf(job));
+    const reached = new Set(jobs.map((job) => stageOf(job)));
+    if (reached.has("done") || !reached.has("merged"))
+        wanted.add("done");
+    if (reached.has("merged"))
+        wanted.add("merged");
+    for (const id of reached)
+        wanted.add(id);
     return CATALOG.filter((stage) => wanted.has(stage.id));
 }
 const REVIEW_FILE = /^(security|ux|ui|code)(?:\.(\d+))?\.json$/;

package/dist/cli.js

@@ -12,7 +12,7 @@ function usage() {
     console.error([
         "Usage: kiln repo add <name> <path> [--test <cmd>] [--deliver local|pr] [--base <branch>] [--config <file>]",
         "       kiln repo list [--config <file>]",
-        "       kiln add <workflow> --repo <name> (--spec <file.md> | --prompt <text> | --jira <KEY>) [--title <text>] [--after <jobId>]... [--stack] [--dry-run] [--config <file>]",
+        "       kiln add <workflow> --repo <name> (--spec <file.md> | --prompt <text> | --jira <KEY>) [--title <text>] [--issue <KEY>] [--after <jobId>]... [--stack] [--dry-run] [--config <file>]",
         "       kiln import <dir> --repo <name> [--workflow <name>] [--context <file.md>] [--stack] [--dry-run] [--config <file>]",
         "       kiln tick [--config <file>]",
         "       kiln status [jobId] [--config <file>]",
@@ -22,8 +22,10 @@ function usage() {
         "       kiln sandbox [build] [--config <file>]",
         "       kiln serve [--port 4100] [--tick <seconds>|--no-tick] [--config <file>]",
         "",
-        "repo add registers a checkout. A relative path is stored absolute, resolved",
-        "from the working directory. ~ is expanded from the home directory.",
+        "repo add registers a checkout and prints the deliver mode (default local)",
+        "and how to change it. Adding an existing name updates that repo in place.",
+        "A relative path is stored absolute, resolved from the working directory.",
+        "~ is expanded from the home directory.",
         "",
         "Config, jobs, logs, and deliveries live in one kiln home: --config <file>",
         "if given, otherwise $KILN_HOME/kiln.config.json when KILN_HOME is set,",
@@ -34,6 +36,8 @@ function usage() {
         "",
         "add writes one job from a spec file, from --prompt text (--prompt - reads stdin),",
         "or from a Jira Cloud issue (--jira PROJ-123). Pass one of those, not more.",
+        "--issue KEY stores an issue id (KEY-123). With deliver=pr the draft title",
+        "defaults to [KEY] title. A job with no issue keeps its title.",
         "The repo and the workflow (workflows/<name>.yaml) must already exist.",
         "--after names jobs that must be done before this one launches. --stack waits",
         "for one upstream to land and opens the pull request against that branch.",
@@ -59,6 +63,7 @@ function usage() {
         "15 minutes; 0 disables it) is killed and retried. A crash, a non-zero exit,",
         "or a process that is already gone when tick or serve starts (orphaned) retries",
         "after 10s, 20s, 40s, and so on, capped at 5 minutes, up to maxAttempts",
+        "A rejected Claude login (401 or an invalid bearer token) is auth-failed and is not retried.",
         "(default 3). The job is then dead. A rejected gate is not retried.",
         "Attempts are files under the kiln home, not fields on the job.",
         "Once a pull request is open, tick watches it. A failed check or a review",
@@ -67,10 +72,17 @@ function usage() {
         "job is needs-human with reason feedback-exhausted.",
         "",
         "serve listens on 127.0.0.1. The page is a board of workflow stages:",
-        "queued, spec, build, review, approve, land, PR review, merged, and needs human.",
-        "Empty stages collapse. Approve, reject, and retry call the same",
-        "functions as the CLI. POST from another origin is rejected. A tick",
-        "runs every 30 seconds unless --no-tick is set, using the tick lock.",
+        "queued, spec, build, review, approve, land, PR review, Done (landed locally),",
+        "Merged (pull request), and needs human. An empty board shows Done.",
+        "Empty stages collapse. Approve, reject, retry, and Add job call the same",
+        "functions as the CLI. Settings edits repos and the global limits in the",
+        "config file and writes it without a restart. POST and PUT send the page's",
+        "CSRF token. A request whose",
+        "Origin or Host is not this localhost port is rejected. Before each",
+        "request and each tick, serve re-reads the kiln config when the file's",
+        "mtime or size changed. A file that fails to load keeps the last good",
+        "config. A tick runs every 30 seconds unless --no-tick is set, using the",
+        "tick lock.",
         "",
         "sandbox prints the resolved mode, allowlist, and anything missing before a",
         "sandboxed run can start. sandbox build builds the yak agent and proxy images",
@@ -151,6 +163,13 @@ function parseFlags(argv) {
             i += 1;
             continue;
         }
+        if (flag === "--issue") {
+            if (!next || next.startsWith("--"))
+                usage();
+            bag.issue = next;
+            i += 1;
+            continue;
+        }
         if (flag === "--after") {
             if (!next || next.startsWith("--"))
                 usage();
@@ -263,6 +282,7 @@ async function addCommand(argv) {
             repo: flags.repo,
             key: flags.jira,
             ...(flags.title !== undefined ? { title: flags.title } : {}),
+            ...(flags.issue !== undefined ? { issue: flags.issue } : {}),
             dependsOn: flags.after,
             ...(flags.stack ? { stack: true } : {}),
             dryRun: flags.dryRun,
@@ -278,6 +298,7 @@ async function addCommand(argv) {
             repo: flags.repo,
             specPath: flags.spec,
             ...(flags.title !== undefined ? { title: flags.title } : {}),
+            ...(flags.issue !== undefined ? { issue: flags.issue } : {}),
             dependsOn: flags.after,
             ...(flags.stack ? { stack: true } : {}),
             cwd: process.cwd(),
@@ -287,6 +308,7 @@ async function addCommand(argv) {
             repo: flags.repo,
             prompt: flags.prompt ?? "",
             ...(flags.title !== undefined ? { title: flags.title } : {}),
+            ...(flags.issue !== undefined ? { issue: flags.issue } : {}),
             dependsOn: flags.after,
             ...(flags.stack ? { stack: true } : {}),
         });
@@ -302,6 +324,7 @@ function importCommand(argv) {
         flags.spec ||
         flags.prompt ||
         flags.title ||
+        flags.issue ||
         flags.after.length > 0 ||
         flags.test ||
         flags.deliver ||
@@ -401,6 +424,7 @@ function hasIntakeFlags(flags) {
         flags.prompt ||
         flags.jira ||
         flags.title ||
+        flags.issue ||
         flags.workflow ||
         flags.context ||
         flags.dryRun ||

package/dist/config.js

@@ -2,9 +2,8 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "no
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { KilnConfigError } from "./errors.js";
-import { DEFAULT_MAX_ATTEMPTS, DEFAULT_MAX_FIX_ROUNDS, DEFAULT_STALL_TIMEOUT_MS, KilnConfigFileSchema, } from "./schemas.js";
+import { DEFAULT_MAX_ATTEMPTS, DEFAULT_MAX_FIX_ROUNDS, DEFAULT_STALL_TIMEOUT_MS, KilnConfigFileSchema, REPO_NAME, } from "./schemas.js";
 const CONFIG_NAME = "kiln.config.json";
-const REPO_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 export function loadKilnConfig(configPath, options = {}) {
     const home = options.home ?? homedir();
     const resolvedPath = resolve(configPath);
@@ -24,15 +23,14 @@ export function loadKilnConfig(configPath, options = {}) {
     const repos = {};
     for (const [name, entry] of Object.entries(parsed.data.repos)) {
         assertRepoName(name);
-        const checkout = resolveConfiguredPath(configDir, entry.path, home);
-        if (!existsSync(checkout) || !statSync(checkout).isDirectory()) {
-            throw new KilnConfigError(`Checkout for ${name} does not exist or is not a directory: ${checkout}. Set repos.${name}.path in the kiln config.`);
-        }
+        const checkout = assertCheckoutDirectory(name, configDir, entry.path, home);
         repos[name] = {
             path: checkout,
             ...(entry.test ? { test: entry.test } : {}),
             deliver: entry.deliver ?? "local",
             ...(entry.base ? { base: entry.base } : {}),
+            ...(entry.prTitle ? { prTitle: entry.prTitle } : {}),
+            ...(entry.branch ? { branchTemplate: entry.branch } : {}),
         };
     }
     const kilnDir = configDir;
@@ -108,6 +106,12 @@ export function addRepo(options) {
     const base = options.base ?? previousString(previous, "base");
     if (base)
         entry.base = base;
+    const prTitle = previousString(previous, "prTitle");
+    if (prTitle)
+        entry.prTitle = prTitle;
+    const branchTemplate = previousString(previous, "branch");
+    if (branchTemplate)
+        entry.branch = branchTemplate;
     repos[options.name] = entry;
     raw.repos = repos;
     const parsed = KilnConfigFileSchema.safeParse(raw);
@@ -116,13 +120,21 @@ export function addRepo(options) {
     }
     mkdirSync(configDir, { recursive: true });
     writeFileSync(configPath, `${JSON.stringify(raw, null, 2)}\n`);
+    const effectiveDeliver = options.deliver ?? previousDeliver(previous) ?? "local";
     const lines = [`added ${options.name}`, `path ${checkout}`];
     if (entry.test)
         lines.push(`test ${entry.test}`);
-    if (entry.deliver)
-        lines.push(`deliver ${entry.deliver}`);
+    lines.push(`deliver ${effectiveDeliver}`);
     if (entry.base)
         lines.push(`base ${entry.base}`);
+    if (entry.prTitle)
+        lines.push(`prTitle ${entry.prTitle}`);
+    if (entry.branch)
+        lines.push(`branch ${entry.branch}`);
+    const change = effectiveDeliver === "pr"
+        ? `kiln repo add ${options.name} ${options.repoPath} --deliver local`
+        : `kiln repo add ${options.name} ${options.repoPath} --deliver pr --base main`;
+    lines.push(`Change delivery with: ${change}`);
     lines.push(`wrote ${configPath}`);
     return `${lines.join("\n")}\n`;
 }
@@ -137,10 +149,13 @@ export function renderRepoList(config) {
         const bits = [name, repo.path];
         if (repo.test)
             bits.push(`test ${repo.test}`);
-        if (repo.deliver === "pr")
-            bits.push("deliver pr");
+        bits.push(`deliver ${repo.deliver}`);
         if (repo.base)
             bits.push(`base ${repo.base}`);
+        if (repo.prTitle)
+            bits.push(`prTitle ${repo.prTitle}`);
+        if (repo.branchTemplate)
+            bits.push(`branch ${repo.branchTemplate}`);
         return bits.join("  ");
     });
     return `${lines.join("\n")}\n`;
@@ -230,6 +245,14 @@ export function resolveConfiguredPath(configDir, value, home) {
     const expanded = expandHome(value, home);
     return isAbsolute(expanded) ? expanded : resolve(configDir, expanded);
 }
+/** Resolved checkout. The loader and the settings API both refuse a missing directory. */
+export function assertCheckoutDirectory(name, configDir, value, home) {
+    const checkout = resolveConfiguredPath(configDir, value, home);
+    if (!existsSync(checkout) || !statSync(checkout).isDirectory()) {
+        throw new KilnConfigError(`Checkout for ${name} does not exist or is not a directory: ${checkout}. Set repos.${name}.path in the kiln config.`);
+    }
+    return checkout;
+}
 function pathToStore(userPath, cwd, home) {
     if (userPath === "~" || userPath.startsWith("~/"))
         return userPath;

package/dist/delivery.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { HostError } from "./host.js";
 import { readJobSpec } from "./jobs.js";
 import { jobBasename } from "./paths.js";
+import { chooseRemoteBranch, defaultRemoteBranch, formatBranchTemplate, isPublishableBranch, pullRequestTitle } from "./pr-names.js";
 /**
  * Derived per run, under `<kilnDir>/deliveries/<jobId>.json`. Not the job file.
  * `pushed` is true once origin has this branch at `sha`. Re-tick uses it, and
@@ -69,7 +70,8 @@ export function clearLaunchError(kilnDir, jobId) {
  *
  * `deliver=local` without `--stack` is checkout HEAD.
  * `deliver=pr` fetches and uses `origin/<base>` (configured, or origin's default).
- * A stacked job uses the upstream `yak/<run-id>` tip in this checkout.
+ * A stacked job uses the local upstream `yak/<run-id>` tip. The caller passes
+ * that ref, not the remote pull request head.
  */
 export function resolveLaunchBase(input) {
     if (input.stack) {
@@ -86,36 +88,72 @@ export function resolveLaunchBase(input) {
     return input.git.revParse(input.checkout, "HEAD");
 }
 /**
- * Push `yak/<run-id>` and open one draft pull request. A later tick looks up
- * the branch's pull request and skips both when the remote SHA already matches.
+ * Remote branch this job would publish, before a delivery record exists.
+ * A branch template that is not a safe ref falls back to the default name.
+ */
+export function plannedRemoteBranch(job, template) {
+    const input = {
+        title: job.title,
+        jobId: job.id,
+        ...(job.issue ? { issue: job.issue } : {}),
+    };
+    if (template?.trim()) {
+        const name = formatBranchTemplate(template, input);
+        if (isPublishableBranch(name))
+            return name;
+    }
+    return defaultRemoteBranch(input);
+}
+/**
+ * Push local `yak/<run-id>` to the remote branch and open one draft pull request.
+ * The delivery record stores the remote name. A later tick looks that name up
+ * and skips both the push and `gh pr create` when origin already has this commit.
+ * A recorded name, including an older `yak/<run-id>` record, is reused.
  * Failures stay on this job (`HostError` text) and do not escape.
  */
 export function deliverJob(request) {
-    const branch = `yak/${request.runId}`;
+    const localBranch = `yak/${request.runId}`;
     const prior = readDelivery(request.config.kilnDir, request.job.id);
     const sameRun = prior?.runId === request.runId ? prior : undefined;
+    const repo = request.config.repos[request.job.repo];
+    let remoteName = sameRun?.branch;
     try {
-        const localSha = request.host.git.revParse(request.checkout, branch);
+        const localSha = request.host.git.revParse(request.checkout, localBranch);
         if (sameRun?.prNumber && sameRun.prUrl && sameRun.sha === localSha) {
             return { ok: true, detail: sameRun.prUrl, prUrl: sameRun.prUrl, prNumber: sameRun.prNumber };
         }
+        if (!remoteName) {
+            remoteName = chooseRemoteBranch({
+                title: request.job.title,
+                jobId: request.job.id,
+                ...(request.job.issue ? { issue: request.job.issue } : {}),
+                ...(repo?.branchTemplate ? { template: repo.branchTemplate } : {}),
+                localSha,
+                remoteSha: (name) => request.host.git.remoteBranchSha(request.checkout, name),
+            });
+        }
         // Ask gh before pushing so a missing or logged-out CLI does not publish the branch.
-        let existing = request.host.github.findByHead(request.checkout, branch);
-        const remoteSha = request.host.git.remoteBranchSha(request.checkout, branch);
+        let existing = request.host.github.findByHead(request.checkout, remoteName);
+        const remoteSha = request.host.git.remoteBranchSha(request.checkout, remoteName);
         if (remoteSha !== localSha) {
-            request.host.git.pushBranch(request.checkout, branch, request.baseBranch);
+            request.host.git.publishBranch(request.checkout, localBranch, remoteName, request.baseBranch);
         }
+        const title = pullRequestTitle({
+            title: request.job.title,
+            ...(request.job.issue ? { issue: request.job.issue } : {}),
+            ...(repo?.prTitle ? { template: repo.prTitle } : {}),
+        });
         writeDelivery(request.config.kilnDir, {
             jobId: request.job.id,
             runId: request.runId,
-            branch,
+            branch: remoteName,
             base: request.baseBranch,
             sha: localSha,
             pushed: true,
             ...(sameRun?.prNumber ? { prNumber: sameRun.prNumber, prUrl: sameRun.prUrl } : {}),
         });
         if (!existing)
-            existing = request.host.github.findByHead(request.checkout, branch);
+            existing = request.host.github.findByHead(request.checkout, remoteName);
         const pr = existing ??
             (sameRun?.prNumber && sameRun.prUrl
                 ? {
@@ -123,20 +161,20 @@ export function deliverJob(request) {
                     url: sameRun.prUrl,
                     state: "OPEN",
                     mergedAt: null,
-                    head: branch,
+                    head: remoteName,
                     base: request.baseBranch,
                 }
                 : request.host.github.createDraft({
                     checkout: request.checkout,
-                    head: branch,
+                    head: remoteName,
                     base: request.baseBranch,
-                    title: request.job.title,
+                    title,
                     body: pullRequestBody(request),
                 }));
         writeDelivery(request.config.kilnDir, {
             jobId: request.job.id,
             runId: request.runId,
-            branch,
+            branch: remoteName,
             base: request.baseBranch,
             sha: localSha,
             pushed: true,
@@ -152,7 +190,7 @@ export function deliverJob(request) {
         writeDelivery(request.config.kilnDir, {
             jobId: request.job.id,
             runId: request.runId,
-            branch,
+            branch: remoteName ?? plannedRemoteBranch(request.job, repo?.branchTemplate),
             base: request.baseBranch,
             ...(base?.sha ? { sha: base.sha } : {}),
             pushed: base?.pushed ?? false,

package/dist/driver.js

@@ -2,8 +2,9 @@ import { spawn, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, linkSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join } from "node:path";
+import { claudeCredentialPreflight } from "./auth.js";
 import { buildAttention } from "./attention.js";
-import { clearLaunchError, deliverJob, readDelivery, readLaunchError, resolveLaunchBase, writeDelivery, writeLaunchError, isMerged, } from "./delivery.js";
+import { clearLaunchError, deliverJob, plannedRemoteBranch, readDelivery, readLaunchError, resolveLaunchBase, writeDelivery, writeLaunchError, isMerged, } from "./delivery.js";
 import { feedbackSpec, openFeedbackRound, planFeedback, readFeedbackLedger, writeFeedbackLedger, } from "./feedback.js";
 import { appendInvestigationFindings, existingFindingsPath, findingsFilePath, INVESTIGATION_WORKFLOW, readFindingsMarkdown, writeFindings, } from "./findings.js";
 import { defaultHost } from "./host.js";
@@ -50,8 +51,11 @@ export function runTick(config, host = defaultHost(), options = {}) {
         const feedbackNotes = watchPullRequests(config, world, host);
         const actions = decide(world.observation, now);
         const body = apply(config, world, actions, host, notes, now, [...published, ...feedbackNotes], facts);
-        const problem = facts ? sandboxPreflight(config, facts) : undefined;
-        return problem ? `${problem}\n${body}` : body;
+        const heads = [
+            claudeCredentialPreflight(process.env, config.adapter),
+            facts ? sandboxPreflight(config, facts) : undefined,
+        ].filter((line) => Boolean(line));
+        return heads.length > 0 ? `${heads.join("\n")}\n${body}` : body;
     });
 }
 /** Startup pass shared by `kiln tick` (via `runTick`) and `kiln serve`. Idempotent. */
@@ -366,7 +370,7 @@ function deliverObserved(config, world, jobId, host) {
         writeDelivery(config.kilnDir, {
             jobId,
             runId: observed.run.runId,
-            branch: `yak/${observed.run.runId}`,
+            branch: plannedRemoteBranch(job, repo.branchTemplate),
             base: repo.base ?? "unknown",
             pushed: false,
             error: message,
@@ -415,6 +419,7 @@ function specHandedToYak(config, world, job) {
     }
     return appendInvestigationFindings(base, sections);
 }
+/** Remote name the stacked pull request targets. Falls back to the local yak ref. */
 function upstreamBranch(world, job) {
     const upstreamId = job.dependsOn?.[0];
     if (!upstreamId)
@@ -424,6 +429,16 @@ function upstreamBranch(world, job) {
         return undefined;
     return upstream.delivery?.branch ?? `yak/${upstream.run.runId}`;
 }
+/** Local `yak/<run-id>` the stacked worktree is cut from. Yak owns that ref. */
+function upstreamLocalBranch(world, job) {
+    const upstreamId = job.dependsOn?.[0];
+    if (!upstreamId)
+        return undefined;
+    const upstream = world.observation.jobs.find((candidate) => candidate.jobId === upstreamId);
+    if (!upstream?.run)
+        return undefined;
+    return `yak/${upstream.run.runId}`;
+}
 function observedDelivery(kilnDir, host, checkout, jobId, runId) {
     const record = readDelivery(kilnDir, jobId);
     if (!record)
@@ -633,6 +648,9 @@ function markFeedback(kilnDir, jobId, reason) {
  * retries on the next tick without consuming a round.
  */
 function startFix(config, world, job, host, now, sandboxFacts) {
+    const refused = claudeCredentialPreflight(process.env, config.adapter);
+    if (refused)
+        return { jobId: job.id, repo: job.repo, kind: "fix", output: refused };
     const observed = world.observation.jobs.find((candidate) => candidate.jobId === job.id);
     const plan = observed?.feedbackPlan;
     const repo = config.repos[job.repo];
@@ -707,6 +725,9 @@ function resolveCommit(host, checkout, sha) {
 }
 /** `workflows/fix.yaml` on `headSha`. Commits on `yak/<run-id>`. Does not push. */
 function launchFixRun(config, job, host, checkout, headSha, specText, sandboxFacts) {
+    const refused = claudeCredentialPreflight(process.env, config.adapter);
+    if (refused)
+        return { jobId: job.id, repo: job.repo, kind: "fix", output: refused };
     const sourceWorkflow = readFileSync(join(packageRoot(), "workflows", "fix.yaml"), "utf8");
     const workflow = materializeWorkflow(config.kilnDir, job.id, "fix");
     const repo = config.repos[job.repo];
@@ -827,6 +848,9 @@ function spawnAgent(host, spec) {
     return { pid: child.pid ?? 0 };
 }
 function launchJob(config, world, job, host, sandboxFacts) {
+    const refused = claudeCredentialPreflight(process.env, config.adapter);
+    if (refused)
+        return { jobId: job.id, repo: job.repo, output: refused };
     const repo = config.repos[job.repo];
     if (!repo) {
         throw new Error(`Repo ${job.repo} is not registered. Run kiln repo add ${job.repo} <path>.`);
@@ -857,7 +881,7 @@ function launchJob(config, world, job, host, sandboxFacts) {
             deliver: repo.deliver,
             stack: job.stack === true,
             ...(repo.base ? { configuredBase: repo.base } : {}),
-            ...(job.stack ? { upstreamBranch: upstreamBranch(world, job) } : {}),
+            ...(job.stack ? { upstreamBranch: upstreamLocalBranch(world, job) } : {}),
             git: host.git,
         });
         specText = specHandedToYak(config, world, job);

package/dist/errors.js

@@ -4,3 +4,12 @@ export class KilnConfigError extends Error {
         this.name = "KilnConfigError";
     }
 }
+/** A request the serve process should answer with `statusCode` and the message. */
+export class HttpError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message);
+        this.name = "HttpError";
+        this.statusCode = statusCode;
+    }
+}