@lchase/kiln 0.1.0 → 0.4.0

package/dist/board.js

@@ -0,0 +1,326 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { scheduledRetry } from "./attention.js";
+const FEATURE_STAGES = ["spec", "build", "review", "approve", "land", "pr-review"];
+const CATALOG = [
+    { id: "queued", label: "Queued", who: "waiting · deps", tone: "queued" },
+    { id: "spec", label: "Spec", who: "spec-writer · opus" },
+    { id: "build", label: "Build", who: "builder · opus" },
+    { id: "review", label: "Review", who: "sec · ux · ui · code" },
+    { id: "approve", label: "Approve", who: "approver · opus" },
+    { 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: "needs-human", label: "Needs human", who: "approve · retry", tone: "human" },
+];
+const STEP_STAGE = {
+    spec: "spec",
+    build: "build",
+    verify: "build",
+    security: "review",
+    ux: "review",
+    ui: "review",
+    code: "review",
+    approver: "approve",
+    approve: "needs-human",
+    land: "land",
+    explore: "explore",
+};
+const HUMAN_STATES = new Set(["needs-human", "failed", "dead", "invalid", "rejected"]);
+/**
+ * Column for one job. Human gates and broken runs sit in Needs human.
+ * A failed job with an automatic retry still scheduled stays on the step
+ * its last run reached. `scheduledRetry` is that decision.
+ */
+export function stageOf(job) {
+    if (scheduledRetry(job))
+        return runStage(job);
+    if (HUMAN_STATES.has(job.state))
+        return "needs-human";
+    if (job.state === "in-review")
+        return "pr-review";
+    if (job.state === "done")
+        return "merged";
+    const current = job.steps.find((step) => step.phase === "current" || step.phase === "failed");
+    if (job.state === "queued" || job.state === "blocked")
+        return "queued";
+    if (job.state === "approved") {
+        if (current && current.id !== "land" && current.id !== "approve" && STEP_STAGE[current.id])
+            return STEP_STAGE[current.id];
+        return "land";
+    }
+    if (current && STEP_STAGE[current.id])
+        return STEP_STAGE[current.id];
+    return runStage(job);
+}
+/**
+ * Stage of the last step the run actually reached.
+ * The approve gate's column is Needs human; a scheduled retry is not a gate,
+ * so that step stays on Approve. Spec or Explore when the run never started a step.
+ */
+function runStage(job) {
+    const last = [...job.steps].reverse().find((step) => step.phase === "current" || step.phase === "failed");
+    const stage = last ? STEP_STAGE[last.id] : undefined;
+    if (stage && stage !== "needs-human")
+        return stage;
+    if (stage === "needs-human") {
+        const earlier = [...job.steps].reverse().find((step) => {
+            const mapped = STEP_STAGE[step.id];
+            return step.phase === "done" && mapped !== undefined && mapped !== "needs-human";
+        });
+        if (earlier)
+            return STEP_STAGE[earlier.id] ?? "approve";
+        return "approve";
+    }
+    return job.workflow === "investigation" ? "explore" : "spec";
+}
+/** Stages to render. An empty kiln still shows the feature pipeline, collapsed. */
+export function stagesFor(jobs) {
+    const workflows = new Set(jobs.map((job) => job.workflow));
+    const wanted = new Set();
+    if (jobs.length === 0 || workflows.has("feature") || [...workflows].some((name) => name !== "investigation")) {
+        for (const id of FEATURE_STAGES)
+            wanted.add(id);
+    }
+    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));
+    return CATALOG.filter((stage) => wanted.has(stage.id));
+}
+const REVIEW_FILE = /^(security|ux|ui|code)(?:\.(\d+))?\.json$/;
+const TEXT_LIMIT = 8_000;
+export function readReviewRounds(runDir) {
+    if (!runDir)
+        return [];
+    const dir = join(runDir, "artifacts");
+    if (!existsSync(dir))
+        return [];
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const rounds = new Map();
+    for (const name of names) {
+        const match = REVIEW_FILE.exec(name);
+        if (!match?.[1])
+            continue;
+        const n = match[2] ? Number(match[2]) : 1;
+        const round = rounds.get(n) ?? { n };
+        const verdict = verdictOf(readJson(join(dir, name)));
+        if (verdict) {
+            if (match[1] === "security")
+                round.security = verdict;
+            else if (match[1] === "ux")
+                round.ux = verdict;
+            else if (match[1] === "ui")
+                round.ui = verdict;
+            else if (match[1] === "code")
+                round.code = verdict;
+        }
+        rounds.set(n, round);
+    }
+    return [...rounds.values()].sort((left, right) => left.n - right.n);
+}
+export function readBoardFiles(input) {
+    const files = [];
+    const spec = readText(input.specPath);
+    if (spec)
+        files.push({ id: "spec", group: "Job", label: "spec.md", text: spec });
+    const build = latestArtifact(input.runDir, "build");
+    if (build) {
+        const doc = artifactDoc(build);
+        files.push({ id: "build", group: "Job", label: "build.md", text: doc.text, ...(doc.tone ? { tone: doc.tone } : {}) });
+    }
+    else if (input.diffSummary?.trim()) {
+        files.push({ id: "build", group: "Job", label: "build.md", text: input.diffSummary.trim() });
+    }
+    const decision = latestArtifact(input.runDir, "decision");
+    if (decision) {
+        const doc = artifactDoc(decision);
+        files.push({ id: "decision", group: "Job", label: "decision.md", text: doc.text, ...(doc.tone ? { tone: doc.tone } : {}) });
+    }
+    const findingsFile = readText(input.findingsPath);
+    const findingsArtifact = latestArtifact(input.runDir, "findings");
+    const findingsMarkdown = findingsFile
+        || (isRecord(findingsArtifact) && typeof findingsArtifact.markdown === "string" ? findingsArtifact.markdown : "");
+    if (input.workflow === "investigation" && findingsMarkdown.trim()) {
+        files.push({ id: "findings", group: "Job", label: "findings.md", text: clip(findingsMarkdown) });
+    }
+    for (const gate of input.gates ?? []) {
+        const body = gate.rendered?.trim() || gate.prompt?.trim();
+        if (body) {
+            const label = input.workflow === "investigation" ? "findings.md" : "gate.md";
+            if (!files.some((file) => file.label === label && file.text.includes(body.slice(0, 40)))) {
+                files.push({ id: `gate-${gate.stepId}`, group: "Job", label, text: clip(body) });
+            }
+        }
+        for (const artifact of gate.artifacts ?? []) {
+            if (!artifact.summary?.trim())
+                continue;
+            const label = artifact.name.endsWith(".md") ? artifact.name : `${artifact.name}.md`;
+            if (files.some((file) => file.label === label || file.label === artifact.name))
+                continue;
+            const tone = toneFromSummary(artifact.summary);
+            files.push({
+                id: `artifact-${gate.stepId}-${artifact.name}`,
+                group: "Job",
+                label,
+                text: clip(artifact.summary),
+                ...(tone ? { tone } : {}),
+            });
+        }
+    }
+    if (input.runDir)
+        addReviewFiles(files, input.runDir);
+    addGateReviews(files, input.gates ?? []);
+    if (input.logTail?.trim()) {
+        files.push({ id: "log", group: "Job", label: "log", text: clip(input.logTail) });
+    }
+    return files;
+}
+function addReviewFiles(files, runDir) {
+    const dir = join(runDir, "artifacts");
+    if (!existsSync(dir))
+        return;
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    const rows = [];
+    for (const name of names) {
+        const match = REVIEW_FILE.exec(name);
+        if (!match?.[1])
+            continue;
+        rows.push({ n: match[2] ? Number(match[2]) : 1, kind: match[1], file: name });
+    }
+    const order = ["security", "ux", "ui", "code"];
+    rows.sort((left, right) => left.n - right.n || order.indexOf(left.kind) - order.indexOf(right.kind));
+    for (const row of rows) {
+        const doc = artifactDoc(readJson(join(dir, row.file)));
+        files.push({
+            id: `r${row.n}-${row.kind}`,
+            group: `Round ${row.n}`,
+            label: row.kind,
+            text: doc.text,
+            ...(doc.tone ? { tone: doc.tone } : {}),
+        });
+    }
+}
+function latestArtifact(runDir, name) {
+    if (!runDir)
+        return undefined;
+    const dir = join(runDir, "artifacts");
+    if (!existsSync(dir))
+        return undefined;
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return undefined;
+    }
+    let best;
+    const pattern = new RegExp(`^${name}(?:\\.(\\d+))?\\.json$`);
+    for (const file of names) {
+        const match = pattern.exec(file);
+        if (!match)
+            continue;
+        const iter = match[1] ? Number(match[1]) : 0;
+        if (!best || iter >= best.iter)
+            best = { iter, file };
+    }
+    return best ? readJson(join(dir, best.file)) : undefined;
+}
+function artifactDoc(value) {
+    if (!isRecord(value))
+        return { text: clip(typeof value === "string" ? value : "") };
+    const head = typeof value.verdict === "string" ? value.verdict : typeof value.decision === "string" ? value.decision : typeof value.status === "string" ? value.status : "";
+    const body = typeof value.findings === "string"
+        ? value.findings
+        : typeof value.reason === "string"
+            ? value.reason
+            : typeof value.summary === "string"
+                ? value.summary
+                : typeof value.markdown === "string"
+                    ? value.markdown
+                    : JSON.stringify(value, null, 2);
+    const tone = toneOf(head);
+    const text = head ? `VERDICT: ${head}\n\n${body}` : body;
+    return { text: clip(text), ...(tone ? { tone } : {}) };
+}
+function toneOf(head) {
+    if (head === "PASS" || head === "APPROVE" || head === "READY")
+        return "good";
+    if (head === "CHANGES")
+        return "warn";
+    if (head === "ESCALATE" || head === "BLOCKED")
+        return "stop";
+    return undefined;
+}
+function toneFromSummary(summary) {
+    const head = summary.trim().split(/[\s—-]/)[0] ?? "";
+    return toneOf(head);
+}
+function addGateReviews(files, gates) {
+    const known = new Set(files.filter((file) => file.group.startsWith("Round")).map((file) => file.label));
+    for (const gate of gates) {
+        for (const review of gate.reviews ?? []) {
+            if (!review.summary?.trim() || known.has(review.name))
+                continue;
+            known.add(review.name);
+            const tone = toneFromSummary(review.summary);
+            files.push({
+                id: `review-${review.name}`,
+                group: "Round 1",
+                label: review.name,
+                text: clip(review.summary),
+                ...(tone ? { tone } : {}),
+            });
+        }
+    }
+}
+function verdictOf(value) {
+    if (!isRecord(value))
+        return undefined;
+    const verdict = value.verdict;
+    return typeof verdict === "string" && verdict.trim() ? verdict.trim() : undefined;
+}
+function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readText(file) {
+    if (!file || !existsSync(file))
+        return undefined;
+    try {
+        const text = readFileSync(file, "utf8").trim();
+        return text ? clip(text) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function clip(text) {
+    const trimmed = text.trim();
+    if (trimmed.length <= TEXT_LIMIT)
+        return trimmed;
+    return `${trimmed.slice(0, TEXT_LIMIT - 1)}…`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { addRepo, renderRepoList, resolveKilnConfig } from "./config.js";
-import { answerJob, runStatus, runTick } from "./driver.js";
+import { answerJob, retryJob, runStatus, runTick } from "./driver.js";
+import { startServe } from "./serve.js";
 import { addFromFile } from "./intake/file.js";
 import { addFromJira } from "./intake/jira.js";
 import { addFromPrompt } from "./intake/prompt.js";
@@ -16,15 +17,25 @@ function usage() {
         "       kiln status [jobId] [--config <file>]",
         "       kiln approve <jobId> [--config <file>]",
         "       kiln reject <jobId> [--config <file>]",
+        "       kiln retry <jobId> [--config <file>]",
+        "       kiln serve [--port 4100] [--tick <seconds>|--no-tick] [--config <file>]",
         "",
-        "repo add registers a checkout. Relative paths are stored relative to the",
-        "config directory. ~ is expanded from the home directory.",
+        "repo add registers a checkout. 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,",
+        "otherwise ~/.kiln/kiln.config.json. repo add creates that directory.",
+        "Run kiln repo add <name> <path> from any directory. A leftover",
+        "./.kiln/kiln.config.json is an error until you mv ./.kiln ~/.kiln,",
+        "pass --config <file>, or set KILN_HOME.",
         "",
         "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.",
         "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.",
+        "--stack cannot target an investigation job: that workflow does not land a branch.",
         "A Jira Blocks link where this issue is blocked by another key is included",
         "when a kiln job for that key already exists.",
         "--dry-run with --jira prints the job and writes nothing. Running add again",
@@ -36,13 +47,29 @@ function usage() {
         "",
         "tick launches at most one ready job. After merged, dependencies must be done.",
         "Stacked jobs launch once the upstream has landed. deliver=pr then pushes",
-        "yak/<run-id> and opens a draft pull request. status prints the derived state.",
-        "approve and reject answer the human gate.",
+        "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",
+        "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",
+        "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",
+        "(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.",
+        "",
+        "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.",
     ].join("\n"));
     process.exit(2);
 }
 function parseFlags(argv) {
-    const bag = { positionals: [], after: [], dryRun: false, stack: false };
+    const bag = { positionals: [], after: [], dryRun: false, stack: false, noTick: false };
     for (let i = 0; i < argv.length; i += 1) {
         const flag = argv[i];
         const next = argv[i + 1];
@@ -138,6 +165,30 @@ function parseFlags(argv) {
             i += 1;
             continue;
         }
+        if (flag === "--port") {
+            if (!next || !/^\d+$/.test(next))
+                usage();
+            const port = Number(next);
+            if (port > 65535)
+                usage();
+            bag.port = port;
+            i += 1;
+            continue;
+        }
+        if (flag === "--tick") {
+            if (!next || !/^[1-9]\d*$/.test(next))
+                usage();
+            const seconds = Number(next);
+            if (seconds > 86_400)
+                usage();
+            bag.tickSeconds = seconds;
+            i += 1;
+            continue;
+        }
+        if (flag === "--no-tick") {
+            bag.noTick = true;
+            continue;
+        }
         if (flag?.startsWith("--"))
             usage();
         if (flag !== undefined)
@@ -145,9 +196,14 @@ function parseFlags(argv) {
     }
     return bag;
 }
+function rejectServeFlags(flags) {
+    if (flags.port !== undefined || flags.tickSeconds !== undefined || flags.noTick)
+        usage();
+}
 function repoCommand(argv) {
     const sub = argv[0];
     const flags = parseFlags(argv.slice(1));
+    rejectServeFlags(flags);
     if (sub === "list") {
         if (flags.positionals.length !== 0 || hasIntakeFlags(flags) || flags.test || flags.deliver || flags.base)
             usage();
@@ -174,6 +230,7 @@ function repoCommand(argv) {
 }
 async function addCommand(argv) {
     const flags = parseFlags(argv);
+    rejectServeFlags(flags);
     const workflow = flags.positionals[0];
     const selected = [flags.spec !== undefined, flags.prompt !== undefined, flags.jira !== undefined].filter(Boolean).length;
     if (!workflow ||
@@ -226,6 +283,7 @@ async function addCommand(argv) {
 }
 function importCommand(argv) {
     const flags = parseFlags(argv);
+    rejectServeFlags(flags);
     const dir = flags.positionals[0];
     if (!dir ||
         flags.positionals.length !== 1 ||
@@ -255,6 +313,7 @@ function importCommand(argv) {
 }
 function tickCommand(argv) {
     const flags = parseFlags(argv);
+    rejectServeFlags(flags);
     if (flags.positionals.length !== 0 || flags.test || hasIntakeFlags(flags) || flags.deliver || flags.base || flags.stack) {
         usage();
     }
@@ -263,14 +322,26 @@ function tickCommand(argv) {
 }
 function statusCommand(argv) {
     const flags = parseFlags(argv);
+    rejectServeFlags(flags);
     if (flags.positionals.length > 1 || flags.test || hasIntakeFlags(flags) || flags.deliver || flags.base || flags.stack) {
         usage();
     }
     const config = resolveKilnConfig({ configPath: flags.configPath });
     process.stdout.write(runStatus(config, flags.positionals[0]));
 }
+function retryCommand(argv) {
+    const flags = parseFlags(argv);
+    rejectServeFlags(flags);
+    const jobId = flags.positionals[0];
+    if (!jobId || flags.positionals.length !== 1 || flags.test || hasIntakeFlags(flags) || flags.deliver || flags.base || flags.stack) {
+        usage();
+    }
+    const config = resolveKilnConfig({ configPath: flags.configPath });
+    process.stdout.write(retryJob(config, jobId));
+}
 function gateCommand(choice, argv) {
     const flags = parseFlags(argv);
+    rejectServeFlags(flags);
     const jobId = flags.positionals[0];
     if (!jobId || flags.positionals.length !== 1 || flags.test || hasIntakeFlags(flags) || flags.deliver || flags.base || flags.stack) {
         usage();
@@ -278,6 +349,26 @@ function gateCommand(choice, argv) {
     const config = resolveKilnConfig({ configPath: flags.configPath });
     process.stdout.write(answerJob(config, jobId, choice));
 }
+async function serveCommand(argv) {
+    const flags = parseFlags(argv);
+    if (flags.positionals.length !== 0 ||
+        flags.test ||
+        hasIntakeFlags(flags) ||
+        flags.deliver ||
+        flags.base ||
+        flags.stack ||
+        (flags.noTick && flags.tickSeconds !== undefined)) {
+        usage();
+    }
+    const config = resolveKilnConfig({ configPath: flags.configPath });
+    const port = flags.port ?? 4100;
+    const tickSeconds = flags.noTick ? undefined : (flags.tickSeconds ?? 30);
+    await startServe({
+        config,
+        port,
+        ...(tickSeconds !== undefined ? { tickSeconds } : {}),
+    });
+}
 function hasIntakeFlags(flags) {
     return Boolean(flags.repo ||
         flags.spec ||
@@ -323,6 +414,14 @@ async function main() {
         gateCommand("reject", argv.slice(1));
         return;
     }
+    if (command === "retry") {
+        retryCommand(argv.slice(1));
+        return;
+    }
+    if (command === "serve") {
+        await serveCommand(argv.slice(1));
+        return;
+    }
     usage();
 }
 try {

package/dist/config.js

@@ -1,12 +1,11 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { KilnConfigError } from "./errors.js";
-import { KilnConfigFileSchema } from "./schemas.js";
+import { DEFAULT_MAX_ATTEMPTS, DEFAULT_STALL_TIMEOUT_MS, KilnConfigFileSchema, } 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 cwd = options.cwd ?? process.cwd();
     const home = options.home ?? homedir();
     const resolvedPath = resolve(configPath);
     let raw;
@@ -36,7 +35,7 @@ export function loadKilnConfig(configPath, options = {}) {
             ...(entry.base ? { base: entry.base } : {}),
         };
     }
-    const kilnDir = basename(configDir) === ".kiln" ? configDir : join(cwd, ".kiln");
+    const kilnDir = configDir;
     const jira = jiraFromFile(parsed.data.jira);
     return {
         configPath: resolvedPath,
@@ -46,12 +45,15 @@ export function loadKilnConfig(configPath, options = {}) {
         kilnDir,
         jobsDir: join(kilnDir, "jobs"),
         maxConcurrent: parsed.data.maxConcurrent ?? 2,
+        stallTimeoutMs: parsed.data.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS,
+        maxAttempts: parsed.data.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
         adapter: parsed.data.adapter ?? "claude-code",
         ...(jira ? { jira } : {}),
     };
 }
 /**
- * Local config wins: `./.kiln/kiln.config.json`, then `~/.kiln/kiln.config.json`.
+ * One kiln home: `--config <file>` if given, else `$KILN_HOME/kiln.config.json`
+ * when `KILN_HOME` is set, else `~/.kiln/kiln.config.json`.
  */
 export function resolveKilnConfig(options = {}) {
     const cwd = options.cwd ?? process.cwd();
@@ -59,18 +61,17 @@ export function resolveKilnConfig(options = {}) {
     if (options.configPath) {
         return loadKilnConfig(resolve(cwd, options.configPath), { cwd, home });
     }
-    const cwdConfig = join(cwd, ".kiln", CONFIG_NAME);
-    if (existsSync(cwdConfig))
-        return loadKilnConfig(cwdConfig, { cwd, home });
-    const homeConfig = join(home, ".kiln", CONFIG_NAME);
-    if (existsSync(homeConfig))
-        return loadKilnConfig(homeConfig, { cwd, home });
-    throw new KilnConfigError([
-        "No kiln config found.",
-        `Run kiln repo add <name> <path> to create ${join(cwd, ".kiln", CONFIG_NAME)},`,
-        `or create ${join(home, ".kiln", CONFIG_NAME)}.`,
-        "Those directories are gitignored. Do not commit checkout paths.",
-    ].join("\n"));
+    const configPath = defaultConfigPath(options);
+    assertNoStaleCwdConfig(cwd, configPath);
+    if (!existsSync(configPath)) {
+        throw new KilnConfigError([
+            "No kiln config found.",
+            `Run kiln repo add <name> <path> from any directory to create ${configPath}.`,
+            "Set KILN_HOME or pass --config <file> to use a different kiln home.",
+            "Do not commit checkout paths.",
+        ].join("\n"));
+    }
+    return loadKilnConfig(configPath, { cwd, home });
 }
 const BRANCH_NAME = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
 /** Create or update one repo entry. Returns the text to print. */
@@ -85,7 +86,7 @@ export function addRepo(options) {
         assertBranchName(options.base);
     const configPath = configPathForWrite(options);
     const configDir = dirname(configPath);
-    const storedPath = pathToStore(options.repoPath, configDir, cwd, home);
+    const storedPath = pathToStore(options.repoPath, cwd, home);
     const checkout = resolveConfiguredPath(configDir, storedPath, home);
     if (!existsSync(checkout) || !statSync(checkout).isDirectory()) {
         throw new KilnConfigError(`Checkout for ${options.name} does not exist or is not a directory: ${checkout}.`);
@@ -151,18 +152,39 @@ export function assertRepoName(name) {
         throw new KilnConfigError(`Repo name ${JSON.stringify(name)} must start with a letter or digit and contain only letters, digits, dots, underscores, and hyphens.`);
     }
 }
-function configPathForWrite(options) {
+function defaultConfigPath(options) {
+    return join(kilnHomeDirectory(options), CONFIG_NAME);
+}
+/** `$KILN_HOME` when set, otherwise `~/.kiln`. A relative `KILN_HOME` resolves from `cwd`. */
+function kilnHomeDirectory(options) {
     const cwd = options.cwd ?? process.cwd();
+    const fromEnv = process.env.KILN_HOME;
+    if (typeof fromEnv === "string" && fromEnv.trim().length > 0)
+        return resolve(cwd, fromEnv);
     const home = options.home ?? homedir();
+    return join(home, ".kiln");
+}
+function configPathForWrite(options) {
+    const cwd = options.cwd ?? process.cwd();
     if (options.configPath)
         return resolve(cwd, options.configPath);
+    const configPath = defaultConfigPath(options);
+    assertNoStaleCwdConfig(cwd, configPath);
+    return configPath;
+}
+/**
+ * A leftover `./.kiln/kiln.config.json` used to be a second kiln home.
+ * Fail instead of ignoring it when the machine home has no config yet.
+ */
+function assertNoStaleCwdConfig(cwd, homeConfig) {
     const cwdConfig = join(cwd, ".kiln", CONFIG_NAME);
-    if (existsSync(cwdConfig))
-        return cwdConfig;
-    const homeConfig = join(home, ".kiln", CONFIG_NAME);
+    if (!existsSync(cwdConfig))
+        return;
+    if (resolve(cwdConfig) === resolve(homeConfig))
+        return;
     if (existsSync(homeConfig))
-        return homeConfig;
-    return cwdConfig;
+        return;
+    throw new KilnConfigError(`Found ${cwdConfig} but no home config at ${homeConfig}. mv ./.kiln ~/.kiln or pass --config / set KILN_HOME.`);
 }
 function readConfigObject(configPath) {
     if (!existsSync(configPath))
@@ -205,14 +227,12 @@ export function resolveConfiguredPath(configDir, value, home) {
     const expanded = expandHome(value, home);
     return isAbsolute(expanded) ? expanded : resolve(configDir, expanded);
 }
-function pathToStore(userPath, configDir, cwd, home) {
+function pathToStore(userPath, cwd, home) {
     if (userPath === "~" || userPath.startsWith("~/"))
         return userPath;
     if (isAbsolute(userPath))
         return userPath;
-    const absolute = resolve(cwd, userPath);
-    const stored = relative(configDir, absolute);
-    return stored === "" ? "." : stored;
+    return resolve(cwd, userPath);
 }
 function jiraFromFile(jira) {
     if (!jira)