@gethmy/agent 1.0.9 → 1.1.1

package/dist/__tests__/worktree-gc.test.js

@@ -0,0 +1,137 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+vi.mock("../worktree.js", () => ({
+    cleanupWorktree: vi.fn((path) => {
+        // Make cleanupWorktree actually remove the directory so our
+        // assertions reflect reality without invoking git.
+        rmSync(path, { recursive: true, force: true });
+    }),
+}));
+import { newRunId, StateStore } from "../state-store.js";
+import { cleanupWorktree } from "../worktree.js";
+import { runWorktreeGc } from "../worktree-gc.js";
+function initRepo(dir) {
+    execFileSync("git", ["init", "-q", dir], { stdio: "pipe" });
+    execFileSync("git", ["-C", dir, "commit", "-q", "--allow-empty", "-m", "init"], {
+        stdio: "pipe",
+        env: {
+            ...process.env,
+            GIT_AUTHOR_NAME: "t",
+            GIT_AUTHOR_EMAIL: "t@t",
+            GIT_COMMITTER_NAME: "t",
+            GIT_COMMITTER_EMAIL: "t@t",
+        },
+    });
+}
+describe("runWorktreeGc", () => {
+    let repoDir;
+    let store;
+    beforeEach(() => {
+        // Realpath to collapse the /tmp → /private/tmp symlink on macOS so
+        // paths match what `git rev-parse --show-toplevel` returns.
+        repoDir = realpathSync(mkdtempSync(join(tmpdir(), "gc-repo-")));
+        initRepo(repoDir);
+        const stateDir = mkdtempSync(join(tmpdir(), "gc-state-"));
+        store = new StateStore(join(stateDir, "state.json"));
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        rmSync(repoDir, { recursive: true, force: true });
+    });
+    function makeWorktreeDir(name, ageMs = 0) {
+        const dir = join(repoDir, ".harmony-worktrees", name);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "marker"), "x");
+        if (ageMs > 0) {
+            const mtime = new Date(Date.now() - ageMs);
+            execFileSync("touch", ["-m", "-t", formatMtime(mtime), dir]);
+        }
+        return dir;
+    }
+    function formatMtime(d) {
+        const pad = (n) => String(n).padStart(2, "0");
+        return (d.getFullYear().toString() +
+            pad(d.getMonth() + 1) +
+            pad(d.getDate()) +
+            pad(d.getHours()) +
+            pad(d.getMinutes()));
+    }
+    it("removes orphan worktrees older than minAgeMs", () => {
+        const cwd = process.cwd();
+        process.chdir(repoDir);
+        try {
+            makeWorktreeDir("agent-42-old", 2 * 60 * 60 * 1000);
+            const result = runWorktreeGc(".harmony-worktrees", store, {
+                minAgeMs: 60 * 60 * 1000,
+            });
+            expect(result.removed).toHaveLength(1);
+            expect(cleanupWorktree).toHaveBeenCalledTimes(1);
+        }
+        finally {
+            process.chdir(cwd);
+        }
+    });
+    it("keeps worktrees that match an active run", async () => {
+        const cwd = process.cwd();
+        process.chdir(repoDir);
+        try {
+            const wtPath = makeWorktreeDir("agent-99", 2 * 60 * 60 * 1000);
+            await store.insertRun({
+                runId: newRunId(),
+                cardId: "c1",
+                cardShortId: 99,
+                pipeline: "implement",
+                workerId: 0,
+                sessionId: null,
+                worktreePath: wtPath,
+                branchName: "agent/99",
+                daemonPid: process.pid,
+                phase: "running",
+                startedAt: Date.now(),
+                lastHeartbeatAt: Date.now(),
+                endedAt: null,
+                status: "active",
+                costCents: 0,
+            });
+            const result = runWorktreeGc(".harmony-worktrees", store, {
+                minAgeMs: 60 * 60 * 1000,
+            });
+            expect(result.removed).toHaveLength(0);
+            expect(result.skipped).toContain(wtPath);
+            expect(cleanupWorktree).not.toHaveBeenCalled();
+        }
+        finally {
+            process.chdir(cwd);
+        }
+    });
+    it("keeps worktrees younger than minAgeMs even if unclaimed", () => {
+        const cwd = process.cwd();
+        process.chdir(repoDir);
+        try {
+            const wt = makeWorktreeDir("agent-fresh", 0);
+            const result = runWorktreeGc(".harmony-worktrees", store, {
+                minAgeMs: 60 * 60 * 1000,
+            });
+            expect(result.removed).toHaveLength(0);
+            expect(result.skipped).toContain(wt);
+        }
+        finally {
+            process.chdir(cwd);
+        }
+    });
+    it("returns cleanly when the worktrees directory doesn't exist yet", () => {
+        const cwd = process.cwd();
+        process.chdir(repoDir);
+        try {
+            const result = runWorktreeGc(".harmony-worktrees", store);
+            expect(result.checked).toBe(0);
+            expect(result.errors).toEqual([]);
+        }
+        finally {
+            process.chdir(cwd);
+        }
+    });
+});

package/dist/budget.d.ts

@@ -0,0 +1,45 @@
+import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
+import type { Card } from "@harmony/shared";
+import type { StateStore } from "./state-store.js";
+import type { AgentConfig } from "./types.js";
+export type GuardDecision = {
+    allow: true;
+} | {
+    allow: false;
+    reason: GuardReason;
+    detail: string;
+};
+export type GuardReason = "dlq" | "max_attempts" | "card_cost_cap" | "daily_budget";
+/**
+ * BudgetGuard is consulted on every pickup and on every run start.
+ * It protects the daemon from three failure modes:
+ *   1. Cards that can never succeed (DLQ after N failed attempts).
+ *   2. Cards that burn unbounded tokens on a single attempt.
+ *   3. Runaway daily spend across the entire daemon.
+ *
+ * The guard is advisory for the hot path (returns a decision); the
+ * caller is responsible for marking DLQ and skipping the enqueue.
+ */
+export declare class BudgetGuard {
+    private config;
+    private store;
+    constructor(config: AgentConfig["budget"], store: StateStore);
+    /**
+     * Inspect a card before we commit to picking it up. If any threshold
+     * is already exceeded, return a skip decision — the caller should
+     * apply the DLQ label (for `dlq`/`max_attempts`/`card_cost_cap`) or
+     * simply hold until the daily budget resets (`daily_budget`).
+     */
+    check(cardId: string): GuardDecision;
+    /**
+     * Does the guard's decision warrant a permanent DLQ marker? The daily
+     * budget is *not* permanent — it resets at UTC midnight — so we only
+     * DLQ for terminal states.
+     */
+    isTerminal(reason: GuardReason): boolean;
+    /**
+     * Apply the DLQ label to a card and post a comment explaining why.
+     * Safe to call repeatedly — labels are idempotent.
+     */
+    markDlq(client: HarmonyApiClient, card: Card, reason: GuardReason, detail: string): Promise<void>;
+}

package/dist/budget.js

@@ -0,0 +1,94 @@
+import { log } from "./log.js";
+import { runTransition } from "./transitions.js";
+const TAG = "budget";
+/**
+ * BudgetGuard is consulted on every pickup and on every run start.
+ * It protects the daemon from three failure modes:
+ *   1. Cards that can never succeed (DLQ after N failed attempts).
+ *   2. Cards that burn unbounded tokens on a single attempt.
+ *   3. Runaway daily spend across the entire daemon.
+ *
+ * The guard is advisory for the hot path (returns a decision); the
+ * caller is responsible for marking DLQ and skipping the enqueue.
+ */
+export class BudgetGuard {
+    config;
+    store;
+    constructor(config, store) {
+        this.config = config;
+        this.store = store;
+    }
+    /**
+     * Inspect a card before we commit to picking it up. If any threshold
+     * is already exceeded, return a skip decision — the caller should
+     * apply the DLQ label (for `dlq`/`max_attempts`/`card_cost_cap`) or
+     * simply hold until the daily budget resets (`daily_budget`).
+     */
+    check(cardId) {
+        if (this.store.isDlq(cardId)) {
+            const rec = this.store.getCard(cardId);
+            return {
+                allow: false,
+                reason: "dlq",
+                detail: rec?.dlqReason ?? "previously marked DLQ",
+            };
+        }
+        const card = this.store.getCard(cardId);
+        if (card) {
+            if (card.attempts >= this.config.maxAttemptsPerCard) {
+                return {
+                    allow: false,
+                    reason: "max_attempts",
+                    detail: `${card.attempts} of ${this.config.maxAttemptsPerCard} attempts exhausted`,
+                };
+            }
+            if (card.totalCostCents >= this.config.maxCentsPerCard) {
+                return {
+                    allow: false,
+                    reason: "card_cost_cap",
+                    detail: `spent ${formatCents(card.totalCostCents)} of ${formatCents(this.config.maxCentsPerCard)} per-card cap`,
+                };
+            }
+        }
+        const dailySpent = this.store.getDailyCostCents();
+        if (dailySpent >= this.config.dailyBudgetCents) {
+            return {
+                allow: false,
+                reason: "daily_budget",
+                detail: `daily budget ${formatCents(dailySpent)}/${formatCents(this.config.dailyBudgetCents)} exhausted`,
+            };
+        }
+        return { allow: true };
+    }
+    /**
+     * Does the guard's decision warrant a permanent DLQ marker? The daily
+     * budget is *not* permanent — it resets at UTC midnight — so we only
+     * DLQ for terminal states.
+     */
+    isTerminal(reason) {
+        return (reason === "dlq" ||
+            reason === "max_attempts" ||
+            reason === "card_cost_cap");
+    }
+    /**
+     * Apply the DLQ label to a card and post a comment explaining why.
+     * Safe to call repeatedly — labels are idempotent.
+     */
+    async markDlq(client, card, reason, detail) {
+        await this.store.markDlq(card.id, `${reason}: ${detail}`);
+        try {
+            await runTransition(client, card, {
+                addLabels: [
+                    { name: this.config.dlqLabel, color: this.config.dlqLabelColor },
+                ],
+            });
+        }
+        catch (err) {
+            log.warn(TAG, `failed to add dlq label to #${card.short_id}: ${err instanceof Error ? err.message : err}`);
+        }
+        log.warn(TAG, `#${card.short_id} DLQ'd — ${reason}: ${detail}`);
+    }
+}
+function formatCents(cents) {
+    return `$${(cents / 100).toFixed(2)}`;
+}

package/dist/cli.d.ts

@@ -1,2 +1,16 @@
 #!/usr/bin/env node
-import "./index.js";
+/**
+ * Harmony Agent CLI entry point.
+ *
+ * Subcommands:
+ *   (no args)       — run the daemon (same as `run`)
+ *   run             — run the daemon
+ *   status          — GET /status from the running daemon, pretty-print
+ *   health          — GET /health, exit 0 if healthy, 1 otherwise
+ *   doctor          — run preflight checks without starting the daemon
+ *   gc              — one-shot worktree garbage collection
+ *   dlq list        — print DLQ entries
+ *   dlq clear <id>  — clear a card's DLQ mark
+ *   help            — show usage
+ */
+export {};

package/dist/cli.js

@@ -1,2 +1,240 @@
 #!/usr/bin/env node
-import "./index.js";
+/**
+ * Harmony Agent CLI entry point.
+ *
+ * Subcommands:
+ *   (no args)       — run the daemon (same as `run`)
+ *   run             — run the daemon
+ *   status          — GET /status from the running daemon, pretty-print
+ *   health          — GET /health, exit 0 if healthy, 1 otherwise
+ *   doctor          — run preflight checks without starting the daemon
+ *   gc              — one-shot worktree garbage collection
+ *   dlq list        — print DLQ entries
+ *   dlq clear <id>  — clear a card's DLQ mark
+ *   help            — show usage
+ */
+import { log } from "./log.js";
+const USAGE = `
+Harmony Agent — push-based daemon + ops toolkit.
+
+Usage:
+  harmony-agent [run]              Start the daemon (default)
+  harmony-agent status             Fetch status from the running daemon
+  harmony-agent health             Exit 0 if daemon is healthy, 1 otherwise
+  harmony-agent doctor             Run preflight checks (don't start)
+  harmony-agent gc                 One-shot worktree garbage collection
+  harmony-agent dlq list           List dead-lettered cards
+  harmony-agent dlq clear <cardId> Clear a card's DLQ marker
+  harmony-agent help               Show this help
+
+Flags:
+  --pretty                         Force colored human log output
+                                   (also: HARMONY_AGENT_PRETTY=1)
+  --json                           Force structured JSON log output
+                                   (also: HARMONY_AGENT_JSON=1)
+
+By default logs are pretty when stderr is a TTY and JSON when piped.
+`.trim();
+async function runDaemon() {
+    const { main } = await import("./index.js");
+    await main();
+}
+async function httpCall(path, init) {
+    const { loadDaemonConfig } = await import("./config.js");
+    const cfg = loadDaemonConfig();
+    const url = `http://${cfg.agent.http.bindAddr}:${cfg.agent.http.port}${path}`;
+    return fetch(url, init);
+}
+/** True if the error looks like "daemon is not running" (ECONNREFUSED). */
+function isDaemonDown(err) {
+    const code = err?.cause?.code;
+    const msg = err instanceof Error ? err.message : String(err);
+    return (code === "ECONNREFUSED" || /ECONNREFUSED|fetch failed|connect/i.test(msg));
+}
+function printStatus(body) {
+    const out = process.stdout;
+    const uptime = formatDuration(body.uptimeMs);
+    out.write(`daemon   ${body.daemonId} (pid ${body.daemonPid}, up ${uptime})\n`);
+    out.write(`budget   $${(body.budget.todayCents / 100).toFixed(2)} / $${(body.budget.dailyCapCents / 100).toFixed(2)} today\n`);
+    out.write(`workers  (${body.workers.length})\n`);
+    for (const w of body.workers) {
+        const card = w.cardId ? ` card=${w.cardId}` : "";
+        const br = w.branchName ? ` branch=${w.branchName}` : "";
+        out.write(`  #${w.id} ${w.pipeline.padEnd(9)} ${w.state}${card}${br}\n`);
+    }
+    out.write(`impl queue   (${body.implQueue.length})\n`);
+    for (const q of body.implQueue) {
+        out.write(`  #${q.shortId} priority=${q.priority}\n`);
+    }
+    out.write(`review queue (${body.reviewQueue.length})\n`);
+    for (const q of body.reviewQueue) {
+        out.write(`  #${q.shortId} priority=${q.priority}\n`);
+    }
+    out.write(`dlq          (${body.dlq.length})\n`);
+    for (const d of body.dlq) {
+        out.write(`  ${d.cardId} attempts=${d.attempts} cost=$${(d.totalCostCents / 100).toFixed(2)} reason=${d.reason}\n`);
+    }
+}
+function formatDuration(ms) {
+    const s = Math.floor(ms / 1000);
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const sec = s % 60;
+    if (h > 0)
+        return `${h}h${m}m`;
+    if (m > 0)
+        return `${m}m${sec}s`;
+    return `${sec}s`;
+}
+async function statusCommand() {
+    try {
+        const res = await httpCall("/status");
+        if (!res.ok) {
+            process.stdout.write(`daemon responded ${res.status} ${res.statusText}\n`);
+            return 1;
+        }
+        const body = (await res.json());
+        printStatus(body);
+        return 0;
+    }
+    catch (err) {
+        process.stderr.write(`could not reach daemon: ${err instanceof Error ? err.message : err}\n`);
+        return 1;
+    }
+}
+async function healthCommand() {
+    try {
+        const res = await httpCall("/health");
+        const body = (await res.json());
+        process.stdout.write(`${JSON.stringify(body, null, 2)}\n`);
+        return body.healthy ? 0 : 1;
+    }
+    catch (err) {
+        process.stderr.write(`could not reach daemon: ${err instanceof Error ? err.message : err}\n`);
+        return 1;
+    }
+}
+async function doctorCommand() {
+    const { loadDaemonConfig } = await import("./config.js");
+    const { validatePrerequisites } = await import("./index.js");
+    try {
+        const config = loadDaemonConfig();
+        const userId = await validatePrerequisites(config);
+        process.stdout.write(`all checks passed — agent user: ${userId}\n`);
+        return 0;
+    }
+    catch (err) {
+        process.stderr.write(`preflight failed: ${err instanceof Error ? err.message : err}\n`);
+        return 1;
+    }
+}
+async function gcCommand() {
+    const { loadDaemonConfig } = await import("./config.js");
+    const { runWorktreeGc } = await import("./worktree-gc.js");
+    const { StateStore } = await import("./state-store.js");
+    const config = loadDaemonConfig();
+    const store = StateStore.open();
+    // For a manual gc, minAge=0 — operator is choosing to sweep now.
+    const result = runWorktreeGc(config.agent.worktree.basePath, store, {
+        minAgeMs: 0,
+    });
+    process.stdout.write(`checked: ${result.checked}, removed: ${result.removed.length}, skipped: ${result.skipped.length}, errors: ${result.errors.length}\n`);
+    if (result.removed.length) {
+        for (const p of result.removed)
+            process.stdout.write(`  removed ${p}\n`);
+    }
+    if (result.errors.length) {
+        for (const e of result.errors) {
+            process.stderr.write(`  error ${e.path}: ${e.error}\n`);
+        }
+        return 1;
+    }
+    return 0;
+}
+async function dlqCommand(args) {
+    const sub = args[0];
+    const { StateStore } = await import("./state-store.js");
+    const store = StateStore.open();
+    if (!sub || sub === "list") {
+        const entries = store.listDlq();
+        if (entries.length === 0) {
+            process.stdout.write("DLQ is empty\n");
+            return 0;
+        }
+        for (const c of entries) {
+            process.stdout.write(`${c.cardId}  attempts=${c.attempts} cost=$${(c.totalCostCents / 100).toFixed(2)}  reason=${c.dlqReason ?? "(unknown)"}\n`);
+        }
+        return 0;
+    }
+    if (sub === "clear") {
+        const cardId = args[1];
+        if (!cardId) {
+            process.stderr.write("usage: harmony-agent dlq clear <cardId>\n");
+            return 2;
+        }
+        // Prefer the running daemon if present — direct file writes race
+        // the daemon's own in-memory state-store and silently lose data.
+        try {
+            const res = await httpCall(`/dlq/clear/${encodeURIComponent(cardId)}`, {
+                method: "POST",
+            });
+            if (res.ok) {
+                process.stdout.write(`cleared DLQ for ${cardId} (via daemon)\n`);
+                return 0;
+            }
+            process.stderr.write(`daemon returned ${res.status} ${res.statusText}\n`);
+            return 1;
+        }
+        catch (err) {
+            if (!isDaemonDown(err)) {
+                process.stderr.write(`daemon HTTP error: ${err instanceof Error ? err.message : err}\n`);
+                return 1;
+            }
+            // Daemon offline → safe to write directly.
+            await store.clearDlq(cardId);
+            process.stdout.write(`cleared DLQ for ${cardId} (daemon offline, wrote directly)\n`);
+            return 0;
+        }
+    }
+    process.stderr.write(`unknown dlq subcommand: ${sub}\n`);
+    return 2;
+}
+async function dispatch(argv) {
+    // Strip node, script, and any global flags we own.
+    const args = argv.filter((a) => a !== "--pretty" && a !== "--json");
+    const cmd = args[0];
+    switch (cmd) {
+        case undefined:
+        case "run":
+        case "daemon":
+            await runDaemon();
+            return 0;
+        case "status":
+            return statusCommand();
+        case "health":
+            return healthCommand();
+        case "doctor":
+            return doctorCommand();
+        case "gc":
+            return gcCommand();
+        case "dlq":
+            return dlqCommand(args.slice(1));
+        case "help":
+        case "--help":
+        case "-h":
+            process.stdout.write(`${USAGE}\n`);
+            return 0;
+        default:
+            process.stderr.write(`unknown subcommand: ${cmd}\n${USAGE}\n`);
+            return 2;
+    }
+}
+dispatch(process.argv.slice(2))
+    .then((code) => {
+    if (code !== 0)
+        process.exit(code);
+})
+    .catch((err) => {
+    log.error("cli", err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/completion.d.ts

@@ -8,6 +8,15 @@ export interface SessionStats {
     toolCalls: number;
     cost: CostUpdate | null;
 }
+export declare function buildTokenPayload(stats?: SessionStats | null): {
+    costCents?: undefined;
+    inputTokens?: undefined;
+    outputTokens?: undefined;
+} | {
+    costCents: number;
+    inputTokens: number;
+    outputTokens: number;
+};
 /**
  * Post-work pipeline: push branch, create PR, move card, post summary.
  */

package/dist/completion.js

@@ -6,6 +6,22 @@ import { AGENT_NAME, agentIdentifier } from "./types.js";
 import { attemptAutoFix, reportFindings, runVerification, } from "./verification.js";
 import { cleanupWorktree } from "./worktree.js";
 const TAG = "completion";
+function formatTokenCount(tokens) {
+    if (tokens >= 1_000_000)
+        return `${(tokens / 1_000_000).toFixed(1)}M`;
+    if (tokens >= 1_000)
+        return `${(tokens / 1_000).toFixed(1)}k`;
+    return String(tokens);
+}
+export function buildTokenPayload(stats) {
+    if (!stats?.cost)
+        return {};
+    return {
+        costCents: Math.round(stats.cost.totalCostUsd * 100),
+        inputTokens: stats.cost.totalInputTokens,
+        outputTokens: stats.cost.totalOutputTokens,
+    };
+}
 /**
  * Post-work pipeline: push branch, create PR, move card, post summary.
  */
@@ -17,6 +33,7 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
         await client.endAgentSession(card.id, {
             status: "completed",
             progressPercent: 100,
+            ...buildTokenPayload(sessionStats),
         });
         cleanupWorktree(worktreePath, branchName);
         return;
@@ -54,7 +71,10 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
             log.warn(TAG, `Verification failed for #${card.short_id} — reporting findings`);
             await reportFindings(client, card.id, result);
             await moveCardToColumn(client, card, config.verification.failColumn);
-            await client.endAgentSession(card.id, { status: "paused" });
+            await client.endAgentSession(card.id, {
+                status: "paused",
+                ...buildTokenPayload(sessionStats),
+            });
             cleanupWorktree(worktreePath, branchName);
             return;
         }
@@ -77,10 +97,11 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
     if (config.completion.postSummary) {
         await postSummary(client, card, branchName, worktreePath, prUrl, config.worktree.baseBranch, sessionStats);
     }
-    // 6. End agent session
+    // 6. End agent session (include final token/cost snapshot)
     await client.endAgentSession(card.id, {
         status: "completed",
         progressPercent: 100,
+        ...buildTokenPayload(sessionStats),
     });
     // 7. Cleanup worktree
     cleanupWorktree(worktreePath, branchName);
@@ -119,6 +140,11 @@ async function postSummary(client, card, branchName, worktreePath, prUrl, baseBr
         if (sessionStats.cost) {
             statParts.push(`$${sessionStats.cost.totalCostUsd.toFixed(2)} cost`);
             statParts.push(`${sessionStats.cost.numTurns} turns`);
+            const totalTokens = sessionStats.cost.totalInputTokens +
+                sessionStats.cost.totalOutputTokens;
+            if (totalTokens > 0) {
+                statParts.push(`${formatTokenCount(totalTokens)} tokens`);
+            }
         }
         parts.push(`Stats: ${statParts.join(" · ")}`);
     }

package/dist/config-validation.d.ts

@@ -0,0 +1,18 @@
+import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
+import type { AgentConfig } from "./types.js";
+export declare class ConfigValidationError extends Error {
+    readonly issues: string[];
+    constructor(message: string, issues: string[]);
+}
+/**
+ * Validate that every column referenced in the agent config actually
+ * exists on the board. Labels that the daemon needs to create (agent,
+ * Ready to Merge, Merged, Need Review, agent-recovered) are not
+ * required to pre-exist — the daemon creates them on demand. Columns
+ * must already exist because moving a card to a non-existent column
+ * silently fails and leaves cards stuck.
+ *
+ * Fail-fast on any mismatch: the operator fixes their config OR the
+ * board before the daemon is useful.
+ */
+export declare function validateColumnReferences(client: HarmonyApiClient, projectId: string, config: AgentConfig): Promise<void>;