routstrd 0.4.8 → 0.4.10

package/src/start-daemon.ts

@@ -9,7 +9,7 @@ import { logger } from "./utils/logger";
 import { CONFIG_DIR, LOGS_DIR } from "./utils/config";
 import { withCrossProcessLock } from "./utils/process-lock";
 import { urlHosts } from "./utils/daemon-client";
-import { fileURLToPath } from "url";
+import { daemonSpawnCommand } from "./runtime";
 
 const DAEMON_STARTUP_LOCK_PATH = `${CONFIG_DIR}/routstrd-startup.lock`;
 const DEBUG_LOG_PATH = `${CONFIG_DIR}/debug.log`;
@@ -88,7 +88,8 @@ function printStartupProgress(offset: number): {
   }
 }
 
-function formatElapsed(elapsedMs: number): string {
+/** Format an elapsed duration as "45s" or "2m 5s". */
+export function formatElapsed(elapsedMs: number): string {
   const seconds = Math.floor(elapsedMs / 1000);
   if (seconds < 60) return `${seconds}s`;
   return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
@@ -151,17 +152,12 @@ async function startDaemonUnlocked(
     args.push("--provider", options.provider);
   }
 
-  let daemonScript = fileURLToPath(new URL("./daemon/index.js", import.meta.url));
-  if (!existsSync(daemonScript)) {
-    daemonScript = fileURLToPath(new URL("./daemon/index.ts", import.meta.url));
-  }
-
   const debugLogOffset = existsSync(DEBUG_LOG_PATH)
     ? fileSize(DEBUG_LOG_PATH)
     : 0;
   const debugLogFd = openSync(DEBUG_LOG_PATH, "a");
 
-  const proc = Bun.spawn(["bun", daemonScript, ...args], {
+  const proc = Bun.spawn(daemonSpawnCommand(args), {
     stdout: debugLogFd,
     stderr: debugLogFd,
     stdin: "ignore",

package/src/tui/usage/app.ts

@@ -1,6 +1,6 @@
 import { getVisibleTabs } from "./constants.ts";
 import type { Tab } from "./types.ts";
-import { fetchBalance, fetchClients, fetchStatus, fetchUsageSummary, hasAnyNpubs, isDaemonRunning, type BalanceInfo, type ClientInfo, type StatusInfo } from "./data.ts";
+import { buildClientNaming, emptyClientNaming, fetchBalance, fetchClients, fetchNpubs, fetchStatus, fetchUsageSummary, hasAnyNpubs, isDaemonRunning, type BalanceInfo, type ClientInfo, type ClientNaming, type NpubEntry, type StatusInfo } from "./data.ts";
 import {
   applyScrollToContent,
   exitSearchMode,
@@ -48,6 +48,8 @@ export async function runUsageTui(): Promise<void> {
   let balance: BalanceInfo | null = null;
   let status: StatusInfo | null = null;
   let clients: ClientInfo[] = [];
+  let npubs: NpubEntry[] = [];
+  let naming: ClientNaming = emptyClientNaming();
   let visibleTabs: Tab[] = getVisibleTabs(false);
   let refreshInterval: ReturnType<typeof setInterval> | null = null;
   let autoRefresh = true;
@@ -144,6 +146,18 @@ export async function runUsageTui(): Promise<void> {
           currentTab = "clients";
           vimState.scrollPos = 0;
         }
+
+        // Names/roles live on the auth proxy, not the usage summary. Only
+        // fetch them when the Npubs tab is actually reachable, and keep the
+        // last good list if the endpoint is temporarily unreachable.
+        if (npubsVisible) {
+          const newNpubs = await fetchNpubs();
+          if (newNpubs.length > 0) npubs = newNpubs;
+        }
+
+        // Owner info (for "Name (client-id)" labels in the Recent tab) comes
+        // from /clients + /npubs; both are empty in local mode.
+        naming = buildClientNaming(clients, npubs);
       }
       render();
     } finally {
@@ -170,7 +184,7 @@ export async function runUsageTui(): Promise<void> {
       return;
     }
 
-    const content = renderTabContent(currentTab, stats, balance, status, width, clients);
+    const content = renderTabContent(currentTab, stats, balance, status, width, naming);
     const footer = `${COLORS.dim}Press [Q] to quit, [R] to refresh, [A] to toggle auto-refresh${autoRefresh ? " (on)" : " (off)"}  scroll:${vimState.scrollPos}${COLORS.reset}${vimState.mode === "normal" ? `  ${COLORS.yellow}vim: hjkl/arrows, / search, g top, gg bottom${COLORS.reset}` : ""}`;
     const chrome = renderHeader(currentTab, width, visibleTabs, updateInfo ?? undefined) + renderTabs(currentTab, visibleTabs) + renderSeparator(width) + renderSearchBar();
     const chromeLines = chrome.split("\n").length - 1;

package/src/tui/usage/data.ts

@@ -1,5 +1,6 @@
 import type { UsageTrackingEntry } from "../../daemon/types.ts";
 import {
+  callAuth,
   callDaemon,
   getDaemonBaseUrl,
   isDaemonRunning,
@@ -145,3 +146,112 @@ export async function fetchClients(): Promise<ClientInfo[]> {
 export function hasAnyNpubs(clients: ClientInfo[]): boolean {
   return clients.some((c) => !!c.ownerNpub);
 }
+
+/** A configured npub as returned by the auth proxy (`/npubs`). */
+export interface NpubEntry {
+  npub: string;
+  name: string | null;
+  role: string;
+}
+
+/**
+ * Fetch the configured npubs (with their display names and roles) from the
+ * auth proxy. Returns an empty list when the endpoint is unavailable — e.g. a
+ * local daemon that doesn't route `/npubs` — so the TUI degrades gracefully.
+ */
+export async function fetchNpubs(): Promise<NpubEntry[]> {
+  try {
+    const result = await callAuth("/npubs");
+    if (result.error) return [];
+
+    // Handle both wrapped { output: { npubs } } and direct { npubs } responses.
+    const direct = (result as { npubs?: NpubEntry[] }).npubs;
+    const wrapped = (result.output as { npubs?: NpubEntry[] } | undefined)?.npubs;
+    return direct ?? wrapped ?? [];
+  } catch {
+    return [];
+  }
+}
+
+/** Number of trailing npub characters the auth proxy folds into a client id. */
+export const NPUB_SUFFIX_LENGTH = 7;
+
+/**
+ * Lookup tables for turning a raw usage `client` id (e.g.
+ * `claude-code-a1b2c3d`) back into a human label (e.g. `Alice (claude-code)`).
+ *
+ * All maps are empty in local mode, so {@link resolveClientLabel} falls back to
+ * the raw id with no behaviour change there.
+ */
+export interface ClientNaming {
+  /** Configured npubs (names + roles) from the auth proxy. */
+  npubs: NpubEntry[];
+  /** bare clientId -> owner npub, from `GET /clients`. */
+  ownersByClientId: Map<string, string>;
+  /** npub -> display name (null when unset). */
+  npubNames: Map<string, string | null>;
+  /** trailing npub suffix -> npub. */
+  npubsBySuffix: Map<string, string>;
+}
+
+export function buildClientNaming(clients: ClientInfo[], npubs: NpubEntry[]): ClientNaming {
+  const ownersByClientId = new Map<string, string>();
+  for (const c of clients) {
+    if (c.ownerNpub) ownersByClientId.set(c.clientId, c.ownerNpub);
+  }
+
+  const npubNames = new Map<string, string | null>();
+  const npubsBySuffix = new Map<string, string>();
+  const remember = (npub: string) => npubsBySuffix.set(npub.slice(-NPUB_SUFFIX_LENGTH), npub);
+
+  for (const n of npubs) {
+    npubNames.set(n.npub, n.name ?? null);
+    remember(n.npub);
+  }
+  // `GET /clients` also carries owner npubs, which covers entries whose owner
+  // isn't present in the (possibly filtered) `/npubs` response.
+  for (const owner of ownersByClientId.values()) remember(owner);
+
+  return { npubs, ownersByClientId, npubNames, npubsBySuffix };
+}
+
+/** Configured display name for an npub, or null when unset/blank. */
+function npubDisplayName(naming: ClientNaming, npub: string): string | null {
+  const name = naming.npubNames.get(npub)?.trim();
+  return name && name.length > 0 ? name : null;
+}
+
+/** `Alice (claude-code)` when the owner has a name, else the bare client id. */
+function formatClientLabel(naming: ClientNaming, bareId: string, ownerNpub: string): string {
+  const name = npubDisplayName(naming, ownerNpub);
+  return name ? `${name} (${bareId})` : bareId;
+}
+
+/**
+ * Render a usage entry's `client` value as `Name (client-id)`, where `Name` is
+ * the owner npub's display name and the `-<npub tail>` suffix is stripped.
+ * Falls back to the raw id when no owner/name can be resolved (local mode).
+ */
+export function resolveClientLabel(clientId: string | undefined, naming: ClientNaming): string {
+  const raw = clientId && clientId.length > 0 ? clientId : "unknown";
+
+  // Exact match: the raw id is a known bare clientId or its suffixed form.
+  for (const [bareId, ownerNpub] of naming.ownersByClientId) {
+    const suffixed = `${bareId}-${ownerNpub.slice(-NPUB_SUFFIX_LENGTH)}`;
+    if (raw !== bareId && raw !== suffixed) continue;
+    return formatClientLabel(naming, bareId, ownerNpub);
+  }
+
+  // Fallback: strip a trailing `-<npub tail>` that matches a known npub.
+  for (const [suffix, npub] of naming.npubsBySuffix) {
+    const marker = `-${suffix}`;
+    if (raw.length <= marker.length || !raw.endsWith(marker)) continue;
+    return formatClientLabel(naming, raw.slice(0, -marker.length), npub);
+  }
+
+  return raw;
+}
+
+export function emptyClientNaming(): ClientNaming {
+  return buildClientNaming([], []);
+}

package/src/tui/usage/render.ts

@@ -3,7 +3,8 @@ import type { Tab } from "./types.ts";
 import {
   formatNumber,
   formatTime,
-  type ClientInfo,
+  resolveClientLabel,
+  type ClientNaming,
 } from "./data.ts";
 import { vimState } from "./state.ts";
 import { stripAnsi } from "./terminal.ts";
@@ -503,20 +504,23 @@ export function renderClients(stats: UsageStats, width: number): string {
   return output;
 }
 
-export function renderNpubs(stats: UsageStats, clients: ClientInfo[], width: number): string {
+export function renderNpubs(stats: UsageStats, naming: ClientNaming, width: number): string {
   const npubStats = stats.summary.npubs;
   if (npubStats.length === 0) return renderBox(["No npub data available"], width, "Npub Breakdown");
 
+  // Index configured npubs by their npub so usage rows can show names/roles.
+  const configured = new Map(naming.npubs.map((entry) => [entry.npub, entry]));
+
   const totalCost = stats.totalSatsCost;
   const maxCost = npubStats[0]!.satsCost;
   const lines: string[] = [];
 
-  const col1 = 24; // Npub (truncated)
+  const col1 = 24; // Name (or truncated npub)
   const col2 = 12; // Requests
   const col3 = 24; // Cost
   const col4 = 12; // Tokens
 
-  const hNpub = "Npub".padEnd(col1);
+  const hNpub = "Name".padEnd(col1);
   const hReqs = "Requests".padEnd(col2);
   const hCost = "Cost".padEnd(col3);
   const hTok = "Tokens".padEnd(col4);
@@ -527,9 +531,11 @@ export function renderNpubs(stats: UsageStats, clients: ClientInfo[], width: num
   for (const npub of npubStats) {
     const pct = totalCost > 0 ? ((npub.satsCost / totalCost) * 100).toFixed(1) : "0.0";
     const avgCostFormatted = formatCost(npub.requests > 0 ? npub.satsCost / npub.requests : 0);
-    const shortNpub = truncateNpub(npub.npub);
+    const entry = configured.get(npub.npub);
+    const name = entry?.name?.trim();
+    const label = name || truncateNpub(npub.npub);
 
-    const dNpub = shortNpub.padEnd(col1);
+    const dNpub = label.slice(0, col1 - 1).padEnd(col1);
     const dReqs = formatReqs(npub.requests).padEnd(col2);
     const dCost = `${formatCost(npub.satsCost)} sats (${pct}%)`.padEnd(col3);
     const dTok = formatNumber(npub.totalTokens).padEnd(col4);
@@ -541,8 +547,9 @@ export function renderNpubs(stats: UsageStats, clients: ClientInfo[], width: num
       `${COLORS.green}${dCost}${COLORS.reset}` +
       `${COLORS.dim}${dTok}${dAvg}${COLORS.reset}`
     );
-    // Full npub on its own line for copy-ability
-    lines.push(`  ${COLORS.dim}${npub.npub}${COLORS.reset}`);
+    // Full npub (and role when known) on its own line for copy-ability.
+    const roleSuffix = entry?.role ? ` [${entry.role}]` : "";
+    lines.push(`  ${COLORS.dim}${npub.npub}${roleSuffix}${COLORS.reset}`);
     lines.push(`  ${renderBarChart("", npub.satsCost, maxCost, width - 6, COLORS.magenta, Number(pct), "npub-detail")}`);
     lines.push("");
   }
@@ -555,7 +562,9 @@ export function renderNpubs(stats: UsageStats, clients: ClientInfo[], width: num
     // Use pre-aggregated topModels from summary
     for (const topNpub of stats.summary.npubs.slice(0, 5)) {
       if (topNpub.topModels.length === 0) continue;
-      npubModelLines.push(`${COLORS.bold}${truncateNpub(topNpub.npub)}${COLORS.reset} (${formatReqs(topNpub.requests)} reqs, ${formatCost(topNpub.satsCost)} sats)`);
+      const name = configured.get(topNpub.npub)?.name?.trim();
+      const label = name || truncateNpub(topNpub.npub);
+      npubModelLines.push(`${COLORS.bold}${label}${COLORS.reset} (${formatReqs(topNpub.requests)} reqs, ${formatCost(topNpub.satsCost)} sats)`);
       for (const m of topNpub.topModels) {
         npubModelLines.push(`  ${(MODEL_COLORS[m.modelId] || MODEL_COLORS.default)}${m.modelId.padEnd(18)}${COLORS.reset} ${formatNumber(m.totalTokens).padEnd(8)} tokens  ${formatCost(m.satsCost)} sats`);
       }
@@ -576,22 +585,38 @@ function truncateNpub(npub: string): string {
   return npub.slice(0, 10) + "…" + npub.slice(-6);
 }
 
-export function renderRecent(stats: UsageStats, width: number): string {
+export function renderRecent(stats: UsageStats, width: number, naming: ClientNaming): string {
   const recentEntries = stats.entries.slice(0, 50);
   if (recentEntries.length === 0) return renderBox(["No recent entries"], width, "Recent Requests");
 
-  const clientCol = 14;
+  const timeCol = 10;
+  const modelCol = 18;
   const tokensCol = 18;
   const costCol = 18;
-  const providerCol = Math.max(16, width - 4 - 10 - 18 - tokensCol - costCol - clientCol - 5);
+
+  // Remote mode: `Alice (claude-code)` — owner display name + the client id
+  // with the `-<npub tail>` suffix stripped. Local mode (no owner/name data)
+  // keeps the previous behaviour: the raw id in a fixed 14-col cell.
+  const hasOwnerInfo = naming.npubs.length > 0 || naming.ownersByClientId.size > 0;
+  const clientLabels = recentEntries.map((entry) =>
+    hasOwnerInfo ? resolveClientLabel(entry.client, naming) : entry.client || "unknown"
+  );
+  const maxLabelLen = clientLabels.reduce((max, label) => Math.max(max, label.length), 6);
+  const clientCol = hasOwnerInfo ? Math.min(32, Math.max(14, maxLabelLen)) : 14;
+
+  // Budget: time + model + tokens + cost + provider + client + 5 separators.
+  const innerWidth = Math.max(0, width - 4);
+  const providerCol = Math.max(12, innerWidth - timeCol - modelCol - tokensCol - costCol - 5 - clientCol);
+
   const msatsToSats = (msats?: number) => typeof msats === "number" ? msats / 1000 : 0;
   const lines: string[] = [];
-  lines.push(`${COLORS.bold}${"TIME".padEnd(10)} ${"MODEL".padEnd(18)} ${"I/CR/CW/O".padEnd(tokensCol)} ${"I/O/T in sats".padEnd(costCol)} ${"BASE:PROVIDER".padEnd(providerCol)} ${"CLIENT".slice(0, clientCol)}${COLORS.reset}`);
+  lines.push(`${COLORS.bold}${["TIME".padEnd(timeCol), "MODEL".padEnd(modelCol), "I/CR/CW/O".padEnd(tokensCol), "I/O/T in sats".padEnd(costCol), "BASE:PROVIDER".padEnd(providerCol), "CLIENT".padEnd(clientCol)].join(" ")}${COLORS.reset}`);
   lines.push(COLORS.dim + "─".repeat(width - 4) + COLORS.reset);
 
-  for (const entry of recentEntries) {
+  for (let i = 0; i < recentEntries.length; i++) {
+    const entry = recentEntries[i]!;
     const time = formatTime(entry.timestamp).slice(0, 8);
-    const model = entry.modelId.slice(0, 18).padEnd(18);
+    const model = entry.modelId.slice(0, modelCol).padEnd(modelCol);
     const tokens = [
       entry.promptTokens,
       entry.cacheReadInputTokens || 0,
@@ -606,16 +631,16 @@ export function renderRecent(stats: UsageStats, width: number): string {
     ].join("/");
     const baseUrl = (entry.baseUrl || "unknown").replace("https://", "").replace("http://", "");
     const provider = `${baseUrl}:${entry.provider || "unknown"}`.slice(0, providerCol).padEnd(providerCol);
-    const clientName = (entry.client || "unknown").slice(0, clientCol - 1);
+    const clientLabel = clientLabels[i]!.slice(0, clientCol).padEnd(clientCol);
     const clientColor = CLIENT_COLORS[entry.client || "unknown"] || CLIENT_COLORS.default || COLORS.white;
     const modelColor = MODEL_COLORS[entry.modelId] || MODEL_COLORS.default;
-    lines.push(`${COLORS.dim}${time}${COLORS.reset} ${modelColor}${model}${COLORS.reset} ${tokens.padEnd(tokensCol)} ${COLORS.green}${cost.padEnd(costCol)}${COLORS.reset} ${COLORS.dim}${provider}${COLORS.reset} ${clientColor}${clientName}${COLORS.reset}`);
+    lines.push(`${COLORS.dim}${time}${COLORS.reset} ${modelColor}${model}${COLORS.reset} ${tokens.padEnd(tokensCol)} ${COLORS.green}${cost.padEnd(costCol)}${COLORS.reset} ${COLORS.dim}${provider}${COLORS.reset} ${clientColor}${clientLabel}${COLORS.reset}`);
   }
 
   return renderBox(lines, width, `Recent Requests (${stats.entries.length} shown)`);
 }
 
-export function renderTabContent(activeTab: TabId, stats: UsageStats, balance: BalanceInfo | null, status: StatusInfo | null, width: number, clients: ClientInfo[] = []): string {
+export function renderTabContent(activeTab: TabId, stats: UsageStats, balance: BalanceInfo | null, status: StatusInfo | null, width: number, naming: ClientNaming): string {
   switch (activeTab) {
     case "overview": return renderOverview(stats, balance, status, width);
     case "today": return renderToday(stats, width);
@@ -623,8 +648,8 @@ export function renderTabContent(activeTab: TabId, stats: UsageStats, balance: B
     case "providers": return renderProviders(stats, width);
     case "tokens": return renderTokens(stats, width);
     case "clients": return renderClients(stats, width);
-    case "npubs": return renderNpubs(stats, clients, width);
-    case "recent": return renderRecent(stats, width);
+    case "npubs": return renderNpubs(stats, naming, width);
+    case "recent": return renderRecent(stats, width, naming);
     default: return "Unknown tab";
   }
 }

package/src/utils/clients.ts

@@ -6,7 +6,11 @@ import {
   ensureDaemonRunning,
 } from "./daemon-client";
 import { logger } from "./logger";
-import { CLIENT_INTEGRATIONS, CLIENT_CONFIGS } from "../integrations/registry";
+import {
+  CLIENT_INTEGRATIONS,
+  CLIENT_CONFIGS,
+  runIntegrationsForClients,
+} from "../integrations/registry";
 
 export interface ClientEntry {
   clientId: string;
@@ -125,6 +129,75 @@ export async function addDaemonClient(
   return { message: output.message, client: output.client, created: true };
 }
 
+/**
+ * Refresh routstr21 models from Nostr, then re-run every registered client
+ * integration so local client configs pick up new models and API keys.
+ *
+ * Shared by `routstrd refresh` and `routstrd clients --manual-refresh` — the
+ * same work the daemon performs on its scheduled refresh.
+ */
+export async function refreshModelsAndClientsAction(): Promise<void> {
+  const config = await loadConfig();
+
+  console.log("Refreshing routstr21 models...");
+  const result = await callDaemon("/v1/models?refresh=true");
+  if (result.error) {
+    console.log(`Model refresh failed: ${result.error}`);
+    process.exit(1);
+  }
+  console.log("Models refreshed.");
+
+  const clients = await getClientsList();
+  if (clients.length === 0) {
+    console.log("No clients to refresh.");
+    return;
+  }
+
+  console.log(`Refreshing ${clients.length} client integration(s)...`);
+  await runIntegrationsForClients(clients, config);
+  console.log("Client integrations refreshed.");
+}
+
+/**
+ * Toggle the daemon's scheduled refresh job. Routed through the daemon so it
+ * also works against a remote daemon, where the config lives on the host.
+ */
+export async function setAutomaticRefreshAction(
+  enabled: boolean,
+): Promise<void> {
+  await ensureDaemonRunning();
+
+  const result = await callDaemon("/settings/auto-refresh", {
+    method: "POST",
+    body: { enabled },
+  });
+
+  if (result.error) {
+    console.log(result.error);
+    process.exit(1);
+  }
+
+  const output = result.output as { message?: string } | undefined;
+  console.log(
+    output?.message ?? `Automatic refresh ${enabled ? "enabled" : "disabled"}.`,
+  );
+
+  if (enabled) {
+    console.log(
+      "The daemon will keep refreshing models and client integrations on a schedule.",
+    );
+    return;
+  }
+
+  console.log(
+    "The daemon will stop the scheduled refresh of models and client integrations.",
+  );
+  console.log("Run 'routstrd clients --manual-refresh' to refresh on demand.");
+  console.log(
+    "Run 'routstrd clients --enable-automatic-refresh' to turn it back on.",
+  );
+}
+
 export async function listClientsAction(): Promise<void> {
   await ensureDaemonRunning();
 

package/src/utils/config.ts

@@ -20,6 +20,18 @@ export interface NwcAutoRefillConfig {
   cooldownMs: number;
 }
 
+/**
+ * Scheduled background refresh job (Nostr events, routstr21 models, and client
+ * integrations). Missing values mean "enabled" with the default interval, so
+ * older config files keep working unchanged.
+ */
+export interface AutoRefreshConfig {
+  /** Run the recurring refresh job. Defaults to true. */
+  enabled?: boolean;
+  /** Milliseconds between refreshes. Defaults to 21 minutes. */
+  intervalMs?: number;
+}
+
 /** NWC configuration section */
 export interface NwcConfig {
   /** NWC mode: "funding_source" = NWC funds the cocod Cashu wallet */
@@ -57,6 +69,8 @@ export interface RoutstrdConfig {
   relays?: string[];
   /** NWC integration configuration */
   nwc?: NwcConfig;
+  /** Scheduled refresh job settings (see AutoRefreshConfig). */
+  autoRefresh?: AutoRefreshConfig;
   /**
    * Default max_tokens (chat/completions) and max_output_tokens (responses)
    * injected into proxied requests when the client does not supply one.

package/src/utils/daemon-stop.ts

@@ -0,0 +1,125 @@
+import { existsSync, readFileSync } from "fs";
+import { isDaemonRunning } from "./daemon-client";
+import { defaultIsProcessRunning } from "../daemon/wallet/coco-client";
+import { walletPidPath } from "../daemon/wallet/paths";
+import { formatElapsed } from "../start-daemon";
+
+/**
+ * Wait for a daemon that was asked to stop (POST /stop) to fully exit.
+ *
+ * The daemon shuts down gracefully: it stops accepting new connections
+ * right away, but keeps serving ongoing requests until they finish; only
+ * then does it dispose of the wallet, release the wallet PID lock, and
+ * exit. Spawning a replacement before the lock is released makes it abort
+ * with "Cannot claim the routstrd wallet lock", so restarts must wait for
+ * the old process to fully exit — telling the user why it is taking a
+ * while ("Finishing all ongoing requests...") and how to force it
+ * ("run 'kill -9 <PID>' to force stop") instead of racing ahead.
+ */
+export interface WaitForDaemonToExitOptions {
+  /** Wallet PID lock file held by the running daemon. */
+  pidFilePath?: string;
+  /** Returns true while the daemon still answers /health. */
+  isHealthy?: () => Promise<boolean>;
+  /** Returns the live PID recorded in the wallet lock file, or null when the
+   * file is gone or unreadable. */
+  readLockPid?: (pidFilePath: string) => number | null;
+  /** Returns true when a PID is alive (zombies count as dead). */
+  isProcessRunning?: (pid: number) => boolean;
+  sleep?: (ms: number) => Promise<void>;
+  log?: (message: string) => void;
+  /** How long to wait for the health check to stop responding after /stop. */
+  healthTimeoutMs?: number;
+  /** Silent window before reporting that ongoing requests are finishing. */
+  drainGraceMs?: number;
+  /** How long to wait for the old daemon to exit and release the lock. */
+  drainTimeoutMs?: number;
+  /** How often to re-report that ongoing requests are still finishing. */
+  drainHeartbeatMs?: number;
+  /** Interval between health and lock polls. */
+  pollIntervalMs?: number;
+}
+
+/** How often to re-report that the daemon is still finishing requests. */
+const DRAIN_HEARTBEAT_MS = 10_000;
+
+function defaultReadLockPid(pidFilePath: string): number | null {
+  if (!existsSync(pidFilePath)) return null;
+  try {
+    const pid = Number.parseInt(readFileSync(pidFilePath, "utf8").trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function waitForDaemonToExit(
+  options: WaitForDaemonToExitOptions = {},
+): Promise<void> {
+  const {
+    pidFilePath = walletPidPath(),
+    isHealthy = isDaemonRunning,
+    readLockPid = defaultReadLockPid,
+    isProcessRunning = defaultIsProcessRunning,
+    sleep = (ms: number) =>
+      new Promise<void>((resolve) => setTimeout(resolve, ms)),
+    log = (message: string) => console.log(message),
+    healthTimeoutMs = 10_000,
+    drainGraceMs = 1_000,
+    drainTimeoutMs = 10 * 60_000,
+    drainHeartbeatMs = DRAIN_HEARTBEAT_MS,
+    pollIntervalMs = 100,
+  } = options;
+
+  // Phase 1: the daemon stops accepting new connections promptly after
+  // /stop, so its health check should stop responding within seconds.
+  const healthDeadline = Date.now() + healthTimeoutMs;
+  while (await isHealthy()) {
+    if (Date.now() >= healthDeadline) {
+      throw new Error(
+        `routstrd did not stop within ${Math.round(healthTimeoutMs / 1000)} seconds`,
+      );
+    }
+    await sleep(pollIntervalMs);
+  }
+
+  // Phase 2: the process stays alive while it finishes ongoing requests and
+  // disposes of the wallet. The wallet PID lock is released only right before
+  // the process exits, so wait for it (or for the recorded PID to die). Both
+  // progress messages offer 'kill -9 <PID>': only SIGKILL interrupts a stuck
+  // drain — a plain SIGTERM just re-runs the same graceful shutdown.
+  const drainStartedAt = Date.now();
+  const drainDeadline = drainStartedAt + drainTimeoutMs;
+  let drainAnnounced = false;
+  let nextHeartbeatAt = 0;
+
+  for (;;) {
+    const lockPid = readLockPid(pidFilePath);
+    if (lockPid === null || !isProcessRunning(lockPid)) return;
+
+    const now = Date.now();
+    if (now >= drainDeadline) {
+      throw new Error(
+        `the previous daemon (PID ${lockPid}) did not finish its ongoing requests within ` +
+          `${formatElapsed(drainTimeoutMs)} and still holds the wallet lock at ${pidFilePath}. ` +
+          `Wait for it to exit and try again, or run 'kill -9 ${lockPid}' to force it.`,
+      );
+    }
+
+    if (!drainAnnounced && now - drainStartedAt >= drainGraceMs) {
+      drainAnnounced = true;
+      log(
+        `  Finishing all ongoing requests... (run 'kill -9 ${lockPid}' to force stop)`,
+      );
+      nextHeartbeatAt = now + drainHeartbeatMs;
+    } else if (drainAnnounced && now >= nextHeartbeatAt) {
+      log(
+        `  Still finishing ongoing requests (${formatElapsed(now - drainStartedAt)} elapsed)... ` +
+          `(run 'kill -9 ${lockPid}' to force stop)`,
+      );
+      nextHeartbeatAt += drainHeartbeatMs;
+    }
+
+    await sleep(pollIntervalMs);
+  }
+}