@hienlh/ppm 0.13.95 → 0.13.97

package/docs/journals/260602-proxy-request-logging-stats.md

@@ -0,0 +1,86 @@
+# Proxy Request Logging & Stats
+
+**Date**: 2026-06-02  
+**Severity**: High  
+**Component**: OAuth Proxy Bridge, SQLite Config  
+**Status**: Resolved  
+**Commit**: d5029ab
+
+## What Happened
+
+Overnight, runaway Python benchmark scripts from vn-legal-rag drained the 5-hour quota of all 4 Claude accounts via PPM's proxy with ZERO traceability. OAuth proxy requests routed through the SDK bridge had no persistent logging — only ephemeral console output. No way to audit which caller, how many requests, or which accounts were consumed.
+
+## The Brutal Truth
+
+This is infuriating because we had no observability into what broke our quota. A user can accidentally (or maliciously) drain accounts through the proxy and we'd only notice the dead quota. Multi-tenant proxy with no audit trail is irresponsible — shipping without this was a blind spot.
+
+## Technical Details
+
+**Schema**: Migration v28 in `src/services/db.service.ts` creates `proxy_requests` table:
+```sql
+CREATE TABLE proxy_requests (
+  id INTEGER PRIMARY KEY,
+  endpoint TEXT NOT NULL,
+  model TEXT,
+  account_id TEXT,
+  account_label TEXT,
+  caller_ip TEXT,
+  caller_ua TEXT,
+  status TEXT NOT NULL, -- 'success'|'error'|'rate_limited'
+  duration_ms INTEGER,
+  created_at TEXT DEFAULT CURRENT_TIMESTAMP
+)
+```
+
+**Logging coverage** (all 3 proxy paths):
+- `proxy.service.ts` intercepts every request in `forward()` / `forwardOpenAi()` / `forwardDirect()` with `performance.now()` timing
+- Early-return cases (no account) still logged with status + duration
+- Try/catch wraps `insertProxyRequest()` internally — DB write failure never breaks a proxy request
+
+**Retrieval**:
+- `GET /proxy/stats` (proxy auth required) returns {lastHour, last24h, total, requestCount}
+- `getProxyStats()` service method for programmatic access
+
+**Retention**:
+- 30-day cleanup job runs on server startup + daily setInterval
+- `cleanupOldProxyRequests(days=30)` removes expired rows
+
+## What We Tried
+
+Initial code review flagged a critical issue: unwrapped `throw` in the logging path could break a previously-working request AND trigger double-insert in the catch block. Fixed by wrapping `insertProxyRequest()` in an internal try/catch so logging failure is safe.
+
+Also applied: cosmetic accuracy update to `CURRENT_SCHEMA_VERSION` (26→28), which was out of sync with actual migration count. Dead constant, zero functional impact, but worth fixing for readability.
+
+## Root Cause Analysis
+
+Multi-tenant proxy with opaque requests is a liability without persistent audit logs. We shipped observability-blind and only noticed the impact after quota exhaustion. The runaway script was the catalyst, but the real failure was: no way to answer "who used what" or "which account did this drain?"
+
+Subagent (docs-manager) claimed `CURRENT_SCHEMA_VERSION` was a "critical bug preventing table creation" — verified FALSE against actual code. Migrations key off `PRAGMA user_version`, not the constant. Lesson: don't trust subagent severity framing without code verification.
+
+## Lessons Learned
+
+1. **Observability is not optional for shared resource proxies.** Log at the service layer (not inside bridge files) — single DRY point covering all code paths.
+2. **Logging must be failure-safe.** DB write errors can NEVER break the request being logged. Wrap at the service layer and silently degrade.
+3. **Metadata-only logging respects privacy by design.** No message content, no tokens — forensic accountability, not surveillance.
+4. **Verify "critical bugs" from subagents.** Dead constants and unused variables aren't bugs. Check the actual code path before trusting severity claims.
+5. **Caller IP is advisory, not authoritative.** x-forwarded-for is spoofable without a trusted reverse proxy in front. Use for forensics, not access control.
+
+## Next Steps
+
+1. Monitor proxy stats for anomalies — set up alerts if request count spikes (owner: ops, timeline: this week)
+2. Document proxy auth/trust model (owner: tech lead, timeline: pending — currently assumes trusted reverse proxy context)
+3. Future: rotate daily stats to cold storage (SQLite → object store) for long-term audit trails (timeline: v0.15)
+
+## Unresolved Questions
+
+- Is the proxy ever fronted by a trusted reverse proxy? If not, caller_ip forensics are unreliable.
+- Should proxy stats be exposed to non-admin callers (read-only dashboard)? Currently admin-only.
+- Should we alert on quota drain events (e.g., 50+ requests in last 10 min)? Not implemented yet.
+
+---
+
+**Files modified**: src/services/db.service.ts, src/services/proxy.service.ts, src/server/routes/proxy.ts, src/server/index.ts  
+**Tests**: 14/14 passing (tests/integration/proxy-requests-table.test.ts)  
+**Code review score**: 8/10 (approved)
+
+**Status:** DONE

package/docs/system-architecture.md

@@ -650,7 +650,7 @@ ppm jira track <issue-key>                 — Manually track ticket (insert res
 - Enforce security (no parent directory access)
 
 **Key Patterns:**
-- SQLite: WAL mode, foreign keys, lazy init, schema v19 (18 tables: config, connections, accounts, usage_history, session_logs, push_subscriptions, session_map, table_metadata, workspace_state, extension_storage, mcp_servers, clawbot_sessions, clawbot_memories, clawbot_paired_chats, jira_config, jira_watchers, jira_watch_results, bot_tasks)
+- SQLite: WAL mode, foreign keys, lazy init, schema v28 (20+ tables: config, connections, accounts, usage_history, session_logs, push_subscriptions, session_map, table_metadata, workspace_state, extension_storage, mcp_servers, clawbot_sessions, clawbot_memories, clawbot_paired_chats, jira_config, jira_watchers, jira_watch_results, bot_tasks, proxy_requests, session_metadata)
 - Path validation: `projectPath/relativePath` only, reject `..`
 - Caching: Directory trees cached with TTL
 - Error handling: Descriptive messages (file not found, permission denied)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.13.95",
+  "version": "0.13.97",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",

package/src/providers/claude-agent-sdk.ts

@@ -77,6 +77,36 @@ function createMessageChannel(): {
   };
 }
 
+/**
+ * Parse a hard usage/session-limit reset hint from SDK error text.
+ * Returns the human-readable reset text and a best-effort absolute timestamp,
+ * or null if no reset time is present (caller treats that as a transient rate limit).
+ *
+ * Examples it handles: "resets 10:10am", "resets at 3pm", "resets 10:10am (Asia/Saigon)".
+ */
+function parseUsageLimitReset(text: string): { text?: string; atMs?: number } | null {
+  const m = /resets?\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)?/i.exec(text);
+  if (!m) return null;
+  const rawText = m[0].replace(/^resets?\s+(?:at\s+)?/i, "").trim();
+
+  let hour = Number(m[1]);
+  const minute = m[2] ? Number(m[2]) : 0;
+  const ampm = m[3]?.toLowerCase();
+  if (Number.isNaN(hour) || hour > 23 || minute > 59) {
+    return { text: rawText || undefined };
+  }
+  if (ampm === "pm" && hour < 12) hour += 12;
+  if (ampm === "am" && hour === 12) hour = 0;
+
+  const now = new Date();
+  const reset = new Date(now);
+  reset.setHours(hour, minute, 0, 0);
+  // If the computed time already passed today, it must mean the next occurrence.
+  if (reset.getTime() <= now.getTime()) reset.setDate(reset.getDate() + 1);
+
+  return { text: rawText || undefined, atMs: reset.getTime() };
+}
+
 /** Build a MessageParam with optional image content blocks */
 function buildMessageParam(
   text: string,
@@ -962,6 +992,8 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       let rateLimitRetryCount = 0;
       let authRetryCount = 0;
       let hadAnyEvents = false;
+      // Accounts that hit a hard usage/session limit this turn — never retried again here.
+      const usageLimitedAccounts = new Set<string>();
       retryLoop: while (true) {
       // Reset streaming state on retry — clears stale content from failed attempts
       // (e.g. "Failed to authenticate. API Error: 401..." text that was already streamed)
@@ -1180,6 +1212,9 @@ export class ClaudeAgentSdkProvider implements AIProvider {
           if (!parentId && (msg as any).uuid) lastAssistantUuid = (msg as any).uuid;
           // SDK assistant messages can carry an error field for auth/billing/rate-limit failures
           let assistantError = (msg as any).error as string | undefined;
+          // Human-readable reset time + parsed timestamp for a hard usage/session limit
+          let usageLimitResetText: string | undefined;
+          let usageLimitResetAtMs: number | undefined;
 
           // SDK sometimes returns auth errors as text content without setting error field.
           // Detect 401 pattern in text: "Failed to authenticate. API Error: 401 ..."
@@ -1189,8 +1224,19 @@ export class ClaudeAgentSdkProvider implements AIProvider {
               assistantError = "authentication_failed";
               console.warn(`[sdk] session=${sessionId} detected 401 in assistant text content — treating as auth error`);
             } else if (textContent && /hit your (?:[\w-]+\s+)*limit/i.test(textContent)) {
-              assistantError = "rate_limit";
-              console.warn(`[sdk] session=${sessionId} detected quota limit in assistant text content — treating as rate_limit`);
+              // A hard usage/session limit carries a reset time ("...resets 10:10am").
+              // Treat those as usage_limit (switch accounts, don't backoff-loop); only
+              // wording without a reset hint falls through to transient rate_limit.
+              const reset = parseUsageLimitReset(textContent);
+              if (reset) {
+                assistantError = "usage_limit";
+                usageLimitResetText = reset.text;
+                usageLimitResetAtMs = reset.atMs;
+                console.warn(`[sdk] session=${sessionId} detected usage/session limit (resets ${reset.text ?? "?"}) — will switch account, no backoff loop`);
+              } else {
+                assistantError = "rate_limit";
+                console.warn(`[sdk] session=${sessionId} detected quota limit in assistant text content — treating as rate_limit`);
+              }
             } else if (textContent && /API Error:\s*5\d{2}\b/i.test(textContent)) {
               // 5xx (e.g. 529 Overloaded) — match the explicit "API Error: 5xx" text only.
               // Treat as server_error so it enters the retry branch and the raw error text is
@@ -1240,6 +1286,42 @@ export class ClaudeAgentSdkProvider implements AIProvider {
               break;
             }
 
+            // Hard usage/session limit — never retry the same account (futile until reset).
+            // Switch to a fresh account if one exists; otherwise stop with one clear error.
+            if (assistantError === "usage_limit") {
+              if (account) {
+                usageLimitedAccounts.add(account.id);
+                accountSelector.onUsageLimit(account.id, usageLimitResetAtMs);
+              }
+              const nextAccount = accountSelector.next(usageLimitedAccounts);
+              if (nextAccount) {
+                account = nextAccount;
+                const label = nextAccount.label ?? nextAccount.email ?? "Unknown";
+                console.warn(`[sdk] session=${sessionId} usage limit — switching to fresh account ${nextAccount.id} (${label}), no backoff`);
+                yield { type: "account_retry" as const, reason: `Usage limit reached — switching account`, accountId: nextAccount.id, accountLabel: label };
+                // Rebuild query with the fresh account env, no backoff delay.
+                const retryU = buildRetryMsg();
+                closeCurrentStream();
+                const ulRetryEnv = this.buildQueryEnv(meta.projectPath, account);
+                const { generator: ulRetryGen, controller: ulRetryCtrl } = createMessageChannel();
+                ulRetryCtrl.push(retryU.msg);
+                const retryOpts = { ...queryOptions, sessionId: undefined, resume: sessionId, env: ulRetryEnv };
+                const rq = query({
+                  prompt: ulRetryGen,
+                  options: { ...retryOpts, ...(permissionHooks && { hooks: permissionHooks }), canUseTool } as any,
+                });
+                this.streamingSessions.set(sessionId, { meta, query: rq, controller: ulRetryCtrl, lastUserContent: retryU.lastUserContent, lastUserImages: retryU.lastUserImages });
+                this.activeQueries.set(sessionId, rq);
+                eventSource = rq;
+                continue retryLoop;
+              }
+              // No fresh account left — stop. One clear error, no retry loop.
+              const resetSuffix = usageLimitResetText ? ` Resets ${usageLimitResetText}.` : "";
+              console.warn(`[sdk] session=${sessionId} usage limit — no fresh account available, stopping`);
+              yield { type: "error", message: `All accounts have hit their usage limit.${resetSuffix} Add another account in Settings → Accounts or wait for the reset.` };
+              break;
+            }
+
             // Rate limit — auto-retry with exponential backoff, switching account if possible
             if ((assistantError === "rate_limit" || assistantError === "server_error") && rateLimitRetryCount < MAX_RATE_LIMIT_RETRIES) {
               const backoff = RATE_LIMIT_BACKOFF_MS[rateLimitRetryCount] ?? 60_000;

package/src/server/index.ts

@@ -228,7 +228,7 @@ export async function startServer(options: {
 
   // Load config
   configService.load();
-  const port = parseInt(options.port ?? String(configService.get("port")), 10);
+  let port = parseInt(options.port ?? String(configService.get("port")), 10);
   const host = configService.get("host");
 
   await setupLogFile();
@@ -336,6 +336,22 @@ export async function startServer(options: {
         .once("listening", () => tester.close(() => resolve(false)))
         .listen(port, host);
     });
+
+    // On Windows, detect zombie sockets: port held by a dead process after crash.
+    // Returns the dead PID if zombie, 0 if the process is alive, -1 if can't determine.
+    const findZombiePortHolder = (): number => {
+      if (process.platform !== "win32") return -1;
+      try {
+        const { execSync } = require("node:child_process") as typeof import("node:child_process");
+        const out = execSync(`netstat -ano | findstr "0.0.0.0:${port}.*LISTENING"`, { encoding: "utf-8", timeout: 5000 });
+        const match = out.trim().match(/LISTENING\s+(\d+)/);
+        if (!match?.[1]) return -1;
+        const ownerPid = parseInt(match[1], 10);
+        // Check if the process is alive
+        try { process.kill(ownerPid, 0); return 0; } catch { return ownerPid; }
+      } catch { return -1; }
+    };
+
     let portInUse = await checkPort();
     if (portInUse) {
       // Retry — port may still be releasing after supervisor self-replace
@@ -346,9 +362,33 @@ export async function startServer(options: {
         if (!portInUse) break;
       }
       if (portInUse) {
-        console.error(`\n  ✗  Port ${port} is already in use.`);
-        console.error(`     Run 'ppm stop' first or use a different port with --port.\n`);
-        process.exit(1);
+        const zombiePid = findZombiePortHolder();
+        if (zombiePid > 0) {
+          // Zombie socket from a dead process — Windows won't release it.
+          // Auto-find a free port nearby so the user isn't stuck.
+          console.warn(`  ⚠  Port ${port} held by dead process (PID: ${zombiePid}) — zombie socket.`);
+          const origPort = port;
+          for (let candidate = port + 1; candidate <= port + 20; candidate++) {
+            const candidateInUse = await new Promise<boolean>((resolve) => {
+              const net = require("node:net") as typeof import("node:net");
+              const tester = net.createServer()
+                .once("error", (err: NodeJS.ErrnoException) => resolve(err.code === "EADDRINUSE"))
+                .once("listening", () => tester.close(() => resolve(false)))
+                .listen(candidate, host);
+            });
+            if (!candidateInUse) { port = candidate; break; }
+          }
+          if (port === origPort) {
+            console.error(`\n  ✗  Port ${port} is blocked by a zombie socket and no nearby port is free.`);
+            console.error(`     Run PowerShell as Admin: netsh int tcp reset   (then restart)\n`);
+            process.exit(1);
+          }
+          console.warn(`     Auto-selected port ${port} instead.`);
+        } else {
+          console.error(`\n  ✗  Port ${port} is already in use.`);
+          console.error(`     Run 'ppm stop' first or use a different port with --port.\n`);
+          process.exit(1);
+        }
       }
     }
 
@@ -585,8 +625,58 @@ if (process.argv.includes("__serve__")) {
     }
   } catch { /* status.json missing or no shareUrl — normal */ }
 
-  Bun.serve({
-    port,
+  // Auto-cleanup old proxy request logs (30-day retention): on startup + daily
+  {
+    const { cleanupOldProxyRequests } = await import("../services/db.service.ts");
+    const deleted = cleanupOldProxyRequests(30);
+    if (deleted > 0) console.log(`[proxy] cleaned up ${deleted} proxy request logs older than 30 days`);
+    setInterval(() => cleanupOldProxyRequests(30), 24 * 60 * 60 * 1000);
+  }
+
+  // On Windows, check for zombie sockets before binding.
+  // After an upgrade, the old server's socket can stay in LISTENING state
+  // because SIGTERM maps to TerminateProcess (graceful handler never fires).
+  let actualPort = port;
+  if (process.platform === "win32") {
+    const portInUse = await new Promise<boolean>((resolve) => {
+      const net = require("node:net") as typeof import("node:net");
+      const tester = net.createServer()
+        .once("error", (e: NodeJS.ErrnoException) => resolve(e.code === "EADDRINUSE"))
+        .once("listening", () => tester.close(() => resolve(false)))
+        .listen(port, host);
+    });
+    if (portInUse) {
+      try {
+        const { execSync } = require("node:child_process") as typeof import("node:child_process");
+        const out = execSync(`netstat -ano | findstr "0.0.0.0:${port}.*LISTENING"`, { encoding: "utf-8", timeout: 5000 });
+        const match = out.trim().match(/LISTENING\s+(\d+)/);
+        if (match?.[1]) {
+          const ownerPid = parseInt(match[1], 10);
+          let isZombie = false;
+          try { process.kill(ownerPid, 0); } catch { isZombie = true; }
+          if (isZombie) {
+            console.warn(`[serve] Port ${port} held by dead process (PID: ${ownerPid}) — zombie socket`);
+            for (let candidate = port + 1; candidate <= port + 20; candidate++) {
+              const busy = await new Promise<boolean>((resolve) => {
+                const net = require("node:net") as typeof import("node:net");
+                const tester = net.createServer()
+                  .once("error", (e: NodeJS.ErrnoException) => resolve(e.code === "EADDRINUSE"))
+                  .once("listening", () => tester.close(() => resolve(false)))
+                  .listen(candidate, host);
+              });
+              if (!busy) { actualPort = candidate; break; }
+            }
+            if (actualPort !== port) {
+              console.warn(`[serve] Auto-selected port ${actualPort} instead`);
+            }
+          }
+        }
+      } catch {}
+    }
+  }
+
+  const server = Bun.serve({
+    port: actualPort,
     hostname: host,
     fetch(req, server) {
       const url = new URL(req.url);
@@ -687,10 +777,47 @@ if (process.argv.includes("__serve__")) {
       jiraWatcherService.startAll().catch((e) => {
         console.error("[jira] Failed to start watchers:", (e as Error).message);
       });
-      process.on("SIGTERM", () => jiraWatcherService.stopAll());
-      process.on("SIGINT", () => jiraWatcherService.stopAll());
     })
     .catch(() => {});
 
-  console.log(`Server child ready on port ${port}`);
+  // If we auto-selected a different port, update status.json so supervisor
+  // health checks and tunnel proxy point at the correct port.
+  if (actualPort !== port) {
+    try {
+      const { resolve: r } = await import("node:path");
+      const { readFileSync: rf, writeFileSync: wf, renameSync: rn } = await import("node:fs");
+      const { getPpmDir: gd } = await import("../services/ppm-dir.ts");
+      const sf = r(gd(), "status.json");
+      const st = JSON.parse(rf(sf, "utf-8"));
+      st.port = actualPort;
+      const tmp = sf + ".tmp." + process.pid;
+      wf(tmp, JSON.stringify(st));
+      rn(tmp, sf);
+    } catch {}
+  }
+
+  // Graceful shutdown: close the listening socket so the port is released
+  const gracefulShutdown = () => {
+    try { server.stop(true); } catch {}
+    process.exit(0);
+  };
+  process.on("SIGTERM", gracefulShutdown);
+  process.on("SIGINT", gracefulShutdown);
+
+  // On Windows, SIGTERM maps to TerminateProcess — graceful handlers never fire.
+  // Poll for a shutdown file written by the supervisor instead.
+  if (process.platform === "win32") {
+    const { getPpmDir: gd } = await import("../services/ppm-dir.ts");
+    const { resolve: r } = await import("node:path");
+    const { existsSync: ex, unlinkSync: ul } = await import("node:fs");
+    const shutdownFile = r(gd(), ".server-shutdown");
+    setInterval(() => {
+      if (ex(shutdownFile)) {
+        try { ul(shutdownFile); } catch {}
+        gracefulShutdown();
+      }
+    }, 200);
+  }
+
+  console.log(`Server child ready on port ${actualPort}`);
 }

package/src/server/routes/proxy.ts

@@ -1,5 +1,7 @@
 import { Hono } from "hono";
+import type { Context } from "hono";
 import { proxyService } from "../../services/proxy.service.ts";
+import { getProxyStats } from "../../services/db.service.ts";
 import { ok, err } from "../../types/api.ts";
 
 /**
@@ -22,6 +24,16 @@ function validateProxyAuth(authHeader: string | undefined): boolean {
   return token === key;
 }
 
+/** Extract caller IP/UA from request headers for proxy logging */
+function getCallerMeta(c: Context): { callerIp?: string; callerUa?: string } {
+  return {
+    callerIp: c.req.header("x-forwarded-for")?.split(",")[0]?.trim()
+      || c.req.header("x-real-ip")
+      || "unknown",
+    callerUa: c.req.header("user-agent") || "unknown",
+  };
+}
+
 /** CORS preflight for external tools */
 proxyRoutes.options("/*", (c) => {
   return new Response(null, {
@@ -54,7 +66,7 @@ proxyRoutes.post("/v1/messages", async (c) => {
     if (val) headers[key] = val;
   }
 
-  return proxyService.forward("/v1/messages", "POST", headers, body);
+  return proxyService.forward("/v1/messages", "POST", headers, body, getCallerMeta(c));
 });
 
 /** POST /proxy/v1/chat/completions — OpenAI-compatible chat completions proxy */
@@ -69,7 +81,7 @@ proxyRoutes.post("/v1/chat/completions", async (c) => {
   }
 
   const body = await c.req.text();
-  return proxyService.forwardOpenAi(body);
+  return proxyService.forwardOpenAi(body, getCallerMeta(c));
 });
 
 /** POST /proxy/v1/messages/count_tokens — token counting proxy */
@@ -90,5 +102,15 @@ proxyRoutes.post("/v1/messages/count_tokens", async (c) => {
     if (val) headers[key] = val;
   }
 
-  return proxyService.forward("/v1/messages/count_tokens", "POST", headers, body);
+  return proxyService.forward("/v1/messages/count_tokens", "POST", headers, body, getCallerMeta(c));
+});
+
+/** GET /proxy/stats — proxy request stats (behind proxy auth) */
+proxyRoutes.get("/stats", (c) => {
+  const authHeader = c.req.header("authorization") || c.req.header("x-api-key");
+  if (!validateProxyAuth(authHeader)) {
+    return c.json({ error: "Invalid proxy auth key" }, 401);
+  }
+  const stats = getProxyStats();
+  return c.json({ ...stats, requestCount: proxyService.getRequestCount() });
 });

package/src/server/routes/upgrade.ts

@@ -44,11 +44,12 @@ upgradeRoutes.post("/apply", async (c) => {
   // Signal supervisor to self-replace
   const signal = signalSupervisorUpgrade();
   if (!signal.sent) {
+    console.warn(`[upgrade] Supervisor signal failed: ${signal.error ?? "unknown"}`);
     return c.json(ok({
       success: true,
       newVersion: result.newVersion,
       restart: false,
-      message: "Upgraded. Restart manually with ppm restart",
+      message: `Upgraded to v${result.newVersion}. Restart manually: ppm restart (signal failed: ${signal.error ?? "unknown"})`,
     }));
   }
 

package/src/services/account-selector.service.ts

@@ -188,6 +188,18 @@ class AccountSelectorService {
     console.log(`[accounts] ${accountId} rate limited — cooldown ${Math.round(backoffMs / 1000)}s (retry #${retries})`);
   }
 
+  /** Called when account hits a hard usage/session limit (5h/weekly cap).
+   *  Cooldown until the real reset time (or ~1h fallback). Does NOT bump retryCounts —
+   *  this is a quota ceiling, not a transient failure, so it carries no escalating penalty. */
+  onUsageLimit(accountId: string, resetAtMs?: number): void {
+    const FALLBACK_MS = 60 * 60_000; // 1 hour
+    const cooldownUntilMs =
+      resetAtMs && resetAtMs > Date.now() ? resetAtMs : Date.now() + FALLBACK_MS;
+    accountService.setCooldown(accountId, cooldownUntilMs);
+    const mins = Math.round((cooldownUntilMs - Date.now()) / 60_000);
+    console.log(`[accounts] ${accountId} usage limit — cooldown ${mins}m (until reset)`);
+  }
+
   /** Called when auth error (401 / authentication_failed) — cooldown with longer backoff */
   onAuthError(accountId: string): void {
     const retries = (this.retryCounts.get(accountId) ?? 0) + 1;

package/src/services/db.service.ts

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 import { mkdirSync, existsSync } from "node:fs";
 import { encrypt, decrypt } from "../lib/account-crypto.ts";
 import { getPpmDir } from "./ppm-dir.ts";
-const CURRENT_SCHEMA_VERSION = 26;
+const CURRENT_SCHEMA_VERSION = 28;
 
 let db: Database | null = null;
 let dbProfile: string | null = null;
@@ -650,6 +650,26 @@ function runMigrations(database: Database): void {
     try { database.exec("ALTER TABLE session_metadata ADD COLUMN model TEXT"); } catch {}
     database.exec("PRAGMA user_version = 27;");
   }
+
+  if (current < 28) {
+    database.exec(`
+      CREATE TABLE IF NOT EXISTS proxy_requests (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        endpoint TEXT NOT NULL,
+        model TEXT,
+        account_id TEXT,
+        account_label TEXT,
+        caller_ip TEXT,
+        caller_ua TEXT,
+        status TEXT NOT NULL,
+        duration_ms INTEGER,
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_proxy_req_created ON proxy_requests(created_at);
+      CREATE INDEX IF NOT EXISTS idx_proxy_req_caller ON proxy_requests(caller_ip);
+      PRAGMA user_version = 28;
+    `);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -982,6 +1002,68 @@ export function getUsageSince(since: string): UsageRow[] {
   ).all(since) as UsageRow[];
 }
 
+// ---------------------------------------------------------------------------
+// Proxy request logging helpers
+// ---------------------------------------------------------------------------
+
+export type ProxyRequestStatus = "success" | "error" | "rate_limited";
+
+// Best-effort: a logging failure must never break the proxy request flow.
+export function insertProxyRequest(record: {
+  endpoint: string;
+  model?: string;
+  accountId?: string;
+  accountLabel?: string;
+  callerIp?: string;
+  callerUa?: string;
+  status: ProxyRequestStatus;
+  durationMs?: number;
+}): void {
+  try {
+    getDb().query(
+      "INSERT INTO proxy_requests (endpoint, model, account_id, account_label, caller_ip, caller_ua, status, duration_ms) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+    ).run(
+      record.endpoint, record.model ?? null, record.accountId ?? null,
+      record.accountLabel ?? null, record.callerIp ?? null, record.callerUa ?? null,
+      record.status, record.durationMs ?? null,
+    );
+  } catch (e) {
+    console.error(`[proxy] failed to log proxy request:`, (e as Error).message);
+  }
+}
+
+export function cleanupOldProxyRequests(days = 30): number {
+  const cutoff = new Date(Date.now() - days * 86_400_000).toISOString();
+  const result = getDb().run(
+    "DELETE FROM proxy_requests WHERE created_at < ?",
+    [cutoff],
+  );
+  return result.changes;
+}
+
+export interface ProxyStatsBucket {
+  model: string | null;
+  account_label: string | null;
+  caller_ip: string | null;
+  count: number;
+}
+
+export function getProxyStats(): { lastHour: ProxyStatsBucket[]; last24h: ProxyStatsBucket[]; total: number } {
+  const lastHour = getDb().query(
+    "SELECT model, account_label, caller_ip, COUNT(*) as count FROM proxy_requests WHERE created_at >= datetime('now', '-1 hour') GROUP BY model, account_label, caller_ip ORDER BY count DESC",
+  ).all() as ProxyStatsBucket[];
+
+  const last24h = getDb().query(
+    "SELECT model, account_label, caller_ip, COUNT(*) as count FROM proxy_requests WHERE created_at >= datetime('now', '-24 hours') GROUP BY model, account_label, caller_ip ORDER BY count DESC",
+  ).all() as ProxyStatsBucket[];
+
+  const totalRow = getDb().query(
+    "SELECT COUNT(*) as count FROM proxy_requests",
+  ).get() as { count: number };
+
+  return { lastHour, last24h, total: totalRow.count };
+}
+
 export function getDbFilePath(): string {
   return getDbPath();
 }