@tidegap/cli 0.0.0-stage → 0.18.0

package/dist/commands/register-wake.js

@@ -0,0 +1,76 @@
+/**
+ * `tidegap register-wake <task-id>` — schedule an RTC/pmset wake event 30s
+ * before the task's `scheduledFor`. macOS uses `pmset schedule wake`;
+ * Linux uses `rtcwake -m no -t <epoch>`.
+ */
+import { TaskStore } from "@tidegap/core";
+import { currentPlatform, } from "../platform/index.js";
+import { pmsetCommand, pmsetScheduleWake } from "../platform/macos.js";
+import { rtcwakeCommand, rtcwakeScheduleWake, } from "../platform/linux.js";
+import { defaultDbPath } from "./tick.js";
+export async function runRegisterWake(opts) {
+    const platform = opts.platform ?? currentPlatform();
+    if (platform === "windows") {
+        return {
+            command: "",
+            ok: false,
+            stderr: "non-posix",
+            message: `[tidegap/cli] register-wake is not supported on Windows — there is no ` +
+                `pmset/rtcwake equivalent wired. Use Task Scheduler's "Wake the ` +
+                `computer to run this task" option on your tidegap-tick job instead.`,
+        };
+    }
+    const dbPath = opts.db ?? defaultDbPath();
+    const store = new TaskStore({ dbPath });
+    let scheduledFor;
+    try {
+        const rec = store.get(opts.taskId);
+        if (!rec) {
+            throw new Error(`register-wake: task ${opts.taskId} not found in ${dbPath}`);
+        }
+        if (!rec.scheduledFor) {
+            throw new Error(`register-wake: task ${opts.taskId} has no scheduled_for; nothing to register against`);
+        }
+        scheduledFor = rec.scheduledFor;
+    }
+    finally {
+        store.close();
+    }
+    const at = new Date(new Date(scheduledFor).getTime() - 30 * 1000);
+    const command = platform === "macos" ? pmsetCommand(at) : rtcwakeCommand(at);
+    if (opts.dryRun) {
+        return {
+            command,
+            ok: true,
+            stderr: "",
+            message: `(dry-run) ${command}`,
+        };
+    }
+    const res = platform === "macos"
+        ? await pmsetScheduleWake(at)
+        : await rtcwakeScheduleWake(at);
+    return {
+        command: res.command,
+        ok: res.ok,
+        stderr: res.stderr,
+        message: res.ok
+            ? `registered: ${res.command}`
+            : `failed (${res.stderr}).\n` +
+                `Run as root, or pre-authorize password-less wake scheduling — add this\n` +
+                `line via \`sudo visudo\` (replace ${whoami()} with your login):\n` +
+                `    ${sudoersLine(platform)}`,
+    };
+}
+/** Best-effort current username for the sudoers hint. */
+function whoami() {
+    return (process.env.SUDO_USER ??
+        process.env.USER ??
+        process.env.LOGNAME ??
+        "youruser");
+}
+/** The exact NOPASSWD sudoers line the user should paste. */
+function sudoersLine(platform) {
+    const bin = platform === "macos" ? "/usr/bin/pmset" : "/usr/sbin/rtcwake";
+    return `${whoami()} ALL=(root) NOPASSWD: ${bin}`;
+}
+//# sourceMappingURL=register-wake.js.map

package/dist/commands/register-wake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-wake.js","sourceRoot":"","sources":["../../src/commands/register-wake.ts"],"names":[],"mappings":"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"}

package/dist/commands/stats.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `tidegap stats` — local-only personal-impact aggregator.
+ *
+ * Reads the SQLite ledger at ~/.tidegap/queue.db (or --db) and renders the
+ * cumulative carbon stats + per-region breakdown + achievement-badge list.
+ * No telemetry, no network, no third-party reporting — everything stays
+ * on the user's machine. The dashboard `/stats` route reads the same
+ * shape over the (planned v0.9) scheduler HTTP API.
+ *
+ * v0.8 surface: read-only. Future versions may add `--since` window
+ * filters and `--per-day` time-bucket histograms.
+ */
+import { type CarbonStats, type RegionStats, type BandHistogram, type Achievement, type CarbonBudgetStatus } from "@tidegap/core";
+export interface StatsCommandOptions {
+    db?: string;
+    json?: boolean;
+    /** Override the carbon-budget config path (tests). Defaults to ~/.tidegap/config. */
+    budgetConfig?: string;
+}
+export interface StatsResult {
+    rendered: string;
+    stats: CarbonStats;
+    perRegion: RegionStats[];
+    bands: BandHistogram;
+    badges: Achievement[];
+    /** Aggregate carbon-budget status when a budget is configured (ROADMAP item 4). */
+    budget?: CarbonBudgetStatus;
+}
+export declare function renderStats(r: StatsResult): string;
+export declare function runStats(opts?: StatsCommandOptions): Promise<StatsResult>;
+//# sourceMappingURL=stats.d.ts.map

package/dist/commands/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../src/commands/stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAQL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAIvB,MAAM,WAAW,mBAAmB;IAClC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,mFAAmF;IACnF,MAAM,CAAC,EAAE,kBAAkB,CAAC;CAC7B;AAuBD,wBAAgB,WAAW,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAuElD;AAED,wBAAsB,QAAQ,CAAC,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,WAAW,CAAC,CAgEnF"}

package/dist/commands/stats.js

@@ -0,0 +1,165 @@
+/**
+ * `tidegap stats` — local-only personal-impact aggregator.
+ *
+ * Reads the SQLite ledger at ~/.tidegap/queue.db (or --db) and renders the
+ * cumulative carbon stats + per-region breakdown + achievement-badge list.
+ * No telemetry, no network, no third-party reporting — everything stays
+ * on the user's machine. The dashboard `/stats` route reads the same
+ * shape over the (planned v0.9) scheduler HTTP API.
+ *
+ * v0.8 surface: read-only. Future versions may add `--since` window
+ * filters and `--per-day` time-bucket histograms.
+ */
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { TaskStore, aggregateStats, aggregateByRegion, bandHistogram, achievements, carbonBudgetStatus, loadCarbonBudgetConfig, } from "@tidegap/core";
+import { readEnvCredentials } from "../env.js";
+import { defaultDbPath } from "./tick.js";
+function fmtNumber(n) {
+    if (n === 0)
+        return "0";
+    if (Math.abs(n) < 1)
+        return n.toFixed(3);
+    if (Math.abs(n) < 10)
+        return n.toFixed(2);
+    if (Math.abs(n) < 100)
+        return n.toFixed(1);
+    return Math.round(n).toLocaleString("en-US");
+}
+function fmtPercent(num, den) {
+    if (den === 0)
+        return "—";
+    return `${Math.round((num / den) * 100)}%`;
+}
+function relativeTime(iso) {
+    if (!iso)
+        return "—";
+    const then = new Date(iso).getTime();
+    if (Number.isNaN(then))
+        return iso;
+    const days = Math.max(1, Math.round((Date.now() - then) / (24 * 60 * 60 * 1000)));
+    return `${iso.slice(0, 10)} (${days}d ago)`;
+}
+export function renderStats(r) {
+    const { stats, perRegion, bands, badges, budget } = r;
+    const lines = [];
+    lines.push("Tidegap · personal impact");
+    lines.push("=".repeat(48));
+    lines.push("");
+    if (budget) {
+        const bar = "#".repeat(Math.min(32, Math.round((budget.pct / 100) * 32)));
+        const flag = budget.exceeded ? "  ⚠ OVER BUDGET" : "";
+        lines.push(`carbon budget (${budget.windowKind})`);
+        lines.push("-".repeat(48));
+        lines.push(`  used ${fmtNumber(budget.usedG)} / ${fmtNumber(budget.thresholdG)} g  ` +
+            `(${budget.pct}%)${flag}`);
+        lines.push(`  ${bar}`);
+        lines.push(`  window started ${budget.windowStart.slice(0, 10)} · ${budget.taskCount} tasks`);
+        if (budget.alerted)
+            lines.push(`  alert fired for this window`);
+        lines.push("");
+    }
+    lines.push(`Tasks dispatched          ${fmtNumber(stats.taskCount)}`);
+    lines.push(`Estimated CO2e accounted  ${fmtNumber(stats.totalEstimatedCarbonGCo2)} g`);
+    lines.push(`Cleanest-window hits      ${stats.scoredHits} (${fmtPercent(stats.scoredHits, stats.taskCount)})`);
+    lines.push(`Run-now dispatches        ${stats.currentDispatches}`);
+    lines.push(`Expedited (skip window)   ${stats.expeditedDispatches}`);
+    lines.push(`First task                ${relativeTime(stats.firstRanAt)}`);
+    lines.push(`Most recent               ${relativeTime(stats.lastRanAt)}`);
+    lines.push("");
+    if (perRegion.length > 0) {
+        lines.push("by region");
+        lines.push("-".repeat(48));
+        for (const r of perRegion.slice(0, 20)) {
+            const tail = `${String(r.taskCount).padStart(5)}  ${fmtNumber(r.totalEstimatedCarbonGCo2).padStart(8)} g  (${fmtNumber(r.avgEstimatedCarbonGCo2)}/task)`;
+            lines.push(`  ${r.region.padEnd(20)}${tail}`);
+        }
+        lines.push("");
+    }
+    const totalBands = bands.veryClean + bands.clean + bands.average + bands.dirty + bands.veryDirty;
+    if (totalBands > 0) {
+        lines.push("dispatch grid-band distribution");
+        lines.push("-".repeat(48));
+        for (const [k, v] of Object.entries(bands)) {
+            const pct = fmtPercent(v, totalBands).padStart(4);
+            const bar = "#".repeat(Math.round((v / totalBands) * 32));
+            lines.push(`  ${k.padEnd(12)} ${String(v).padStart(5)}  ${pct}  ${bar}`);
+        }
+        lines.push("");
+    }
+    const unlocked = badges.filter((b) => b.unlocked);
+    const locked = badges.filter((b) => !b.unlocked);
+    lines.push(`achievements  (${unlocked.length}/${badges.length} unlocked)`);
+    lines.push("-".repeat(48));
+    for (const b of badges) {
+        const mark = b.unlocked ? "✓" : "·";
+        lines.push(`  ${mark} ${b.label.padEnd(22)} ${b.description}`);
+    }
+    lines.push("");
+    if (stats.taskCount === 0) {
+        lines.push("Queue is empty. Run `/tidegap:defer …` from a Claude Code session,");
+        lines.push("or `npx -y @tidegap/mcp` from your MCP host, to start.");
+    }
+    return lines.join("\n");
+}
+export async function runStats(opts = {}) {
+    const dbPath = opts.db ?? defaultDbPath();
+    // Ensure the parent directory exists before better-sqlite3 opens the
+    // file. Matches the MCP server's behaviour, so a first-time `tidegap
+    // stats` invocation before the MCP server has ever written to the
+    // ledger returns an empty result rather than throwing ENOENT.
+    if (dbPath !== ":memory:") {
+        try {
+            mkdirSync(dirname(dbPath), { recursive: true });
+        }
+        catch {
+            // Best-effort; the open below will surface any real error.
+        }
+    }
+    const store = new TaskStore({ dbPath });
+    try {
+        const completed = store.list({ status: "completed" });
+        const stats = aggregateStats(completed);
+        const perRegion = aggregateByRegion(completed);
+        const bands = bandHistogram(completed);
+        const badges = achievements(stats, perRegion);
+        // Aggregate carbon-budget status (ROADMAP item 4): only when configured.
+        // Core is environment-pure, so the CLI (the host) reads the two
+        // TIDEGAP_CARBON_BUDGET_* variables and passes them in — same precedence as
+        // before: an exported variable beats the ~/.tidegap/config file.
+        const budgetConfig = loadCarbonBudgetConfig({
+            path: opts.budgetConfig,
+            env: readEnvCredentials().carbonBudget,
+        });
+        let budget;
+        if (budgetConfig) {
+            const now = new Date();
+            const status = carbonBudgetStatus(completed, budgetConfig, now, false);
+            let alerted = false;
+            try {
+                alerted = store.hasBudgetAlert(budgetConfig.windowKind, status.windowStart, budgetConfig.thresholdG);
+            }
+            catch {
+                // best-effort — leave alerted false
+            }
+            budget = { ...status, alerted };
+        }
+        const result = {
+            rendered: "",
+            stats,
+            perRegion,
+            bands,
+            badges,
+            ...(budget ? { budget } : {}),
+        };
+        result.rendered = renderStats(result);
+        if (opts.json) {
+            result.rendered = JSON.stringify({ stats, perRegion, bands, badges, ...(budget ? { budget } : {}) }, null, 2);
+        }
+        return result;
+    }
+    finally {
+        store.close();
+    }
+}
+//# sourceMappingURL=stats.js.map

package/dist/commands/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../src/commands/stats.ts"],"names":[],"mappings":"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"}

package/dist/commands/tick.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `tidegap tick` — drain due provider-call tasks.
+ *
+ * One-shot by default; `--daemon` loops on the supplied interval until
+ * SIGINT. Reads API keys from the environment and constructs the
+ * matching adapters lazily. If neither key is set we still exit 0 with
+ * a warning — useful for "this cron only kicks in once a key is added".
+ */
+import { type TickAdapters } from "@tidegap/core";
+import { type SpawnOptions } from "node:child_process";
+import { type ProviderCredentials } from "../env.js";
+export interface TickCommandOptions {
+    db?: string;
+    daemon?: boolean;
+    once?: boolean;
+    interval?: number;
+    region?: string;
+    /** Override the secrets file path (tests). Defaults to ~/.config/tidegap/env. */
+    envFile?: string;
+    /**
+     * Override the ~/.tidegap/config path (tests): carbon budget and quota
+     * reset schedules are both read from it.
+     */
+    budgetConfig?: string;
+    /** `false` (`--no-notify`) posts no OS notification for finished tasks. */
+    notify?: boolean;
+    /** Spawner for the notification command (tests). Defaults to node's spawn. */
+    spawnNotify?: NotifySpawner;
+    /** Platform for the notification command (tests). Defaults to os.platform(). */
+    platform?: NodeJS.Platform;
+}
+/** Starts a notification process; the tick never waits on it. */
+export type NotifySpawner = (cmd: string, args: string[], opts: SpawnOptions) => void;
+/** `TIDEGAP_NOTIFY=0` (or false/off/no; 0.17: `EBB_NOTIFY`) in ~/.tidegap/config turns notifications off. */
+export declare function notifyDisabledInConfig(path?: string): boolean;
+export interface TickRunResult {
+    exitCode: number;
+    message: string;
+}
+/**
+ * Default queue path. Matches the MCP server's persistence default
+ * (`~/.tidegap/queue.db`, established in v0.7.1) so `tidegap tick`,
+ * `tidegap queue list`, `tidegap receipts list`, and `tidegap stats` all read
+ * the same SQLite ledger the MCP server writes to. Prior versions
+ * defaulted to `~/.ebb/queue.sqlite`, which silently diverged from
+ * the MCP server's actual path — fixed in v0.8.x.
+ *
+ * If the legacy `~/.ebb/queue.sqlite` exists and the new path
+ * doesn't, the legacy path is returned so users who pre-date v0.7.1
+ * keep seeing their historical data. Once they begin writing to
+ * the new path (via the MCP server), pass `--db` explicitly to
+ * read the old one.
+ */
+export declare function defaultDbPath(): string;
+/**
+ * Build the tick adapters from host-supplied credentials.
+ *
+ * `@tidegap/core` no longer reads the environment, so the CLI (the host)
+ * reads it once via `readEnvCredentials()` and injects the values here. The
+ * registration rules are unchanged: an adapter appears exactly when its
+ * credential is present, Gemini prefers GEMINI_API_KEY over GOOGLE_API_KEY,
+ * and Ollama is an explicit OLLAMA_HOST opt-in.
+ */
+export declare function buildAdapters(creds?: ProviderCredentials): TickAdapters;
+/**
+ * Inspect the ledger for pending provider-call tasks whose provider key
+ * is missing from the environment. Returns the distinct missing keys.
+ * Best-effort — never throws (a broken/absent DB just yields []).
+ */
+export declare function missingProviderKeysForPending(dbPath: string): string[];
+export declare function runTickOnce(opts?: TickCommandOptions): Promise<TickRunResult>;
+export declare function runTick(opts?: TickCommandOptions): Promise<number>;
+//# sourceMappingURL=tick.d.ts.map

package/dist/commands/tick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tick.d.ts","sourceRoot":"","sources":["../../src/commands/tick.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAmBL,KAAK,YAAY,EAElB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAI9D,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAGzE,MAAM,WAAW,kBAAkB;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B;AAED,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;AAqBtF,6GAA6G;AAC7G,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,MAAiC,GAAG,OAAO,CAQvF;AA0CD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,KAAK,GAAE,mBAA0C,GAChD,YAAY,CAmBd;AAaD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CA4BtE;AAED,wBAAsB,WAAW,CAC/B,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,aAAa,CAAC,CAuFxB;AAED,wBAAsB,OAAO,CAAC,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB5E"}

package/dist/commands/tick.js

@@ -0,0 +1,294 @@
+/**
+ * `tidegap tick` — drain due provider-call tasks.
+ *
+ * One-shot by default; `--daemon` loops on the supplied interval until
+ * SIGINT. Reads API keys from the environment and constructs the
+ * matching adapters lazily. If neither key is set we still exit 0 with
+ * a warning — useful for "this cron only kicks in once a key is added".
+ */
+import { AnthropicAdapter, buildDefaultGridFeed, carbonBudgetConfigPath, GeminiAdapter, loadCarbonBudgetConfig, loadQuotaResetConfig, OllamaAdapter, OpenAIAdapter, osNotifyCommand, parseKeyValues, resolveTidegapHome, withTidegapKeys, prepareTick, resolveRegion, Scheduler, taskNotificationContent, TaskStore, } from "@tidegap/core";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir, platform as osPlatform } from "node:os";
+import { join } from "node:path";
+import { readEnvCredentials } from "../env.js";
+import { loadEnvFileIntoProcess } from "./env-file.js";
+const NOTIFY_TIMEOUT_MS = 5_000;
+/**
+ * True under a test runner. A test that reaches the default spawner without
+ * injecting `spawnNotify` must not post a real notification on the
+ * developer's desktop.
+ */
+function underTest() {
+    return process.env.VITEST !== undefined || process.env.NODE_ENV === "test";
+}
+const defaultSpawnNotify = (cmd, args, opts) => {
+    if (underTest())
+        return;
+    const child = spawn(cmd, args, opts);
+    // A missing binary (no notify-send) or a failed toast is not a tick error.
+    child.on("error", () => { });
+    child.unref();
+};
+/** `TIDEGAP_NOTIFY=0` (or false/off/no; 0.17: `EBB_NOTIFY`) in ~/.tidegap/config turns notifications off. */
+export function notifyDisabledInConfig(path = carbonBudgetConfigPath()) {
+    try {
+        if (!existsSync(path))
+            return false;
+        const v = withTidegapKeys(parseKeyValues(readFileSync(path, "utf8"))).TIDEGAP_NOTIFY;
+        return v !== undefined && /^(0|false|off|no)$/i.test(v.trim());
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Post one OS notification per task that reached `completed` or `failed`
+ * in this tick. Best-effort: an unknown platform, a missing record, or a
+ * spawner that throws is skipped silently.
+ */
+function notifyFinished(dbPath, entries, opts) {
+    const finished = entries.filter((e) => e.status === "completed" || e.status === "failed");
+    if (finished.length === 0)
+        return;
+    const platform = opts.platform ?? osPlatform();
+    const spawnNotify = opts.spawnNotify ?? defaultSpawnNotify;
+    let store;
+    try {
+        store = new TaskStore({ dbPath });
+        for (const entry of finished) {
+            const record = store.get(entry.taskId);
+            if (!record)
+                continue;
+            const { title, body } = taskNotificationContent(record);
+            const command = osNotifyCommand(platform, title, body);
+            if (!command)
+                return;
+            try {
+                spawnNotify(command.cmd, command.args, {
+                    stdio: "ignore",
+                    timeout: NOTIFY_TIMEOUT_MS,
+                    ...(command.env ? { env: { ...process.env, ...command.env } } : {}),
+                });
+            }
+            catch {
+                // ignore: a notification never changes the tick outcome
+            }
+        }
+    }
+    catch {
+        // unreadable ledger: skip notifications
+    }
+    finally {
+        store?.close();
+    }
+}
+/**
+ * Default queue path. Matches the MCP server's persistence default
+ * (`~/.tidegap/queue.db`, established in v0.7.1) so `tidegap tick`,
+ * `tidegap queue list`, `tidegap receipts list`, and `tidegap stats` all read
+ * the same SQLite ledger the MCP server writes to. Prior versions
+ * defaulted to `~/.ebb/queue.sqlite`, which silently diverged from
+ * the MCP server's actual path — fixed in v0.8.x.
+ *
+ * If the legacy `~/.ebb/queue.sqlite` exists and the new path
+ * doesn't, the legacy path is returned so users who pre-date v0.7.1
+ * keep seeing their historical data. Once they begin writing to
+ * the new path (via the MCP server), pass `--db` explicitly to
+ * read the old one.
+ */
+export function defaultDbPath() {
+    const newPath = join(resolveTidegapHome(), "queue.db");
+    const legacyPath = join(homedir(), ".ebb", "queue.sqlite");
+    if (!existsSync(newPath) && existsSync(legacyPath))
+        return legacyPath;
+    return newPath;
+}
+/**
+ * Build the tick adapters from host-supplied credentials.
+ *
+ * `@tidegap/core` no longer reads the environment, so the CLI (the host)
+ * reads it once via `readEnvCredentials()` and injects the values here. The
+ * registration rules are unchanged: an adapter appears exactly when its
+ * credential is present, Gemini prefers GEMINI_API_KEY over GOOGLE_API_KEY,
+ * and Ollama is an explicit OLLAMA_HOST opt-in.
+ */
+export function buildAdapters(creds = readEnvCredentials()) {
+    const out = {};
+    if (creds.anthropicApiKey) {
+        out.anthropic = new AnthropicAdapter({ apiKey: creds.anthropicApiKey });
+    }
+    if (creds.openaiApiKey) {
+        out.openai = new OpenAIAdapter({ apiKey: creds.openaiApiKey });
+    }
+    // Gemini reads GEMINI_API_KEY, falling back to GOOGLE_API_KEY (resolved in
+    // readEnvCredentials, so `geminiApiKey` here is already the winner).
+    if (creds.geminiApiKey) {
+        out.gemini = new GeminiAdapter({ apiKey: creds.geminiApiKey });
+    }
+    // Ollama is local + keyless: register it only when OLLAMA_HOST is set
+    // (explicit opt-in). The adapter defaults to http://localhost:11434.
+    if (creds.ollamaHost) {
+        out.ollama = new OllamaAdapter({ host: creds.ollamaHost });
+    }
+    return out;
+}
+/**
+ * Provider key expected in the env for a given provider name. Ollama has no
+ * key (it is local + keyless), so it is intentionally absent — a pending
+ * Ollama task is never reported as "missing a key".
+ */
+const PROVIDER_KEY = {
+    anthropic: "ANTHROPIC_API_KEY",
+    openai: "OPENAI_API_KEY",
+    gemini: "GEMINI_API_KEY",
+};
+/**
+ * Inspect the ledger for pending provider-call tasks whose provider key
+ * is missing from the environment. Returns the distinct missing keys.
+ * Best-effort — never throws (a broken/absent DB just yields []).
+ */
+export function missingProviderKeysForPending(dbPath) {
+    const missing = new Set();
+    let store;
+    try {
+        store = new TaskStore({ dbPath });
+        const pending = [
+            ...store.list({ status: "queued" }),
+            ...store.list({ status: "scheduled" }),
+            ...store.list({ status: "submitted" }),
+        ];
+        for (const rec of pending) {
+            if (!rec.bodyJson)
+                continue;
+            let provider;
+            try {
+                provider = JSON.parse(rec.bodyJson)
+                    .provider;
+            }
+            catch {
+                continue;
+            }
+            const key = provider ? PROVIDER_KEY[provider] : undefined;
+            if (key && !process.env[key])
+                missing.add(key);
+        }
+    }
+    catch {
+        // absent / unreadable DB — nothing to warn about.
+    }
+    finally {
+        store?.close();
+    }
+    return [...missing];
+}
+export async function runTickOnce(opts = {}) {
+    // Load the standardized secrets file into the environment for any key
+    // not already set — covers launchd (bare env), systemd, and manual
+    // cron uniformly. Explicit env always wins.
+    loadEnvFileIntoProcess(opts.envFile);
+    // The CLI is the HOST: it reads its environment here, once (after the
+    // secrets file has been folded in), and injects the values into the
+    // environment-pure core library.
+    const env = readEnvCredentials();
+    const dbPath = opts.db ?? defaultDbPath();
+    const adapters = buildAdapters(env);
+    if (Object.keys(adapters).length === 0) {
+        // Loud warning when pending provider tasks exist but no adapter is
+        // configured (no ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY /
+        // OLLAMA_HOST).
+        const missing = missingProviderKeysForPending(dbPath);
+        const detail = missing.length > 0
+            ? `; pending tasks need ${missing.join(" / ")} — set them in ~/.config/tidegap/env`
+            : "";
+        return {
+            exitCode: 0,
+            message: `tick: no adapters configured (set ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY, or OLLAMA_HOST for local); nothing to dispatch${detail}`,
+        };
+    }
+    // Even with some keys present, warn about pending tasks needing a key
+    // we do not have (e.g. OpenAI tasks queued but only ANTHROPIC set).
+    const missingForPending = missingProviderKeysForPending(dbPath);
+    // Aggregate carbon-budget alerts (ROADMAP item 4): read the local budget
+    // config (env wins over ~/.tidegap/config) and log any crossing prominently.
+    // Core no longer reads the environment, so the two TIDEGAP_CARBON_BUDGET_*
+    // variables are read here and passed in — same precedence as before.
+    const carbonBudget = loadCarbonBudgetConfig({
+        path: opts.budgetConfig,
+        env: env.carbonBudget,
+    });
+    const firedAlerts = [];
+    const quotaConfig = loadQuotaResetConfig(opts.budgetConfig !== undefined ? { path: opts.budgetConfig } : {});
+    const scheduler = new Scheduler({
+        dbPath,
+        // A quota_reset series rolls to the label's next reset (ui v2).
+        quotaConfig: () => quotaConfig,
+        defaultRegion: resolveRegion(undefined, opts.region).region,
+        // Same feed the MCP server uses, so the receipt's dispatch-time
+        // intensity comes from the region's live feed (mock only as fallback).
+        feed: buildDefaultGridFeed(env.grid),
+        ...(carbonBudget
+            ? {
+                carbonBudget,
+                onCarbonAlert: (a) => {
+                    firedAlerts.push(a);
+                },
+            }
+            : {}),
+    });
+    try {
+        // Shared pre-tick step (same as the OpenClaw loop): record last_tick_at
+        // and re-resolve quota_reset tasks whose weekly reset already passed, so
+        // they are rescheduled through the window picker, not dispatched late.
+        const preTick = await prepareTick(scheduler, { quotaConfig });
+        const result = await scheduler.tick(adapters);
+        if (opts.notify !== false && !env.noNotify && !notifyDisabledInConfig(opts.budgetConfig)) {
+            notifyFinished(dbPath, result.results, opts);
+        }
+        let msg = `tick: ${result.inspected} inspected, ${result.dispatched} dispatched, ${result.failed} failed`;
+        for (const line of preTick)
+            msg += `\n${line}`;
+        for (const a of firedAlerts) {
+            msg +=
+                `\n!! CARBON BUDGET ALERT: ${a.windowKind} carbon budget crossed — ` +
+                    `${a.actualG} gCO2e used this window vs ${a.thresholdG} g threshold ` +
+                    `(crossed by task ${a.taskIdThatCrossed}). ` +
+                    `Window started ${a.windowStart}.`;
+        }
+        if (missingForPending.length > 0) {
+            msg +=
+                `\n!! WARNING: pending tasks need ${missingForPending.join(" / ")} ` +
+                    `but that key is not set — those tasks cannot dispatch. ` +
+                    `Add it to ~/.config/tidegap/env.`;
+        }
+        return { exitCode: result.failed > 0 ? 1 : 0, message: msg };
+    }
+    finally {
+        scheduler.shutdown();
+    }
+}
+export async function runTick(opts = {}) {
+    if (opts.daemon) {
+        const interval = Math.max(1, opts.interval ?? 60);
+        // eslint-disable-next-line no-console
+        console.log(`[tidegap] tick daemon: every ${interval}s, db=${opts.db ?? defaultDbPath()}`);
+        let stopped = false;
+        const onSignal = () => {
+            stopped = true;
+        };
+        process.on("SIGINT", onSignal);
+        process.on("SIGTERM", onSignal);
+        while (!stopped) {
+            const result = await runTickOnce(opts);
+            // eslint-disable-next-line no-console
+            console.log(result.message);
+            await new Promise((r) => setTimeout(r, interval * 1000));
+        }
+        return 0;
+    }
+    const result = await runTickOnce(opts);
+    // eslint-disable-next-line no-console
+    console.log(result.message);
+    return result.exitCode;
+}
+//# sourceMappingURL=tick.js.map