cartethyia 2.5.3 → 2.5.6

package/dist/dashboard/precompressed-assets.json

@@ -2,72 +2,72 @@
   "count": 114,
   "assets": [
     "assets\\AccountCooldown-Bjo92Qat.js",
-    "assets\\BannedPage-hfCzi-Ux.js",
-    "assets\\CliToolDetailPage-DLGqYEwI.js",
-    "assets\\CliToolsPage-DEDyKBlC.js",
-    "assets\\CombosPage-CfuYiQ8Z.js",
-    "assets\\ConsoleLogPage-bsLuZmYH.js",
-    "assets\\CustomizationPage-_UWhwziJ.js",
-    "assets\\HealthEventsModal-Cjfc5WFS.js",
-    "assets\\LoginPage-DDVIfZGW.js",
-    "assets\\ModelPicker-CWkTUtpX.js",
-    "assets\\OverviewPage-B53YYMng.js",
-    "assets\\ProviderDetailPage-B0KaAQf0.js",
+    "assets\\BannedPage-CADDq4IU.js",
+    "assets\\CliToolDetailPage-_z1hID7E.js",
+    "assets\\CliToolsPage-DuO1Z7dq.js",
+    "assets\\CombosPage-DNEPi3xU.js",
+    "assets\\ConsoleLogPage-BVdpfiz1.js",
+    "assets\\CustomizationPage-BR5HHvbi.js",
+    "assets\\HealthEventsModal-mUfcknqm.js",
+    "assets\\LoginPage-V5faV9V2.js",
+    "assets\\ModelPicker-C7pDb41R.js",
+    "assets\\OverviewPage-BDu20Jdx.js",
+    "assets\\ProviderDetailPage-Dllr_aFO.js",
     "assets\\ProviderIcon-CmfzxpVM.js",
-    "assets\\ProvidersPage-Dx31DgIO.js",
-    "assets\\ProxyPage-BpnR4kXT.js",
-    "assets\\QuotaPage-BpOQCnun.js",
-    "assets\\SettingsPage-DV1eo2J_.js",
-    "assets\\SetupPage-D6pmQ86L.js",
-    "assets\\SortableList-DWvKiuSl.js",
-    "assets\\StudioPage-CmkUrgdj.js",
+    "assets\\ProvidersPage-uPiGVTTK.js",
+    "assets\\ProxyPage-BaUkO-4O.js",
+    "assets\\QuotaPage-o0IFAsFb.js",
+    "assets\\SettingsPage-CYWqbXjp.js",
+    "assets\\SetupPage-UB690SE2.js",
+    "assets\\SortableList-BLujdX7N.js",
+    "assets\\StudioPage-D5C2raAc.js",
     "assets\\ToolIcon-K1ckcDKg.js",
-    "assets\\UsagePage-B47uOydr.js",
-    "assets\\api-keys-uNywYlfv.js",
-    "assets\\app-CafWtVXA.js",
-    "assets\\app-DxivpfYG.css",
+    "assets\\UsagePage-8uIcxa1W.js",
+    "assets\\api-keys-DQYLQxpW.js",
+    "assets\\app-BIt446yE.js",
+    "assets\\app-CX_Z8cMs.css",
     "assets\\arrow-left-CpBxkoxI.js",
     "assets\\arrow-right-Dl5yKnp8.js",
-    "assets\\assert-NHwYq95t.js",
+    "assets\\assert-C9FD_JwJ.js",
     "assets\\backup-file-gdKIlg8U.js",
-    "assets\\badge-6uzDDvqs.js",
-    "assets\\banner-4_WNg2WZ.js",
+    "assets\\badge-CR72dasT.js",
+    "assets\\banner-CI9_eSfO.js",
     "assets\\brain-Cwed_72z.js",
-    "assets\\card--AtFedAq.js",
+    "assets\\card-DS7CQEsO.js",
     "assets\\chevron-right-BXIy5l3h.js",
     "assets\\circle-alert-CntYHV5v.js",
     "assets\\circle-check-BU3v_mFW.js",
-    "assets\\cli-tools-B3e7dx3N.js",
-    "assets\\clipboard-button-NreUx6c8.js",
+    "assets\\cli-tools-CNqzrfdb.js",
+    "assets\\clipboard-button-611pSsaX.js",
     "assets\\cog-CdWhsajs.js",
-    "assets\\dialog-BtpsJU98.js",
+    "assets\\concurrency-BDF0ok7y.js",
+    "assets\\database-Dz9N3zGd.js",
     "assets\\dialog-actions-B1axpEg7.js",
-    "assets\\download-A0SW9OCW.js",
+    "assets\\dialog-k37exjNt.js",
     "assets\\download-dRFo5_Wu.js",
-    "assets\\drawer-WwwtzihF.js",
-    "assets\\entry-CkryrIea.js",
-    "assets\\entry-TJIye_jT.js",
-    "assets\\entry-jy9_4-Ke.js",
+    "assets\\drawer-CX7N8ucR.js",
+    "assets\\entry-B9Xvtnfj.js",
+    "assets\\entry-CTP8AyiS.js",
+    "assets\\entry-DxBHnauy.js",
     "assets\\eye-C_hawfH4.js",
     "assets\\eye-off-Bk5g2luF.js",
-    "assets\\fingerprint-pattern-BWuHtbW4.js",
     "assets\\gauge-BbIMy7MB.js",
-    "assets\\github-badge-D_eM3IgG.js",
+    "assets\\github-badge-sltk1qUi.js",
     "assets\\image-BPaouViG.js",
-    "assets\\index-BydyKaDz.js",
-    "assets\\inline-BcNGF8Gr.js",
-    "assets\\input-BG41et9G.js",
+    "assets\\index-CmxZr14F.js",
+    "assets\\inline-BhY2sSnO.js",
+    "assets\\input-V1umFiBk.js",
     "assets\\jsx-runtime-CXUMngI_.js",
     "assets\\key-round-UkavsGxp.js",
     "assets\\layers-2-glBbjl.js",
-    "assets\\layout-C8mer_Ak.js",
-    "assets\\list-row-Gh_W4OR_.js",
-    "assets\\live-BJGYRBnR.js",
+    "assets\\layout-BBOYycyS.js",
+    "assets\\list-row-1zzZYM0B.js",
+    "assets\\live-BivGfuUs.js",
     "assets\\log-in-BmRjy60c.js",
     "assets\\message-circle-CCxGwRvv.js",
-    "assets\\model-bans-DeVLDA7I.js",
-    "assets\\mutation-BkoLM5Ba.js",
-    "assets\\numbers-Bs4LOOuf.js",
+    "assets\\model-bans-CmffjLuG.js",
+    "assets\\mutation-46P0oWMe.js",
+    "assets\\numbers-DkfMR5Qs.js",
     "assets\\pencil-768ysRAr.js",
     "assets\\plus-DIdX_g-x.js",
     "assets\\power-off-Yjw9GMJh.js",
@@ -89,31 +89,31 @@
     "assets\\providers\\parallel.svg",
     "assets\\providers\\tokenharbor.svg",
     "assets\\providers\\zai-coding-plan.svg",
-    "assets\\query-keys-D7wX2vM5.js",
+    "assets\\query-keys-BFhGpwR1.js",
     "assets\\quota-DZGyp0N5.js",
     "assets\\refresh-cw-BqJFk4sU.js",
     "assets\\rotate-ccw-CufcqITi.js",
     "assets\\route-CNSNj9Zm.js",
-    "assets\\routing-CcusqXA7.js",
+    "assets\\routing-CAb4F37R.js",
     "assets\\scaling-nWE4Cx8f.js",
     "assets\\search-JOKus9rb.js",
-    "assets\\select-BO6h8yNv.js",
-    "assets\\settings-mpmXTgUa.js",
+    "assets\\select-BYR_5K2c.js",
+    "assets\\settings-DNX9sydi.js",
     "assets\\shield-check-DVS0Foqh.js",
-    "assets\\sparkles-BRaRUxAU.js",
-    "assets\\stack-DwLmjUFK.js",
-    "assets\\state-DYdQmdAl.js",
+    "assets\\stack-BHTfXdz_.js",
+    "assets\\state-mPDRlQkl.js",
     "assets\\stream-retry-5QnVuSSo.js",
-    "assets\\switch-CidSfbG7.js",
-    "assets\\terminal-Bd4ee8TA.js",
-    "assets\\tokens-DDxMbSRL.js",
+    "assets\\switch-DOmJxg7H.js",
+    "assets\\terminal-0_IjPWTk.js",
+    "assets\\tokens-COzario9.js",
     "assets\\trash-Cppn5c3R.js",
     "assets\\use-clipboard-B0Sy03fE.js",
-    "assets\\use-presence-BSZEBx7U.js",
+    "assets\\use-modal-focus-By7oJoGd.js",
     "assets\\use-reduced-motion-C4B0R6Sz.js",
     "assets\\use-timeout-BwcBBRrT.js",
-    "assets\\useMutation-w4u4CVue.js",
+    "assets\\useMutation-Dem0lXQj.js",
     "assets\\wrench-B6E1oEuY.js",
+    "assets\\zap-C4EeVW4q.js",
     "index.html"
   ]
 }

package/migrations/README.md

@@ -1,52 +1,52 @@
-# Database baselines
-
-Cartethyia keeps one SQL baseline per database backend:
-
-- `full-postgres/0000_baseline.sql` defines the foundational PostgreSQL schema
-  for a new database.
-- `lite-sqlite3/0000_baseline.sql` is generated from the PostgreSQL baseline by
-  `scripts/generate/sqlite-ddl.ts`; do not edit it by hand.
-
-The startup runner applies the baseline and numbered forward migrations,
-recording them in `cartethyia_schema_migrations` along with a hash marker for
-the exact baseline contents. Released baselines are immutable so existing
-installations keep matching their marker; numbered migrations bring that
-foundational schema up to the current schema. Each backend's migrations must
-have matching behavior. Startup fails with a recovery instruction for a
-database with unsupported retired migration history instead of treating it as
-current.
-
-## Recovering an existing installation
-
-1. Export a backup from the existing installation before switching it to a
-   release with unsupported migration history.
-2. Create a fresh database and point the application at it.
-3. Start the application so it creates the baseline schema.
-4. Restore the backup through the console restore flow.
-
-Restore normalizes legacy values that no longer satisfy current constraints,
-including `bypass_proxy` → `skip_proxy`, `bridge` → `https`, the retired
-provider User-Agent default, Cline's skip-proxy default, and `fusion` →
-`fallback`. Unknown or retired columns are reported and skipped according to
-the backup contract.
-
-Do not point tests or recovery steps at development or production databases.
-The startup path runs `ensureMigrated()` before provider/catalog seeding. Full
-mode uses `src/persistence/db-pg.ts` and an advisory lock; Lite uses
-`src/persistence/db-sqlite.ts`. Readiness compares the ledger to the available baseline and forward migration
-files. A failed migration aborts startup and is not recorded.
-
-Migrations are package assets, not resolved from the process working directory:
-`src/config/package-paths.ts` resolves them from the package root. `package.json`
-includes `migrations/` in the published files, and the Dockerfile copies the
-migration directories into `/app/migrations`.
-
-## Next schema change
-
-1. Update `src/persistence/schema.ts` and add matching numbered migrations to
-   both backends. Preserve released baseline files so existing baseline markers
-   remain valid.
-2. Update backup validation/mapping when old exported rows need normalization
-   or new required values.
-3. Run focused migration, restore, and typecheck tests. Validate against an
-   isolated database only.
+# Database baselines
+
+Cartethyia keeps one SQL baseline per database backend:
+
+- `full-postgres/0000_baseline.sql` defines the foundational PostgreSQL schema
+  for a new database.
+- `lite-sqlite3/0000_baseline.sql` is generated from the PostgreSQL baseline by
+  `scripts/tools/generate-sqlite.ts`; do not edit it by hand.
+
+The startup runner applies the baseline and numbered forward migrations,
+recording them in `cartethyia_schema_migrations` along with a hash marker for
+the exact baseline contents. Released baselines are immutable so existing
+installations keep matching their marker; numbered migrations bring that
+foundational schema up to the current schema. Each backend's migrations must
+have matching behavior. Startup fails with a recovery instruction for a
+database with unsupported retired migration history instead of treating it as
+current.
+
+## Recovering an existing installation
+
+1. Export a backup from the existing installation before switching it to a
+   release with unsupported migration history.
+2. Create a fresh database and point the application at it.
+3. Start the application so it creates the baseline schema.
+4. Restore the backup through the console restore flow.
+
+Restore normalizes legacy values that no longer satisfy current constraints,
+including `bypass_proxy` → `skip_proxy`, `bridge` → `https`, the retired
+provider User-Agent default, Cline's skip-proxy default, and `fusion` →
+`fallback`. Unknown or retired columns are reported and skipped according to
+the backup contract.
+
+Do not point tests or recovery steps at development or production databases.
+The startup path runs `ensureMigrated()` before provider/catalog seeding. Full
+mode uses `src/persistence/db-pg.ts` and an advisory lock; Lite uses
+`src/persistence/db-sqlite.ts`. Readiness compares the ledger to the available baseline and forward migration
+files. A failed migration aborts startup and is not recorded.
+
+Migrations are package assets, not resolved from the process working directory:
+`src/config/package-paths.ts` resolves them from the package root. `package.json`
+includes `migrations/` in the published files, and the Dockerfile copies the
+migration directories into `/app/migrations`.
+
+## Next schema change
+
+1. Update `src/persistence/schema.ts` and add matching numbered migrations to
+   both backends. Preserve released baseline files so existing baseline markers
+   remain valid.
+2. Update backup validation/mapping when old exported rows need normalization
+   or new required values.
+3. Run focused migration, restore, and typecheck tests. Validate against an
+   isolated database only.

package/migrations/lite-sqlite3/0000_baseline.sql

@@ -1,6 +1,6 @@
--- Generated by scripts/generate/sqlite-ddl.ts from migrations/full-postgres/0000_baseline.sql.
+-- Generated by scripts/tools/generate-sqlite.ts from migrations/full-postgres/0000_baseline.sql.
 -- Do not edit by hand: change src/persistence/schema.ts, then re-run
--- `bun scripts/generate/sqlite-ddl.ts`. The PostgreSQL baseline this is
+-- `bun scripts/tools/generate-sqlite.ts`. The PostgreSQL baseline this is
 -- derived from is hand-written and hash-pinned; add a numbered migration
 -- for a schema change instead of editing it.
 --> statement-breakpoint

package/package.json

@@ -1,95 +1,96 @@
-{
-  "name": "cartethyia",
-  "version": "2.5.3",
-  "description": "A powerful, self-hosted reverse proxy for OpenAI- and Anthropic-compatible AI clients, powered by native Bun and Elysia. It serves both protocols from a single server, routes every model across any configured provider, and translates requests and responses in real time — streaming and prompt caching included. Underneath it runs a full delivery engine: per-account health tracking, quota and cooldown enforcement, automatic failover across pools and providers, usage accounting, and telemetry. Point OpenCode, Cline, Claude Code, Codex, or any compatible client at Cartethyia and it keeps its native protocol while the gateway absorbs every provider-specific difference behind it. Runs on embedded SQLite or external PostgreSQL with optional Redis coordination, ships as a global CLI with a system-tray console, and needs only Bun 1.4+ alongside Node.js/npm.",
-  "license": "GPL-3.0-only",
-  "type": "module",
-  "packageManager": "bun@1.4.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/risunCodex/Cartethyia.git"
-  },
-  "homepage": "https://github.com/risunCodex/Cartethyia#readme",
-  "bugs": {
-    "url": "https://github.com/risunCodex/Cartethyia/issues"
-  },
-  "keywords": [
-    "ai",
-    "gateway",
-    "llm",
-    "bun",
-    "self-hosted"
-  ],
-  "bin": {
-    "cartethyia": "scripts/cli/bin/cartethyia.cjs",
-    "carte": "scripts/cli/bin/carte.cjs"
-  },
-  "files": [
-    "scripts/cli/",
-    "src/",
-    "migrations/",
-    "dist/dashboard/",
-    ".env.example",
-    "README.md"
-  ],
-  "workspaces": [
-    "dashboard"
-  ],
-  "engines": {
-    "bun": ">=1.4.0"
-  },
-  "scripts": {
-    "dev": "bun run dev:stack",
-    "dev:watch": "bun run scripts/dev/supervisor.ts",
-    "test": "bun run scripts/ci/run.ts",
-    "build": "bun run scripts/binary/build.ts",
-    "prepack": "bun run dashboard:build",
-    "setup": "bun run scripts/cli/command/setup.ts",
-    "start": "bun run scripts/cli/main.ts start",
-    "doctor": "bun run scripts/cli/command/doctor.ts",
-    "probe:egress": "bun run scripts/operations/probe-egress.ts",
-    "restart": "bun run scripts/binary/restart.ts",
-    "build:aot": "bun run scripts/binary/aot.ts",
-    "dev:stack": "concurrently -n BACKEND,DASHBOARD -c cyan,magenta --kill-others-on-fail \"bun run dev:backend\" \"bun run dashboard:dev\"",
-    "typecheck": "tsc --noEmit",
-    "test:watch": "bun run scripts/ci/run.ts --watch",
-    "test-db:up": "docker compose -f docker-compose.test.yml up -d --wait postgres-test",
-    "dev:backend": "bun run --hot src/main.ts",
-    "dev:console-auth": "bun run scripts/qa/console-session.ts",
-    "dev:visual-baseline": "bun run scripts/qa/visual-baseline.ts",
-    "build:binary": "bun run scripts/binary/compile.ts",
-    "test:backend": "bun run scripts/ci/run.ts --scope backend",
-    "test-db:down": "docker compose -f docker-compose.test.yml down",
-    "dashboard:dev": "bun run --cwd dashboard dev",
-    "test-db:check": "bun run scripts/ci/db-check.ts",
-    "dashboard:test": "bun run scripts/ci/run.ts --scope dashboard",
-    "test-db:reset": "docker compose -f docker-compose.test.yml down -v && docker compose -f docker-compose.test.yml up -d --wait postgres-test",
-    "dashboard:build": "bun run --cwd dashboard build",
-    "dashboard:typecheck": "bun run --cwd dashboard typecheck",
-    "check:migrations": "bun run scripts/ci/check-migrations.ts"
-  },
-  "dependencies": {
-    "drizzle-orm": "0.45.2",
-    "elysia": "^2.0.0-beta.16",
-    "enquirer": "^2.4.1",
-    "ioredis": "6.0.0",
-    "jose": "^6.2.12",
-    "jsonrepair": "^3.15.0",
-    "pg": "8.23.0",
-    "pino": "^10.3.1",
-    "pino-pretty": "^13.1.3",
-    "protobufjs": "^7.6.5",
-    "socks-proxy-agent": "^10.1.0",
-    "systray2": "2.1.4",
-    "typebox": "1.3.27",
-    "ws": "8.22.0"
-  },
-  "devDependencies": {
-    "@types/pg": "8.11.10",
-    "@types/ws": "8.18.1",
-    "bun-types": "1.4.0",
-    "concurrently": "^10.0.5",
-    "drizzle-kit": "^0.31.11",
-    "typescript": "5.9.2"
-  }
-}
+{
+  "name": "cartethyia",
+  "version": "2.5.6",
+  "description": "A powerful, self-hosted reverse proxy for OpenAI- and Anthropic-compatible AI clients, powered by native Bun and Elysia. It serves both protocols from a single server, routes every model across any configured provider, and translates requests and responses in real time \u2014 streaming and prompt caching included. Underneath it runs a full delivery engine: per-account health tracking, quota and cooldown enforcement, automatic failover across pools and providers, usage accounting, and telemetry. Point OpenCode, Cline, Claude Code, Codex, or any compatible client at Cartethyia and it keeps its native protocol while the gateway absorbs every provider-specific difference behind it. Runs on embedded SQLite or external PostgreSQL with optional Redis coordination, ships as a global CLI with a system-tray console, and needs only Bun 1.4+ alongside Node.js/npm.",
+  "license": "GPL-3.0-only",
+  "type": "module",
+  "packageManager": "bun@1.4.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/risunCodex/Cartethyia.git"
+  },
+  "homepage": "https://github.com/risunCodex/Cartethyia#readme",
+  "bugs": {
+    "url": "https://github.com/risunCodex/Cartethyia/issues"
+  },
+  "keywords": [
+    "ai",
+    "gateway",
+    "llm",
+    "bun",
+    "self-hosted"
+  ],
+  "bin": {
+    "cartethyia": "scripts/cli/bin/cartethyia.cjs",
+    "carte": "scripts/cli/bin/carte.cjs"
+  },
+  "files": [
+    "scripts/cli/",
+    "src/",
+    "migrations/",
+    "dist/dashboard/",
+    ".env.example",
+    "README.md"
+  ],
+  "workspaces": [
+    "dashboard"
+  ],
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "scripts": {
+    "dev": "bun run dev:stack",
+    "dev:watch": "bun run scripts/dev/supervisor.ts",
+    "test": "bun run scripts/test/run.ts",
+    "build": "bun run scripts/build/build.ts",
+    "prepack": "bun run dashboard:build",
+    "setup": "bun run scripts/cli/setup.ts",
+    "start": "bun run scripts/cli/main.ts start",
+    "doctor": "bun run scripts/cli/doctor.ts",
+    "probe:egress": "bun run scripts/tools/probe-egress.ts",
+    "restart": "bun run scripts/build/restart.ts",
+    "build:aot": "bun run scripts/build/aot.ts",
+    "dev:stack": "concurrently -n BACKEND,DASHBOARD -c cyan,magenta --kill-others-on-fail \"bun run dev:backend\" \"bun run dashboard:dev\"",
+    "typecheck": "tsc --noEmit",
+    "test:watch": "bun run scripts/test/run.ts --watch",
+    "test-db:up": "docker compose -f docker-compose.test.yml up -d --wait postgres-test",
+    "dev:backend": "bun run --hot src/main.ts",
+    "dev:console-auth": "bun run scripts/test/console-session.ts",
+    "dev:visual-baseline": "bun run scripts/test/visual-baseline.ts",
+    "build:binary": "bun run scripts/build/compile.ts",
+    "test:backend": "bun run scripts/test/run.ts --scope backend",
+    "test-db:down": "docker compose -f docker-compose.test.yml down",
+    "dashboard:dev": "bun run --cwd dashboard dev",
+    "test-db:check": "bun run scripts/test/check-db.ts",
+    "dashboard:test": "bun run scripts/test/run.ts --scope dashboard",
+    "test-db:reset": "docker compose -f docker-compose.test.yml down -v && docker compose -f docker-compose.test.yml up -d --wait postgres-test",
+    "dashboard:build": "bun run --cwd dashboard build",
+    "dashboard:typecheck": "bun run --cwd dashboard typecheck",
+    "check:migrations": "bun run scripts/test/check-migrations.ts",
+    "install": "bun run scripts/install/install.ts"
+  },
+  "dependencies": {
+    "drizzle-orm": "0.45.2",
+    "elysia": "2.0.0-beta.16",
+    "enquirer": "^2.4.1",
+    "ioredis": "6.0.0",
+    "jose": "^6.2.12",
+    "jsonrepair": "^3.15.0",
+    "pg": "8.23.0",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "protobufjs": "^7.6.5",
+    "socks-proxy-agent": "^10.1.0",
+    "systray2": "2.1.4",
+    "typebox": "1.3.27",
+    "ws": "8.22.0"
+  },
+  "devDependencies": {
+    "@types/pg": "8.11.10",
+    "@types/ws": "8.18.1",
+    "bun-types": "1.4.0",
+    "concurrently": "^10.0.5",
+    "drizzle-kit": "^0.31.11",
+    "typescript": "5.9.2"
+  }
+}

package/scripts/cli/admin.ts

@@ -0,0 +1,125 @@
+/**
+ * The two admin actions the menu and the tray both offer.
+ *
+ * Both go through the running gateway rather than the database file: the
+ * gateway holds the connection and the schema is dialect-dependent, so reading
+ * or writing the tables from this process would need a second implementation
+ * of both.
+ */
+
+import { ENV_PATH, readEnvFile } from "./env";
+
+/**
+ * Asks the gateway to write a gzipped config backup into the download
+ * directory. Returns the written path and counts, or null when it failed.
+ */
+export async function exportBackup(
+  port: number,
+  token: string,
+): Promise<{ path: string; bytes: number; counts: Record<string, number> } | null> {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/admin/export-backup`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-drain-token": token },
+      body: JSON.stringify({}),
+      signal: AbortSignal.timeout(60_000),
+    });
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      console.error(`The gateway refused the backup (HTTP ${response.status}). ${detail}`.trim());
+      return null;
+    }
+    return (await response.json()) as {
+      path: string;
+      bytes: number;
+      counts: Record<string, number>;
+    };
+  } catch {
+    console.error("Could not reach the gateway. Is it still running?");
+    return null;
+  }
+}
+
+/**
+ * Posts the console-account reset to the running gateway.
+ *
+ * Returns 0 on success and 1 on any failure so the caller can print one line
+ * either way.
+ */
+export async function resetConsoleAccount(port: number, token: string): Promise<number> {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/admin/reset-console-account`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-drain-token": token },
+      body: JSON.stringify({ confirm: "RESET" }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      console.error(`The gateway refused the reset (HTTP ${response.status}). ${detail}`.trim());
+      return 1;
+    }
+    return 0;
+  } catch {
+    console.error("Could not reach the gateway. Is it still running?");
+    return 1;
+  }
+}
+
+
+/**
+ * Operator escape hatch: clears the console login lockout bucket.
+ *
+ * The lockout is keyed by `<username>:<clientIp>` and lasts an hour, and there
+ * is no console surface to clear it — a locked-out operator has no way back in
+ * short of editing the database by hand. This is the documented reset.
+ *
+ * Usage:
+ *   cartethyia admin reset-lockout <username> <clientIp>
+ *   cartethyia admin reset-lockout --all
+ */
+export async function resetLockout(args: readonly string[]): Promise<void> {
+  const all = args.includes("--all");
+  const positional = args.filter((arg) => !arg.startsWith("--"));
+  if (!all && positional.length < 2) {
+    console.error("Usage: cartethyia admin reset-lockout <username> <clientIp>");
+    console.error("       cartethyia admin reset-lockout --all");
+    process.exit(1);
+  }
+
+  const env = await readEnvFile(ENV_PATH);
+  const databaseUrl = env.DATABASE_URL ?? process.env.DATABASE_URL;
+  if (!databaseUrl) {
+    console.error("✗ DATABASE_URL is not set; cannot reach the lockout table.");
+    process.exit(1);
+  }
+  process.env.DATABASE_URL = databaseUrl;
+
+  const { getDb, closeDb } = await import("../../src/persistence/boot");
+  const { consoleLockouts } = await import("../../src/persistence/schema");
+  const { eq, or } = await import("drizzle-orm");
+
+  const db = getDb();
+  try {
+    if (all) {
+      const cleared = await db.delete(consoleLockouts).returning({ ip: consoleLockouts.ip });
+      console.log(`✓ Cleared ${cleared.length} lockout row(s).`);
+      return;
+    }
+    const username = positional[0]!.trim().toLowerCase();
+    const clientIp = positional[1]!;
+    // The bucket key is `<identifier>:<ip>`; match either exact spelling so
+    // an operator does not have to guess how the identifier was normalized.
+    const cleared = await db
+      .delete(consoleLockouts)
+      .where(or(eq(consoleLockouts.ip, `${username}:${clientIp}`), eq(consoleLockouts.ip, clientIp)))
+      .returning({ ip: consoleLockouts.ip });
+    if (cleared.length === 0) {
+      console.log(`• No lockout row for ${username}:${clientIp} (already clear).`);
+    } else {
+      console.log(`✓ Cleared lockout for ${cleared.map((row) => row.ip).join(", ")}.`);
+    }
+  } finally {
+    await closeDb();
+  }
+}