github-issue-tower-defence-management 1.88.1 → 1.90.0

package/src/adapter/entry-points/console/ui-dist/assets/index-DHlBLm7d.css

@@ -0,0 +1 @@
+/*! tailwindcss v4.3.0 | MIT License | https://tailwindcss.com */@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-divide-y-reverse:0;--tw-border-style:solid;--tw-font-weight:initial;--tw-outline-style:solid;--tw-shadow:0 0 #0000;--tw-shadow-color:initial;--tw-shadow-alpha:100%;--tw-inset-shadow:0 0 #0000;--tw-inset-shadow-color:initial;--tw-inset-shadow-alpha:100%;--tw-ring-color:initial;--tw-ring-shadow:0 0 #0000;--tw-inset-ring-color:initial;--tw-inset-ring-shadow:0 0 #0000;--tw-ring-inset:initial;--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-offset-shadow:0 0 #0000}}}@layer theme{:root,:host{--font-sans:ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";--font-mono:ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;--spacing:.25rem;--container-3xl:48rem;--text-xs:.75rem;--text-xs--line-height:calc(1 / .75);--text-sm:.875rem;--text-sm--line-height:calc(1.25 / .875);--text-base:1rem;--text-base--line-height: 1.5 ;--font-weight-medium:500;--font-weight-semibold:600;--radius-md:.375rem;--default-transition-duration:.15s;--default-transition-timing-function:cubic-bezier(.4, 0, .2, 1);--default-font-family:var(--font-sans);--default-mono-font-family:var(--font-mono);--color-border:#e5e5e5;--color-input:#e5e5e5;--color-ring:#0a0a0a;--color-background:#fff;--color-foreground:#0a0a0a;--color-primary:#171717;--color-primary-foreground:#fafafa;--color-secondary:#f5f5f5;--color-secondary-foreground:#171717;--color-muted-foreground:#737373;--color-accent:#f5f5f5;--color-accent-foreground:#171717;--color-destructive:#ef4444}}@layer base{*,:after,:before,::backdrop{box-sizing:border-box;border:0 solid;margin:0;padding:0}::file-selector-button{box-sizing:border-box;border:0 solid;margin:0;padding:0}html,:host{-webkit-text-size-adjust:100%;-moz-tab-size:4;tab-size:4;line-height:1.5;font-family:var(--default-font-family,ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji");font-feature-settings:var(--default-font-feature-settings,normal);font-variation-settings:var(--default-font-variation-settings,normal);-webkit-tap-highlight-color:transparent}hr{height:0;color:inherit;border-top-width:1px}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;-webkit-text-decoration:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,samp,pre{font-family:var(--default-mono-font-family,ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace);font-feature-settings:var(--default-mono-font-feature-settings,normal);font-variation-settings:var(--default-mono-font-variation-settings,normal);font-size:1em}small{font-size:80%}sub,sup{vertical-align:baseline;font-size:75%;line-height:0;position:relative}sub{bottom:-.25em}sup{top:-.5em}table{text-indent:0;border-color:inherit;border-collapse:collapse}:-moz-focusring{outline:auto}progress{vertical-align:baseline}summary{display:list-item}ol,ul,menu{list-style:none}img,svg,video,canvas,audio,iframe,embed,object{vertical-align:middle;display:block}img,video{max-width:100%;height:auto}button,input,select,optgroup,textarea{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}::file-selector-button{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}:where(select:is([multiple],[size])) optgroup{font-weight:bolder}:where(select:is([multiple],[size])) optgroup option{padding-inline-start:20px}::file-selector-button{margin-inline-end:4px}::placeholder{opacity:1}@supports (not ((-webkit-appearance:-apple-pay-button))) or (contain-intrinsic-size:1px){::placeholder{color:currentColor}@supports (color:color-mix(in lab,red,red)){::placeholder{color:color-mix(in oklab,currentcolor 50%,transparent)}}}textarea{resize:vertical}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-date-and-time-value{min-height:1lh;text-align:inherit}::-webkit-datetime-edit{display:inline-flex}::-webkit-datetime-edit-fields-wrapper{padding:0}::-webkit-datetime-edit{padding-block:0}::-webkit-datetime-edit-year-field{padding-block:0}::-webkit-datetime-edit-month-field{padding-block:0}::-webkit-datetime-edit-day-field{padding-block:0}::-webkit-datetime-edit-hour-field{padding-block:0}::-webkit-datetime-edit-minute-field{padding-block:0}::-webkit-datetime-edit-second-field{padding-block:0}::-webkit-datetime-edit-millisecond-field{padding-block:0}::-webkit-datetime-edit-meridiem-field{padding-block:0}::-webkit-calendar-picker-indicator{line-height:1}:-moz-ui-invalid{box-shadow:none}button,input:where([type=button],[type=reset],[type=submit]){-webkit-appearance:button;-moz-appearance:button;appearance:button}::file-selector-button{-webkit-appearance:button;-moz-appearance:button;appearance:button}::-webkit-inner-spin-button{height:auto}::-webkit-outer-spin-button{height:auto}[hidden]:where(:not([hidden=until-found])){display:none!important}}@layer components;@layer utilities{.container{width:100%}@media(min-width:40rem){.container{max-width:40rem}}@media(min-width:48rem){.container{max-width:48rem}}@media(min-width:64rem){.container{max-width:64rem}}@media(min-width:80rem){.container{max-width:80rem}}@media(min-width:96rem){.container{max-width:96rem}}.mx-auto{margin-inline:auto}.flex{display:flex}.inline-flex{display:inline-flex}.h-8{height:calc(var(--spacing) * 8)}.h-9{height:calc(var(--spacing) * 9)}.h-10{height:calc(var(--spacing) * 10)}.max-w-3xl{max-width:var(--container-3xl)}.flex-col{flex-direction:column}.flex-wrap{flex-wrap:wrap}.items-baseline{align-items:baseline}.items-center{align-items:center}.justify-center{justify-content:center}.gap-1{gap:calc(var(--spacing) * 1)}.gap-2{gap:calc(var(--spacing) * 2)}:where(.divide-y>:not(:last-child)){--tw-divide-y-reverse:0;border-bottom-style:var(--tw-border-style);border-top-style:var(--tw-border-style);border-top-width:calc(1px * var(--tw-divide-y-reverse));border-bottom-width:calc(1px * calc(1 - var(--tw-divide-y-reverse)))}:where(.divide-border>:not(:last-child)){border-color:var(--color-border)}.rounded-md{border-radius:var(--radius-md)}.border{border-style:var(--tw-border-style);border-width:1px}.border-b{border-bottom-style:var(--tw-border-style);border-bottom-width:1px}.border-border{border-color:var(--color-border)}.border-input{border-color:var(--color-input)}.border-transparent{border-color:#0000}.bg-background{background-color:var(--color-background)}.bg-primary{background-color:var(--color-primary)}.bg-secondary{background-color:var(--color-secondary)}.p-2{padding:calc(var(--spacing) * 2)}.p-3{padding:calc(var(--spacing) * 3)}.p-4{padding:calc(var(--spacing) * 4)}.px-2\.5{padding-inline:calc(var(--spacing) * 2.5)}.px-3{padding-inline:calc(var(--spacing) * 3)}.px-4{padding-inline:calc(var(--spacing) * 4)}.px-8{padding-inline:calc(var(--spacing) * 8)}.py-0\.5{padding-block:calc(var(--spacing) * .5)}.py-2{padding-block:calc(var(--spacing) * 2)}.text-base{font-size:var(--text-base);line-height:var(--tw-leading,var(--text-base--line-height))}.text-sm{font-size:var(--text-sm);line-height:var(--tw-leading,var(--text-sm--line-height))}.text-xs{font-size:var(--text-xs);line-height:var(--tw-leading,var(--text-xs--line-height))}.font-medium{--tw-font-weight:var(--font-weight-medium);font-weight:var(--font-weight-medium)}.font-semibold{--tw-font-weight:var(--font-weight-semibold);font-weight:var(--font-weight-semibold)}.whitespace-nowrap{white-space:nowrap}.text-destructive{color:var(--color-destructive)}.text-foreground{color:var(--color-foreground)}.text-muted-foreground{color:var(--color-muted-foreground)}.text-primary-foreground{color:var(--color-primary-foreground)}.text-secondary-foreground{color:var(--color-secondary-foreground)}.underline-offset-2{text-underline-offset:2px}.outline{outline-style:var(--tw-outline-style);outline-width:1px}.transition-colors{transition-property:color,background-color,border-color,outline-color,text-decoration-color,fill,stroke,--tw-gradient-from,--tw-gradient-via,--tw-gradient-to;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}@media(hover:hover){.hover\:bg-accent:hover{background-color:var(--color-accent)}.hover\:bg-primary\/90:hover{background-color:#171717e6}@supports (color:color-mix(in lab,red,red)){.hover\:bg-primary\/90:hover{background-color:color-mix(in oklab,var(--color-primary) 90%,transparent)}}.hover\:bg-secondary\/80:hover{background-color:#f5f5f5cc}@supports (color:color-mix(in lab,red,red)){.hover\:bg-secondary\/80:hover{background-color:color-mix(in oklab,var(--color-secondary) 80%,transparent)}}.hover\:text-accent-foreground:hover{color:var(--color-accent-foreground)}.hover\:underline:hover{text-decoration-line:underline}}.focus-visible\:ring-2:focus-visible{--tw-ring-shadow:var(--tw-ring-inset,) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color,currentcolor);box-shadow:var(--tw-inset-shadow),var(--tw-inset-ring-shadow),var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow)}.focus-visible\:ring-ring:focus-visible{--tw-ring-color:var(--color-ring)}.focus-visible\:outline-none:focus-visible{--tw-outline-style:none;outline-style:none}.disabled\:pointer-events-none:disabled{pointer-events:none}.disabled\:opacity-50:disabled{opacity:.5}}body{background-color:var(--color-background);color:var(--color-foreground);margin:0;font-family:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica,Arial,sans-serif}@property --tw-divide-y-reverse{syntax:"*";inherits:false;initial-value:0}@property --tw-border-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-outline-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-shadow-color{syntax:"*";inherits:false}@property --tw-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-inset-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-inset-shadow-color{syntax:"*";inherits:false}@property --tw-inset-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-ring-color{syntax:"*";inherits:false}@property --tw-ring-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-inset-ring-color{syntax:"*";inherits:false}@property --tw-inset-ring-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-ring-inset{syntax:"*";inherits:false}@property --tw-ring-offset-width{syntax:"<length>";inherits:false;initial-value:0}@property --tw-ring-offset-color{syntax:"*";inherits:false;initial-value:#fff}@property --tw-ring-offset-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}

package/src/adapter/entry-points/console/ui-dist/index.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>TDPM Console</title>
-    <script type="module" crossorigin src="./assets/index-DcOZ02ON.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-DFxrSRH4.css">
+    <script type="module" crossorigin src="/assets/index-DDjYPXRT.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DHlBLm7d.css">
   </head>
   <body>
     <div id="root"></div>

package/src/adapter/entry-points/handlers/OauthTokenSelectHandler.test.ts

@@ -0,0 +1,204 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { hashToken } from '../../proxy/RateLimitCache';
+import {
+  OauthTokenSelectHandler,
+  resolveCacheDirectory,
+  resolveTokenListJsonPath,
+} from './OauthTokenSelectHandler';
+
+const NOW = 2_000_000;
+const HOUR = 3600;
+const DAY = 86400;
+
+type FakeHeaders = {
+  fiveHourUtilization: number;
+  fiveHourReset: number;
+  sevenDayUtilization: number;
+  sevenDayReset: number;
+};
+
+describe('OauthTokenSelectHandler', () => {
+  let tempDir: string;
+  let cacheDirectory: string;
+  let tokenListPath: string;
+  const originalTokenListEnv =
+    process.env.CLAUDE_CODE_OAUTH_TOKEN_LIST_JSON_PATH;
+  const originalCacheEnv = process.env.TDPM_RATELIMIT_CACHE_DIR;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'select-token-'));
+    cacheDirectory = path.join(tempDir, 'cache');
+    fs.mkdirSync(cacheDirectory, { recursive: true });
+    tokenListPath = path.join(tempDir, 'tokens.json');
+    delete process.env.CLAUDE_CODE_OAUTH_TOKEN_LIST_JSON_PATH;
+    delete process.env.TDPM_RATELIMIT_CACHE_DIR;
+  });
+
+  afterEach(() => {
+    if (originalTokenListEnv === undefined) {
+      delete process.env.CLAUDE_CODE_OAUTH_TOKEN_LIST_JSON_PATH;
+    } else {
+      process.env.CLAUDE_CODE_OAUTH_TOKEN_LIST_JSON_PATH = originalTokenListEnv;
+    }
+    if (originalCacheEnv === undefined) {
+      delete process.env.TDPM_RATELIMIT_CACHE_DIR;
+    } else {
+      process.env.TDPM_RATELIMIT_CACHE_DIR = originalCacheEnv;
+    }
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  const writeTokenList = (entries: { name: string; token: string }[]): void => {
+    fs.writeFileSync(tokenListPath, JSON.stringify(entries));
+  };
+
+  const writeCache = (token: string, headers: FakeHeaders): void => {
+    const payload = {
+      ts: NOW,
+      headers: {
+        'anthropic-ratelimit-unified-status': 'allowed',
+        'anthropic-ratelimit-unified-5h-status': 'allowed',
+        'anthropic-ratelimit-unified-5h-reset': String(headers.fiveHourReset),
+        'anthropic-ratelimit-unified-5h-utilization': String(
+          headers.fiveHourUtilization,
+        ),
+        'anthropic-ratelimit-unified-7d-status': 'allowed',
+        'anthropic-ratelimit-unified-7d-reset': String(headers.sevenDayReset),
+        'anthropic-ratelimit-unified-7d-utilization': String(
+          headers.sevenDayUtilization,
+        ),
+      },
+      modelWeeklyLimits: {},
+    };
+    fs.writeFileSync(
+      path.join(cacheDirectory, `${hashToken(token)}.json`),
+      JSON.stringify(payload),
+    );
+  };
+
+  it('selects the eligible token with the soonest 7d reset', () => {
+    writeTokenList([
+      { name: 'far', token: 'fake-far' },
+      { name: 'soon', token: 'fake-soon' },
+    ]);
+    writeCache('fake-far', {
+      fiveHourUtilization: 0.1,
+      fiveHourReset: NOW + HOUR,
+      sevenDayUtilization: 0.1,
+      sevenDayReset: NOW + 6 * DAY,
+    });
+    writeCache('fake-soon', {
+      fiveHourUtilization: 0.1,
+      fiveHourReset: NOW + HOUR,
+      sevenDayUtilization: 0.1,
+      sevenDayReset: NOW + 2 * DAY,
+    });
+
+    const handler = new OauthTokenSelectHandler();
+    const output = handler.handle({
+      tokenListJsonPath: tokenListPath,
+      cacheDirectory,
+      nowEpochSeconds: NOW,
+    });
+
+    expect(output.selectedName).toBe('soon');
+    expect(output.selectedToken).toBe('fake-soon');
+  });
+
+  it('treats a token with no cache file as fully free', () => {
+    writeTokenList([{ name: 'fresh', token: 'fake-fresh' }]);
+
+    const handler = new OauthTokenSelectHandler();
+    const output = handler.handle({
+      tokenListJsonPath: tokenListPath,
+      cacheDirectory,
+      nowEpochSeconds: NOW,
+    });
+
+    expect(output.selectedName).toBe('fresh');
+  });
+
+  it('returns null and a diagnostic when no token passes the filter', () => {
+    writeTokenList([{ name: 'busy', token: 'fake-busy' }]);
+    writeCache('fake-busy', {
+      fiveHourUtilization: 0.9,
+      fiveHourReset: NOW + HOUR,
+      sevenDayUtilization: 0.1,
+      sevenDayReset: NOW + DAY,
+    });
+
+    const handler = new OauthTokenSelectHandler();
+    const output = handler.handle({
+      tokenListJsonPath: tokenListPath,
+      cacheDirectory,
+      nowEpochSeconds: NOW,
+    });
+
+    expect(output.selectedToken).toBeNull();
+    expect(output.diagnostics.join('\n')).toContain(
+      'No eligible token passed the rate-limit filter.',
+    );
+  });
+
+  it('returns a diagnostic when no token list path is resolvable', () => {
+    const handler = new OauthTokenSelectHandler();
+    const output = handler.handle({
+      tokenListJsonPath: null,
+      cacheDirectory,
+      nowEpochSeconds: NOW,
+    });
+
+    expect(output.selectedToken).toBeNull();
+    expect(output.diagnostics.join('\n')).toContain('No token list path');
+  });
+
+  it('returns a diagnostic when the token list file has no usable entries', () => {
+    fs.writeFileSync(tokenListPath, JSON.stringify([]));
+
+    const handler = new OauthTokenSelectHandler();
+    const output = handler.handle({
+      tokenListJsonPath: tokenListPath,
+      cacheDirectory,
+      nowEpochSeconds: NOW,
+    });
+
+    expect(output.selectedToken).toBeNull();
+    expect(output.diagnostics.join('\n')).toContain('No usable token entries');
+  });
+
+  describe('resolveTokenListJsonPath', () => {
+    it('prefers the explicit path over the environment variable', () => {
+      process.env.CLAUDE_CODE_OAUTH_TOKEN_LIST_JSON_PATH = '/from/env.json';
+      expect(resolveTokenListJsonPath('/explicit.json')).toBe('/explicit.json');
+    });
+
+    it('falls back to the environment variable when no explicit path is given', () => {
+      process.env.CLAUDE_CODE_OAUTH_TOKEN_LIST_JSON_PATH = '/from/env.json';
+      expect(resolveTokenListJsonPath(null)).toBe('/from/env.json');
+    });
+
+    it('returns null when neither source provides a path', () => {
+      expect(resolveTokenListJsonPath(null)).toBeNull();
+    });
+  });
+
+  describe('resolveCacheDirectory', () => {
+    it('prefers the explicit directory over the environment variable', () => {
+      process.env.TDPM_RATELIMIT_CACHE_DIR = '/from/env';
+      expect(resolveCacheDirectory('/explicit')).toBe('/explicit');
+    });
+
+    it('falls back to the environment variable when no explicit directory is given', () => {
+      process.env.TDPM_RATELIMIT_CACHE_DIR = '/from/env';
+      expect(resolveCacheDirectory(null)).toBe('/from/env');
+    });
+
+    it('falls back to the default tdpm cache directory', () => {
+      expect(resolveCacheDirectory(null)).toContain(
+        path.join('tdpm', 'ratelimit'),
+      );
+    });
+  });
+});

package/src/adapter/entry-points/handlers/OauthTokenSelectHandler.ts

@@ -0,0 +1,132 @@
+import {
+  OauthTokenCandidate,
+  OauthTokenSelectResult,
+  OauthTokenSelectUseCase,
+} from '../../../domain/usecases/OauthTokenSelectUseCase';
+import { cacheDir, readRateLimit } from '../../proxy/RateLimitCache';
+import { loadTokenEntries } from '../../proxy/TokenListLoader';
+
+export type OauthTokenSelectHandlerInput = {
+  tokenListJsonPath: string | null;
+  cacheDirectory: string | null;
+  nowEpochSeconds: number;
+};
+
+export type OauthTokenSelectHandlerOutput = {
+  selectedToken: string | null;
+  selectedName: string | null;
+  diagnostics: string[];
+};
+
+const DEFAULT_TOKEN_LIST_PATH_ENV = 'CLAUDE_CODE_OAUTH_TOKEN_LIST_JSON_PATH';
+const DEFAULT_CACHE_DIRECTORY_ENV = 'TDPM_RATELIMIT_CACHE_DIR';
+
+export const resolveTokenListJsonPath = (
+  explicitPath: string | null,
+): string | null => {
+  if (explicitPath !== null && explicitPath.length > 0) {
+    return explicitPath;
+  }
+  const fromEnv = process.env[DEFAULT_TOKEN_LIST_PATH_ENV];
+  if (fromEnv !== undefined && fromEnv.length > 0) {
+    return fromEnv;
+  }
+  return null;
+};
+
+export const resolveCacheDirectory = (
+  explicitDirectory: string | null,
+): string => {
+  if (explicitDirectory !== null && explicitDirectory.length > 0) {
+    return explicitDirectory;
+  }
+  const fromEnv = process.env[DEFAULT_CACHE_DIRECTORY_ENV];
+  if (fromEnv !== undefined && fromEnv.length > 0) {
+    return fromEnv;
+  }
+  return cacheDir();
+};
+
+export class OauthTokenSelectHandler {
+  constructor(
+    private readonly useCase: OauthTokenSelectUseCase = new OauthTokenSelectUseCase(),
+  ) {}
+
+  handle = (
+    input: OauthTokenSelectHandlerInput,
+  ): OauthTokenSelectHandlerOutput => {
+    const tokenListJsonPath = resolveTokenListJsonPath(input.tokenListJsonPath);
+    if (tokenListJsonPath === null) {
+      return {
+        selectedToken: null,
+        selectedName: null,
+        diagnostics: [
+          `No token list path provided. Pass --tokenListJsonPath or set ${DEFAULT_TOKEN_LIST_PATH_ENV}.`,
+        ],
+      };
+    }
+
+    const entries = loadTokenEntries(tokenListJsonPath);
+    if (entries === null) {
+      return {
+        selectedToken: null,
+        selectedName: null,
+        diagnostics: [
+          `No usable token entries loaded from ${tokenListJsonPath}.`,
+        ],
+      };
+    }
+
+    const cacheDirectory = resolveCacheDirectory(input.cacheDirectory);
+
+    const candidates: OauthTokenCandidate[] = entries.map(({ name, token }) => {
+      const snapshot = readRateLimit(token, cacheDirectory);
+      return {
+        name,
+        token,
+        snapshot:
+          snapshot === null
+            ? null
+            : {
+                fiveHourUtilization: snapshot.fiveHourUtilization,
+                fiveHourReset: snapshot.fiveHourReset,
+                sevenDayUtilization: snapshot.sevenDayUtilization,
+                sevenDayReset: snapshot.sevenDayReset,
+              },
+      };
+    });
+
+    const result = this.useCase.run(candidates, input.nowEpochSeconds);
+
+    return {
+      selectedToken: result.selected?.token ?? null,
+      selectedName: result.selected?.name ?? null,
+      diagnostics: this.formatDiagnostics(result, input.nowEpochSeconds),
+    };
+  };
+
+  private formatDiagnostics = (
+    result: OauthTokenSelectResult,
+    nowEpochSeconds: number,
+  ): string[] => {
+    const lines = result.metrics.map((metric) => {
+      const secondsUntilSevenDayEnd = Math.round(
+        metric.sevenDayEndEpoch - nowEpochSeconds,
+      );
+      const status = metric.eligible
+        ? 'eligible'
+        : `excluded (${metric.exclusionReason})`;
+      return `${metric.name}: 5h ${Math.round(metric.fiveHourFreeRatio * 100)}% free, 7d ${Math.round(metric.sevenDayFreeRatio * 100)}% free, 7d-end in ${secondsUntilSevenDayEnd}s -> ${status}`;
+    });
+
+    if (result.selected === null) {
+      lines.push('No eligible token passed the rate-limit filter.');
+    } else {
+      lines.push(
+        `Selected ${result.selected.name} (soonest 7d reset among eligible tokens).`,
+      );
+    }
+
+    return lines;
+  };
+}

package/src/adapter/proxy/RateLimitCache.ts

@@ -39,8 +39,10 @@ export const cacheDir = (): string => {
 export const hashToken = (token: string): string =>
   crypto.createHash(HASH_ALGORITHM).update(token).digest('hex');
 
-export const cachePathForToken = (token: string): string =>
-  path.join(cacheDir(), `${hashToken(token)}.json`);
+export const cachePathForToken = (
+  token: string,
+  baseDir: string = cacheDir(),
+): string => path.join(baseDir, `${hashToken(token)}.json`);
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -222,8 +224,11 @@ export const parseModelRateLimitsFromHeaders = (
   return result;
 };
 
-export const readRateLimit = (token: string): RateLimitSnapshot | null => {
-  const filePath = cachePathForToken(token);
+export const readRateLimit = (
+  token: string,
+  baseDir: string = cacheDir(),
+): RateLimitSnapshot | null => {
+  const filePath = cachePathForToken(token, baseDir);
   if (!fs.existsSync(filePath)) return null;
   try {
     const raw = fs.readFileSync(filePath, 'utf8');

package/src/domain/usecases/OauthTokenSelectUseCase.test.ts

@@ -0,0 +1,179 @@
+import {
+  OauthTokenCandidate,
+  OauthTokenSelectUseCase,
+  OauthTokenWindowSnapshot,
+} from './OauthTokenSelectUseCase';
+
+const NOW = 1_000_000;
+const HOUR = 3600;
+const DAY = 86400;
+
+const snapshot = (
+  overrides: Partial<OauthTokenWindowSnapshot>,
+): OauthTokenWindowSnapshot => ({
+  fiveHourUtilization: 0,
+  fiveHourReset: NOW + HOUR,
+  sevenDayUtilization: 0,
+  sevenDayReset: NOW + DAY,
+  ...overrides,
+});
+
+const candidate = (
+  name: string,
+  snapshotValue: OauthTokenWindowSnapshot | null,
+): OauthTokenCandidate => ({
+  name,
+  token: `fake-token-${name}`,
+  snapshot: snapshotValue,
+});
+
+describe('OauthTokenSelectUseCase', () => {
+  const useCase = new OauthTokenSelectUseCase();
+
+  it('selects the eligible token whose 7d window resets soonest', () => {
+    const result = useCase.run(
+      [
+        candidate(
+          'far',
+          snapshot({ sevenDayUtilization: 0.1, sevenDayReset: NOW + 6 * DAY }),
+        ),
+        candidate(
+          'soon',
+          snapshot({ sevenDayUtilization: 0.1, sevenDayReset: NOW + 2 * DAY }),
+        ),
+        candidate(
+          'middle',
+          snapshot({ sevenDayUtilization: 0.1, sevenDayReset: NOW + 4 * DAY }),
+        ),
+      ],
+      NOW,
+    );
+
+    expect(result.selected?.name).toBe('soon');
+    expect(result.selected?.token).toBe('fake-token-soon');
+  });
+
+  it('excludes a token whose 5h window is less than 60% free', () => {
+    const result = useCase.run(
+      [
+        candidate('busy5h', snapshot({ fiveHourUtilization: 0.41 })),
+        candidate('ok', snapshot({ fiveHourUtilization: 0.4 })),
+      ],
+      NOW,
+    );
+
+    expect(result.selected?.name).toBe('ok');
+    const busy = result.metrics.find((m) => m.name === 'busy5h');
+    expect(busy?.eligible).toBe(false);
+    expect(busy?.exclusionReason).toContain('5h window');
+  });
+
+  it('treats exactly 40% used 5h utilization as eligible (boundary)', () => {
+    const result = useCase.run(
+      [candidate('boundary', snapshot({ fiveHourUtilization: 0.4 }))],
+      NOW,
+    );
+
+    expect(result.selected?.name).toBe('boundary');
+  });
+
+  it('excludes a token whose 7d window is less than 30% free', () => {
+    const result = useCase.run(
+      [
+        candidate('busy7d', snapshot({ sevenDayUtilization: 0.71 })),
+        candidate('ok', snapshot({ sevenDayUtilization: 0.7 })),
+      ],
+      NOW,
+    );
+
+    expect(result.selected?.name).toBe('ok');
+    const busy = result.metrics.find((m) => m.name === 'busy7d');
+    expect(busy?.eligible).toBe(false);
+    expect(busy?.exclusionReason).toContain('7d window');
+  });
+
+  it('treats a token with no snapshot as fully free', () => {
+    const result = useCase.run([candidate('fresh', null)], NOW);
+
+    expect(result.selected?.name).toBe('fresh');
+    const fresh = result.metrics.find((m) => m.name === 'fresh');
+    expect(fresh?.fiveHourFreeRatio).toBe(1);
+    expect(fresh?.sevenDayFreeRatio).toBe(1);
+  });
+
+  it('treats an expired window as fully free', () => {
+    const result = useCase.run(
+      [
+        candidate(
+          'expired',
+          snapshot({
+            fiveHourUtilization: 0.99,
+            fiveHourReset: NOW - HOUR,
+            sevenDayUtilization: 0.99,
+            sevenDayReset: NOW - DAY,
+          }),
+        ),
+      ],
+      NOW,
+    );
+
+    expect(result.selected?.name).toBe('expired');
+    const expired = result.metrics.find((m) => m.name === 'expired');
+    expect(expired?.fiveHourFreeRatio).toBe(1);
+    expect(expired?.sevenDayFreeRatio).toBe(1);
+  });
+
+  it('treats a token with no active 7d window as having the farthest 7d end', () => {
+    const result = useCase.run(
+      [
+        candidate(
+          'noSevenDay',
+          snapshot({ sevenDayReset: 0, sevenDayUtilization: 0 }),
+        ),
+        candidate(
+          'activeSoon',
+          snapshot({
+            sevenDayUtilization: 0.1,
+            sevenDayReset: NOW + 3 * DAY,
+          }),
+        ),
+      ],
+      NOW,
+    );
+
+    expect(result.selected?.name).toBe('activeSoon');
+    const noSevenDay = result.metrics.find((m) => m.name === 'noSevenDay');
+    expect(noSevenDay?.sevenDayEndEpoch).toBe(NOW + 7 * DAY);
+  });
+
+  it('returns null selection when no token passes the filter', () => {
+    const result = useCase.run(
+      [
+        candidate('busy', snapshot({ fiveHourUtilization: 0.9 })),
+        candidate('alsoBusy', snapshot({ sevenDayUtilization: 0.9 })),
+      ],
+      NOW,
+    );
+
+    expect(result.selected).toBeNull();
+  });
+
+  it('returns null selection for an empty candidate list', () => {
+    const result = useCase.run([], NOW);
+
+    expect(result.selected).toBeNull();
+    expect(result.metrics).toEqual([]);
+  });
+
+  it('reports per-candidate metrics for every input token', () => {
+    const result = useCase.run(
+      [
+        candidate('a', snapshot({ fiveHourUtilization: 0.2 })),
+        candidate('b', snapshot({ fiveHourUtilization: 0.95 })),
+      ],
+      NOW,
+    );
+
+    expect(result.metrics.map((m) => m.name)).toEqual(['a', 'b']);
+  });
+});