routstrd 0.3.11 → 0.4.0

package/src/daemon/wallet/cocod-client.ts

@@ -1,7 +1,9 @@
 import { existsSync } from "fs";
 import { createHash } from "crypto";
+import { isAbsolute } from "path";
 import { logger } from "../../utils/logger";
 import { withCrossProcessLock } from "../../utils/process-lock";
+import type { HistoryEntry } from "@cashu/coco-core";
 
 const DEFAULT_CONFIG_DIR =
   process.env.COCOD_DIR || `${process.env.HOME || process.env.USERPROFILE || ""}/.cocod`;
@@ -34,6 +36,27 @@ export type CocodState = "UNINITIALIZED" | "LOCKED" | "UNLOCKED" | "ERROR";
 
 export type CocodBalanceOutput = Record<string, { sats?: number } | number>;
 
+/** NPC (npubx.cash) Lightning address details for this wallet. */
+export interface NpcAddress {
+  /** Full Lightning address, e.g. "alice@npubx.cash" (npub fallback when no username is set). */
+  address: string;
+  /** NPC username, when one has been claimed. */
+  name?: string;
+  /** Nostr hex pubkey of the NPC account (only available from the in-process wallet). */
+  pubkey?: string;
+}
+
+/** Result of an NPC username claim attempt. */
+export interface NpcUsernameResult {
+  success: boolean;
+  /** Present when NPC requires payment to claim the username. */
+  paymentRequest?: {
+    amount?: number;
+    mints?: string[];
+    [key: string]: unknown;
+  };
+}
+
 export class CocodHttpError extends Error {
   status: number;
 
@@ -56,6 +79,17 @@ export interface CocodClient {
   listMints(): Promise<string[]>;
   addMint(url: string): Promise<string>;
   getMintInfo(url: string): Promise<unknown>;
+  getDefaultMint(): Promise<string | null>;
+  setDefaultMint(url: string): Promise<string>;
+  /** Release resources held by in-process wallet implementations. */
+  dispose?(): Promise<void>;
+  getHistory(offset?: number, limit?: number): Promise<HistoryEntry[]>;
+  /** NPC (npubx.cash) Lightning address for this wallet. */
+  getNpcAddress(): Promise<NpcAddress>;
+  /** Claim an NPC username; pass confirm=true to pay the claim fee from the wallet. */
+  setNpcUsername(username: string, confirm?: boolean): Promise<NpcUsernameResult>;
+  /** Manually trigger an NPC quote sync into the wallet. */
+  syncNpc(): Promise<void>;
 }
 
 export function resolveCocodExecutable(cocodPath?: string | null): string {
@@ -68,13 +102,18 @@ export async function isCocodInstalled(
 ): Promise<boolean> {
   const executable = resolveCocodExecutable(cocodPath);
 
-  if (executable.includes("/")) {
+  if (
+    isAbsolute(executable) ||
+    executable.includes("/") ||
+    executable.includes("\\")
+  ) {
     return existsSync(executable);
   }
 
   try {
+    const command = process.platform === "win32" ? "where.exe" : "which";
     const proc = Bun.spawn({
-      cmd: ["which", executable],
+      cmd: [command, executable],
       stdout: "ignore",
       stderr: "ignore",
     });
@@ -353,5 +392,50 @@ export function createCocodClient(
     async getMintInfo(url: string): Promise<unknown> {
       return post<unknown>("/mints/info", { url });
     },
+    async getDefaultMint(): Promise<string | null> {
+      return callDaemon<string | null>("/mints/default");
+    },
+    async setDefaultMint(url: string): Promise<string> {
+      return post<string>("/mints/default", { url });
+    },
+    async getHistory(_offset?: number, _limit?: number): Promise<HistoryEntry[]> {
+      return [];
+    },
+    async getNpcAddress(): Promise<NpcAddress> {
+      const address = await callDaemon<string>("/npc/address");
+      if (typeof address !== "string" || !address.trim()) {
+        throw new CocodHttpError(
+          502,
+          "Unexpected response from cocod while fetching NPC address.",
+        );
+      }
+      const trimmed = address.trim();
+      const localPart = trimmed.split("@")[0];
+      return {
+        address: trimmed,
+        ...(localPart && !localPart.startsWith("npub1")
+          ? { name: localPart }
+          : {}),
+      };
+    },
+    async setNpcUsername(
+      username: string,
+      confirm?: boolean,
+    ): Promise<NpcUsernameResult> {
+      // cocod answers 402 with a payment-required message when the claim fee
+      // has not been confirmed; fetchJson preserves that status on the thrown
+      // CocodHttpError, so callers can surface it unchanged.
+      const result = await post<{ success?: boolean }>("/npc/username", {
+        username,
+        confirm: confirm === true,
+      });
+      return { success: result?.success !== false };
+    },
+    async syncNpc(): Promise<void> {
+      throw new CocodHttpError(
+        501,
+        "Manual NPC sync is not supported by the legacy cocod client.",
+      );
+    },
   };
 }

package/src/daemon/wallet/migration.test.ts

@@ -0,0 +1,147 @@
+import { afterEach, describe, expect, it, mock } from "bun:test";
+import { Database } from "bun:sqlite";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { migrateLegacyWallet } from "./migration";
+
+const roots: string[] = [];
+function root(): string {
+  const path = mkdtempSync(join(tmpdir(), "routstrd-migration-"));
+  roots.push(path);
+  return path;
+}
+afterEach(() => {
+  for (const path of roots.splice(0)) rmSync(path, { recursive: true, force: true });
+});
+
+describe("migrateLegacyWallet", () => {
+  it("snapshots committed WAL data and leaves process files behind", async () => {
+    const base = root();
+    const legacyDir = join(base, ".cocod");
+    const walletDir = join(base, ".routstrd", "wallet");
+    mkdirSync(legacyDir);
+    const config = JSON.stringify({
+      mnemonic: "seed words",
+      encrypted: false,
+      defaultMintUrl: "https://mint.example",
+      unknown: { preserved: true },
+    });
+    writeFileSync(join(legacyDir, "config.json"), config);
+    writeFileSync(join(legacyDir, "cocod.pid"), "123");
+    writeFileSync(join(legacyDir, "cocod.sock"), "not-a-real-socket");
+
+    const source = new Database(join(legacyDir, "coco.db"));
+    source.exec("PRAGMA journal_mode=WAL; PRAGMA wal_autocheckpoint=0");
+    source.exec(`
+      CREATE TABLE coco_cashu_proofs (mintUrl TEXT, state TEXT, amount INTEGER);
+      CREATE TABLE coco_cashu_counters (mintUrl TEXT, keysetId TEXT, counter INTEGER);
+      CREATE TABLE coco_cashu_mint_operations (state TEXT);
+      CREATE TABLE coco_cashu_send_operations (state TEXT);
+      CREATE TABLE coco_cashu_melt_operations (state TEXT);
+      CREATE TABLE coco_cashu_mints (mintUrl TEXT, trusted INTEGER);
+      INSERT INTO coco_cashu_proofs VALUES ('https://mint.example', 'ready', 21);
+      INSERT INTO coco_cashu_counters VALUES ('https://mint.example', 'keyset', 3);
+      INSERT INTO coco_cashu_mints VALUES ('https://mint.example', 1);
+    `);
+    expect(existsSync(join(legacyDir, "coco.db-wal"))).toBe(true);
+
+    const assertStopped = mock(async () => {});
+    const releaseLock = mock(() => {});
+    const acquireLock = mock(() => releaseLock);
+    const result = await migrateLegacyWallet({
+      walletDir,
+      legacyDir,
+      assertLegacyStopped: assertStopped,
+      acquireLegacyLock: acquireLock,
+    });
+    source.close();
+
+    expect(result.status).toBe("migrated");
+    expect(assertStopped).toHaveBeenCalledTimes(2);
+    expect(acquireLock).toHaveBeenCalledTimes(1);
+    expect(releaseLock).toHaveBeenCalledTimes(1);
+    expect(readFileSync(join(walletDir, "config.json"), "utf8")).toBe(config);
+    const migrated = new Database(join(walletDir, "coco.db"), { readonly: true });
+    expect(migrated.query("PRAGMA quick_check").values()).toEqual([["ok"]]);
+    expect(migrated.query("SELECT state, amount FROM coco_cashu_proofs").values()).toEqual([
+      ["ready", 21],
+    ]);
+    expect(migrated.query("SELECT counter FROM coco_cashu_counters").get()).toEqual({
+      counter: 3,
+    });
+    migrated.close();
+    expect(existsSync(join(walletDir, "coco.db-wal"))).toBe(false);
+    expect(statSync(walletDir).mode & 0o777).toBe(0o700);
+    expect(statSync(join(walletDir, "config.json")).mode & 0o777).toBe(0o600);
+    expect(existsSync(join(walletDir, "cocod.pid"))).toBe(false);
+    expect(existsSync(join(walletDir, "cocod.sock"))).toBe(false);
+    expect(existsSync(join(legacyDir, "config.json"))).toBe(false);
+    expect(existsSync(join(legacyDir, "coco.db"))).toBe(false);
+    expect(existsSync(join(legacyDir, "cocod.pid"))).toBe(true);
+    expect(existsSync(join(legacyDir, "cocod.sock"))).toBe(true);
+    const archive = readdirSync(legacyDir).find((name) => name.startsWith("wallet-migrated-"));
+    expect(archive).toBeDefined();
+    expect(existsSync(join(legacyDir, archive!, "config.json"))).toBe(true);
+    expect(existsSync(join(legacyDir, archive!, "coco.db"))).toBe(true);
+  });
+
+  it("treats a config-only initialized wallet as migratable", async () => {
+    const base = root();
+    const legacyDir = join(base, ".cocod");
+    const walletDir = join(base, ".routstrd", "wallet");
+    mkdirSync(legacyDir);
+    writeFileSync(join(legacyDir, "config.json"), '{"mnemonic":"seed"}');
+
+    expect((await migrateLegacyWallet({ walletDir, legacyDir })).status).toBe("migrated");
+    expect(existsSync(join(walletDir, "config.json"))).toBe(true);
+    expect(existsSync(join(walletDir, "coco.db"))).toBe(false);
+  });
+
+  it("refuses a database without its mnemonic config", async () => {
+    const base = root();
+    const legacyDir = join(base, ".cocod");
+    mkdirSync(legacyDir);
+    writeFileSync(join(legacyDir, "coco.db"), "database");
+
+    await expect(migrateLegacyWallet({ walletDir: join(base, "wallet"), legacyDir })).rejects.toThrow(
+      "without config.json",
+    );
+  });
+
+  it("refuses orphaned SQLite sidecars", async () => {
+    const base = root();
+    const legacyDir = join(base, ".cocod");
+    mkdirSync(legacyDir);
+    writeFileSync(join(legacyDir, "coco.db-wal"), "orphaned WAL");
+
+    await expect(migrateLegacyWallet({ walletDir: join(base, "wallet"), legacyDir })).rejects.toThrow(
+      "sidecar files without coco.db",
+    );
+  });
+
+  it("refuses when both canonical and legacy configs exist", async () => {
+    const base = root();
+    const legacyDir = join(base, ".cocod");
+    const walletDir = join(base, ".routstrd", "wallet");
+    mkdirSync(legacyDir, { recursive: true });
+    mkdirSync(walletDir, { recursive: true });
+    writeFileSync(join(legacyDir, "config.json"), "legacy");
+    writeFileSync(join(walletDir, "config.json"), "current");
+
+    await expect(migrateLegacyWallet({ walletDir, legacyDir })).rejects.toThrow(
+      "both",
+    );
+    expect(readFileSync(join(walletDir, "config.json"), "utf8")).toBe("current");
+    expect(readFileSync(join(legacyDir, "config.json"), "utf8")).toBe("legacy");
+  });
+});

package/src/daemon/wallet/migration.ts

@@ -0,0 +1,209 @@
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+} from "fs";
+import { Database } from "bun:sqlite";
+import { basename, dirname, join } from "path";
+import { legacyCocodDir, walletDir } from "./paths";
+
+export type WalletMigrationResult =
+  | { status: "fresh" }
+  | { status: "already-current" }
+  | { status: "migrated"; from: string; to: string; cleanupWarnings: string[] };
+
+export interface WalletMigrationOptions {
+  walletDir?: string;
+  legacyDir?: string;
+  /** Called after state validation and before legacy files are copied. */
+  assertLegacyStopped?: () => void | Promise<void>;
+  /** Claims the legacy cocod exclusion lock for the duration of the copy. */
+  acquireLegacyLock?: () => (() => void) | Promise<() => void>;
+}
+
+type WalletState = "absent" | "database-only" | "initialized";
+
+function state(configPath: string, dbPath: string): WalletState {
+  const hasConfig = existsSync(configPath);
+  const hasDb = existsSync(dbPath);
+  if (hasConfig) return "initialized";
+  if (hasDb) return "database-only";
+  return "absent";
+}
+
+function filesEqual(left: string, right: string): boolean {
+  if (!existsSync(left) || !existsSync(right)) return false;
+  if (statSync(left).size !== statSync(right).size) return false;
+  return readFileSync(left).equals(readFileSync(right));
+}
+
+function sqlString(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+type WalletSummary = Record<string, unknown[]>;
+const SUMMARY_QUERIES: Record<string, string> = {
+  proofs:
+    "SELECT mintUrl, state, COUNT(*) count, COALESCE(SUM(amount), 0) amount FROM coco_cashu_proofs GROUP BY mintUrl, state ORDER BY mintUrl, state",
+  counters:
+    "SELECT mintUrl, keysetId, counter FROM coco_cashu_counters ORDER BY mintUrl, keysetId",
+  mintOperations:
+    "SELECT state, COUNT(*) count FROM coco_cashu_mint_operations GROUP BY state ORDER BY state",
+  sendOperations:
+    "SELECT state, COUNT(*) count FROM coco_cashu_send_operations GROUP BY state ORDER BY state",
+  meltOperations:
+    "SELECT state, COUNT(*) count FROM coco_cashu_melt_operations GROUP BY state ORDER BY state",
+  mints: "SELECT mintUrl, trusted FROM coco_cashu_mints ORDER BY mintUrl",
+};
+
+function verifyDatabase(database: Database, label: string): WalletSummary {
+  const checks = database.query("PRAGMA quick_check").values() as unknown[][];
+  if (checks.length !== 1 || checks[0]?.[0] !== "ok") {
+    throw new Error(`${label} failed PRAGMA quick_check: ${JSON.stringify(checks)}`);
+  }
+
+  const tables = new Set(
+    (database
+      .query("SELECT name FROM sqlite_master WHERE type = 'table'")
+      .values() as string[][]).map(([name]) => name),
+  );
+  const summary: WalletSummary = {};
+  for (const [name, query] of Object.entries(SUMMARY_QUERIES)) {
+    const table = query.match(/FROM\s+(coco_cashu_\w+)/i)?.[1];
+    summary[name] = table && tables.has(table) ? database.query(query).all() : [];
+  }
+  return summary;
+}
+
+/** Write a standalone SQLite snapshot containing committed WAL frames. */
+function snapshotDatabase(sourcePath: string, destinationPath: string): void {
+  const source = new Database(sourcePath);
+  let sourceSummary: WalletSummary;
+  try {
+    sourceSummary = verifyDatabase(source, "Legacy wallet database");
+    source.exec(`VACUUM INTO ${sqlString(destinationPath)}`);
+  } finally {
+    source.close();
+  }
+
+  const destination = new Database(destinationPath, { readonly: true });
+  try {
+    const destinationSummary = verifyDatabase(destination, "Staged wallet database");
+    if (JSON.stringify(sourceSummary) !== JSON.stringify(destinationSummary)) {
+      throw new Error(
+        "Staged wallet database does not contain the same proofs, counters, operations, and mints as the legacy database.",
+      );
+    }
+  } finally {
+    destination.close();
+  }
+}
+
+/**
+ * Copy a legacy cocod wallet into the canonical routstrd wallet directory.
+ * The staging directory is renamed atomically, so the canonical path is never
+ * exposed with only one of its two required files.
+ */
+export async function migrateLegacyWallet(
+  options: WalletMigrationOptions = {},
+): Promise<WalletMigrationResult> {
+  const targetDir = options.walletDir || walletDir();
+  const sourceDir = options.legacyDir || legacyCocodDir();
+  const targetConfig = join(targetDir, "config.json");
+  const targetDb = join(targetDir, "coco.db");
+  const sourceConfig = join(sourceDir, "config.json");
+  const sourceDb = join(sourceDir, "coco.db");
+  const sourceWal = `${sourceDb}-wal`;
+  const sourceShm = `${sourceDb}-shm`;
+  const targetState = state(targetConfig, targetDb);
+  const sourceState = state(sourceConfig, sourceDb);
+
+  // config.json is sufficient for a newly initialized wallet; coco.db is
+  // created on first open. A database without its mnemonic is never usable.
+  if (targetState === "initialized" && sourceState === "initialized") {
+    // A prior migration may have committed successfully but failed to remove
+    // its source files. Identical leftovers are safe; divergent wallets are not.
+    const configsMatch = filesEqual(targetConfig, sourceConfig);
+    const databasesMatch =
+      !existsSync(targetDb) && !existsSync(sourceDb)
+        ? true
+        : filesEqual(targetDb, sourceDb);
+    if (configsMatch && databasesMatch) return { status: "already-current" };
+    throw new Error(
+      `Cannot migrate wallet: both ${targetDir} and ${sourceDir} contain different wallet data. ` +
+        "Refusing to choose a mnemonic or merge wallet databases automatically.",
+    );
+  }
+  if (targetState === "initialized") return { status: "already-current" };
+  if (!existsSync(sourceDb) && (existsSync(sourceWal) || existsSync(sourceShm))) {
+    throw new Error(
+      `Cannot migrate wallet: ${sourceDir} contains SQLite sidecar files without coco.db. ` +
+        "Restore the matching main database before migration.",
+    );
+  }
+  if (targetState === "database-only" || sourceState === "database-only") {
+    throw new Error(
+      `Cannot migrate wallet: ${targetDir} is ${targetState} and ${sourceDir} is ${sourceState}. ` +
+        "A coco.db without config.json cannot be opened; restore the matching config first.",
+    );
+  }
+  if (sourceState === "absent") return { status: "fresh" };
+
+  await options.assertLegacyStopped?.();
+  const releaseLegacyLock = await options.acquireLegacyLock?.();
+  const stagingDir = join(
+    dirname(targetDir),
+    `.${targetDir.split(/[\\/]/).at(-1) || "wallet"}.staging-${process.pid}-${Date.now()}`,
+  );
+
+  try {
+    // Recheck after claiming the exclusion lock to close the probe/claim race.
+    await options.assertLegacyStopped?.();
+    mkdirSync(dirname(targetDir), { recursive: true, mode: 0o700 });
+    mkdirSync(stagingDir, { mode: 0o700 });
+    const stagedConfig = join(stagingDir, "config.json");
+    const stagedDb = join(stagingDir, "coco.db");
+    copyFileSync(sourceConfig, stagedConfig);
+    chmodSync(stagedConfig, 0o600);
+    const hasSourceDb = existsSync(sourceDb);
+    if (hasSourceDb) {
+      // A SQLite WAL is part of the logical database. Raw-copying coco.db can
+      // silently omit proofs and counters that have not yet been checkpointed.
+      snapshotDatabase(sourceDb, stagedDb);
+      chmodSync(stagedDb, 0o600);
+    }
+
+    if (statSync(stagedConfig).size !== statSync(sourceConfig).size) {
+      throw new Error("Cannot migrate wallet: staged config failed size validation.");
+    }
+
+    renameSync(stagingDir, targetDir);
+  } catch (error) {
+    rmSync(stagingDir, { recursive: true, force: true });
+    throw error;
+  } finally {
+    releaseLegacyLock?.();
+  }
+
+  // Preserve the complete legacy SQLite file set for manual recovery instead
+  // of deleting the only rollback copy immediately after migration.
+  const cleanupWarnings: string[] = [];
+  const sourceFiles = [sourceConfig, sourceDb, sourceWal, sourceShm].filter(existsSync);
+  if (sourceFiles.length > 0) {
+    const archiveDir = join(sourceDir, `wallet-migrated-${Date.now()}`);
+    try {
+      mkdirSync(archiveDir, { mode: 0o700 });
+      for (const path of sourceFiles) renameSync(path, join(archiveDir, basename(path)));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      cleanupWarnings.push(`Could not archive legacy wallet files: ${message}`);
+    }
+  }
+
+  return { status: "migrated", from: sourceDir, to: targetDir, cleanupWarnings };
+}

package/src/daemon/wallet/paths.ts

@@ -0,0 +1,33 @@
+import { join } from "path";
+
+function homeDir(): string {
+  return process.env.HOME || process.env.USERPROFILE || "";
+}
+
+/** Root directory for routstrd state. Evaluated lazily so env overrides work in tests. */
+export function routstrdConfigDir(): string {
+  return process.env.ROUTSTRD_DIR || join(homeDir(), ".routstrd");
+}
+
+/** Canonical directory for the in-process Cashu wallet. */
+export function walletDir(): string {
+  return process.env.ROUTSTRD_WALLET_DIR || join(routstrdConfigDir(), "wallet");
+}
+
+/** Lock owned by an in-process routstrd wallet instance. */
+export function walletPidPath(): string {
+  return process.env.ROUTSTRD_WALLET_PID || join(walletDir(), "wallet.pid");
+}
+
+/** Legacy external cocod directory. This is not the routstrd wallet directory. */
+export function legacyCocodDir(): string {
+  return process.env.COCOD_DIR || join(homeDir(), ".cocod");
+}
+
+export function legacyCocodSocketPath(): string {
+  return process.env.COCOD_SOCKET || join(legacyCocodDir(), "cocod.sock");
+}
+
+export function legacyCocodPidPath(): string {
+  return process.env.COCOD_PID || join(legacyCocodDir(), "cocod.pid");
+}

package/src/integrations/claudecode.ts

@@ -27,7 +27,8 @@ export async function installClaudeCodeIntegration(
       settings = JSON.parse(content);
     }
   } catch (error) {
-    console.error(`Error reading ${configPath}, creating new one.`);
+    console.error(`Failed to read or parse ${configPath}; leaving it unchanged:`, error);
+    return;
   }
 
   if (!settings.env) {

package/src/integrations/hermes.ts

@@ -17,6 +17,13 @@ interface HermesCustomProvider {
   [key: string]: unknown;
 }
 
+/** Hermes references a custom provider as `custom:<slug>`, where the slug is
+ *  the provider name lowercased with runs of whitespace collapsed to hyphens
+ *  (e.g. `Routstr (routstr.ft.hn)` -> `custom:routstr-(routstr.ft.hn)`). */
+function hermesProviderRef(name: string): string {
+  return `custom:${name.toLowerCase().replace(/\s+/g, "-")}`;
+}
+
 export function mergeHermesConfig(
   content: string,
   routstr: HermesRoutstrConfig,
@@ -29,8 +36,9 @@ export function mergeHermesConfig(
   const urlDisplay = routstr.baseUrl
     .replace(/\/v1$/, "")
     .replace(/^https?:\/\//, "");
+  const providerName = `Routstr (${urlDisplay})`;
   const provider = {
-    name: `Routstr (${urlDisplay})`,
+    name: providerName,
     base_url: routstr.baseUrl,
     api_key: routstr.apiKey,
     model: routstr.defaultModel,
@@ -46,17 +54,48 @@ export function mergeHermesConfig(
     });
   }
 
+  // Replace an existing Routstr custom provider in place so that re-running
+  // `clients add --hermes` after changing the daemon URL updates base_url /
+  // api_key / model instead of silently keeping the stale entry. We only touch
+  // the first matching entry; any other providers are left as-is.
   const existingConfig = document.toJS() as {
     custom_providers?: HermesCustomProvider[];
   };
   const existingProviders = existingConfig.custom_providers;
-  const providers = Array.isArray(existingProviders) ? existingProviders : [];
-  if (providers.some((item) => item.name?.startsWith("Routstr ("))) {
-    return content;
+  const providers = Array.isArray(existingProviders)
+    ? existingProviders.slice()
+    : [];
+  const routstrIndex = providers.findIndex(
+    (item) => typeof item?.name === "string" && item.name.startsWith("Routstr ("),
+  );
+  let previousName: string | undefined;
+  if (routstrIndex >= 0) {
+    previousName = providers[routstrIndex]!.name;
+    providers[routstrIndex] = { ...providers[routstrIndex], ...provider };
+  } else {
+    providers.push(provider);
   }
-  providers.push(provider);
   document.set("custom_providers", providers);
 
+  // If we renamed the Routstr provider, keep `model.provider` pointing at it so
+  // Hermes doesn't end up referencing a provider that no longer exists. We only
+  // adjust configs whose default model already routes through a Routstr custom
+  // provider, leaving any other selection untouched.
+  if (
+    !isNewConfig &&
+    previousName &&
+    previousName !== providerName &&
+    document.hasIn(["model", "provider"])
+  ) {
+    const currentRef = document.getIn(["model", "provider"]);
+    if (
+      typeof currentRef === "string" &&
+      currentRef === hermesProviderRef(previousName)
+    ) {
+      document.setIn(["model", "provider"], hermesProviderRef(providerName));
+    }
+  }
+
   return document.toString();
 }
 
@@ -99,7 +138,8 @@ export async function installHermesIntegration(
       content = await readFile(configPath, "utf-8");
     }
   } catch (error) {
-    console.error(`Error reading ${configPath}, creating new one.`);
+    console.error(`Failed to read ${configPath}; leaving it unchanged:`, error);
+    return;
   }
 
   let newContent: string;

package/src/integrations/openclaw.ts

@@ -67,8 +67,9 @@ export async function installOpenClawIntegration(
       const content = await readFile(configPath, "utf-8");
       openclawConfig = JSON.parse(content) as OpenClawConfig;
     }
-  } catch {
-    openclawConfig = {};
+  } catch (error) {
+    console.error(`Failed to read or parse ${configPath}; leaving it unchanged:`, error);
+    return;
   }
 
   if (!openclawConfig.models) {

package/src/integrations/opencode.ts

@@ -40,8 +40,9 @@ export async function installOpencodeIntegration(
     } else {
       opencodeConfig = { provider: {} };
     }
-  } catch {
-    opencodeConfig = { provider: {} };
+  } catch (error) {
+    console.error(`Failed to read or parse ${configPath}; leaving it unchanged:`, error);
+    return;
   }
 
   if (!opencodeConfig.provider) {

package/src/integrations/pi.ts

@@ -40,8 +40,9 @@ export async function installPiIntegration(
       const content = await readFile(configPath, "utf-8");
       piConfig = JSON.parse(content) as PiConfig;
     }
-  } catch {
-    piConfig = {};
+  } catch (error) {
+    console.error(`Failed to read or parse ${configPath}; leaving it unchanged:`, error);
+    return;
   }
 
   if (!piConfig.providers) {