@cleocode/core 2026.9.22 → 2026.9.23

package/dist/decide/spend.js

@@ -0,0 +1,387 @@
+/**
+ * Monthly spend cap for System One decisions — the CLEO-enforced COST budget
+ * of owner decision D11159 (spec `system-one-integration` §7).
+ *
+ * Every CLEO process on the machine records provider-reported cost (integer
+ * micro-dollars) into ONE ledger, `<cleoHome>/decide/spend.json`, guarded by a
+ * `proper-lockfile` lock. Once the month-to-date spend reaches the cap
+ * (`decide.budget.monthlyMicros`, default
+ * {@link DEFAULT_MONTHLY_SPEND_CAP_MICROS} = $1), every site degrades to its
+ * heuristic with fallback reason `budget` until the UTC month rolls over. It
+ * never fails a command.
+ *
+ * ## Reserve, then commit
+ *
+ * A caller reserves its estimated cost BEFORE the provider call, under the
+ * same lock as the cap check, and commits the reported cost (or releases the
+ * reservation) after it. Concurrent callers therefore see each other's
+ * in-flight spend and cannot overshoot the cap together. A reservation still
+ * pending after {@link RESERVATION_TTL_MS} (its process died, or exited
+ * before its commit landed) is CHARGED at its estimate, not dropped: the
+ * request may have been billed, and the cap must not undercount it.
+ *
+ * The lock retries for about a second with backoff: a decision may wait for
+ * the ledger, but a cost is never dropped because 40 processes recorded at
+ * once (review of #1685: the first version lost 33 of 40 concurrent records).
+ *
+ * The ledger also carries the key-limit stop: a 403 `key_limit_exceeded`
+ * (an unverified provider extension) means the key's monthly decision limit
+ * is reached, so decisions stop until the end of the UTC month.
+ *
+ * A corrupt ledger fails closed (every site uses its heuristic) and
+ * `cleo decide status` says so; `cleo decide budget reset` repairs it, moving
+ * the bad file aside as a receipt. It refuses a readable ledger unless
+ * `--force` is given, and then keeps the month-to-date spend, so a reset can
+ * never lift a reached cap.
+ *
+ * @task T12664
+ * @epic T12486
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getCleoHome } from '@cleocode/paths';
+import lockfile from 'proper-lockfile';
+import { z } from 'zod';
+/** Default monthly cap: 1,000,000 micro-dollars = $1 (D11159). */
+export const DEFAULT_MONTHLY_SPEND_CAP_MICROS = 1_000_000;
+/** Config key holding the monthly cap in micro-dollars. */
+export const MONTHLY_SPEND_CAP_KEY = 'decide.budget.monthlyMicros';
+/**
+ * How long a reservation stays pending, ms. After that it is charged at its
+ * estimate (it may have been billed). Decision deadlines are hundreds of ms,
+ * so a live call always commits or releases long before this.
+ */
+export const RESERVATION_TTL_MS = 60_000;
+/**
+ * The UTC month of `epochMs`, `YYYY-MM`.
+ *
+ * @param epochMs - Epoch milliseconds.
+ * @returns The month string.
+ */
+export function utcMonth(epochMs) {
+    const d = new Date(epochMs);
+    return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
+}
+/**
+ * Epoch ms of the first instant of the next UTC month.
+ *
+ * @param epochMs - Epoch milliseconds.
+ * @returns Start of the next UTC month.
+ */
+export function startOfNextUtcMonth(epochMs) {
+    const d = new Date(epochMs);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1);
+}
+function freshState(now) {
+    return { month: utcMonth(now), spentMicros: 0, keyLimitedUntil: 0, reservations: {} };
+}
+/**
+ * Roll a state over to the current month and charge expired reservations at
+ * their estimate (mutates). An expired reservation's call may have been
+ * billed, so it is counted rather than forgotten.
+ */
+function roll(state, now) {
+    const month = utcMonth(now);
+    if (state.month !== month) {
+        state.month = month;
+        state.spentMicros = 0;
+    }
+    if (state.keyLimitedUntil <= now)
+        state.keyLimitedUntil = 0;
+    for (const [id, r] of Object.entries(state.reservations)) {
+        if (now - r.at >= RESERVATION_TTL_MS) {
+            state.spentMicros += positive(r.micros);
+            delete state.reservations[id];
+        }
+    }
+}
+function reservedOf(state) {
+    return Object.values(state.reservations).reduce((n, r) => n + r.micros, 0);
+}
+function positive(micros) {
+    return Number.isFinite(micros) && micros > 0 ? Math.round(micros) : 0;
+}
+function doReserve(state, capMicros, estimateMicros, now) {
+    roll(state, now);
+    if (state.keyLimitedUntil > now)
+        return { verdict: 'key_limited' };
+    const estimate = positive(estimateMicros);
+    if (state.spentMicros + reservedOf(state) + estimate > capMicros ||
+        state.spentMicros >= capMicros) {
+        return { verdict: 'over_budget' };
+    }
+    const id = randomBytes(8).toString('hex');
+    state.reservations[id] = { micros: estimate, at: now };
+    return { verdict: 'ok', id };
+}
+function toStatus(state) {
+    return {
+        month: state.month,
+        spentMicros: state.spentMicros,
+        reservedMicros: reservedOf(state),
+        ...(state.keyLimitedUntil > 0 ? { keyLimitedUntil: state.keyLimitedUntil } : {}),
+    };
+}
+/** The operations every ledger implements, over a state accessor. */
+function ledgerOver(withState, now) {
+    return {
+        async reserve(capMicros, estimateMicros) {
+            try {
+                return await withState((s) => doReserve(s, capMicros, estimateMicros, now()), true);
+            }
+            catch {
+                return { verdict: 'unavailable' };
+            }
+        },
+        async commit(id, costMicros) {
+            try {
+                await withState((s) => {
+                    roll(s, now());
+                    delete s.reservations[id];
+                    s.spentMicros += positive(costMicros);
+                }, true);
+            }
+            catch {
+                /* the reservation expires; an unrecorded cost only makes the cap later */
+            }
+        },
+        async release(id) {
+            try {
+                await withState((s) => {
+                    delete s.reservations[id];
+                }, true);
+            }
+            catch {
+                /* the reservation expires on its own */
+            }
+        },
+        async record(costMicros) {
+            const micros = positive(costMicros);
+            if (micros === 0)
+                return;
+            try {
+                await withState((s) => {
+                    roll(s, now());
+                    s.spentMicros += micros;
+                }, true);
+            }
+            catch {
+                /* best effort */
+            }
+        },
+        async markKeyLimited() {
+            try {
+                await withState((s) => {
+                    roll(s, now());
+                    s.keyLimitedUntil = startOfNextUtcMonth(now());
+                }, true);
+            }
+            catch {
+                /* the next call meets the 403 again */
+            }
+        },
+        async status() {
+            try {
+                return await withState((s) => {
+                    roll(s, now());
+                    return toStatus(s);
+                }, false);
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+/**
+ * A process-local ledger (tests, callers that must not touch disk).
+ *
+ * @param opts - Clock.
+ * @returns A {@link SpendLedger} that does NOT coordinate across processes.
+ */
+export function createMemorySpendLedger(opts = {}) {
+    const now = opts.now ?? Date.now;
+    const state = freshState(now());
+    return ledgerOver(async (mutate) => mutate(state), now);
+}
+/**
+ * Default ledger location: `<cleoHome>/decide/spend.json`.
+ *
+ * @returns Absolute path.
+ */
+export function defaultSpendStatePath() {
+    return join(getCleoHome(), 'decide', 'spend.json');
+}
+/**
+ * Lock retries: about a second with backoff (5 ms growing to 50 ms). Long
+ * enough that dozens of concurrent processes all get their turn; a caller on
+ * a decision deadline is bounded by that deadline, not by this.
+ */
+const LOCK_OPTIONS = {
+    realpath: false,
+    stale: 5_000,
+    retries: { retries: 40, factor: 1.2, minTimeout: 5, maxTimeout: 50, randomize: true },
+};
+const ledgerSchema = z.object({
+    month: z.string(),
+    spentMicros: z.number().nonnegative(),
+    keyLimitedUntil: z.number().nonnegative(),
+    reservations: z
+        .record(z.string(), z.object({ micros: z.number().nonnegative(), at: z.number() }))
+        .default({}),
+});
+/** Thrown when the ledger file exists but cannot be parsed. */
+class CorruptLedgerError extends Error {
+}
+function readLedger(path, now) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return freshState(now);
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        throw new CorruptLedgerError('spend ledger is not JSON');
+    }
+    const parsed = ledgerSchema.safeParse(json);
+    if (!parsed.success)
+        throw new CorruptLedgerError('spend ledger has an unexpected shape');
+    return parsed.data;
+}
+function writeLedger(path, state) {
+    const tmp = join(dirname(path), `.spend.${randomBytes(6).toString('hex')}.tmp`);
+    writeFileSync(tmp, JSON.stringify(state), 'utf-8');
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* ignore cleanup failure */
+        }
+        throw err;
+    }
+}
+/**
+ * A ledger shared by every process on the machine through a locked JSON file.
+ * A lock or read failure (including a corrupt file) makes `reserve` answer
+ * `unavailable`, which the client treats as a fallback: the cap fails closed,
+ * like the request bucket.
+ *
+ * @param opts - Clock and state path.
+ * @returns A {@link SpendLedger}.
+ */
+export function createFileSpendLedger(opts = {}) {
+    const now = opts.now ?? Date.now;
+    const statePath = opts.statePath ?? defaultSpendStatePath();
+    return ledgerOver(async (mutate, write) => {
+        mkdirSync(dirname(statePath), { recursive: true });
+        const release = await lockfile.lock(statePath, LOCK_OPTIONS);
+        try {
+            const state = readLedger(statePath, now());
+            const result = mutate(state);
+            if (write)
+                writeLedger(statePath, state);
+            return result;
+        }
+        finally {
+            await release().catch(() => undefined);
+        }
+    }, now);
+}
+/**
+ * Whether the ledger file is readable.
+ *
+ * @param statePath - Ledger path. Default {@link defaultSpendStatePath}.
+ * @returns `ok`, `absent`, `corrupt` or `unavailable` (unreadable for another reason).
+ */
+export function inspectSpendLedger(statePath = defaultSpendStatePath()) {
+    if (!existsSync(statePath))
+        return 'absent';
+    try {
+        readLedger(statePath, Date.now());
+        return 'ok';
+    }
+    catch (err) {
+        return err instanceof CorruptLedgerError ? 'corrupt' : 'unavailable';
+    }
+}
+/**
+ * Thrown by {@link resetSpendLedger} when the ledger is not corrupt and
+ * `force` was not given. A reached cap is not a fault to repair.
+ */
+export class SpendResetRefusedError extends Error {
+    /** Health of the ledger that was not reset. */
+    health;
+    /** @param health - The ledger's health (anything but `corrupt`). */
+    constructor(health) {
+        super(`The System One spend ledger is ${health === 'ok' ? 'healthy' : health}, so it was not reset: ` +
+            '`cleo decide budget reset` only repairs a corrupt ledger. A reached monthly cap lifts when ' +
+            'the UTC month rolls over or when `decide.budget.monthlyMicros` is raised; resetting does not ' +
+            'lift it. Pass --force to reset anyway (month-to-date spend is kept; in-flight reservations ' +
+            'and the key-limit stop are cleared).');
+        this.name = 'SpendResetRefusedError';
+        this.health = health;
+    }
+}
+/**
+ * Reset the ledger (`cleo decide budget reset`): move the current file aside
+ * to `spend.json.reset-<iso>` and start a new ledger for this month. The
+ * repair for a corrupt ledger, which otherwise fails closed forever.
+ *
+ * Refuses (throws {@link SpendResetRefusedError}) unless the ledger is
+ * corrupt or `opts.force` is set, so an agent cannot reset its way past a
+ * reached cap. When the old file is readable its month-to-date spend
+ * (expired reservations included) is carried over; only a corrupt file's
+ * spend is lost, and the moved file is kept as the receipt of it.
+ *
+ * @param statePath - Ledger path. Default {@link defaultSpendStatePath}.
+ * @param now - Wall clock, epoch ms.
+ * @param opts - `force` resets a ledger that is not corrupt.
+ * @returns What was reset, the spend carried over and where the old file went.
+ * @throws {SpendResetRefusedError} When the ledger is not corrupt and `force` is not set.
+ */
+export async function resetSpendLedger(statePath = defaultSpendStatePath(), now = Date.now(), opts = {}) {
+    const resetAt = new Date(now).toISOString();
+    mkdirSync(dirname(statePath), { recursive: true });
+    const release = await lockfile.lock(statePath, LOCK_OPTIONS);
+    try {
+        // Inspect under the lock, so the verdict is about the file we move.
+        const before = inspectSpendLedger(statePath);
+        const forced = opts.force === true;
+        if (before !== 'corrupt' && !forced)
+            throw new SpendResetRefusedError(before);
+        const next = freshState(now);
+        if (before === 'ok') {
+            const old = readLedger(statePath, now);
+            roll(old, now);
+            next.spentMicros = old.spentMicros;
+        }
+        let backupPath;
+        if (existsSync(statePath)) {
+            backupPath = `${statePath}.reset-${resetAt.replace(/[:.]/g, '-')}`;
+            renameSync(statePath, backupPath);
+        }
+        writeLedger(statePath, next);
+        return {
+            statePath,
+            before,
+            ...(backupPath ? { backupPath } : {}),
+            resetAt,
+            spentMicros: next.spentMicros,
+            forced,
+        };
+    }
+    finally {
+        await release().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=spend.js.map

package/dist/decide/spend.js.map

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

package/dist/decide/wizard.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Interactive System One setup: `cleo decide config` on a TTY, and the
+ * `system-one` section of `cleo setup`.
+ *
+ * Steps: pick the provider (layahost first, recommended) → `jev` only: the
+ * URL → the API key through {@link WizardIO.secret} (never echoed) → probe
+ * `GET /v1/models` → pick the model (layahost defaults to its routing model)
+ * → optionally confirm a one-question smoke test → save (which probes again
+ * and re-detects capabilities) → run the smoke test when confirmed.
+ *
+ * All logic lives here; the IO is injected, so tests drive it with a stub and
+ * the CLI with readline. Nothing this module returns or prints carries the
+ * key: only the masked last-4 preview from the saved summary.
+ *
+ * @task T12713
+ * @epic T12486
+ */
+import type { WizardIO } from '../setup/wizard.js';
+import { type DecideAskResult, type DecideConfigureResult } from './operations.js';
+/** How many times the wizard re-asks for a URL or model name before giving up. */
+export declare const DECIDE_WIZARD_MAX_ATTEMPTS = 3;
+/** Options for {@link runDecideWizard}. */
+export interface DecideWizardOptions {
+    /** `fetch` for the model probe and the save-time probe; tests inject a stub. */
+    readonly fetch?: typeof fetch;
+    /** Deadline for each probe, ms. Default {@link DEFAULT_DECIDE_PROBE_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** Smoke-test runner. Default: one `decide ask` through the saved settings. */
+    readonly smoke?: () => Promise<DecideAskResult>;
+    /** Project root for the smoke test's audit line. Default: the resolved project root. */
+    readonly projectRoot?: string;
+}
+/** Result of {@link runDecideWizard}. Secret-free. */
+export interface DecideWizardResult {
+    /** Whether settings were saved. */
+    readonly configured: boolean;
+    /** One-line human summary. */
+    readonly summary: string;
+    /** The saved settings, when saved. */
+    readonly config?: DecideConfigureResult;
+    /** The smoke-test answer, when one ran. */
+    readonly smoke?: DecideAskResult;
+}
+/**
+ * Run the interactive System One setup.
+ *
+ * @param io - Prompt surface. The key is read with {@link WizardIO.secret}.
+ * @param opts - Injectable `fetch`, deadline and smoke runner.
+ * @returns Whether settings were saved, a summary and the secret-free results.
+ * @throws {DecideCredentialsError} Only when the save itself rejects the settings.
+ */
+export declare function runDecideWizard(io: WizardIO, opts?: DecideWizardOptions): Promise<DecideWizardResult>;
+//# sourceMappingURL=wizard.d.ts.map

package/dist/decide/wizard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wizard.d.ts","sourceRoot":"","sources":["../../src/decide/wizard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AAGzB,kFAAkF;AAClF,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAM5C,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,oFAAoF;IACpF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;IAChD,wFAAwF;IACxF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,mCAAmC;IACnC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IACxC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;CAClC;AAkDD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,QAAQ,EACZ,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAsF7B"}

package/dist/decide/wizard.js

@@ -0,0 +1,144 @@
+/**
+ * Interactive System One setup: `cleo decide config` on a TTY, and the
+ * `system-one` section of `cleo setup`.
+ *
+ * Steps: pick the provider (layahost first, recommended) → `jev` only: the
+ * URL → the API key through {@link WizardIO.secret} (never echoed) → probe
+ * `GET /v1/models` → pick the model (layahost defaults to its routing model)
+ * → optionally confirm a one-question smoke test → save (which probes again
+ * and re-detects capabilities) → run the smoke test when confirmed.
+ *
+ * All logic lives here; the IO is injected, so tests drive it with a stub and
+ * the CLI with readline. Nothing this module returns or prints carries the
+ * key: only the masked last-4 preview from the saved summary.
+ *
+ * @task T12713
+ * @epic T12486
+ */
+import { isAllowedDecideBaseUrl } from './credentials.js';
+import { isValidDecisionModelName, listJevModels } from './jev-wire.js';
+import { askDecideDebug, configureDecide, DEFAULT_DECIDE_PROBE_TIMEOUT_MS, } from './operations.js';
+import { listDecisionProviderPresets } from './providers.js';
+/** How many times the wizard re-asks for a URL or model name before giving up. */
+export const DECIDE_WIZARD_MAX_ATTEMPTS = 3;
+/** State the smoke test judges; the question should come back "yes". */
+const SMOKE_STATE = 'CLEO setup check: the System One provider was just configured.';
+const SMOKE_QUESTION = 'The text says a provider was configured.';
+/** Ask for a base URL until it is acceptable, or give up. */
+async function askBaseUrl(io) {
+    for (let attempt = 0; attempt < DECIDE_WIZARD_MAX_ATTEMPTS; attempt++) {
+        const url = (await io.prompt('Jev-compatible base URL (e.g. https://provider.example):')).trim();
+        if (!url)
+            return undefined;
+        if (isAllowedDecideBaseUrl(url))
+            return url;
+        io.warn('That URL is not accepted: use an absolute https:// URL (plain http:// only for localhost, 127.0.0.1 or ::1), without user:pass@.');
+    }
+    return undefined;
+}
+/** Ask for a model name until it is valid, or give up. */
+async function askModelName(io) {
+    for (let attempt = 0; attempt < DECIDE_WIZARD_MAX_ATTEMPTS; attempt++) {
+        const model = (await io.prompt('Model name (the provider listed none):')).trim();
+        if (!model)
+            return undefined;
+        if (isValidDecisionModelName(model))
+            return model;
+        io.warn('Model names may contain only letters, digits and . _ : / @ - (1-128 characters).');
+    }
+    return undefined;
+}
+/**
+ * Choose the model: the preset default first (layahost), then the listed
+ * models in the provider's order. With one candidate there is nothing to ask.
+ */
+async function chooseModel(io, preset, listed) {
+    const fallback = preset.defaultModel;
+    const candidates = fallback ? [fallback, ...listed.filter((m) => m !== fallback)] : [...listed];
+    if (candidates.length === 0)
+        return askModelName(io);
+    if (candidates.length === 1) {
+        io.info(`Model: ${candidates[0]}`);
+        return candidates[0];
+    }
+    const question = fallback
+        ? `Which model? (${fallback} is the recommended default)`
+        : 'Which model?';
+    return io.select(question, candidates);
+}
+/**
+ * Run the interactive System One setup.
+ *
+ * @param io - Prompt surface. The key is read with {@link WizardIO.secret}.
+ * @param opts - Injectable `fetch`, deadline and smoke runner.
+ * @returns Whether settings were saved, a summary and the secret-free results.
+ * @throws {DecideCredentialsError} Only when the save itself rejects the settings.
+ */
+export async function runDecideWizard(io, opts = {}) {
+    const presets = listDecisionProviderPresets();
+    const picked = await io.select('Which System One provider?', presets.map((p) => p.label));
+    const preset = presets.find((p) => p.label === picked) ?? presets[0];
+    if (!preset)
+        return { configured: false, summary: 'skipped (no provider presets)' };
+    let baseUrl = preset.defaultBaseUrl;
+    if (preset.requiresUrl || !baseUrl) {
+        baseUrl = await askBaseUrl(io);
+        if (!baseUrl) {
+            io.warn('No valid URL entered; System One left unchanged.');
+            return { configured: false, summary: 'skipped (no valid URL)' };
+        }
+    }
+    const apiKey = (await io.secret(`${preset.kind} API key (input hidden):`)).trim();
+    if (!apiKey) {
+        io.warn('No API key entered; System One left unchanged.');
+        return { configured: false, summary: 'skipped (empty api key)' };
+    }
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_DECIDE_PROBE_TIMEOUT_MS;
+    let listed = [];
+    try {
+        listed = await listJevModels({ baseUrl, apiKey }, AbortSignal.timeout(timeoutMs), {
+            fetch: opts.fetch,
+        });
+        io.info(`Reached ${baseUrl}: ${listed.length} model(s) listed.`);
+    }
+    catch (err) {
+        io.warn(`Could not list models at ${baseUrl}: ${err instanceof Error ? err.message : 'probe failed'}`);
+        if (!(await io.confirm('Save these settings anyway?', false))) {
+            return { configured: false, summary: 'cancelled (provider probe failed)' };
+        }
+    }
+    const model = await chooseModel(io, preset, listed);
+    if (!model) {
+        io.warn('No model chosen; System One left unchanged (the provider rejects requests without one).');
+        return { configured: false, summary: 'skipped (no model)' };
+    }
+    const wantsSmoke = await io.confirm('After saving, ask one test question to confirm it works? (one billed decision)', true);
+    const config = await configureDecide({
+        provider: preset.kind,
+        baseUrl,
+        apiKey,
+        model,
+        fetch: opts.fetch,
+        timeoutMs,
+    });
+    io.info(`Saved ${preset.kind} at ${config.baseUrl ?? baseUrl}: model ${config.model ?? 'none'}, key ${config.keyPreview ?? '…'} (${config.providerState}).`);
+    if (config.warning)
+        io.warn(config.warning);
+    const summary = `${preset.kind} configured (model ${config.model ?? 'none'}, ${config.providerState})`;
+    if (!wantsSmoke)
+        return { configured: true, summary, config };
+    const smoke = await (opts.smoke ??
+        (() => askDecideDebug({
+            state: SMOKE_STATE,
+            question: SMOKE_QUESTION,
+            ...(opts.projectRoot ? { projectRoot: opts.projectRoot } : {}),
+        })))();
+    if (smoke.source === 'provider') {
+        io.info(`Smoke test answered by the provider in ${smoke.latencyMs} ms.`);
+    }
+    else {
+        io.warn(`Smoke test fell back to the heuristic (${smoke.fallbackReason ?? smoke.source}). Check \`cleo decide status\`.`);
+    }
+    return { configured: true, summary, config, smoke };
+}
+//# sourceMappingURL=wizard.js.map

package/dist/decide/wizard.js.map

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

package/dist/docs/docs-audit.d.ts.map

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

package/dist/docs/docs-audit.js

@@ -18,7 +18,7 @@
  * @task T11182 (Saga T10516 — docs audit trail)
  */
 import { createHmac, randomBytes } from 'node:crypto';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
 // ─── Constants ────────────────────────────────────────────────────────────────
 /** Project-root-relative path to the unified docs audit log. */
@@ -46,7 +46,6 @@ function getCheckpointSecret(projectRoot) {
     const secret = randomBytes(CHECKPOINT_SECRET_BYTES);
     // Atomically write: tmp → rename
     const tmpPath = join(auditDir, '.audit-secret.tmp');
-    const { writeFileSync } = require('node:fs');
     writeFileSync(tmpPath, secret.toString('hex'), { encoding: 'utf-8', mode: 0o600 });
     renameSync(tmpPath, secretPath);
     return secret;