honeydo 0.1.0 → 0.1.2

package/packages/gcli/dist/cli.js

@@ -25,7 +25,7 @@
  * backend's own timeout flag.
  */
 import { spawn } from "node:child_process";
-import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { copyFileSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { emitKeypressEvents } from "node:readline";
@@ -60,6 +60,38 @@ export const QUOTA_CACHE_PATH = `${homedir()}/.config/gcli/quota-cache.json`;
 const QUOTA_TTL_OK_MS = 60_000;
 const QUOTA_TTL_FAIL_MS = 15_000;
 const QUOTA_FETCH_TIMEOUT_MS = 2_500;
+// ---------------------------------------------------------------------------
+// hermes backend — paths & constants
+// ---------------------------------------------------------------------------
+const HERMES_BIN = "hermes";
+/** hermes 主配置文件（model 段 + providers 段是本子命令的编辑目标）。 */
+export const HERMES_CONFIG_PATH = `${homedir()}/.hermes/config.yaml`;
+/** hermes env 文件（provider API key 的落点；全程保持 0o600）。 */
+export const HERMES_ENV_PATH = `${homedir()}/.hermes/.env`;
+/** hermes cron 任务定义（重 pin 只读它；改动经 `hermes cron edit` 下发）。 */
+export const HERMES_CRON_JOBS_PATH = `${homedir()}/.hermes/cron/jobs.json`;
+/** hermes 会话库（session_model_usage 表在此 —— 实测在顶层 state.db）。 */
+export const HERMES_STATE_DB_PATH = `${homedir()}/.hermes/state.db`;
+/** cc-switch name → hermes provider 字段映射（keyEnv/modelOverride）。 */
+export const HERMES_PROVIDERS_REGISTRY_PATH = `${homedir()}/.config/gcli/hermes-providers.json`;
+/** 上一次切换的一跳记录（0o600，含旧 token 的 prevValue）。 */
+export const HERMES_STATE_PATH = `${homedir()}/.config/gcli/hermes-state.json`;
+/** hermes providers 条目的 transport 常量（cc-switch 只提供 anthropic 兼容端点）。 */
+export const HERMES_TRANSPORT = "anthropic_messages";
+/** 切换后验证 ping 的硬超时。 */
+export const HERMES_VERIFY_TIMEOUT_MS = 60_000;
+/**
+ * 内置 seed（防推导造出与现有配置平行的条目）：键是 cc-switch provider 名，
+ * 值是 hermes 侧已手工建立好的 id/keyEnv。
+ */
+export const HERMES_PROVIDER_SEEDS = {
+    // cc-switch 真实条目名（09-06 sqlite3 实证）：kimi 系的 coding plan 条目叫 "kimi"
+    kimi: { id: "kimi-coding", keyEnv: "KIMI_CODING_API_KEY" },
+    "Kimi For Coding": { id: "kimi-coding", keyEnv: "KIMI_CODING_API_KEY" },
+    "glm flash lastest": { id: "glm-flash", keyEnv: "BIGMODEL_API_KEY" },
+};
+/** `status`/`rollback` 为 hermes 子命令的保留字位置参数。 */
+const HERMES_RESERVED_WORDS = new Set(["status", "rollback"]);
 /** Provider-name allowlist (C4b). Names outside this set are rejected. */
 const PROVIDER_NAME_RE = /^[A-Za-z0-9 &._-]+$/;
 // ---------------------------------------------------------------------------
@@ -87,6 +119,8 @@ export function parseSubcommand(argv) {
         return { subcommand: "claude", rest: argv.slice(1) };
     if (first === "api")
         return { subcommand: "api", rest: argv.slice(1) };
+    if (first === "hermes")
+        return { subcommand: "hermes", rest: argv.slice(1) };
     if (first.startsWith("-"))
         return { subcommand: undefined, rest: argv };
     return { error: `unknown subcommand: ${first}` };
@@ -466,15 +500,28 @@ export function buildClaudeArgs(opts) {
  * high-quality output in ~45s vs claude-agent's 53min). We rely on a sufficient
  * --max-tokens budget (default 80000) to cover both thinking and text, not on
  * disabling thinking. Disabling it would discard the very capability we chose
- * k3 for.
+ * k3 for. (`--thinking auto`, the CLI default, preserves this omitted-field
+ * behaviour. bigmodel GLM endpoints default thinking ON and share max_tokens
+ * between thinking and text — small explicit budgets can end up thinking-only;
+ * --thinking off/on send explicit disabled/enabled for that case.)
  */
 export function buildApiBody(req) {
-    return {
+    const body = {
         model: req.model,
         max_tokens: req.maxTokens,
         stream: req.stream,
         messages: [{ role: "user", content: req.prompt }],
     };
+    if (req.thinking === "off") {
+        body.thinking = { type: "disabled" };
+    }
+    else if (req.thinking === "on") {
+        body.thinking = {
+            type: "enabled",
+            budget_tokens: Math.floor(req.maxTokens / 2),
+        };
+    }
+    return body;
 }
 /**
  * Build the full URL for the messages endpoint. The cc-switch base_url is
@@ -497,24 +544,7 @@ export function buildApiEndpoint(baseUrl) {
  * `data:{...}` (kimi, no space) and `data: {...}` (with space) parse the same.
  */
 export function extractTextDelta(line) {
-    const trimmed = line.trim();
-    if (!trimmed.startsWith("data:"))
-        return null;
-    const payload = trimmed.slice("data:".length).trim();
-    if (!payload || payload === "[DONE]")
-        return null;
-    try {
-        const evt = JSON.parse(payload);
-        if (evt.type === "content_block_delta" &&
-            evt.delta?.type === "text_delta" &&
-            typeof evt.delta.text === "string") {
-            return evt.delta.text;
-        }
-        return null;
-    }
-    catch {
-        return null;
-    }
+    return extractSseLineMeta(line).text;
 }
 /**
  * Aggregate text from a non-streaming messages response body.
@@ -539,6 +569,564 @@ export function extractNonStreamText(body) {
     }
     return out;
 }
+const SSE_LINE_EMPTY = {
+    text: null,
+    thinkingChars: 0,
+    parsed: false,
+};
+/**
+ * SSE line → structured meta (text delta + thinking volume + stop_reason).
+ *
+ * One JSON.parse per line feeding both the text aggregation and the "why did a
+ * stream produce no text" diagnosis (thinking-only streams that end in
+ * stop_reason=max_tokens are an endpoint budget issue, not a transport one).
+ * Non-`data:` lines / malformed JSON → empty meta.
+ */
+export function extractSseLineMeta(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("data:"))
+        return SSE_LINE_EMPTY;
+    const payload = trimmed.slice("data:".length).trim();
+    if (!payload || payload === "[DONE]")
+        return SSE_LINE_EMPTY;
+    try {
+        const evt = JSON.parse(payload);
+        const meta = {
+            text: null,
+            thinkingChars: 0,
+            parsed: true,
+        };
+        if (evt.type === "content_block_delta") {
+            if (evt.delta?.type === "text_delta" &&
+                typeof evt.delta.text === "string") {
+                meta.text = evt.delta.text;
+            }
+            else if (evt.delta?.type === "thinking_delta" &&
+                typeof evt.delta.thinking === "string") {
+                meta.thinkingChars = evt.delta.thinking.length;
+            }
+        }
+        else if (evt.type === "message_delta" &&
+            typeof evt.delta?.stop_reason === "string") {
+            meta.stopReason = evt.delta.stop_reason;
+        }
+        return meta;
+    }
+    catch {
+        return SSE_LINE_EMPTY;
+    }
+}
+/**
+ * Inspect a 200 non-streaming messages body that yielded no text, so the error
+ * can say WHY (thinking-only under a starved max_tokens budget vs an empty
+ * content array from a flaky gateway — the former is deterministic, the latter
+ * is worth retrying).
+ */
+export function describeNoTextBody(body) {
+    const info = { blocks: "", sawThinking: false };
+    if (typeof body !== "object" || body === null)
+        return info;
+    const obj = body;
+    if (typeof obj.stop_reason === "string")
+        info.stopReason = obj.stop_reason;
+    if (!Array.isArray(obj.content))
+        return info;
+    const names = [];
+    for (const block of obj.content) {
+        if (typeof block === "object" && block !== null) {
+            const type = block.type;
+            if (typeof type === "string") {
+                names.push(type);
+                if (type === "thinking")
+                    info.sawThinking = true;
+            }
+        }
+    }
+    info.blocks = names.join(",");
+    return info;
+}
+/** HTTP statuses worth an automatic retry (transient server/gateway trouble). */
+export const API_RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);
+// ---------------------------------------------------------------------------
+// hermes backend — pure helpers (unit-tested in cli.test.ts)
+// ---------------------------------------------------------------------------
+/**
+ * Strip a trailing context-window marker like `[1M]` (a claude-agent
+ * convention cc-switch stores in model names; raw APIs reject it).
+ * Only a suffix anchored at the very end is removed.
+ */
+export function stripContextSuffix(model) {
+    return model.replace(/\[[^\]]*\]$/, "");
+}
+/** cc-switch 值入行级文件（.env/config.yaml）前的消毒：拒绝裸换行（防行注入）。 */
+function containsLineBreak(value) {
+    return value.includes("\n") || value.includes("\r");
+}
+/**
+ * Parse argv for `gcli hermes ...`. Strict like parseApiArgs (unknown flags
+ * are exit-2 errors — there is no backend to forward to). `--no-verify` is
+ * accepted via allowNegative. At most one positional.
+ */
+export function parseHermesArgs(argv) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            options: {
+                model: { type: "string" },
+                "dry-run": { type: "boolean" },
+                verify: { type: "boolean" },
+                "keep-on-fail": { type: "boolean" },
+                help: { type: "boolean" },
+            },
+            strict: true,
+            allowPositionals: true,
+            allowNegative: true,
+        });
+        if (positionals.length > 1) {
+            return {
+                error: `hermes: unexpected extra argument: "${positionals[1]}" (usage: gcli hermes <provider|status|rollback> [--model <m>] [--dry-run] [--no-verify] [--keep-on-fail])`,
+            };
+        }
+        return {
+            provider: positionals[0],
+            model: typeof values.model === "string" ? values.model : undefined,
+            dryRun: values["dry-run"] === true,
+            verify: values.verify !== false,
+            keepOnFail: values["keep-on-fail"] === true,
+            help: values.help === true,
+        };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Derive a hermes provider id from a cc-switch display name: lowercase,
+ * non-[a-z0-9] runs folded to `-`, leading/trailing dashes trimmed.
+ * May return "" for names with no alphanumerics (caller treats as error).
+ */
+export function deriveHermesId(ccName) {
+    return ccName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/** Derive the .env key name from a hermes provider id: UPPER + `_API_KEY`. */
+export function deriveKeyEnv(id) {
+    return `${id.toUpperCase().replace(/-/g, "_")}_API_KEY`;
+}
+/** Safe YAML scalars are written bare; anything else is single-quoted. */
+const SAFE_YAML_SCALAR_RE = /^[A-Za-z0-9._/:@-]+$/;
+/** Quote a scalar for our line-level YAML writer ('' escapes a single quote). */
+export function quoteYamlScalar(value) {
+    if (value === "")
+        return "''";
+    if (SAFE_YAML_SCALAR_RE.test(value))
+        return value;
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** Inverse of quoteYamlScalar for reading (unescapes '' inside '...'). */
+function unquoteYamlScalar(raw) {
+    const t = raw.trim();
+    if (t.length >= 2 && t.startsWith("'") && t.endsWith("'")) {
+        return t.slice(1, -1).replace(/''/g, "'");
+    }
+    return t;
+}
+/** col-0 bare section header, e.g. `model:` / `providers:` (nothing after `:`). */
+const TOP_SECTION_RE = /^(\S[^:]*):\s*$/;
+/**
+ * Where to insert new lines at a section's end: just before endLine, unless
+ * the preceding element is the trailing-newline artifact (`"a\n".split("\n")
+ * → ["a",""]`), in which case before that empty element — so an appended
+ * block keeps the file's trailing newline and gains no stray blank line.
+ */
+function sectionInsertAt(lines, span) {
+    let at = span.endLine;
+    while (at > span.headerLine + 1 && lines[at - 1] === "")
+        at--;
+    return at;
+}
+/**
+ * Build the top-level section table: col-0 `key:` headers delimit sections;
+ * any other col-0 line (a scalar like `timezone: Asia/Shanghai`) is still a
+ * boundary. endLine is exclusive.
+ */
+function findTopLevelSections(lines) {
+    const col0 = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (/^\S/.test(lines[i]))
+            col0.push(i);
+    }
+    const spans = [];
+    for (let j = 0; j < col0.length; j++) {
+        const start = col0[j];
+        const m = TOP_SECTION_RE.exec(lines[start]);
+        if (m === null)
+            continue;
+        const end = j + 1 < col0.length ? col0[j + 1] : lines.length;
+        spans.push({ key: m[1], headerLine: start, endLine: end });
+    }
+    return spans;
+}
+/**
+ * Edit the top-level `model:` section (2-space `key: value` lines only):
+ * replace the wanted keys in place; insert missing ones at the section end;
+ * any unexpected structure (deeper nesting, a bare `key:` sub-section) is an
+ * error — 宁报错不猜.
+ */
+function editModelSection(lines, span, model) {
+    const wanted = [
+        ["default", model.default],
+        ["provider", model.provider],
+        ["base_url", model.base_url],
+    ];
+    const out = [...lines];
+    const found = new Set();
+    for (let i = span.headerLine + 1; i < span.endLine; i++) {
+        const line = out[i];
+        if (line.trim() === "" || line.trimStart().startsWith("#"))
+            continue;
+        // exactly 2-space indent, then `key: value`; a 4-space line (nested) or a
+        // bare `key:` (sub-section) fails this match → structural error.
+        const m = /^( {2})([^\s:#][^:]*?):(.+)$/.exec(line);
+        if (m === null) {
+            return {
+                error: `config.yaml model 段第 ${i + 1} 行结构无法识别（意外嵌套？）: ${line.trim()}`,
+            };
+        }
+        const key = m[2].trim();
+        const w = wanted.find(([k]) => k === key);
+        if (w !== undefined) {
+            out[i] = `${m[1]}${key}: ${quoteYamlScalar(w[1])}`;
+            found.add(key);
+        }
+    }
+    const missing = wanted.filter(([k]) => !found.has(k));
+    if (missing.length > 0) {
+        out.splice(sectionInsertAt(out, span), 0, ...missing.map(([k, v]) => `  ${k}: ${quoteYamlScalar(v)}`));
+    }
+    return { lines: out };
+}
+/**
+ * Edit the top-level `providers:` section: entries are 2-space `id:` blocks
+ * with 4-space `key: value` fields. Upserts the wanted fields of the entry
+ * `prov.id` (missing fields appended at the block end); appends a new block
+ * at the section end when the id is absent. Any other shape → error.
+ */
+function editProvidersSection(lines, span, prov) {
+    const wanted = [
+        ["name", prov.name],
+        ["base_url", prov.base_url],
+        ["transport", prov.transport],
+        ["key_env", prov.key_env],
+        ["default_model", prov.default_model],
+    ];
+    const entries = [];
+    let cur;
+    for (let i = span.headerLine + 1; i < span.endLine; i++) {
+        const line = lines[i];
+        if (line.trim() === "" || line.trimStart().startsWith("#"))
+            continue;
+        const h = /^ {2}(\S[^:]*):\s*$/.exec(line);
+        if (h !== null) {
+            cur = { id: h[1], start: i, end: i + 1 };
+            entries.push(cur);
+            continue;
+        }
+        const f = /^ {4}\S[^:]*:/.exec(line);
+        if (f !== null && cur !== undefined) {
+            cur.end = i + 1;
+            continue;
+        }
+        return {
+            error: `config.yaml providers 段第 ${i + 1} 行结构无法识别（意外嵌套？）: ${line.trim()}`,
+        };
+    }
+    const out = [...lines];
+    const target = entries.find((e) => e.id === prov.id);
+    if (target === undefined) {
+        const block = [
+            `  ${prov.id}:`,
+            ...wanted.map(([k, v]) => `    ${k}: ${quoteYamlScalar(v)}`),
+        ];
+        out.splice(sectionInsertAt(out, span), 0, ...block);
+        return { lines: out };
+    }
+    const found = new Set();
+    for (let i = target.start + 1; i < target.end; i++) {
+        const line = out[i];
+        const f = /^( {4})([^\s:#][^:]*?):/.exec(line);
+        if (f === null)
+            continue; // blank/comment line inside the block
+        const key = f[2].trim();
+        const w = wanted.find(([k]) => k === key);
+        if (w !== undefined) {
+            out[i] = `${f[1]}${key}: ${quoteYamlScalar(w[1])}`;
+            found.add(key);
+        }
+    }
+    const missing = wanted.filter(([k]) => !found.has(k));
+    if (missing.length > 0) {
+        out.splice(target.end, 0, ...missing.map(([k, v]) => `    ${k}: ${quoteYamlScalar(v)}`));
+    }
+    return { lines: out };
+}
+/**
+ * Targeted line-level YAML editor for hermes' config.yaml (zero-dep: no yaml
+ * lib guaranteed). Only the top-level `model:` (3 keys) and `providers:`
+ * (one entry) sections are touched; everything else is byte-preserved.
+ * Missing sections / unexpected nesting → {error}, never a guess (callers
+ * must not write on error). Idempotent by construction.
+ */
+export function editHermesConfig(text, edit) {
+    const lines = text.split("\n");
+    const modelSpan = findTopLevelSections(lines).find((s) => s.key === "model");
+    if (modelSpan === undefined) {
+        return { error: "config.yaml 缺少顶层 model: 段" };
+    }
+    const r1 = editModelSection(lines, modelSpan, edit.model);
+    if ("error" in r1)
+        return r1;
+    const provSpan = findTopLevelSections(r1.lines).find((s) => s.key === "providers");
+    if (provSpan === undefined) {
+        return { error: "config.yaml 缺少顶层 providers: 段" };
+    }
+    const r2 = editProvidersSection(r1.lines, provSpan, edit.provider);
+    if ("error" in r2)
+        return r2;
+    return { text: r2.lines.join("\n") };
+}
+/**
+ * Read (not edit) the parts of config.yaml the hermes backend needs: the
+ * current model section values and the list of providers entry ids.
+ * Missing model: section or unparseable model lines → {error}.
+ */
+export function parseHermesConfig(text) {
+    const lines = text.split("\n");
+    const sections = findTopLevelSections(lines);
+    const modelSpan = sections.find((s) => s.key === "model");
+    if (modelSpan === undefined) {
+        return { error: "config.yaml 缺少顶层 model: 段" };
+    }
+    const model = {};
+    for (let i = modelSpan.headerLine + 1; i < modelSpan.endLine; i++) {
+        const line = lines[i];
+        if (line.trim() === "" || line.trimStart().startsWith("#"))
+            continue;
+        const m = /^ {2}([^\s:#][^:]*?):(.*)$/.exec(line);
+        if (m === null) {
+            return {
+                error: `config.yaml model 段第 ${i + 1} 行结构无法识别: ${line.trim()}`,
+            };
+        }
+        const key = m[1].trim();
+        const val = unquoteYamlScalar(m[2]);
+        if (key === "default")
+            model.default = val;
+        else if (key === "provider")
+            model.provider = val;
+        else if (key === "base_url")
+            model.base_url = val;
+    }
+    const providerIds = [];
+    const provSpan = sections.find((s) => s.key === "providers");
+    if (provSpan !== undefined) {
+        for (let i = provSpan.headerLine + 1; i < provSpan.endLine; i++) {
+            const h = /^ {2}(\S[^:]*):\s*$/.exec(lines[i]);
+            if (h !== null)
+                providerIds.push(h[1]);
+        }
+    }
+    return { info: { model, providerIds } };
+}
+/**
+ * Upsert one `KEY=value` line in a .env text (pure). Only active lines
+ * (`^KEY=`) match — commented-out occurrences are left alone; comments and
+ * blank lines are byte-preserved. value=null deletes the line(s); a missing
+ * key with a non-null value is appended at the end.
+ */
+export function upsertEnvLines(text, key, value) {
+    const lines = text.split("\n");
+    const prefix = `${key}=`;
+    let seen = false;
+    const out = [];
+    for (const line of lines) {
+        if (line.startsWith(prefix)) {
+            seen = true;
+            if (value !== null)
+                out.push(`${key}=${value}`);
+            continue; // null → drop the line
+        }
+        out.push(line);
+    }
+    if (!seen && value !== null) {
+        // keep a trailing newline trailing: insert before a final empty element
+        if (out.length > 0 && out[out.length - 1] === "") {
+            out.splice(out.length - 1, 0, `${key}=${value}`);
+        }
+        else {
+            out.push(`${key}=${value}`);
+        }
+    }
+    return out.join("\n");
+}
+/**
+ * Plan cron re-pins: jobs that are enabled AND pinned to `oldProvider`
+ * (jobs.json shape `{jobs: [...]}`, a bare array tolerated). Malformed input
+ * yields an empty plan, never a throw.
+ */
+export function buildCronRepinPlan(jobsJson, oldProvider) {
+    const jobs = Array.isArray(jobsJson)
+        ? jobsJson
+        : typeof jobsJson === "object" && jobsJson !== null
+            ? jobsJson.jobs
+            : undefined;
+    if (!Array.isArray(jobs))
+        return [];
+    const out = [];
+    for (const j of jobs) {
+        if (typeof j !== "object" || j === null)
+            continue;
+        const r = j;
+        if (r.enabled !== true)
+            continue;
+        if (r.provider !== oldProvider)
+            continue;
+        if (typeof r.id !== "string" || r.id === "")
+            continue;
+        out.push({
+            jobId: r.id,
+            prevProvider: oldProvider,
+            prevModel: typeof r.model === "string" && r.model !== "" ? r.model : null,
+        });
+    }
+    return out;
+}
+/**
+ * Parse the provider registry (`hermes-providers.json`). Corrupt/missing
+ * content is best-effort → empty registry; entries lacking id/keyEnv are
+ * dropped.
+ */
+export function parseHermesRegistry(text) {
+    try {
+        const raw = JSON.parse(text);
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            return {};
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(raw)) {
+            if (typeof v !== "object" || v === null)
+                continue;
+            const r = v;
+            if (typeof r.id !== "string" || r.id === "")
+                continue;
+            if (typeof r.keyEnv !== "string" || r.keyEnv === "")
+                continue;
+            const entry = { id: r.id, keyEnv: r.keyEnv };
+            if (typeof r.modelOverride === "string" && r.modelOverride !== "") {
+                entry.modelOverride = r.modelOverride;
+            }
+            out[k] = entry;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+export function serializeHermesRegistry(reg) {
+    return `${JSON.stringify(reg, null, 2)}\n`;
+}
+function parseHermesModelPoint(v) {
+    if (typeof v !== "object" || v === null)
+        return undefined;
+    const r = v;
+    if (typeof r.id !== "string" ||
+        typeof r.model !== "string" ||
+        typeof r.base_url !== "string") {
+        return undefined;
+    }
+    return { id: r.id, model: r.model, base_url: r.base_url };
+}
+/**
+ * Parse `hermes-state.json` STRICTLY (畸形 → {error}，不猜): it carries the
+ * previous token and the rollback plan, so a half-broken state must not be
+ * acted on.
+ */
+export function parseHermesStateFile(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return { error: "state 文件不是合法 JSON" };
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return { error: "state 文件根不是对象" };
+    }
+    const ls = raw.lastSwitch;
+    if (typeof ls !== "object" || ls === null || Array.isArray(ls)) {
+        return { error: "state 缺少 lastSwitch 对象" };
+    }
+    const r = ls;
+    const to = parseHermesModelPoint(r.to);
+    const from = parseHermesModelPoint(r.from);
+    if (to === undefined || from === undefined) {
+        return { error: "state lastSwitch.to/from 畸形" };
+    }
+    if (typeof r.ts !== "number" ||
+        typeof r.ccName !== "string" ||
+        typeof r.configBackup !== "string") {
+        return { error: "state lastSwitch 标量字段畸形" };
+    }
+    const env = r.env;
+    if (typeof env !== "object" || env === null || Array.isArray(env)) {
+        return { error: "state env 畸形" };
+    }
+    const e = env;
+    if (typeof e.key !== "string" ||
+        (e.prevValue !== null && typeof e.prevValue !== "string")) {
+        return { error: "state env 畸形" };
+    }
+    const cr = r.cronRepinned;
+    if (!Array.isArray(cr)) {
+        return { error: "state cronRepinned 畸形" };
+    }
+    const cronRepinned = [];
+    for (const c of cr) {
+        if (typeof c !== "object" || c === null) {
+            return { error: "state cronRepinned 条目畸形" };
+        }
+        const x = c;
+        if (typeof x.jobId !== "string" ||
+            typeof x.prevProvider !== "string" ||
+            (x.prevModel !== null && typeof x.prevModel !== "string")) {
+            return { error: "state cronRepinned 条目畸形" };
+        }
+        cronRepinned.push({
+            jobId: x.jobId,
+            prevProvider: x.prevProvider,
+            prevModel: x.prevModel,
+        });
+    }
+    return {
+        state: {
+            lastSwitch: {
+                ts: r.ts,
+                ccName: r.ccName,
+                to,
+                from,
+                configBackup: r.configBackup,
+                env: { key: e.key, prevValue: e.prevValue },
+                cronRepinned,
+            },
+        },
+    };
+}
+export function serializeHermesStateFile(s) {
+    return `${JSON.stringify(s, null, 2)}\n`;
+}
 function isOk(r) {
     return !("error" in r);
 }
@@ -654,6 +1242,8 @@ export function parseApiArgs(argv) {
                 provider: { type: "string" },
                 "max-tokens": { type: "string" },
                 timeout: { type: "string" },
+                thinking: { type: "string" },
+                retry: { type: "string" },
                 stream: { type: "boolean" },
                 version: { type: "boolean" },
                 help: { type: "boolean" },
@@ -682,6 +1272,35 @@ export function parseApiArgs(argv) {
             }
             timeoutMs = n;
         }
+        // thinking: auto (default, omit field — endpoint default, k3 keeps its
+        // quality source) | off (disabled; avoids thinking-only responses on
+        // budget-starved requests) | on (enabled, budget = max_tokens/2, hence
+        // the >= 2048 floor).
+        let thinking = "auto";
+        if (values.thinking !== undefined) {
+            const t = values.thinking;
+            if (t !== "auto" && t !== "off" && t !== "on") {
+                return {
+                    error: `--thinking must be auto|off|on, got "${t}"`,
+                };
+            }
+            thinking = t;
+        }
+        if (thinking === "on" && maxTokens < 2048) {
+            return {
+                error: `--thinking on needs --max-tokens >= 2048 (thinking budget = max_tokens/2 = ${Math.floor(maxTokens / 2)}), got ${maxTokens}`,
+            };
+        }
+        let retries = 1;
+        if (values.retry !== undefined) {
+            const n = Number(values.retry);
+            if (!Number.isInteger(n) || n < 0 || n > 5) {
+                return {
+                    error: `--retry must be an integer in [0, 5], got "${values.retry}"`,
+                };
+            }
+            retries = n;
+        }
         return {
             prompt: typeof values.prompt === "string" ? values.prompt : undefined,
             model: typeof values.model === "string" ? values.model : undefined,
@@ -690,6 +1309,8 @@ export function parseApiArgs(argv) {
             timeoutMs,
             // default stream=true; --no-stream (allowNegative) → false
             stream: values.stream !== false,
+            thinking,
+            retries,
             version: values.version === true,
             help: values.help === true,
             cwd: typeof values.cwd === "string" ? values.cwd : undefined,
@@ -832,30 +1453,57 @@ export function runAgyInteractive(args, cwd) {
 export function runClaudeInteractive(args, cwd) {
     return spawnInteractive(CLAUDE_BIN, args, cwd);
 }
-// ---------------------------------------------------------------------------
-// api backend — production HTTP implementation (zero deps: fetch + TextDecoder)
-// ---------------------------------------------------------------------------
+const API_RETRY_BASE_DELAY_MS = 400;
+const API_RETRY_MAX_DELAY_MS = 4000;
 /**
  * Production deps.runApi: POST an anthropic-compatible /v1/messages request
  * and return a normalized RunOutcome.
  *
  * - stream=true: reads the SSE body chunk-by-chunk, decodes UTF-8, splits on
  *   newlines, and aggregates `text_delta` payloads into stdout. Two clocks
- *   guard against hangs: an idle timer (reset on every text-bearing chunk)
- *   and an absolute timer (timeoutMs). Either firing aborts the fetch via
- *   AbortController → exit 1 with a timeout message.
+ *   guard against hangs: an idle timer (reset on EVERY received chunk —
+ *   thinking models can emit long non-text stretches) and an absolute timer
+ *   (timeoutMs). Either firing aborts the fetch via AbortController → exit 1
+ *   with a timeout message.
  * - stream=false: awaits the full JSON body and extracts `content[].text`,
  *   then applies the 50k-char truncation.
  *
+ * TRANSIENT failures are retried automatically (default 1 retry, `--retry N`):
+ * network-level fetch errors, HTTP 408/429/5xx, malformed JSON, empty-content
+ * 200 bodies, and streams that die or deliver no SSE events at all. Each retry
+ * note lands on stderr (stdout stays pipe-clean), so a recovered attempt still
+ * leaves a trace. Deterministic failures are NOT retried — timeouts, 4xx, and
+ * thinking-only responses (retrying cannot fix a max_tokens budget starved by
+ * endpoint-default thinking); those errors carry a diagnosis instead.
+ *
  * HTTP errors (non-2xx, network failure, abort) → exit 1 with diagnostics on
  * stderr; stdout stays empty so the caller's empty-output guard still works.
  */
 export async function runApi(req) {
+    const maxAttempts = Math.max(1, (req.retries ?? 0) + 1);
+    const retryNotes = [];
+    for (let attempt = 1;; attempt++) {
+        const res = await runApiAttempt(req);
+        if (res.retryable === false || attempt >= maxAttempts) {
+            if (retryNotes.length === 0)
+                return res.outcome;
+            return {
+                ...res.outcome,
+                stderr: [...retryNotes, res.outcome.stderr].join("\n"),
+            };
+        }
+        const delayMs = Math.min(API_RETRY_MAX_DELAY_MS, API_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1));
+        retryNotes.push(`gcli: api attempt ${attempt}/${maxAttempts} failed (${res.retryable}); retrying in ${delayMs}ms`);
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+}
+/** A single fetch + body-consumption pass (fresh AbortController + timers). */
+async function runApiAttempt(req) {
     const controller = new AbortController();
     const { signal } = controller;
     // Two timers: absolute + idle. timeoutMs is both the hard ceiling and the
     // default idle budget — SSE streams that go quiet for that long are treated
-    // as hung. We reset the idle clock whenever we receive text.
+    // as hung. We reset the idle clock whenever we receive any chunk.
     let idleTimer;
     let absoluteTimer;
     let timedOut = false;
@@ -878,6 +1526,11 @@ export async function runApi(req) {
         if (absoluteTimer)
             clearTimeout(absoluteTimer);
     };
+    const timeoutOutcome = () => ({
+        exitCode: 1,
+        stdout: "",
+        stderr: `gcli: api timed out after ${req.timeoutMs}ms`,
+    });
     const headers = {
         Authorization: `Bearer ${req.token}`,
         "anthropic-version": "2023-06-01",
@@ -895,18 +1548,16 @@ export async function runApi(req) {
     }
     catch (err) {
         clearTimers();
-        if (timedOut) {
-            return {
-                exitCode: 1,
-                stdout: "",
-                stderr: `gcli: api timed out after ${req.timeoutMs}ms`,
-            };
-        }
+        if (timedOut)
+            return { outcome: timeoutOutcome(), retryable: false };
         const msg = err instanceof Error ? err.message : String(err);
         return {
-            exitCode: 1,
-            stdout: "",
-            stderr: `gcli: api request failed: ${msg}`,
+            outcome: {
+                exitCode: 1,
+                stdout: "",
+                stderr: `gcli: api request failed: ${msg}`,
+            },
+            retryable: `fetch failed: ${msg}`.slice(0, 120),
         };
     }
     if (!response.ok) {
@@ -920,9 +1571,14 @@ export async function runApi(req) {
         }
         const trimmed = detail.trim().slice(0, 1000);
         return {
-            exitCode: 1,
-            stdout: "",
-            stderr: `gcli: api returned HTTP ${response.status}${trimmed ? `: ${trimmed}` : ""}`,
+            outcome: {
+                exitCode: 1,
+                stdout: "",
+                stderr: `gcli: api returned HTTP ${response.status}${trimmed ? `: ${trimmed}` : ""}`,
+            },
+            retryable: API_RETRYABLE_STATUS.has(response.status)
+                ? `HTTP ${response.status}`
+                : false,
         };
     }
     if (!req.stream) {
@@ -934,58 +1590,118 @@ export async function runApi(req) {
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             return {
-                exitCode: 1,
-                stdout: "",
-                stderr: `gcli: api returned malformed JSON: ${msg}`,
+                outcome: {
+                    exitCode: 1,
+                    stdout: "",
+                    stderr: `gcli: api returned malformed JSON: ${msg}`,
+                },
+                retryable: "malformed JSON",
+            };
+        }
+        // Some gateways answer 200 with an error envelope instead of a message.
+        const errEnvelope = body;
+        if (errEnvelope.type === "error" || errEnvelope.error != null) {
+            return {
+                outcome: {
+                    exitCode: 1,
+                    stdout: "",
+                    stderr: `gcli: api returned an error body: ${JSON.stringify(body).slice(0, 500)}`,
+                },
+                retryable: false,
             };
         }
         const text = extractNonStreamText(body);
         if (!text) {
+            const info = describeNoTextBody(body);
+            if (!info.blocks) {
+                // 200 with nothing usable in content — gateway hiccup, worth a retry.
+                return {
+                    outcome: {
+                        exitCode: 1,
+                        stdout: "",
+                        stderr: "gcli: api returned no text content (empty content[])",
+                    },
+                    retryable: "empty content[]",
+                };
+            }
             return {
-                exitCode: 1,
-                stdout: "",
-                stderr: "gcli: api returned no text content",
+                outcome: {
+                    exitCode: 1,
+                    stdout: "",
+                    stderr: `gcli: api returned no text content (blocks=[${info.blocks}]` +
+                        `${info.stopReason ? `, stop_reason=${info.stopReason}` : ""})` +
+                        (info.sawThinking
+                            ? " — thinking consumed the whole max_tokens budget; raise --max-tokens or pass --thinking off"
+                            : ""),
+                },
+                // thinking-only is a deterministic budget outcome, not a flake
+                retryable: false,
             };
         }
-        return { exitCode: 0, stdout: truncate(text), stderr: "" };
+        return {
+            outcome: { exitCode: 0, stdout: truncate(text), stderr: "" },
+            retryable: false,
+        };
     }
     // Streaming: aggregate text_delta chunks. response.body is a web stream;
     // TextDecoder handles multi-byte UTF-8 split across chunk boundaries, and a
     // leftover buffer carries the partial final line until the next newline.
     if (response.body === null) {
         clearTimers();
-        return { exitCode: 1, stdout: "", stderr: "gcli: api stream had no body" };
+        return {
+            outcome: {
+                exitCode: 1,
+                stdout: "",
+                stderr: "gcli: api stream had no body",
+            },
+            retryable: "stream had no body",
+        };
     }
     const reader = response.body.getReader();
     const decoder = new TextDecoder("utf-8");
     let aggregated = "";
     let leftover = "";
+    let sawEvent = false;
+    let thinkingChars = 0;
+    let stopReason;
     try {
         // eslint-disable-next-line no-constant-condition
         while (true) {
             const { done, value } = await reader.read();
             if (done)
                 break;
+            // Any traffic proves the stream is alive — reset the idle clock on every
+            // chunk, not only text-bearing ones (thinking models can emit long
+            // non-text stretches before the first text_delta).
+            resetIdle();
             leftover += decoder.decode(value, { stream: true });
             // SSE events are separated by newlines; process every complete line and
             // keep the trailing partial in `leftover`.
             const lines = leftover.split(/\r?\n/);
             leftover = lines.pop() ?? "";
             for (const line of lines) {
-                const delta = extractTextDelta(line);
-                if (delta !== null) {
-                    aggregated += delta;
-                    resetIdle();
-                }
+                const meta = extractSseLineMeta(line);
+                if (meta.parsed)
+                    sawEvent = true;
+                if (meta.text !== null)
+                    aggregated += meta.text;
+                thinkingChars += meta.thinkingChars;
+                if (meta.stopReason !== undefined)
+                    stopReason = meta.stopReason;
             }
         }
         // Flush any trailing line (some servers omit the final newline).
         const tail = decoder.decode();
         leftover += tail;
         if (leftover.length > 0) {
-            const delta = extractTextDelta(leftover);
-            if (delta !== null)
-                aggregated += delta;
+            const meta = extractSseLineMeta(leftover);
+            if (meta.parsed)
+                sawEvent = true;
+            if (meta.text !== null)
+                aggregated += meta.text;
+            thinkingChars += meta.thinkingChars;
+            if (meta.stopReason !== undefined)
+                stopReason = meta.stopReason;
         }
     }
     catch (err) {
@@ -993,31 +1709,54 @@ export async function runApi(req) {
         if (timedOut) {
             // Timeout is a backend error (exit 1) per the contract, even when some
             // text was already received — callers must not treat a timed-out
-            // response as success.
-            return {
-                exitCode: 1,
-                stdout: "",
-                stderr: `gcli: api timed out after ${req.timeoutMs}ms`,
-            };
+            // response as success. Nothing has been emitted yet (stream output is
+            // aggregated before printing), so a retry would also be safe — but a
+            // request that already burned its whole time budget won't get one.
+            return { outcome: timeoutOutcome(), retryable: false };
         }
         const msg = err instanceof Error ? err.message : String(err);
         return {
-            exitCode: 1,
-            stdout: "",
-            stderr: `gcli: api stream read failed: ${msg}`,
+            outcome: {
+                exitCode: 1,
+                stdout: "",
+                stderr: `gcli: api stream read failed: ${msg}`,
+            },
+            retryable: `stream read failed: ${msg}`.slice(0, 120),
         };
     }
     clearTimers();
     if (!aggregated) {
+        if (!sawEvent) {
+            // Connection delivered no SSE events at all — transport-level flake.
+            return {
+                outcome: {
+                    exitCode: 1,
+                    stdout: "",
+                    stderr: "gcli: api stream produced no text (stream closed with no SSE events)",
+                },
+                retryable: "no SSE events",
+            };
+        }
+        const detail = thinkingChars > 0
+            ? ` (thinking ~${thinkingChars}ch${stopReason ? `, stop_reason=${stopReason}` : ""}) — thinking consumed the whole max_tokens budget; raise --max-tokens or pass --thinking off`
+            : stopReason
+                ? ` (stop_reason=${stopReason})`
+                : "";
         return {
-            exitCode: 1,
-            stdout: "",
-            stderr: "gcli: api stream produced no text",
+            outcome: {
+                exitCode: 1,
+                stdout: "",
+                stderr: `gcli: api stream produced no text${detail}`,
+            },
+            retryable: false,
         };
     }
     // Streaming output is not truncated (real-time, contract §A); only the
     // non-stream path truncates.
-    return { exitCode: 0, stdout: aggregated, stderr: "" };
+    return {
+        outcome: { exitCode: 0, stdout: aggregated, stderr: "" },
+        retryable: false,
+    };
 }
 // ---------------------------------------------------------------------------
 // cc-switch provider lookup
@@ -1387,12 +2126,161 @@ async function fetchProviderQuotasHttp(items) {
     return out;
 }
 // ---------------------------------------------------------------------------
+// hermes backend — production deps implementations
+// ---------------------------------------------------------------------------
+/**
+ * Production deps.runHermes: spawn `hermes <args>` with the same IO/timeout
+ * contract as runClaude (pipe stdout/stderr, SIGTERM on timeout, no stdin
+ * inheritance needed — cron edit / gateway / -z ping never read stdin).
+ */
+function runHermesProcess(args, timeoutMs) {
+    return new Promise((resolveFn) => {
+        const child = spawn(HERMES_BIN, args, {
+            env: { ...process.env },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+        }, timeoutMs);
+        child.on("error", () => {
+            clearTimeout(timer);
+            resolveFn({ stdout, stderr, exitCode: null, timedOut: false });
+        });
+        child.on("close", (code, signal) => {
+            clearTimeout(timer);
+            resolveFn({
+                stdout,
+                stderr,
+                exitCode: code,
+                signal: signal ?? null,
+                timedOut,
+            });
+        });
+    });
+}
+/** Production deps.readTextFile: UTF-8 read; missing/unreadable → undefined. */
+function readTextFileFromDisk(path) {
+    return new Promise((resolvePromise) => {
+        try {
+            resolvePromise(readFileSync(path, "utf8"));
+        }
+        catch {
+            resolvePromise(undefined);
+        }
+    });
+}
+/**
+ * Production deps.writeTextFileAtomic: tmp + rename (atomic on POSIX).
+ * mode 缺省时沿用目标文件现有权限，目标不存在则 0o600。Any failure →
+ * {ok:false} (never throws); the tmp file is cleaned up best-effort.
+ */
+function writeTextFileAtomicToDisk(path, text, mode) {
+    return new Promise((resolvePromise) => {
+        const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+        try {
+            let m = mode;
+            if (m === undefined) {
+                try {
+                    m = statSync(path).mode & 0o777;
+                }
+                catch {
+                    m = 0o600;
+                }
+            }
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(tmp, text, { encoding: "utf8", mode: m });
+            renameSync(tmp, path);
+            resolvePromise({ ok: true });
+        }
+        catch (err) {
+            try {
+                rmSync(tmp, { force: true });
+            }
+            catch {
+                // best-effort cleanup
+            }
+            resolvePromise({
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    });
+}
+/** Production deps.copyFile: full-file copy (backup / whole-file restore). */
+function copyFileOnDisk(src, dest) {
+    return new Promise((resolvePromise) => {
+        try {
+            mkdirSync(dirname(dest), { recursive: true });
+            copyFileSync(src, dest);
+            resolvePromise({ ok: true });
+        }
+        catch (err) {
+            resolvePromise({
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    });
+}
+/**
+ * Production deps.queryLastSessionModel: sqlite3 -readonly -json against
+ * HERMES_STATE_DB_PATH for the newest session_model_usage row (best-effort
+ * verification; any failure → undefined). Same spawn skeleton as
+ * readCcSwitchProvider.
+ */
+function queryLastSessionModelFromDb() {
+    return new Promise((resolvePromise) => {
+        const sql = "SELECT model, billing_provider AS provider FROM session_model_usage ORDER BY last_seen DESC LIMIT 1";
+        const child = spawn("sqlite3", ["-readonly", "-json", HERMES_STATE_DB_PATH, sql], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.on("error", () => resolvePromise(undefined));
+        child.on("close", (code) => {
+            if (code !== 0) {
+                resolvePromise(undefined);
+                return;
+            }
+            try {
+                const parsed = JSON.parse(stdout.trim() || "[]");
+                if (!Array.isArray(parsed) || parsed.length === 0) {
+                    resolvePromise(undefined);
+                    return;
+                }
+                const row = parsed[0];
+                if (typeof row.model !== "string" || typeof row.provider !== "string") {
+                    resolvePromise(undefined);
+                    return;
+                }
+                resolvePromise({ model: row.model, provider: row.provider });
+            }
+            catch {
+                resolvePromise(undefined);
+            }
+        });
+    });
+}
+// ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
 const HELP = `Usage:
   gcli [claude] [options] [-- <args>]  wrap the claude CLI (default backend)
   gcli agy [options] [-- <args>]       wrap the agy CLI (explicit subcommand)
   gcli api [options]                   call an anthropic-compatible messages API
+  gcli hermes <provider|status|rollback> [options]  hermes agent 主模型一键切换
 
 gcli sits in front of three backends and gives skills a stable entry point:
 50k-char output truncation (agy/claude; api only when non-stream), a hard
@@ -1461,6 +2349,13 @@ api backend (\`gcli api ...\`) — pure HTTP, no agent, no subprocess:
       --max-tokens <n>    Output token budget (default 80000)
       --timeout <ms>      Idle + absolute timeout in ms (default 300000, max 1800000)
       --stream|--no-stream  Stream SSE and aggregate live (default stream)
+      --thinking <mode>   auto|off|on (default auto = omit the thinking field,
+                          endpoint default applies; off sends disabled; on
+                          sends enabled with budget = max_tokens/2, needs
+                          --max-tokens >= 2048)
+      --retry <n>         Auto retries for transient failures: network errors,
+                          HTTP 408/429/5xx, malformed JSON, empty content
+                          (default 1, max 5; exponential backoff 400ms..4s)
       --version           Print the api backend identity
       --help              Show this help
 
@@ -1468,8 +2363,38 @@ api backend (\`gcli api ...\`) — pure HTTP, no agent, no subprocess:
     - No --cwd (no file operations; supplied --cwd is warned + ignored).
     - --yolo/--sandbox are rejected (they are agent flags; api has no agent).
     - Unknown flags exit 2 (strict; nothing to forward to).
-    - thinking is left ENABLED (k3 quality source); use a sufficient
-      --max-tokens budget (default 80000) to cover thinking + text.
+    - thinking auto keeps the endpoint's own default. Beware bigmodel GLM
+      endpoints: thinking defaults ON there and shares the max_tokens budget
+      with text, so a small explicit budget can yield a thinking-only response
+      ("no text content ... blocks=[thinking], stop_reason=max_tokens").
+      Fix: raise --max-tokens or pass --thinking off (k3 quality workflows:
+      keep auto/on + a generous budget). Deterministic failures are never
+      retried; transient ones (network/408/429/5xx/empty body) are, with each
+      attempt noted on stderr.
+
+hermes backend (\`gcli hermes ...\`) — hermes agent 主模型/provider 一键切换:
+  <provider>            cc-switch provider 名（exact/case/substring 三层匹配）;
+                        TTY 下省略则弹出选择菜单；非 TTY 省略 → exit 2 零交互
+  status                当前 model 段 + .env key 存在性 + 上次切换记录
+  rollback              切回上一个 provider（from/to 互换写回，支持来回 toggle）
+      --model <name>    覆盖模型名（自动剥 [1M] 后缀），并持久化进 registry
+      --dry-run         只输出计划：零写入零 spawn（.env 行显示 KEY=<redacted>）
+      --no-verify       跳过切换后的 hermes -z ping 验证
+      --keep-on-fail    验证/网关失败时不自动回滚（默认自动回滚）
+
+  Notes:
+    - 切换流程 = 备份 config.yaml → 改 model/providers 段（原子写）→ .env
+      upsert key（0o600）→ cron 重 pin（仅 enabled 且 pin 在旧 provider 的
+      job，单条失败 warn 继续）→ 重启网关 → hermes -z ping 验证（60s 硬门槛）
+      + state.db session_model_usage best-effort 比对。
+    - 验证或网关失败默认自动回滚整链路（config/.env/cron pin/网关）。
+    - 备份命名 config.yaml.bak-before-<id>-<epoch>，写入均 tmp+rename 原子写。
+    - registry: ~/.config/gcli/hermes-providers.json（cc-switch 名 → id/keyEnv
+      /modelOverride）；state: ~/.config/gcli/hermes-state.json（0o600，含旧
+      token 的 prevValue 供 rollback）。
+    - 输出红线：任何 stdout/stderr/dry-run 计划只打印 key 名，永不打印 token 值。
+    - 绝不修改 ~/.claude/settings.json 与 cc-switch.db（后者只读）。
+    - config.yaml 结构不认识（缺 model:/providers: 段、意外嵌套）→ 报错零写盘。
 
 Exit codes: 0 success | 1 backend error / timeout / empty output | 2 bad args
          | N (interactive mode: child's exit code passed through unchanged)`;
@@ -1870,7 +2795,7 @@ async function resolveApiProviderEnv(providerName, model, deps) {
         envResult.env.ANTHROPIC_MODEL ??
         envResult.env.ANTHROPIC_DEFAULT_SONNET_MODEL ??
         envResult.env.ANTHROPIC_DEFAULT_HAIKU_MODEL;
-    const resolvedModel = rawModel?.replace(/\[[^\]]*\]$/, "");
+    const resolvedModel = rawModel === undefined ? undefined : stripContextSuffix(rawModel);
     if (!baseUrl) {
         return err(1, "gcli: provider env is missing ANTHROPIC_BASE_URL");
     }
@@ -1938,6 +2863,9 @@ async function runApiBackend(parsed, deps) {
         prompt,
         stream: parsed.stream,
         timeoutMs: parsed.timeoutMs,
+        // auto = omit the thinking field entirely (endpoint default)
+        thinking: parsed.thinking === "auto" ? undefined : parsed.thinking,
+        retries: parsed.retries,
     };
     const outcome = await deps.runApi(req);
     // Empty output is a backend error (exit 1), consistent with the other
@@ -1951,6 +2879,494 @@ async function runApiBackend(parsed, deps) {
     }
     return wrap(outcome);
 }
+// ---------------------------------------------------------------------------
+// hermes backend — orchestration (status / rollback / switch)
+// ---------------------------------------------------------------------------
+const HERMES_USAGE = "gcli hermes <provider|status|rollback> [--model <m>] [--dry-run] [--no-verify] [--keep-on-fail]";
+function hermesFail(exitCode, stderr) {
+    return { exitCode, stdout: "", stderr };
+}
+/** Read the active (uncommented) value of KEY from a .env text, or null. */
+function envValueOf(envText, key) {
+    const prefix = `${key}=`;
+    for (const line of envText.split("\n")) {
+        if (line.startsWith(prefix))
+            return line.slice(prefix.length);
+    }
+    return null;
+}
+/**
+ * `gcli hermes status`：当前 model 段 + .env key 存在性 + 上次切换记录。
+ * 无切换历史时优雅显示（exit 0）。config 不可读/不可解析 → exit 1。
+ */
+async function hermesStatus(deps) {
+    const configText = await deps.readTextFile(HERMES_CONFIG_PATH);
+    if (configText === undefined) {
+        return hermesFail(1, "gcli: hermes: 无法读取 ~/.hermes/config.yaml");
+    }
+    const info = parseHermesConfig(configText);
+    if ("error" in info) {
+        return hermesFail(1, `gcli: hermes: ${info.error}`);
+    }
+    const provider = info.info.model.provider ?? "(unset)";
+    const model = info.info.model.default ?? "(unset)";
+    const baseUrl = info.info.model.base_url ?? "(unset)";
+    // .env key 存在性：按当前 provider id 反查 registry/seed 的 keyEnv
+    const regText = await deps.readTextFile(HERMES_PROVIDERS_REGISTRY_PATH);
+    const registry = regText === undefined ? {} : parseHermesRegistry(regText);
+    const known = [
+        ...Object.values(registry),
+        ...Object.values(HERMES_PROVIDER_SEEDS),
+    ];
+    const entry = known.find((e) => e.id === provider);
+    let envLine = "env_key: unknown（provider 不在 registry/seed 中）";
+    if (entry !== undefined) {
+        const envText = await deps.readTextFile(HERMES_ENV_PATH);
+        const present = envText !== undefined && envValueOf(envText, entry.keyEnv) !== null;
+        envLine = `env_key: ${entry.keyEnv} ${present ? "present" : "missing"}`;
+    }
+    let lastLine = "last_switch: none";
+    const stateText = await deps.readTextFile(HERMES_STATE_PATH);
+    if (stateText !== undefined) {
+        const st = parseHermesStateFile(stateText);
+        if ("state" in st) {
+            const s = st.state.lastSwitch;
+            lastLine = `last_switch: ${s.from.id} -> ${s.to.id}（${s.from.model} -> ${s.to.model}）@ ${new Date(s.ts).toISOString()}`;
+        }
+        else {
+            lastLine = "last_switch: (state file malformed)";
+        }
+    }
+    return {
+        exitCode: 0,
+        stdout: [
+            `provider: ${provider}`,
+            `model: ${model}`,
+            `base_url: ${baseUrl}`,
+            envLine,
+            lastLine,
+        ].join("\n"),
+        stderr: "",
+    };
+}
+/**
+ * 回滚执行体（rollback 命令与切换失败自动回滚共用）：
+ * 快照现状 config → copyFile 整文件恢复 → .env 回写/删行 → cron 逐条回放旧
+ * pin（单条失败 warn 继续）→ 网关重启（stop 失败仅 warn，start 失败=失败）→
+ * ping 验证（可选）。全程不 throw。
+ */
+async function performHermesRollback(s, deps, verify, logs) {
+    let ok = true;
+    let snapshotPath;
+    const snap = `${HERMES_CONFIG_PATH}.bak-before-${s.from.id}-${Math.floor(Date.now() / 1000)}`;
+    const snapR = await deps.copyFile(HERMES_CONFIG_PATH, snap);
+    if (snapR.ok) {
+        snapshotPath = snap;
+    }
+    else {
+        logs.push(`gcli: hermes: rollback: warn: 现状快照失败（toggle 将不可用）: ${snapR.error}`);
+    }
+    const envText = (await deps.readTextFile(HERMES_ENV_PATH)) ?? "";
+    const currentEnvValue = envValueOf(envText, s.env.key);
+    const rc = await deps.copyFile(s.configBackup, HERMES_CONFIG_PATH);
+    if (!rc.ok) {
+        logs.push(`gcli: hermes: rollback: 备份恢复失败（${s.configBackup}）: ${rc.error}`);
+        return { ok: false, snapshotPath, currentEnvValue };
+    }
+    logs.push("gcli: hermes: rollback: config.yaml 已整文件恢复");
+    const we = await deps.writeTextFileAtomic(HERMES_ENV_PATH, upsertEnvLines(envText, s.env.key, s.env.prevValue), 0o600);
+    if (!we.ok) {
+        logs.push(`gcli: hermes: rollback: .env 回写失败: ${we.error}`);
+        ok = false;
+    }
+    else {
+        logs.push(`gcli: hermes: rollback: .env 已回写 ${s.env.key}`);
+    }
+    for (const c of s.cronRepinned) {
+        const args = ["cron", "edit", c.jobId, "--provider", c.prevProvider];
+        if (c.prevModel !== null)
+            args.push("--model", c.prevModel);
+        const r = await deps.runHermes(args, DEFAULT_TIMEOUT_MS);
+        if (r.exitCode !== 0) {
+            logs.push(`gcli: hermes: rollback: warn: cron edit ${c.jobId} 回放失败（继续）: ${(r.stderr || r.stdout).trim().slice(0, 200)}`);
+        }
+        else {
+            logs.push(`gcli: hermes: rollback: cron ${c.jobId} 已回 pin → ${c.prevProvider}`);
+        }
+    }
+    const gst = await deps.runHermes(["gateway", "stop"], DEFAULT_TIMEOUT_MS);
+    if (gst.exitCode !== 0) {
+        logs.push("gcli: hermes: rollback: warn: gateway stop 非零退出（网关可能本就没跑），继续 start");
+    }
+    const gsa = await deps.runHermes(["gateway", "start"], DEFAULT_TIMEOUT_MS);
+    if (gsa.exitCode !== 0) {
+        logs.push(`gcli: hermes: rollback: gateway start 失败: ${(gsa.stderr || gsa.stdout).trim().slice(0, 300)}`);
+        ok = false;
+    }
+    else {
+        logs.push("gcli: hermes: rollback: 网关已重启");
+    }
+    if (verify) {
+        const ping = await deps.runHermes(["-z", "ping"], HERMES_VERIFY_TIMEOUT_MS);
+        if (ping.timedOut === true || ping.exitCode !== 0) {
+            logs.push("gcli: hermes: rollback: 回滚后验证 ping 未通过");
+            ok = false;
+        }
+        else {
+            logs.push("gcli: hermes: rollback: 验证 ping 通过");
+        }
+    }
+    return { ok, snapshotPath, currentEnvValue };
+}
+/** `gcli hermes rollback`：无 state → exit 1；畸形 → exit 1（不猜）。 */
+async function hermesRollback(parsed, deps) {
+    const stateText = await deps.readTextFile(HERMES_STATE_PATH);
+    if (stateText === undefined) {
+        return hermesFail(1, "gcli: hermes: 无可回滚的切换历史 / no switch history to roll back");
+    }
+    const st = parseHermesStateFile(stateText);
+    if ("error" in st) {
+        return hermesFail(1, `gcli: hermes: state 文件畸形，拒绝回滚（不猜）: ${st.error}`);
+    }
+    const s = st.state.lastSwitch;
+    const logs = [
+        `gcli: hermes: 回滚 ${s.to.id}（${s.to.model}）-> ${s.from.id}（${s.from.model}）…`,
+    ];
+    const r = await performHermesRollback(s, deps, parsed.verify, logs);
+    if (!r.ok || r.snapshotPath === undefined) {
+        logs.push("gcli: hermes: 回滚未完全成功（详见上方日志）");
+        return { exitCode: 1, stdout: "", stderr: logs.join("\n") };
+    }
+    // toggle：from/to 互换写回；configBackup 指向本次快照（= 旧 to 的配置）。
+    const swapped = {
+        lastSwitch: {
+            ts: Date.now(),
+            ccName: s.ccName,
+            to: s.from,
+            from: s.to,
+            configBackup: r.snapshotPath,
+            env: { key: s.env.key, prevValue: r.currentEnvValue },
+            cronRepinned: s.cronRepinned,
+        },
+    };
+    const ws = await deps.writeTextFileAtomic(HERMES_STATE_PATH, serializeHermesStateFile(swapped), 0o600);
+    if (!ws.ok) {
+        logs.push(`gcli: hermes: warn: state 写回失败（toggle 将不可用）: ${ws.error}`);
+    }
+    logs.push(`gcli: hermes: 回滚完成，当前 ${s.from.id} / ${s.from.model}`);
+    return { exitCode: 0, stdout: "", stderr: logs.join("\n") };
+}
+/**
+ * `gcli hermes <provider>` 一键切换（设计文档流程 0-9）。所有失败 resolve
+ * RunOutcome，禁止 throw。进度/诊断全走 stderr；stdout 仅 dry-run 计划。
+ * token 红线：任何输出只打印 key 名，token 值永不出现。
+ */
+async function hermesSwitch(parsed, deps) {
+    const logs = [];
+    // 0. 目标 provider 名：位置参数，或 TTY picker；非 TTY 缺参 → exit 2 零交互
+    let ccQuery = parsed.provider;
+    if (ccQuery === undefined) {
+        if (!deps.isInteractive()) {
+            return hermesFail(2, `gcli: hermes 需要 provider 位置参数（或保留字 status/rollback）；非 TTY 下零交互。\nusage: ${HERMES_USAGE}`);
+        }
+        const lookup0 = await deps.readCcSwitchProvider();
+        if (!lookup0.ok) {
+            return hermesFail(1, `gcli: hermes: ${lookup0.message}`);
+        }
+        if (lookup0.providers.length === 0) {
+            return hermesFail(1, "gcli: hermes: no cc-switch providers configured");
+        }
+        const picked = await deps.pickProvider(lookup0.providers.map((p) => ({ name: p.name })), 0);
+        if (picked.kind === "skip") {
+            return {
+                exitCode: 0,
+                stdout: "",
+                stderr: "gcli: hermes: 已取消，未切换",
+            };
+        }
+        ccQuery = picked.entry.name;
+    }
+    // 1. cc-switch 取 provider（复用三层匹配）
+    const lookup = await deps.readCcSwitchProvider();
+    if (!lookup.ok) {
+        return hermesFail(1, `gcli: hermes: ${lookup.message}`);
+    }
+    const match = matchProviderName(ccQuery, lookup.providers.map((p) => p.name));
+    if ("none" in match) {
+        return hermesFail(2, `gcli: hermes: provider not found / 未知 provider: ${ccQuery}`);
+    }
+    if ("ambiguous" in match) {
+        const candidates = match.ambiguous
+            .map((n) => `"${n}"`)
+            .sort()
+            .join(", ");
+        return hermesFail(2, `gcli: hermes: ambiguous provider: ${candidates}`);
+    }
+    const ccName = match.matched;
+    const target = lookup.providers.find((p) => p.name === ccName);
+    if (target === undefined) {
+        return hermesFail(2, `gcli: hermes: provider not found: ${ccQuery}`);
+    }
+    const cfgJson = typeof target.settingsConfig === "string"
+        ? target.settingsConfig
+        : JSON.stringify(target.settingsConfig);
+    const envResult = extractProviderEnv(cfgJson);
+    if ("error" in envResult) {
+        return hermesFail(1, `gcli: hermes: ${envResult.error}`);
+    }
+    const penv = envResult.env;
+    const baseUrl = penv.ANTHROPIC_BASE_URL;
+    const token = penv.ANTHROPIC_AUTH_TOKEN ?? penv.ANTHROPIC_API_KEY;
+    if (baseUrl === undefined || baseUrl === "") {
+        return hermesFail(1, "gcli: hermes: provider env is missing ANTHROPIC_BASE_URL");
+    }
+    if (token === undefined || token === "") {
+        return hermesFail(1, "gcli: hermes: provider env is missing ANTHROPIC_AUTH_TOKEN（无 token）");
+    }
+    // 换行消毒：cc-switch 值将写入行级文件（.env/config.yaml），裸换行会破坏行结构
+    for (const [label, value] of [
+        ["name", ccName],
+        ["ANTHROPIC_BASE_URL", baseUrl],
+        ["token", token],
+    ]) {
+        if (containsLineBreak(value)) {
+            return hermesFail(1, `gcli: hermes: cc-switch provider ${label} 含裸换行，拒绝写入（宁报错不猜）`);
+        }
+    }
+    // 2. 读现状（= rollback 的 from）并验证结构
+    const configText = await deps.readTextFile(HERMES_CONFIG_PATH);
+    if (configText === undefined) {
+        return hermesFail(1, "gcli: hermes: 无法读取 ~/.hermes/config.yaml");
+    }
+    const info = parseHermesConfig(configText);
+    if ("error" in info) {
+        return hermesFail(1, `gcli: hermes: ${info.error} —— 无法安全解析 config.yaml，拒绝写入`);
+    }
+    const fromId = info.info.model.provider ?? "";
+    const fromModel = info.info.model.default ?? "";
+    if (fromId === "" || fromModel === "") {
+        return hermesFail(1, "gcli: hermes: config.yaml model 段缺 provider/default，拒绝写入");
+    }
+    const from = {
+        id: fromId,
+        model: fromModel,
+        base_url: info.info.model.base_url ?? "",
+    };
+    // 3. registry 解析 hermes 字段（文件 → seed → 推导+写回）
+    const regText = await deps.readTextFile(HERMES_PROVIDERS_REGISTRY_PATH);
+    const registry = regText === undefined ? {} : parseHermesRegistry(regText);
+    let entry = registry[ccName] ?? HERMES_PROVIDER_SEEDS[ccName];
+    let registryDirty = false;
+    if (entry === undefined) {
+        const id = deriveHermesId(ccName);
+        if (id === "") {
+            return hermesFail(1, `gcli: hermes: 无法从 "${ccName}" 推导 provider id`);
+        }
+        if (info.info.providerIds.includes(id)) {
+            return hermesFail(1, `gcli: hermes: 推导 id "${id}" 与 config.yaml 已有 providers 条目冲突，拒绝覆盖；请在 ${HERMES_PROVIDERS_REGISTRY_PATH} 手工登记`);
+        }
+        entry = { id, keyEnv: deriveKeyEnv(id) };
+        registry[ccName] = entry;
+        registryDirty = true;
+    }
+    // 4. 模型名推导：--model > registry modelOverride > cc-switch（剥 [1M] 后缀）
+    const ccModel = penv.ANTHROPIC_MODEL !== undefined
+        ? stripContextSuffix(penv.ANTHROPIC_MODEL)
+        : undefined;
+    if (parsed.model !== undefined) {
+        // --model 持久化进 registry 的 modelOverride
+        entry = { ...entry, modelOverride: parsed.model };
+        registry[ccName] = entry;
+        registryDirty = true;
+    }
+    const model = parsed.model ?? entry.modelOverride ?? ccModel;
+    if (model === undefined || model === "") {
+        return hermesFail(1, "gcli: hermes: no model resolved（cc-switch 无 ANTHROPIC_MODEL，可用 --model 指定）");
+    }
+    if (containsLineBreak(model)) {
+        return hermesFail(1, "gcli: hermes: 模型名含裸换行，拒绝写入（宁报错不猜）");
+    }
+    const to = { id: entry.id, model, base_url: baseUrl };
+    // 5. 构造编辑（纯函数；结构异常 → 报错零写盘）
+    const edit = {
+        model: { default: model, provider: to.id, base_url: baseUrl },
+        provider: {
+            id: to.id,
+            name: ccName,
+            base_url: baseUrl,
+            transport: HERMES_TRANSPORT,
+            key_env: entry.keyEnv,
+            default_model: model,
+        },
+    };
+    const edited = editHermesConfig(configText, edit);
+    if ("error" in edited) {
+        return hermesFail(1, `gcli: hermes: ${edited.error} —— 无法安全识别 config.yaml 结构，拒绝写入 / refusing to write`);
+    }
+    // cron 重 pin 计划（读 jobs.json；读不到/畸形 → warn 跳过，不阻塞）
+    let cronPlan = [];
+    let cronWarn;
+    const jobsText = await deps.readTextFile(HERMES_CRON_JOBS_PATH);
+    if (jobsText === undefined) {
+        cronWarn = "无法读取 cron jobs.json，跳过重 pin";
+    }
+    else {
+        try {
+            cronPlan = buildCronRepinPlan(JSON.parse(jobsText), from.id);
+        }
+        catch {
+            cronWarn = "cron jobs.json 不是合法 JSON，跳过重 pin";
+        }
+    }
+    // 6. dry-run：输出计划，零写入零 spawn（备份路径仅为预告）
+    const backupPath = `${HERMES_CONFIG_PATH}.bak-before-${to.id}-${Math.floor(Date.now() / 1000)}`;
+    if (parsed.dryRun) {
+        const planLines = [
+            "gcli hermes 切换计划（dry-run，未做任何写入）:",
+            `  provider: ${to.id}（cc-switch: ${ccName}）`,
+            `  model: ${model}`,
+            `  base_url: ${baseUrl}`,
+            `  backup: ${backupPath}`,
+            `  config.yaml: model.default=${model} model.provider=${to.id} model.base_url=${baseUrl}; providers upsert ${to.id}`,
+            `  .env: upsert ${entry.keyEnv}=<redacted>`,
+            `  cron: repin ${cronPlan.length} job(s) ${from.id} -> ${to.id}${cronPlan.length > 0 ? `（${cronPlan.map((c) => c.jobId).join(", ")}）` : ""}`,
+            "  gateway: hermes gateway stop && hermes gateway start",
+            `  verify: ${parsed.verify ? `hermes -z ping（${HERMES_VERIFY_TIMEOUT_MS}ms 超时）+ state.db best-effort 比对` : "已跳过（--no-verify）"}`,
+        ];
+        if (cronWarn !== undefined)
+            planLines.push(`  warn: ${cronWarn}`);
+        return { exitCode: 0, stdout: planLines.join("\n"), stderr: "" };
+    }
+    // 7. registry 写回（推导/modelOverride 持久化；best-effort）
+    if (registryDirty) {
+        const w = await deps.writeTextFileAtomic(HERMES_PROVIDERS_REGISTRY_PATH, serializeHermesRegistry(registry));
+        if (!w.ok) {
+            logs.push(`gcli: hermes: warn: registry 写回失败（不影响本次切换）: ${w.error}`);
+        }
+    }
+    // 8. 备份先行 → 原子写 config
+    const bak = await deps.copyFile(HERMES_CONFIG_PATH, backupPath);
+    if (!bak.ok) {
+        return hermesFail(1, `gcli: hermes: 备份失败，中止切换（未写入任何内容）: ${bak.error}`);
+    }
+    logs.push(`gcli: hermes: 已备份 config.yaml → ${backupPath}`);
+    const wc = await deps.writeTextFileAtomic(HERMES_CONFIG_PATH, edited.text);
+    if (!wc.ok) {
+        return hermesFail(1, `gcli: hermes: config.yaml 写入失败（备份在 ${backupPath}）: ${wc.error}`);
+    }
+    logs.push(`gcli: hermes: config.yaml 已切换到 ${to.id} / ${model}`);
+    // 9. .env upsert（保持 0o600；失败则从备份恢复 config 避免半切换态）
+    const envText = (await deps.readTextFile(HERMES_ENV_PATH)) ?? "";
+    const prevValue = envValueOf(envText, entry.keyEnv);
+    const we = await deps.writeTextFileAtomic(HERMES_ENV_PATH, upsertEnvLines(envText, entry.keyEnv, token), 0o600);
+    if (!we.ok) {
+        await deps.copyFile(backupPath, HERMES_CONFIG_PATH);
+        return hermesFail(1, `gcli: hermes: .env 写入失败，已从备份恢复 config.yaml: ${we.error}`);
+    }
+    logs.push(`gcli: hermes: .env 已 upsert ${entry.keyEnv}=<redacted>`);
+    // 10. cron 重 pin（单条失败 warn 继续，不触发回滚）
+    const cronRepinned = [];
+    if (cronWarn !== undefined) {
+        logs.push(`gcli: hermes: warn: ${cronWarn}`);
+    }
+    for (const c of cronPlan) {
+        cronRepinned.push(c);
+        const r = await deps.runHermes(["cron", "edit", c.jobId, "--provider", to.id, "--model", model], DEFAULT_TIMEOUT_MS);
+        if (r.exitCode !== 0) {
+            logs.push(`gcli: hermes: warn: cron edit ${c.jobId} 失败（继续，不触发回滚）: ${(r.stderr || r.stdout).trim().slice(0, 200)}`);
+        }
+        else {
+            logs.push(`gcli: hermes: cron ${c.jobId} 重 pin → ${to.id}`);
+        }
+    }
+    // 11. 网关重启（stop 失败仅 warn；start 失败 = 网关失败）
+    let gatewayFailed;
+    const gst = await deps.runHermes(["gateway", "stop"], DEFAULT_TIMEOUT_MS);
+    if (gst.exitCode !== 0) {
+        logs.push("gcli: hermes: warn: gateway stop 非零退出（网关可能本就没跑），继续 start");
+    }
+    const gsa = await deps.runHermes(["gateway", "start"], DEFAULT_TIMEOUT_MS);
+    if (gsa.exitCode !== 0) {
+        gatewayFailed = `hermes gateway start 失败: ${(gsa.stderr || gsa.stdout).trim().slice(0, 300)}`;
+        logs.push(`gcli: hermes: ${gatewayFailed}`);
+    }
+    else {
+        logs.push("gcli: hermes: 网关已重启");
+    }
+    // 12. 验证：(a) ping 硬门槛；(b) state.db 比对 best-effort（不一致仅 warn）
+    let verifyFailed;
+    if (parsed.verify) {
+        const ping = await deps.runHermes(["-z", "ping"], HERMES_VERIFY_TIMEOUT_MS);
+        if (ping.timedOut === true) {
+            verifyFailed = `hermes -z ping 超时（${HERMES_VERIFY_TIMEOUT_MS}ms）`;
+        }
+        else if (ping.exitCode !== 0) {
+            verifyFailed = `hermes -z ping 退出码 ${ping.exitCode}: ${(ping.stderr || ping.stdout).trim().slice(0, 300)}`;
+        }
+        else {
+            logs.push("gcli: hermes: 验证 ping 通过");
+        }
+        if (verifyFailed === undefined) {
+            const last = await deps.queryLastSessionModel();
+            if (last === undefined) {
+                logs.push("gcli: hermes: warn: state.db 比对不可用（best-effort，跳过）");
+            }
+            else if (last.provider !== to.id) {
+                logs.push(`gcli: hermes: warn: state.db 最新 session 的 billing_provider=${last.provider}（期望 ${to.id}）——请人工复核`);
+            }
+        }
+    }
+    else {
+        logs.push("gcli: hermes: 已跳过验证（--no-verify）");
+    }
+    const stateRecord = {
+        lastSwitch: {
+            ts: Date.now(),
+            ccName,
+            to,
+            from,
+            configBackup: backupPath,
+            env: { key: entry.keyEnv, prevValue },
+            cronRepinned,
+        },
+    };
+    // 13. 失败 → 默认自动回滚（--keep-on-fail 抑制，但仍写 state 以便手动 rollback）
+    const failedReason = gatewayFailed ?? verifyFailed;
+    if (failedReason !== undefined) {
+        logs.push(`gcli: hermes: 切换验证失败 / verification failed: ${failedReason}`);
+        const ws = await deps.writeTextFileAtomic(HERMES_STATE_PATH, serializeHermesStateFile(stateRecord), 0o600);
+        if (!ws.ok) {
+            logs.push(`gcli: hermes: warn: state 文件写入失败: ${ws.error}`);
+        }
+        if (parsed.keepOnFail) {
+            logs.push("gcli: hermes: --keep-on-fail 生效，保留现场（可 gcli hermes rollback 手动回滚）");
+            return { exitCode: 1, stdout: "", stderr: logs.join("\n") };
+        }
+        logs.push("gcli: hermes: 开始自动回滚…");
+        const rb = await performHermesRollback(stateRecord.lastSwitch, deps, parsed.verify, logs);
+        logs.push(rb.ok
+            ? "gcli: hermes: 验证失败，已自动回滚 / rolled back"
+            : "gcli: hermes: 自动回滚未完全成功，请检查现场（备份文件仍在）");
+        return { exitCode: 1, stdout: "", stderr: logs.join("\n") };
+    }
+    // 14. 成功 → 写 state（best-effort；失败仅 warn，切换本身已成功）
+    const ws = await deps.writeTextFileAtomic(HERMES_STATE_PATH, serializeHermesStateFile(stateRecord), 0o600);
+    if (!ws.ok) {
+        logs.push(`gcli: hermes: warn: state 文件写入失败（rollback 将不可用）: ${ws.error}`);
+    }
+    logs.push(`gcli: hermes: 切换完成 ${from.id} -> ${to.id}（${model}）`);
+    return { exitCode: 0, stdout: "", stderr: logs.join("\n") };
+}
+/** hermes 子命令入口：status / rollback / switch 三分支。 */
+async function runHermesBackend(parsed, deps) {
+    if (parsed.provider !== undefined &&
+        HERMES_RESERVED_WORDS.has(parsed.provider)) {
+        return parsed.provider === "status"
+            ? hermesStatus(deps)
+            : hermesRollback(parsed, deps);
+    }
+    return hermesSwitch(parsed, deps);
+}
 /**
  * Route argv to the agy / claude / api backend via injectable deps (C1/C2).
  * Returns a {exitCode, stdout, stderr} outcome; main() owns process.exit.
@@ -1970,6 +3386,16 @@ export async function run(argv, deps) {
         }
         return runApiBackend(parsed, deps);
     }
+    if (sub.subcommand === "hermes") {
+        const parsed = parseHermesArgs(sub.rest);
+        if ("error" in parsed) {
+            return { exitCode: 2, stdout: "", stderr: `gcli: ${parsed.error}` };
+        }
+        if (parsed.help) {
+            return { exitCode: 0, stdout: HELP, stderr: "" };
+        }
+        return runHermesBackend(parsed, deps);
+    }
     const parsed = parseCliArgs(sub.rest);
     if (!isOk(parsed)) {
         return { exitCode: 2, stdout: "", stderr: `gcli: ${parsed.error}` };
@@ -1996,6 +3422,11 @@ async function main() {
         fetchProviderQuotas: (items) => fetchProviderQuotasHttp(items),
         readLastProvider: () => readLastProviderFromDisk(),
         writeLastProvider: (name) => writeLastProviderToDisk(name),
+        runHermes: (args, timeoutMs) => runHermesProcess(args, timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        readTextFile: (path) => readTextFileFromDisk(path),
+        writeTextFileAtomic: (path, text, mode) => writeTextFileAtomicToDisk(path, text, mode),
+        copyFile: (src, dest) => copyFileOnDisk(src, dest),
+        queryLastSessionModel: () => queryLastSessionModelFromDb(),
     };
     const r = await run(process.argv.slice(2), deps);
     if (r.stdout)