@astrosheep/keiyaku 2.8.4 → 2.9.0

package/build/core/renew.js

@@ -5,9 +5,10 @@ import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError
 import { KEIYAKU_FILE } from "../keiyaku.js";
 import { activeLedgerRef, appendWithRetry, readLedger } from "./ledger.js";
 import { readProjectionStatusBoard } from "./projection-status.js";
-import { renderContractView } from "./render.js";
-import { captureSeal, findOpenArc, receiptsAfterFence, sealOpenArc } from "./seal.js";
-import { commissionTarget, deriveContractState, isTerminalState, latestBase } from "./status.js";
+import { renderContractView } from "./contract-view.js";
+import { captureSeal, findOpenArc, getMaxArc, receiptsAfterFence, sealCurrentArc } from "./seal.js";
+import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
+import { commissionTarget, latestBase } from "./status/drift.js";
 import { findContractWorktreePath } from "./worktree-path.js";
 import { getCurrentBranch, isGitRepo } from "../git/branches.js";
 import { resolveContractAddress, withResolvedAddress } from "./addressing.js";
@@ -101,9 +102,8 @@ export async function renewContract(input) {
         throw new FlowError("INTERNAL_STATE", "ledger must contain bind entry");
     const branch = `keiyaku/${input.contractId}`;
     const oldHead = await resolveCommit(input.cwd, branch);
-    const open = findOpenArc(ledger.entries);
-    const capture = open ? await captureSeal(input.cwd, ledger.entries, oldHead, input.waivePaths) : null;
-    if (!open) {
+    const capture = await captureSeal(input.cwd, ledger.entries, oldHead, input.waivePaths);
+    if (getMaxArc(ledger.entries) > 0 && !findOpenArc(ledger.entries)) {
         const loose = await receiptsAfterFence(input.cwd, ledger.entries, oldHead);
         if (loose.length > 0)
             throw looseCommitError(input.contractId, loose);
@@ -125,7 +125,7 @@ export async function renewContract(input) {
     assertNoInFlightProjection(rewriteCwd, input.contractId, input.nowMs);
     await rewriteBranch(rewriteCwd, targetHead, oldBase, worktreePath ? undefined : branch);
     const newHead = await resolveCommit(input.cwd, branch);
-    const sealed = await sealOpenArc({
+    const sealed = await sealCurrentArc({
         cwd: input.cwd,
         renderCwd: rewriteCwd,
         contractId: input.contractId,

package/build/core/response-artifact-catalog-sqlite.js

@@ -0,0 +1,112 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+const CATALOG_FILE = "catalog.db";
+const CREATE_CATALOG_SQL = `
+  CREATE TABLE IF NOT EXISTS response_artifacts (
+    id TEXT PRIMARY KEY,
+    stable_root TEXT NOT NULL,
+    registered_at TEXT NOT NULL,
+    last_seen_at TEXT NOT NULL
+  ) STRICT
+`;
+function recordFromRow(row) {
+    return {
+        id: row.id,
+        stableRoot: row.stable_root,
+        registeredAt: row.registered_at,
+        lastSeenAt: row.last_seen_at,
+    };
+}
+export function createSqliteResponseArtifactCatalog(input) {
+    const databasePath = path.join(path.resolve(input.keiyakuHome), CATALOG_FILE);
+    const timestamp = () => (input.now?.() ?? new Date()).toISOString();
+    const withWritableDatabase = (operation) => {
+        fs.mkdirSync(path.dirname(databasePath), { recursive: true });
+        const database = new DatabaseSync(databasePath);
+        try {
+            database.exec("PRAGMA busy_timeout = 5000");
+            database.exec(CREATE_CATALOG_SQL);
+            return operation(database);
+        }
+        finally {
+            database.close();
+        }
+    };
+    const withExistingDatabase = (fallback, operation) => {
+        if (!fs.existsSync(databasePath))
+            return fallback;
+        const database = new DatabaseSync(databasePath, { readOnly: true });
+        try {
+            database.exec("PRAGMA busy_timeout = 5000");
+            return operation(database);
+        }
+        catch (error) {
+            if (error instanceof Error && /no such table/i.test(error.message))
+                return fallback;
+            throw error;
+        }
+        finally {
+            database.close();
+        }
+    };
+    const upsert = (coordinate, touchedAt) => {
+        withWritableDatabase((database) => {
+            database.prepare(`
+        INSERT INTO response_artifacts (id, stable_root, registered_at, last_seen_at)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET
+          registered_at = CASE
+            WHEN response_artifacts.stable_root <> excluded.stable_root THEN excluded.registered_at
+            ELSE response_artifacts.registered_at
+          END,
+          stable_root = excluded.stable_root,
+          last_seen_at = excluded.last_seen_at
+      `).run(coordinate.id, path.resolve(coordinate.stableRoot), touchedAt, touchedAt);
+        });
+    };
+    const records = () => withExistingDatabase([], (database) => {
+        const rows = database.prepare(`
+      SELECT id, stable_root, registered_at, last_seen_at
+      FROM response_artifacts
+      ORDER BY id
+    `).all();
+        return rows.map(recordFromRow);
+    });
+    return {
+        register(coordinate) {
+            upsert(coordinate, timestamp());
+        },
+        touch(coordinate) {
+            upsert(coordinate, timestamp());
+        },
+        lookup(id) {
+            return withExistingDatabase(undefined, (database) => {
+                const row = database.prepare(`
+          SELECT id, stable_root, registered_at, last_seen_at
+          FROM response_artifacts
+          WHERE id = ?
+        `).get(id);
+                return row ? recordFromRow(row) : undefined;
+            });
+        },
+        removeDead(coordinate) {
+            if (!fs.existsSync(databasePath))
+                return;
+            withWritableDatabase((database) => {
+                database.prepare(`
+          DELETE FROM response_artifacts
+          WHERE id = ? AND stable_root = ?
+        `).run(coordinate.id, path.resolve(coordinate.stableRoot));
+            });
+        },
+        async diagnoseDead(exists) {
+            const result = [];
+            for (const record of records()) {
+                if (!(await exists(record)))
+                    result.push(record);
+            }
+            return result;
+        },
+    };
+}

package/build/core/response-artifact-catalog.js

@@ -0,0 +1,7 @@
+let activeCatalog;
+export function configureResponseArtifactCatalog(catalog) {
+    activeCatalog = catalog;
+}
+export function getResponseArtifactCatalog() {
+    return activeCatalog;
+}

package/build/core/seal.js

@@ -4,9 +4,9 @@ import { FlowError } from "../flow-error.js";
 import { createGit, wrapGitError } from "../git/core.js";
 import { KEIYAKU_FILE } from "../keiyaku.js";
 import { activeLedgerRef, appendWithRetry, readLedger } from "./ledger.js";
-import { renderContractView } from "./render.js";
+import { renderContractView } from "./contract-view.js";
 import { normalizeScopePath, pathsMatchingScope } from "./scope.js";
-import { deriveContractState, isTerminalState } from "./status.js";
+import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
 function findBind(entries) {
     const bind = entries.find((entry) => entry.kind === "bind");
     if (!bind)
@@ -116,10 +116,28 @@ function assertOperable(contractId, entries) {
         throw new FlowError("INTERNAL_STATE", `contract ${contractId} cannot seal from state ${state.state}`);
     }
 }
-export async function captureSeal(cwd, entries, head = "HEAD", waivePaths = []) {
+/** Current seal intent: open explicit arc, else derived a0 while no explicit arc has ever existed. */
+export function currentSealArc(entries) {
     const open = findOpenArc(entries);
-    if (!open)
-        return null;
+    if (open)
+        return open.data.arc;
+    if (getMaxArc(entries) === 0)
+        return 0;
+    return null;
+}
+/** Stable read-only coordinate naming the receipt source a petition would seal. */
+export function petitionSealSource(entries) {
+    const arc = currentSealArc(entries);
+    const fence = getFence(entries);
+    return arc === null
+        ? `no open arc · fence ${fence}`
+        : `a${arc} · fence ${fence}▸HEAD`;
+}
+/** Shared read-only owner for the seal capture and its compact changed-path evidence. */
+export async function previewSeal(cwd, entries, head = "HEAD", waivePaths = []) {
+    const arc = currentSealArc(entries);
+    if (arc === null)
+        return { capture: null, paths: [] };
     const oldFence = getFence(entries);
     const newFence = await resolveCommit(cwd, head);
     const [receipts, paths, stat] = await Promise.all([
@@ -132,17 +150,23 @@ export async function captureSeal(cwd, entries, head = "HEAD", waivePaths = [])
     const waivedPaths = new Set(waivePaths.map(normalizeScopePath));
     const unwaived = violations.filter((violation) => !waivedPaths.has(violation));
     if (unwaived.length > 0) {
-        throw new FlowError("INTERNAL_STATE", `scope audit failed for contract ${open.contract}: paths ${unwaived.join(", ")} outside ${scope.join(", ")}`);
+        throw new FlowError("INTERNAL_STATE", `scope audit failed for contract ${findBind(entries).contract}: paths ${unwaived.join(", ")} outside ${scope.join(", ")}`);
     }
     return {
-        arc: open.data.arc,
-        oldFence,
-        newFence,
-        receipts,
-        diffstat: stat,
-        scopeAudit: { violations, waived: violations.length > 0 },
+        capture: {
+            arc,
+            oldFence,
+            newFence,
+            receipts,
+            diffstat: stat,
+            scopeAudit: { violations, waived: violations.length > 0 },
+        },
+        paths,
     };
 }
+export async function captureSeal(cwd, entries, head = "HEAD", waivePaths = []) {
+    return (await previewSeal(cwd, entries, head, waivePaths)).capture;
+}
 async function renderUpdatedContract(ledgerCwd, renderCwd, contractId) {
     const ledger = await readLedger(ledgerCwd, contractId);
     if (!ledger) {
@@ -150,7 +174,7 @@ async function renderUpdatedContract(ledgerCwd, renderCwd, contractId) {
     }
     await fs.writeFile(path.join(renderCwd, KEIYAKU_FILE), renderContractView({ id: contractId, entries: ledger.entries }), "utf8");
 }
-export async function sealOpenArc(input) {
+export async function sealCurrentArc(input) {
     const ledger = await readLedger(input.cwd, input.contractId);
     if (!ledger) {
         throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} not found or not active`);
@@ -162,10 +186,14 @@ export async function sealOpenArc(input) {
     const at = new Date(input.nowMs).toISOString();
     const result = await appendWithRetry(input.cwd, activeLedgerRef(input.contractId), (_head, entries) => {
         assertOperable(input.contractId, entries);
-        const open = findOpenArc(entries);
-        if (!open)
+        const currentArc = currentSealArc(entries);
+        if (currentArc === null)
             return null;
-        if (open.data.arc !== capture.arc || getFence(entries) !== capture.oldFence) {
+        // a0 is legal only while no explicit arc has ever existed; otherwise treat as concurrent change.
+        if (capture.arc === 0 && getMaxArc(entries) > 0) {
+            throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} changed while sealing arc a${capture.arc}`);
+        }
+        if (currentArc !== capture.arc || getFence(entries) !== capture.oldFence) {
             throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} changed while sealing arc a${capture.arc}`);
         }
         return {

package/build/core/status/board.js

@@ -0,0 +1,286 @@
+import { loadKeiyakuSettings } from "../../config/settings/loader.js";
+import { isGitRepo } from "../../git/branches.js";
+import { listContractIds, readLedger } from "../ledger.js";
+import { readProjectionStatusBoard } from "../projection-status.js";
+import { deriveQueueReadModel, queueMembership, } from "../queue.js";
+import { findOpenArc, getMaxArc, receiptsAfterFence } from "../seal.js";
+import { readTaskBoard } from "../task.js";
+import { openTaskStore } from "../task-git-store.js";
+import { taskRepositoryFromStore } from "../task-store-repository.js";
+import { deriveBootstrapDiagnostics, deriveContractState, hasCurrentPetitionVerdict, isTerminalState, } from "./lifecycle.js";
+import { commissionTarget, evaluateBaseDrift, latestBase, resolveDefaultBranchFromSettings, } from "./drift.js";
+import { computeClaimReconciliation, } from "./reconciliation.js";
+function compareTaskStatusRows(left, right) {
+    if (left.pri !== right.pri)
+        return left.pri - right.pri;
+    if (left.createdAt !== right.createdAt)
+        return left.createdAt < right.createdAt ? -1 : 1;
+    return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
+}
+async function readTaskStatusSummary(cwd) {
+    try {
+        const board = await readTaskBoard(taskRepositoryFromStore(await openTaskStore(cwd)));
+        const eligible = board.tasks.filter((task) => !task.contractId && (task.state === "open" || task.state === "in_progress"));
+        const inProgress = eligible.filter((task) => task.state === "in_progress").length;
+        const topTasks = [
+            ...eligible.filter((task) => task.state === "in_progress").sort(compareTaskStatusRows),
+            ...eligible.filter((task) => task.state === "open" && !task.blocked).sort(compareTaskStatusRows),
+        ]
+            .slice(0, 5)
+            .map(({ id, title, pri, createdAt, state, blocked }) => ({ id, title, pri, createdAt, state, blocked }));
+        const ready = eligible.filter((task) => task.state === "open" && !task.blocked).length;
+        const blocked = eligible.filter((task) => task.state === "open" && task.blocked).length;
+        if (board.tasks.length === 0 && board.diseases.length === 0)
+            return undefined;
+        return { total: board.tasks.length, inProgress, ready, blocked, topTasks, diseases: board.diseases };
+    }
+    catch (error) {
+        return {
+            total: 0,
+            inProgress: 0,
+            ready: 0,
+            blocked: 0,
+            topTasks: [],
+            diseases: [],
+            diagnostic: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function isQueueHeadStall(input) {
+    return (input.queuePosition === 1 &&
+        input.queueLength > 1 &&
+        input.state.state === "petitioned" &&
+        !hasCurrentPetitionVerdict(input.entries));
+}
+function findBindEntry(entries) {
+    return entries.find((entry) => entry.kind === "bind");
+}
+function contractSlugFromId(id) {
+    const dot = id.indexOf(".");
+    if (dot > 0)
+        return id.slice(0, dot);
+    return id;
+}
+function deriveCurrentArc(entries, bindObjective, lifecycle) {
+    // No explicit arc has ever existed: derive a0 from bind objective.
+    if (getMaxArc(entries) === 0) {
+        const a0Open = lifecycle.state === "bound" || lifecycle.state === "active";
+        return {
+            number: 0,
+            objective: bindObjective ?? "",
+            state: a0Open ? "open" : "closed",
+        };
+    }
+    const arcObjectives = new Map();
+    let currentArc = null;
+    for (const entry of entries) {
+        if (entry.kind === "arc") {
+            arcObjectives.set(entry.data.arc, entry.data.objective);
+            currentArc = {
+                number: entry.data.arc,
+                objective: entry.data.objective,
+                state: "open",
+            };
+            continue;
+        }
+        if (entry.kind === "seal" && entry.data.arc > 0) {
+            currentArc = {
+                number: entry.data.arc,
+                objective: arcObjectives.get(entry.data.arc) ?? bindObjective ?? "",
+                state: "closed",
+            };
+        }
+    }
+    if (currentArc)
+        return currentArc;
+    return {
+        number: 0,
+        objective: bindObjective ?? "",
+        state: "closed",
+    };
+}
+function deriveNextStep(input) {
+    if (input.state.state === "corrupt") {
+        return { kind: "inspect-log", detail: "inspect log" };
+    }
+    const pendingAfter = input.after.filter((item) => !item.terminal).map((item) => contractSlugFromId(item.id));
+    if (pendingAfter.length > 0) {
+        return { kind: "wait-after", detail: `finish after ${pendingAfter.join(",")}` };
+    }
+    if (input.state.state === "petitioned") {
+        return { kind: "await-claim", detail: "await claim" };
+    }
+    if (input.baseDrift.state === "drift" || input.baseDrift.state === "orphaned") {
+        return { kind: "renew", detail: "renew" };
+    }
+    // Derived a0 (bound/active, no explicit arc) petitions directly; explicit open arcs still suggest arc work.
+    if (input.currentArc.state === "open" && input.currentArc.number === 0) {
+        return { kind: "petition", detail: "petition" };
+    }
+    if (input.currentArc.state === "open") {
+        return { kind: "arc", detail: "arc" };
+    }
+    if (input.state.state === "active" && input.currentArc.number > 0) {
+        return { kind: "petition", detail: "petition" };
+    }
+    return { kind: "arc", detail: "arc" };
+}
+function deriveLastActiveAge(entries, now) {
+    const last = entries.at(-1);
+    if (!last)
+        return {};
+    const atMs = Date.parse(last.at);
+    if (!Number.isFinite(atMs)) {
+        return { lastActivityAt: last.at };
+    }
+    return {
+        lastActivityAt: last.at,
+        lastActiveMs: Math.max(0, now - atMs),
+    };
+}
+export async function readKanshiBoard(cwd, now, opts) {
+    const targetFilter = opts?.target ?? null;
+    const loadedSettings = await loadKeiyakuSettings(cwd);
+    const tasks = await readTaskStatusSummary(cwd);
+    if (!(await isGitRepo(cwd))) {
+        return {
+            contracts: [],
+            projections: null,
+            queueLength: 0,
+            diseases: loadedSettings.diseases,
+            claimReconciliation: null,
+            targetFilter,
+            ...(tasks ? { tasks } : {}),
+        };
+    }
+    // Status is a pure reader: use the same resolver, but retain its ability to
+    // open when the defaultBranch knob itself is diseased.
+    let defaultBranch = null;
+    try {
+        defaultBranch = await resolveDefaultBranchFromSettings(cwd, loadedSettings, false);
+    }
+    catch {
+        defaultBranch = null;
+    }
+    const contractIds = await listContractIds(cwd);
+    const terminalById = new Map();
+    const ledgers = [];
+    const readableLedgers = [];
+    for (const id of contractIds) {
+        try {
+            const ledger = await readLedger(cwd, id);
+            if (ledger) {
+                ledgers.push(ledger);
+                readableLedgers.push(ledger);
+                terminalById.set(id, isTerminalState(deriveContractState(ledger.entries)));
+            }
+        }
+        catch (error) {
+            ledgers.push({ id, error: error instanceof Error ? error : new Error(String(error)) });
+        }
+    }
+    const queueModel = deriveQueueReadModel(readableLedgers);
+    const boardQueueLength = queueModel.targetQueues.reduce((sum, queue) => sum + queue.ordered.length, 0);
+    const contracts = [];
+    // Readable-ledger commission targets retained for post-assembly filter only.
+    const derivedTargetById = new Map();
+    for (const item of ledgers) {
+        if ("error" in item) {
+            // Unreadable ledgers have no derivable target and stay under every filter.
+            derivedTargetById.set(item.id, undefined);
+            contracts.push({
+                id: item.id,
+                slug: contractSlugFromId(item.id),
+                state: { state: "corrupt", at: 0, reason: item.error.message },
+                queueHeadStalled: false,
+                arcs: 0,
+                currentArc: { number: 0, objective: "", state: "closed" },
+                nextStep: { kind: "inspect-log", detail: "inspect log" },
+                baseDrift: { state: "unknown", label: "n/a (corrupt ledger)" },
+                after: [],
+                corruptReason: item.error.message,
+                bootstrapDiagnostics: [],
+                queueDiagnostics: [],
+            });
+            continue;
+        }
+        const bind = findBindEntry(item.entries);
+        derivedTargetById.set(item.contractId, commissionTarget(item.entries)?.ref);
+        const base = latestBase(item.entries);
+        const state = deriveContractState(item.entries);
+        if (isTerminalState(state))
+            continue;
+        const after = (bind?.data.after ?? []).map((id) => ({ id, terminal: terminalById.get(id) ?? false }));
+        const currentArc = deriveCurrentArc(item.entries, bind?.data.objective, state);
+        const baseDrift = base
+            ? await evaluateBaseDrift(cwd, base, defaultBranch)
+            : { state: "unknown", label: "n/a (no default branch)" };
+        const nextStep = deriveNextStep({
+            id: item.contractId,
+            state,
+            currentArc,
+            baseDrift,
+            after,
+        });
+        if (nextStep.kind === "renew" && baseDrift.state === "drift") {
+            const openArc = findOpenArc(item.entries);
+            let receiptCount = 0;
+            if (openArc) {
+                try {
+                    receiptCount = (await receiptsAfterFence(cwd, item.entries, `keiyaku/${item.contractId}`)).length;
+                }
+                catch {
+                    // A ledger-only here contract may not have a delivery ref yet.
+                }
+            }
+            const sealForecast = openArc ? `seals a${openArc.data.arc} (${receiptCount} receipts), ` : "";
+            nextStep.hint = `run: keiyaku @${item.contractId} renew — ${sealForecast}follows ${baseDrift.defaultBranch} ▲${baseDrift.behindBy}`;
+        }
+        const membership = queueMembership(queueModel, item.contractId);
+        const queuePosition = membership?.position ?? null;
+        const targetQueueLength = membership?.queueLength ?? 0;
+        contracts.push({
+            id: item.contractId,
+            slug: contractSlugFromId(item.contractId),
+            state,
+            queuePosition,
+            queueHeadStalled: isQueueHeadStall({
+                entries: item.entries,
+                queuePosition,
+                queueLength: targetQueueLength,
+                state,
+            }),
+            arcs: getMaxArc(item.entries),
+            currentArc,
+            nextStep,
+            ...deriveLastActiveAge(item.entries, now),
+            place: bind?.data.place ?? null,
+            base,
+            baseDrift,
+            after,
+            bootstrapDiagnostics: deriveBootstrapDiagnostics(item.entries),
+            queueDiagnostics: membership ? [...membership.diagnostics] : [],
+        });
+    }
+    const filteredContracts = targetFilter === null
+        ? contracts
+        : contracts.filter((contract) => {
+            const derived = derivedTargetById.get(contract.id);
+            return derived === undefined || derived === targetFilter;
+        });
+    const queueLength = targetFilter === null
+        ? boardQueueLength
+        : (queueModel.targetQueues.find((queue) => queue.target === targetFilter)?.ordered.length ?? 0);
+    const claimReconciliation = await computeClaimReconciliation(cwd, defaultBranch);
+    return {
+        contracts: filteredContracts,
+        projections: readProjectionStatusBoard(cwd, now, { showAll: opts?.showAllProjections }),
+        queueLength,
+        defaultBranch: defaultBranch?.branch,
+        defaultHead: defaultBranch?.head,
+        diseases: loadedSettings.diseases,
+        claimReconciliation,
+        targetFilter,
+        ...(tasks ? { tasks } : {}),
+    };
+}

package/build/core/status/drift.js

@@ -0,0 +1,99 @@
+import { assertSettingsKnobUsable } from "../../config/settings/disease.js";
+import { loadKeiyakuSettings } from "../../config/settings/loader.js";
+import { FlowError } from "../../flow-error.js";
+import { SETTINGS_FILE } from "../../keiyaku.js";
+import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError } from "../../git/core.js";
+function findBindEntry(entries) {
+    return entries.find((entry) => entry.kind === "bind");
+}
+export function latestBase(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry.kind === "renew")
+            return entry.data.newBase;
+    }
+    return entries.find((entry) => entry.kind === "bind")?.data.base;
+}
+/** Commission settlement target from the bind entry. Schema guarantees refs/heads/<name>. */
+export function commissionTarget(entries) {
+    const bind = findBindEntry(entries);
+    if (!bind)
+        return undefined;
+    const ref = bind.data.target;
+    return {
+        ref,
+        branch: ref.slice("refs/heads/".length),
+    };
+}
+export async function resolveCommit(cwd, ref) {
+    const git = createGit(cwd);
+    try {
+        return (await git.raw(["rev-parse", "--verify", `${ref}^{commit}`])).trim();
+    }
+    catch (error) {
+        if (errorContainsAnyPattern(error, MISSING_HEAD_PATTERNS))
+            return null;
+        throw wrapGitError(`rev-parse ${ref}`, error, cwd);
+    }
+}
+export async function readSettingsDiseases(cwd) {
+    const loaded = await loadKeiyakuSettings(cwd);
+    return loaded.diseases;
+}
+export async function readDefaultBranchOverride(cwd) {
+    const loaded = await loadKeiyakuSettings(cwd);
+    return loaded.knobs?.defaultBranch;
+}
+export async function resolveDefaultBranchFromSettings(cwd, loaded, rejectDiseasedOverride) {
+    if (rejectDiseasedOverride)
+        assertSettingsKnobUsable(loaded, "defaultBranch");
+    const override = loaded.knobs?.defaultBranch;
+    if (override) {
+        const head = await resolveCommit(cwd, override);
+        if (!head)
+            throw new FlowError("INVALID_SETTINGS", `${SETTINGS_FILE} defaultBranch '${override}' does not resolve`);
+        return { branch: override, head };
+    }
+    const git = createGit(cwd);
+    for (const branch of ["main", "master"]) {
+        const head = await resolveCommit(cwd, branch);
+        if (head)
+            return { branch, head };
+    }
+    try {
+        const originHead = (await git.raw(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"])).trim();
+        if (originHead) {
+            const head = await resolveCommit(cwd, originHead);
+            if (head)
+                return { branch: originHead, head };
+        }
+    }
+    catch {
+        // Fall through to local branch heuristics.
+    }
+    return null;
+}
+export async function resolveDefaultBranch(cwd) {
+    return resolveDefaultBranchFromSettings(cwd, await loadKeiyakuSettings(cwd), true);
+}
+export async function evaluateBaseDrift(cwd, base, defaultBranch) {
+    if (!defaultBranch)
+        return { state: "unknown", label: "n/a (no default branch)" };
+    if (base === defaultBranch.head) {
+        return { state: "green", defaultBranch: defaultBranch.branch, defaultHead: defaultBranch.head };
+    }
+    const git = createGit(cwd);
+    try {
+        await git.raw(["merge-base", "--is-ancestor", base, defaultBranch.head]);
+        const behindBy = Number.parseInt((await git.raw(["rev-list", "--count", `${base}..${defaultBranch.head}`])).trim(), 10);
+        return {
+            state: "drift",
+            defaultBranch: defaultBranch.branch,
+            defaultHead: defaultBranch.head,
+            behindBy: Number.isFinite(behindBy) ? behindBy : 0,
+        };
+    }
+    catch {
+        return { state: "orphaned", defaultBranch: defaultBranch.branch, defaultHead: defaultBranch.head };
+    }
+}