llm-relay 0.43.0 → 0.45.1

package/dist/cli.js

@@ -8,7 +8,7 @@ import { loadEnvFile } from "./dotenv.js";
 import { recoverWindowsEnv } from "./winenv.js";
 import { offloadState, setOffload } from "./offload.js";
 import { buildCandidates } from "./candidates.js";
-import { makeCredentialId } from "./credential-id.js";
+import { CREDENTIAL_LABEL_PATTERN, makeCredentialId, parseCredentialId } from "./credential-id.js";
 import { providerCredentialSlots, slotAllowsModel } from "./credential-fleet.js";
 import { loadLaneManifest, verifyModel } from "./lane-manifest.js";
 import { probeLanes } from "./lane-probe.js";
@@ -33,6 +33,7 @@ import { DASHBOARD_MEDIA_TYPE, isDashboardUtcTimestamp } from "./dashboard-contr
 import { DASHBOARD_BOOTSTRAP_SCHEMA, DASHBOARD_BOOTSTRAP_REQUEST_SCHEMA } from "./dashboard-routes.js";
 import { flushRuntimeTelemetry } from "./ping/runtime-telemetry.js";
 import { flushProbeCache } from "./ping/probe-cache.js";
+import { runKeysAddLocal, runKeysDisableLocal, runKeysEnableLocal, runKeysExportLocal, runKeysImportLocal, runKeysListLocal, runKeysRemoveLocal, runKeysRevokeLocal, runKeysRotateLocal, runKeysUnlockLocal, } from "./keys-cli.js";
 const VALUE_FLAGS = new Set([
     "--config", "-config", "-c",
     "--provider", "-provider", "-p",
@@ -51,6 +52,7 @@ const VALUE_FLAGS = new Set([
     "--host", "-host",
     "--client", "-client",
     "--scope", "-scope",
+    "--credential", "-credential",
     "--include", "-include",
     "--window", "-window",
     "--by", "-by",
@@ -62,6 +64,9 @@ const VALUE_FLAGS = new Set([
     "--reset-field", "-reset-field",
     "--reset-ms", "-reset-ms",
     "--import", "-import",
+    "--label", "-label",
+    "--env-name", "-env-name",
+    "--out", "-out",
 ]);
 let cachedArgv;
 let cachedParsedArgs;
@@ -157,7 +162,8 @@ ${formatTextTable([
     ["llm-relay [options]", "Start proxy."],
     ["llm-relay onboard [--import <file>] [--force]", "Set up or import provider keys."],
     ["llm-relay setup [target]", "target: claude-cli | claude-desktop."],
-    ["llm-relay keys | check-keys", "Check every configured credential slot."],
+    ["llm-relay keys | keys check | check-keys", "Check every configured credential slot."],
+    ["llm-relay keys <action> ...", "action: add|list|rotate|revoke|remove|disable|enable|export|import|unlock."],
     ["llm-relay pools [--probe]", "List members; --probe tests each deployment once."],
     ["llm-relay pools <action> <name> [<spec>...]", "action: set|add|remove|delete."],
     ["llm-relay routing <action> ...", "action: show|get|default|tier|subagent|sort|benchmark|set|unset."],
@@ -168,6 +174,7 @@ ${formatTextTable([
     ["llm-relay telemetry", "Print telemetry JSON."],
     ["llm-relay offload [status]", "Show current offload rules."],
     ["llm-relay offload <harness> <on|off> [--scope <scope>]", "Toggle one harness (claude | codex); scope: subagents | all."],
+    ["llm-relay cooldowns clear <provider>[/<model>] [--credential <label>]", "Clear live cooling state; requires the running relay."],
     ["llm-relay candidates [-p <name>]", "Compare deployment x credential-slot targets."],
     ["llm-relay cost [--window <w>] [--by <d>] [--include-repair]", "Summarise spend from the local accounting ledger."],
     ["llm-relay eligibility", "What backends said about themselves; refusals awaiting interpretation."],
@@ -262,6 +269,7 @@ ${formatTextTable([
     ["GET /candidates", "Deployment x credential policy/state/quota/breaker cells."],
     ["GET|POST /offload", "Read/set rules; accepts ?client=<name>."],
     ["GET|POST /dispatch", "Read/set next lane; POST {\"exhausted\":\"<lane>\"}."],
+    ["POST /cooldowns/clear", "Clear scoped live cooling state."],
     ["GET /telemetry", "Provider telemetry."],
     ["GET /ping", "Run health probe."],
     ["GET /health", "Provider health."],
@@ -666,6 +674,43 @@ export async function runCheckKeys() {
     ];
     process.stdout.write(formatTextTable(rows) + "\n");
 }
+/** `llm-relay keys add` — CLI-local credential insertion; secret input is never argv. */
+export async function runKeysAdd(provider = getPositionalArgs(process.argv)[2], deps = {}) {
+    await runKeysAddLocal(deps.config ?? loadOrExit(), provider, {
+        ...(argValue("--label", "-label") === undefined
+            ? {} : { label: argValue("--label", "-label") }),
+        ...(argValue("--env-name", "-env-name") === undefined
+            ? {} : { envName: argValue("--env-name", "-env-name") }),
+        check: hasFlag("--check", "-check"),
+    }, deps);
+}
+export async function runKeysList(deps = {}) {
+    runKeysListLocal(deps.config ?? loadOrExit(), deps);
+}
+export async function runKeysRotate(credential = getPositionalArgs(process.argv)[2], deps = {}) {
+    await runKeysRotateLocal(deps.config ?? loadOrExit(), credential, deps);
+}
+export async function runKeysRevoke(credential = getPositionalArgs(process.argv)[2], deps = {}) {
+    runKeysRevokeLocal(credential, deps);
+}
+export async function runKeysRemove(credential = getPositionalArgs(process.argv)[2], deps = {}) {
+    runKeysRemoveLocal(credential, hasFlag("--purge", "-purge"), deps);
+}
+export async function runKeysDisable(credential = getPositionalArgs(process.argv)[2], deps = {}) {
+    runKeysDisableLocal(credential, deps);
+}
+export async function runKeysEnable(credential = getPositionalArgs(process.argv)[2], deps = {}) {
+    runKeysEnableLocal(credential, deps);
+}
+export async function runKeysExport(deps = {}) {
+    await runKeysExportLocal(argValue("--out", "-out"), deps);
+}
+export async function runKeysImport(importPath = getPositionalArgs(process.argv)[2], deps = {}) {
+    await runKeysImportLocal(deps.config ?? loadOrExit(), importPath, deps);
+}
+export async function runKeysUnlock(deps = {}) {
+    await runKeysUnlockLocal(deps);
+}
 /**
  * Talk to a RUNNING proxy if there is one. The offload switch has to reach the live process to
  * take effect without a restart, and `candidates` gets better data from it (warm ping history,
@@ -702,6 +747,301 @@ export function proxyUrl(cfg, path) {
     const host = cfg.host.includes(":") ? `[${cfg.host}]` : cfg.host;
     return `http://${host}:${cfg.port}${path}`;
 }
+function cooldownCommandFailure(message) {
+    process.stderr.write(`llm-relay cooldowns: ${message}\n`);
+    process.exit(1);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+    const actual = Object.keys(value);
+    return actual.length === keys.length && actual.every((key) => keys.includes(key));
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+const COOLING_FACT_KINDS = new Set([
+    "allowance-exhausted",
+    "rate-limited",
+    "credential-invalid",
+]);
+function credentialIdBelongsTo(provider, value) {
+    if (typeof value !== "string")
+        return false;
+    return parseCredentialId(value)?.provider === provider;
+}
+function isCooldownFactScope(value) {
+    if (!isRecord(value))
+        return false;
+    switch (value.kind) {
+        case "attempt":
+            return hasExactKeys(value, ["kind", "provider", "credentialId", "model"]) &&
+                nonEmptyString(value.provider) &&
+                credentialIdBelongsTo(value.provider, value.credentialId) &&
+                nonEmptyString(value.model);
+        case "group": {
+            const keys = Object.hasOwn(value, "credentialId")
+                ? ["kind", "provider", "credentialId", "members"]
+                : ["kind", "provider", "members"];
+            return hasExactKeys(value, keys) &&
+                nonEmptyString(value.provider) &&
+                Array.isArray(value.members) &&
+                value.members.length > 0 &&
+                value.members.every(nonEmptyString) &&
+                (!Object.hasOwn(value, "credentialId") || credentialIdBelongsTo(value.provider, value.credentialId));
+        }
+        case "deployment":
+            return hasExactKeys(value, ["kind", "provider", "model"]) &&
+                nonEmptyString(value.provider) && nonEmptyString(value.model);
+        case "credential":
+            return hasExactKeys(value, ["kind", "provider", "credentialId"]) &&
+                nonEmptyString(value.provider) && credentialIdBelongsTo(value.provider, value.credentialId);
+        case "provider":
+            return hasExactKeys(value, ["kind", "provider"]) && nonEmptyString(value.provider);
+        case "model":
+            return hasExactKeys(value, ["kind", "model"]) && nonEmptyString(value.model);
+        default:
+            return false;
+    }
+}
+function scopeIsContainedByTarget(scope, target) {
+    const credentialId = target.credential === undefined
+        ? undefined
+        : makeCredentialId(target.provider, target.credential);
+    switch (scope.kind) {
+        case "attempt":
+            return scope.provider === target.provider &&
+                (target.model === undefined || scope.model === target.model) &&
+                (credentialId === undefined || scope.credentialId === credentialId);
+        case "group":
+            return scope.provider === target.provider &&
+                (target.model === undefined || scope.members.every((member) => member === target.model)) &&
+                (credentialId === undefined || scope.credentialId === credentialId);
+        case "deployment":
+            return scope.provider === target.provider && credentialId === undefined &&
+                (target.model === undefined || scope.model === target.model);
+        case "credential":
+            return scope.provider === target.provider && target.model === undefined &&
+                (credentialId === undefined || scope.credentialId === credentialId);
+        case "provider":
+            return scope.provider === target.provider && target.model === undefined && credentialId === undefined;
+        case "model":
+            return false;
+    }
+}
+function isCooldownCell(value, target) {
+    if (!isRecord(value) || !hasExactKeys(value, ["provider", "model", "credential"]))
+        return false;
+    if (!nonEmptyString(value.provider) || value.provider !== target.provider)
+        return false;
+    if (!(value.model === null || nonEmptyString(value.model)))
+        return false;
+    if (!nonEmptyString(value.credential) || !CREDENTIAL_LABEL_PATTERN.test(value.credential))
+        return false;
+    return (target.model === undefined || value.model === target.model) &&
+        (target.credential === undefined || value.credential === target.credential);
+}
+function isCooldownFact(value, target) {
+    return isRecord(value) &&
+        hasExactKeys(value, ["kind", "scope"]) &&
+        typeof value.kind === "string" &&
+        COOLING_FACT_KINDS.has(value.kind) &&
+        isCooldownFactScope(value.scope) &&
+        scopeIsContainedByTarget(value.scope, target);
+}
+function isClearedGroup(value, isItem) {
+    if (!isRecord(value) || !hasExactKeys(value, ["count", "items"]) ||
+        typeof value.count !== "number" || !Number.isSafeInteger(value.count) ||
+        value.count < 0 || !Array.isArray(value.items)) {
+        return false;
+    }
+    return value.count === value.items.length && value.items.every(isItem);
+}
+function isExactCooldownTarget(value, expected) {
+    if (!isRecord(value))
+        return false;
+    const keys = [
+        "provider",
+        ...(expected.model === undefined ? [] : ["model"]),
+        ...(expected.credential === undefined ? [] : ["credential"]),
+    ];
+    return hasExactKeys(value, keys) &&
+        value.provider === expected.provider &&
+        (expected.model === undefined || value.model === expected.model) &&
+        (expected.credential === undefined || value.credential === expected.credential);
+}
+function isCooldownClearResult(value, target) {
+    if (!isRecord(value) || !hasExactKeys(value, ["target", "cleared"]) ||
+        !isExactCooldownTarget(value.target, target) || !isRecord(value.cleared) ||
+        !hasExactKeys(value.cleared, ["breakerCells", "credentialFaults", "facts"])) {
+        return false;
+    }
+    return isClearedGroup(value.cleared.breakerCells, (item) => isCooldownCell(item, target)) &&
+        isClearedGroup(value.cleared.credentialFaults, (item) => isCooldownCell(item, target)) &&
+        isClearedGroup(value.cleared.facts, (item) => isCooldownFact(item, target));
+}
+const COOLDOWN_CLEAR_OPTIONS = new Map([
+    ["--credential", { semantic: "credential", takesValue: true }],
+    ["--json", { semantic: "json", takesValue: false }],
+    ["--config", { semantic: "config", takesValue: true }],
+    ["-c", { semantic: "config", takesValue: true }],
+    ["--provider", { semantic: "provider", takesValue: true }],
+    ["-p", { semantic: "provider", takesValue: true }],
+    ["--refresh", { semantic: "refresh", takesValue: false }],
+    ["-r", { semantic: "refresh", takesValue: false }],
+]);
+const CLI_COMMAND_NAMES = new Set([
+    "onboard", "setup", "keys", "check-keys", "models", "ping", "dashboard", "telemetry",
+    "offload", "lanes", "dispatch", "cooldowns", "eligibility", "candidates", "cost", "pools",
+    "routing", "route", "config", "help", "version",
+]);
+/** Find a real command token without letting a typoed option/value pair hide a later mutation. */
+function rawCliCommand(argv) {
+    for (let index = 2; index < argv.length; index++) {
+        const arg = argv[index];
+        if (!arg.startsWith("-")) {
+            if (CLI_COMMAND_NAMES.has(arg))
+                return arg;
+            continue;
+        }
+        const equalsAt = arg.indexOf("=");
+        const flag = equalsAt === -1 ? arg : arg.slice(0, equalsAt);
+        if (equalsAt === -1 && VALUE_FLAGS.has(flag)) {
+            // A missing value before the mutation must reach the strict parser, where it exits 1.
+            if (argv[index + 1] === "cooldowns" && argv[index + 2] === "clear")
+                return "cooldowns";
+            index += 1;
+        }
+    }
+    return undefined;
+}
+function parseCooldownClearArgs(argv) {
+    const positionals = [];
+    const seen = new Set();
+    let credential;
+    let json = false;
+    for (let index = 2; index < argv.length; index++) {
+        const arg = argv[index];
+        if (!arg.startsWith("-")) {
+            positionals.push(arg);
+            continue;
+        }
+        const equalsAt = arg.indexOf("=");
+        const flag = equalsAt === -1 ? arg : arg.slice(0, equalsAt);
+        const option = COOLDOWN_CLEAR_OPTIONS.get(flag);
+        if (option === undefined)
+            cooldownCommandFailure(`unknown option "${flag}"`);
+        if (seen.has(option.semantic))
+            cooldownCommandFailure(`duplicate option "${flag}"`);
+        seen.add(option.semantic);
+        if (!option.takesValue) {
+            if (equalsAt !== -1)
+                cooldownCommandFailure(`${flag} does not take a value`);
+            if (option.semantic === "json")
+                json = true;
+            continue;
+        }
+        const value = equalsAt === -1 ? argv[index + 1] : arg.slice(equalsAt + 1);
+        if (value === undefined || value.length === 0 || (equalsAt === -1 && value.startsWith("-"))) {
+            cooldownCommandFailure(`${flag} requires a value`);
+        }
+        if (equalsAt === -1)
+            index += 1;
+        if (option.semantic === "credential")
+            credential = value;
+    }
+    if (positionals.length !== 3 || positionals[0] !== "cooldowns" || positionals[1] !== "clear") {
+        cooldownCommandFailure("usage: llm-relay cooldowns clear <provider>[/<model>] [--credential <label>] [--json]");
+    }
+    return {
+        spec: positionals[2],
+        ...(credential === undefined ? {} : { credential }),
+        json,
+    };
+}
+function controlErrorMessage(value) {
+    if (!isRecord(value) || !isRecord(value.error) || typeof value.error.message !== "string")
+        return null;
+    return value.error.message;
+}
+/** Clear process-local routing cooldowns through the protected live control plane only. */
+export async function runCooldowns(_action, _spec) {
+    const parsed = parseCooldownClearArgs(process.argv);
+    const { spec, credential } = parsed;
+    const { provider, model } = splitSpec(spec);
+    if (provider.length === 0 || model === "") {
+        cooldownCommandFailure("target must be <provider> or <provider>/<model>");
+    }
+    if (credential !== undefined && !CREDENTIAL_LABEL_PATTERN.test(credential)) {
+        cooldownCommandFailure("--credential must match [A-Za-z0-9_.-]{1,32}");
+    }
+    const target = {
+        provider,
+        ...(model === undefined ? {} : { model }),
+        ...(credential === undefined ? {} : { credential }),
+    };
+    const cfg = loadOrExit();
+    if (!Object.hasOwn(cfg.providers, provider)) {
+        cooldownCommandFailure(`no provider "${provider}" configured`);
+    }
+    let authorization;
+    try {
+        authorization = createControlAuthorization(resolveControlAuthorizationConfigDir(cfg.sourcePath));
+    }
+    catch {
+        cooldownCommandFailure("control authorization is unavailable; the relay must be running with this config");
+    }
+    let response = null;
+    try {
+        response = await fetch(proxyUrl(cfg, "/cooldowns/clear"), {
+            method: "POST",
+            headers: authorization.attach({ "content-type": "application/json" }),
+            body: JSON.stringify(target),
+            signal: AbortSignal.timeout(5000),
+        });
+    }
+    catch {
+        // Report below with the same explicit no-file-fallback outcome for every transport failure.
+    }
+    if (response === null) {
+        cooldownCommandFailure("the relay must be running to clear cooldowns");
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        cooldownCommandFailure("the running relay returned an invalid cooldown-clear response");
+    }
+    if (!response.ok) {
+        const detail = controlErrorMessage(payload);
+        cooldownCommandFailure(`the running relay rejected the clear${detail === null ? "" : `: ${detail}`}`);
+    }
+    if (!isCooldownClearResult(payload, target)) {
+        cooldownCommandFailure("the running relay returned an invalid cooldown-clear response");
+    }
+    if (parsed.json) {
+        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+        return;
+    }
+    const targetLabel = `${provider}${model === undefined ? "" : `/${model}`}${credential === undefined ? "" : ` [credential ${credential}]`}`;
+    process.stdout.write(`Cleared cooldown state for ${targetLabel}\n`);
+    const groups = [
+        ["breaker cells", payload.cleared.breakerCells],
+        ["credential faults", payload.cleared.credentialFaults],
+    ];
+    for (const [label, group] of groups) {
+        process.stdout.write(`  ${label}: ${group.count}\n`);
+        for (const cell of group.items) {
+            process.stdout.write(`    ${cell.provider}/${cell.model ?? "*"} [credential ${cell.credential}]\n`);
+        }
+    }
+    process.stdout.write(`  cooling facts: ${payload.cleared.facts.count}\n`);
+    for (const fact of payload.cleared.facts.items) {
+        process.stdout.write(`    ${fact.kind} ${describeScope(fact.scope)}\n`);
+    }
+}
 export const DASHBOARD_BROWSER_OPEN_TIMEOUT_MS = 5_000;
 function isDashboardBootstrapWire(value, now) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
@@ -2418,11 +2758,107 @@ import { importKeysFromFile } from "./key-import.js";
 import { setupClaudeCli, setupClaudeDesktop } from "./setup-claude.js";
 import { getTelemetryReport } from "./telemetry.js";
 import { globalCircuitBreaker } from "./circuit-breaker.js";
+const KEYS_SUBCOMMANDS = [
+    "add", "list", "rotate", "revoke", "remove", "disable", "enable", "export", "import",
+    "unlock", "check",
+];
+const KEYS_GLOBAL_FLAGS = ["--config", "-config", "-c"];
+const KEYS_FLAGS = {
+    add: ["--label", "-label", "--env-name", "-env-name", "--check", "-check"],
+    list: [],
+    rotate: [],
+    revoke: [],
+    remove: ["--purge", "-purge"],
+    disable: [],
+    enable: [],
+    export: ["--out", "-out"],
+    import: [],
+    unlock: [],
+    check: [],
+};
+const KEYS_POSITIONAL_COUNT = {
+    add: 3,
+    list: 2,
+    rotate: 3,
+    revoke: 3,
+    remove: 3,
+    disable: 3,
+    enable: 3,
+    export: 2,
+    import: 3,
+    unlock: 2,
+    check: 2,
+};
+/** Strict, secret-safe keys parser. Diagnostics deliberately never echo rejected argv tokens. */
+export function validateKeysCommandArgs(argv) {
+    const positionals = getPositionalArgs(argv);
+    const candidate = positionals[1];
+    if (candidate !== undefined && !KEYS_SUBCOMMANDS.includes(candidate)) {
+        return `unknown subcommand; valid subcommands: ${KEYS_SUBCOMMANDS.join(", ")}`;
+    }
+    const subcommand = candidate;
+    const allowed = new Set(KEYS_GLOBAL_FLAGS);
+    if (subcommand !== undefined) {
+        for (const flag of KEYS_FLAGS[subcommand])
+            allowed.add(flag);
+    }
+    for (let index = 2; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === undefined || !arg.startsWith("-"))
+            continue;
+        const equalsAt = arg.indexOf("=");
+        const flag = equalsAt === -1 ? arg : arg.slice(0, equalsAt);
+        if (!allowed.has(flag))
+            return "unsupported option";
+        if (VALUE_FLAGS.has(flag)) {
+            if (equalsAt !== -1) {
+                if (arg.slice(equalsAt + 1).length === 0)
+                    return "invalid arguments";
+            }
+            else {
+                const value = argv[index + 1];
+                if (value === undefined || value.startsWith("-"))
+                    return "invalid arguments";
+                index += 1;
+            }
+        }
+        else if (equalsAt !== -1) {
+            return "invalid arguments";
+        }
+    }
+    const expected = subcommand === undefined ? 1 : KEYS_POSITIONAL_COUNT[subcommand];
+    return positionals.length === expected ? null : "invalid arguments";
+}
+function reportKeysCommandError(error) {
+    process.stderr.write(`llm-relay keys: ${error.message}\n`);
+    process.exit(1);
+}
+function runKeysPromise(operation) {
+    operation.catch(reportKeysCommandError);
+}
 export function main() {
+    const rawCommand = rawCliCommand(process.argv);
     const positionals = getPositionalArgs(process.argv);
     const arg2 = positionals[0];
     const arg3 = positionals[1];
     const arg4 = positionals[2];
+    if (arg2 === "keys") {
+        const validationError = validateKeysCommandArgs(process.argv);
+        if (validationError !== null) {
+            process.stderr.write(`llm-relay keys: ${validationError}\n`);
+            process.exit(1);
+            return;
+        }
+    }
+    // Mutation parsing owns its raw argv so help/version-shaped typos cannot bypass fail-closed
+    // validation and turn a scoped clear into a wider request.
+    if (rawCommand === "cooldowns" || arg2 === "cooldowns") {
+        // Keep validation synchronous at the entrypoint; `runCooldowns` is async, and otherwise a
+        // parser failure would become an unobserved rejected promise after main returned.
+        parseCooldownClearArgs(process.argv);
+        void runCooldowns(arg3, arg4);
+        return;
+    }
     if (hasFlag("--help", "-h") || arg2 === "help") {
         process.stdout.write(HELP);
         process.exit(0);
@@ -2471,13 +2907,57 @@ export function main() {
         process.stdout.write(JSON.stringify(report, null, 2) + "\n");
         return;
     }
-    if (arg2 === "keys" || arg2 === "check-keys") {
+    if (arg2 === "check-keys") {
         runCheckKeys().catch((e) => {
             process.stderr.write(`llm-relay check-keys: ${e.message}\n`);
             process.exit(1);
         });
         return;
     }
+    if (arg2 === "keys") {
+        switch (arg3) {
+            case undefined:
+            case "check":
+                // Bare `keys` remains byte-for-byte the same status command as `check-keys`.
+                runCheckKeys().catch((e) => {
+                    process.stderr.write(`llm-relay check-keys: ${e.message}\n`);
+                    process.exit(1);
+                });
+                return;
+            case "add":
+                runKeysPromise(runKeysAdd(arg4));
+                return;
+            case "list":
+                runKeysPromise(runKeysList());
+                return;
+            case "rotate":
+                runKeysPromise(runKeysRotate(arg4));
+                return;
+            case "revoke":
+                runKeysPromise(runKeysRevoke(arg4));
+                return;
+            case "remove":
+                runKeysPromise(runKeysRemove(arg4));
+                return;
+            case "disable":
+                runKeysPromise(runKeysDisable(arg4));
+                return;
+            case "enable":
+                runKeysPromise(runKeysEnable(arg4));
+                return;
+            case "export":
+                runKeysPromise(runKeysExport());
+                return;
+            case "import":
+                runKeysPromise(runKeysImport(arg4));
+                return;
+            case "unlock":
+                runKeysPromise(runKeysUnlock());
+                return;
+            default:
+                throw new Error("unreachable keys subcommand after validation");
+        }
+    }
     if (arg2 === "models") {
         runModels().catch((e) => {
             process.stderr.write(`llm-relay: ${e.message}\n`);
@@ -2623,6 +3103,15 @@ export function classifyCommand(argv) {
             return arg4 === "on" || arg4 === "enable" || arg4 === "off" || arg4 === "disable"
                 ? "mutating"
                 : "read-only";
+        // Clears process-local relay state through the authenticated mutation plane.
+        case "cooldowns":
+            return arg3 === "clear" ? "mutating" : "read-only";
+        case "keys":
+            return arg3 === "add" || arg3 === "rotate" || arg3 === "revoke" ||
+                arg3 === "remove" || arg3 === "disable" || arg3 === "enable" ||
+                arg3 === "export" || arg3 === "import"
+                ? "mutating"
+                : "read-only";
         case "config":
             return arg3 === "set" || arg3 === "unset" ? "mutating" : "read-only";
         case "routing":
@@ -2641,7 +3130,7 @@ export function classifyCommand(argv) {
             return arg3 === "accept" || arg3 === "reject" || arg3 === "propose" ? "mutating" : "read-only";
         case "dashboard":
             return "read-only";
-        // keys, check-keys, models, telemetry, dispatch, candidates, pools, ping, help, version —
+        // check-keys, models, telemetry, dispatch, candidates, pools, ping, help, version —
         // and anything not yet listed. `dispatch -x` is included on purpose: it reports spend to a
         // running proxy's in-memory cooldowns and changes nothing on this machine.
         default:
@@ -2649,10 +3138,23 @@ export function classifyCommand(argv) {
     }
 }
 /**
- * Entrypoint: currency gate first (may replace this install and re-exec), then
- * the command itself. `main` stays synchronous so its exit paths are direct.
+ * Entrypoint: fail-closed mutation syntax, then the currency gate (which may replace this install
+ * and re-exec), then the command itself. `main` stays synchronous so its exit paths are direct.
  */
 export async function run() {
+    // Reject malformed mutation argv before the self-update gate can perform any network request
+    // or replace the installed CLI. Keys diagnostics stay generic so rejected argv is never echoed.
+    const command = rawCliCommand(process.argv);
+    if (command === "cooldowns")
+        parseCooldownClearArgs(process.argv);
+    if (command === "keys") {
+        const validationError = validateKeysCommandArgs(process.argv);
+        if (validationError !== null) {
+            process.stderr.write(`llm-relay keys: ${validationError}\n`);
+            process.exit(1);
+            return;
+        }
+    }
     if (shouldCheckUpdates(process.argv, process.env, classifyCommand(process.argv))) {
         try {
             await ensureUpToDate();